Writing drivers for KolibriOS/ru: Difference between revisions

(4 intermediate revisions by the same user not shown)

Line 6:

== Вступление ==

'''Предупреждение 0.''' Данная статья описывает написание драйверов для основной ветки Колибри ОС и не включает в себя исторические моменты. Предыдущая версия статьи находится на форуме по [http://board.kolibrios.org/viewtopic.php?p=10987#p10987 ссылке].

'''Предупреждение 1.''' Прежде чем писать драйвер, хорошо подумайте, нельзя ли обойтись средствами прикладных [http://ru.wikipedia.org/wiki/API API], в частности, функций работы с оборудованием [[SysFn46/ru|46]] и [[SysFn62/ru|62]]. Во-первых, от ошибки в кривом приложении пострадает только это кривое приложение, а кривой драйвер способен без особого труда обрушить всю систему. Во-вторых, для приложений можно вылавливать баги в отладчике [[Mtdbg/ru|MTDBG]], обладающем определёнными возможностями, а для драйверов этот путь закрыт (разве что встроенный отладчик эмулятора [http://ru.wikipedia.org/wiki/Bochs Bochs], но он заведомо непригоден для отладки с реальным железом), так что единственным средством остаётся отладочный вывод на доску отладки [[Board/ru|BOARD]] со всеми недостатками.

Line 18:

Line 20:

== Описание работы с драйверной подсистемой ==

Драйверная подсистема позволяет загружать драйвера в формате PE и работать с ними. Для загрузки драйверов ~~в ядре придусмотрено~~ 2 ~~сисфункции~~ 68.16 и 68.21 а для управления драйвером ~~сисфункция~~ 68.17. Драйвер должен иметь ~~экспортируемую функцию START~~, которая должна возвращать хандлер ~~стуктуры~~ драйвера в случае успеха, и ноль в случае, если драйвер не ~~загружен~~. Для работы ~~с ядром драйверу нужно импортировать~~ некоторые функции ядра, которые экспортируются ядром как core.dll.

Драйверная подсистема позволяет ядру загружать драйвера в формате PE и работать с ними. Для загрузки драйверов предусмотрено 2 системных вызова: 68.16 и 68.21, а для управления драйвером системный вызов 68.17. Драйвер должен иметь точку входа с функцией, которая должна возвращать хандлер структуры драйвера в случае успеха, и ноль в случае, если драйвер не инициализировался. Для работы драйвер импортирует некоторые функции ядра, которые экспортируются ядром как core.dll.

== Драйвер ==

Специально для желающих написать свой драйвер предоставляется каркас драйвера. Он находится в ~~svn~~-репозитории ~~вместе с ядром, точнее,~~ в папке ~~{{#svn~~:/~~kernel~~/~~trunk~~/~~drivers|svn:~~//~~kolibrios.org~~/~~kernel~~/~~trunk~~/drivers}}. Ну что же, давайте посмотрим ~~({{#svn~~:/~~kernel~~/~~trunk~~/drivers/sceletone.asm|sceletone.asm ~~из #450|450}}~~):

Специально для желающих написать свой драйвер предоставляется каркас драйвера. Он находится в git-репозитории в папке [https://git.kolibrios.org/KolibriOS/kolibrios/src/branch/main/drivers drivers]. Ну что же, давайте посмотрим [https://git.kolibrios.org/KolibriOS/kolibrios/src/branch/main/drivers/sceletone.asm sceletone.asm]):

Line 44:

Line 47:

</syntaxhighlight>

Ну, "[http://ru.wikipedia.org/wiki/Copyright Copyright]" - он и есть копирайт, комментарий в следующей строке извещает нас, куда же мы собственно попали, это неинтересно. Дальше мы должны известить компилятор, какой формат мы хотим получить. Драйвера должны иметь формат [https://en.wikipedia.org/wiki/Portable_Executable PE]. В общем, так должно быть для всех драйверов. Дальше идёт указание функции START как точки входа, которую вызовет ядро после загрузки драйвера. После этого объявляется секция ".flat", в которой будет располагаться код нашего драйвера, после объявления секции подключаем вспомогательные файлы. ~~{{#svn~~:/drivers/proc32.inc|proc32.inc}} содержит макросы для определения и вызова стандартных процедур (<tt>proc/endp</tt>, <tt>stdcall/ccall/invoke/cinvoke</tt>, <tt>local</tt> для создания локальных переменных) и находится в той же папке, что и ~~{{#svn:/drivers/~~sceletone.asm~~|sceletone.asm}}~~. Его можно включать или не включать, макросы оттуда можно использовать или не использовать, в этой статье они используются, чтобы не усложнять восприятие (вообще говоря, при стремлении к максимальной эффективности использование макросов может повредить, но это тема отдельных жарких споров). ~~{{#svn~~:/drivers/peimport.inc|peimport.inc}} содержит объявления для всех экспортируемых функций ядра. Загляните туда, ничего сложного там нет, просто куча стереотипных конструкций. На самом деле (в смысле того, как разрешается импорт при загрузке драйвера) список всех экспортируемых функций и данных ядра находится в файле {{#svn:/kernel/trunk/core/exports.inc|core/exports.inc}} (метка <tt>kernel_export</tt>), так что если вам как программисту ядра вдруг понадобиться что-нибудь своё экспортировать, лезьте туда (ну ~~и {{#svn:/drivers/~~peimport.inc~~|peimport.inc}}~~ отредактируйте из вежливости к другим).

Ну, "[http://ru.wikipedia.org/wiki/Copyright Copyright]" - он и есть копирайт, комментарий в следующей строке извещает нас, куда же мы собственно попали, это неинтересно. Дальше мы должны известить компилятор, какой формат мы хотим получить. Драйвера должны иметь формат [https://en.wikipedia.org/wiki/Portable_Executable PE]. В общем, так должно быть для всех драйверов. Дальше идёт указание функции START как точки входа, которую вызовет ядро после загрузки драйвера. После этого объявляется секция ".flat", в которой будет располагаться код нашего драйвера, после объявления секции подключаем вспомогательные файлы. [https://git.kolibrios.org/KolibriOS/kolibrios/src/branch/main/drivers/proc32.inc proc32.inc] содержит макросы для определения и вызова стандартных процедур (<tt>proc/endp</tt>, <tt>stdcall/ccall/invoke/cinvoke</tt>, <tt>local</tt> для создания локальных переменных) и находится в той же папке, что и sceletone.asm. Его можно включать или не включать, макросы оттуда можно использовать или не использовать, в этой статье они используются, чтобы не усложнять восприятие (вообще говоря, при стремлении к максимальной эффективности использование макросов может повредить, но это тема отдельных жарких споров). [https://git.kolibrios.org/KolibriOS/kolibrios/src/branch/main/drivers/peimport.inc peimport.inc] содержит объявления для всех экспортируемых функций ядра. Загляните туда, ничего сложного там нет, просто куча стереотипных конструкций. На самом деле (в смысле того, как разрешается импорт при загрузке драйвера) список всех экспортируемых функций и данных ядра находится в файле {{#svn:/kernel/trunk/core/exports.inc|core/exports.inc}} (метка <tt>kernel_export</tt>), так что если вам как программисту ядра вдруг понадобиться что-нибудь своё экспортировать, лезьте туда (ну peimport.inc отредактируйте из вежливости к другим).

Внимание! Здесь появляется возможность несовместимости: если вы используете какие-нибудь функции, которых (ещё или уже) нет в ядре, на которое вы рассчитываете, ядро откажется грузить ваш драйвер (ругнувшись на доске отладки нехорошим словом на ненашем языке "unresolved" с указанием имени функции).

Line 1,163:

Line 1,166:

</syntaxhighlight>

== Загрузка и установка драйвера ==

В приведённом выше примере загрузкой драйвера занимается управляющая программа, вызывая соответствующие системные функции ядра. Но управляющая программа нужна далеко не всем видам драйверов и во многих случаях является просто приятным бонусом к основному функционалу драйвера, например для драйверов запоминающих устройств управляющая программа не обязательна и важны лишь экспортируемые ядром функции для работы с дисковой подсистемой.

По этой причине для загрузки внешних драйверов можно применить другие методы. Одним из оптимальных методов является использование программы "loaddrv", которая принимает в качестве аргумента командной строки имя драйвера без его расширения и загружает его через системную функцию 68.16. Например, при исполнении команды "loaddrv sdhci" программа загрузит драйвер "/sys/drivers/sdhci.sys". Данный способ загрузки позволяет без дополнительных изменений ядра добавить загрузку драйвера, прописав его в файл "/sys/settings/autorun.dat". Этот метод предпочтителен при добавлении новых драйверов в основной образ системы.

Но существуют ситуации когда драйвер не может быть добавлен в основной образ(образ дискеты) по причине слишком большого размера файла для этого образа. В данной ситуации целесообразнее написать собственный загрузчик драйвера, который определит путь к расположению файла и сможет передать необходимую для загрузки командную строку.

Существует также ситуация, когда драйвер необходимо загрузить во время инициализации самого ядра, например для работы USB подсистемы ядро само загружает драйвера хост-контроллеров и драйвера классов устройств. Загрузка драйверов из ядра аналогична загрузке через системную функцию 68.16. Данный метод не рекомендуется, но может быть применён в специализированных под определённое железо сборках ядра.

== Краткое описание экспортируемых ядром функций ==

Описание подробностей применения функций ядра можно достаточно легко посмотреть на основе имеющихся драйверов, но это требует достаточно хорошего знания языка ассемблера fasm и понимания общей структуры ядра. Для более краткого описания в данной статье описаны некоторые из интерфейсов ядра, предоставляемых драйверам. Описания достаточны для написания некоторых типов драйверов.

=== Мьютексы и семафоры ===

В большинстве случаев для обработки нескольких одновременных вызовов функций необходимы средства синхронизации и блокировки доступа к ресурсам, с которыми работает данная функция. Для обеспечения такой блокировки драйвер импортирует функции, реализующие мьютексы и семафоры

struct mutex {

struct list_head wait_list;

atomic_t count;

};

void fastcall mutex_init(struct mutex *lock);

void fastcall mutex_lock(struct mutex *lock);

void fastcall mutex_unlock(struct mutex *lock);

void fastcall init_rwsem(struct rw_semaphore *sem);

void fastcall down_read(struct rw_semaphore *sem);

void fastcall down_write(struct rw_semaphore *sem);

void fastcall up_read(struct rw_semaphore *sem);

void fastcall up_write(struct rw_semaphore *sem);

</syntaxhighlight>

=== Работа с подсистемой событий ===

Подсистема событий является одной из важнейших частей ядра, необходимой для реализации сложных драйверов, требующих надёжный метод коммуникации между различными потоками и функциями драйвера. Подробное описание этой подсистемы находится [http://wiki.kolibrios.org/wiki/Kernel_Event/ru в отдельной статье].

=== Интерфейс работы с дисковой подсистемой ===

Ядро предоставляет интерфейс для добавления, удаления и работы с логическими дисками. Данный интерфейс позволяет реализовывать драйвера различных дисковых устройств, вне зависимости от их физического интерфейса, в том числе и виртуальные.

Для добавления нового диска используется функция DiskAdd. Описание передаваемых в неё параметров приведено ниже по тексту.

Для удаления диска используется функция DiskDel, в которую передаётся полученный ранее указатель. Эта функция удаляет диск из единого списка логических дисков.

void* DiskAdd(DISKFUNC* functions, const char* name, uint32_t userdata, uint32_t flags);

void DiskDel(void* hDisk);

void DiskMediaChanged(void* hDisk, int newstate);

; Flags for add new disk

DISK_NO_INSERT_NOTIFICATION = 1

</syntaxhighlight>

Некоторые диски имеют возможность изменения содержимого, например CD приводы, и по этому в ядре предусмотрена функция "DiskMediaChanged".

Эта функция информирует ядро о том, что носитель был вставлен, удален или изменен. Значение "newstate" должно быть равно нулю, если в данный момент носитель не вставлен, и ненулевым в противном случае. Эта функция не должна вызываться с ненулевым значением newstate ни из одной callback функции. Эта функция не должна вызываться, если активен другой вызов этой функции.

Если при добавлении диска был установлен флаг DISK_NO_INSERT_NOTIFICATION, то драйвер не должен вызывать функцию "DiskMediaChanged" и ядро будет проверять наличие носителя при каждой операции. Данный подход может использоваться для дисков, подключение или изъятие носителей которых не может быть определено драйвером, например данный флаг применяется в драйвере контроллера floppy дисков.

==== Callback функции драйвера диска ====

Как уже было описано выше, при добавлении нового диска, драйвер должен передать ядру указатель на структуру DISKFUNC, которая содержит общий размер структуры(поле strucsize) и массив указателей на функции. Если функция отсутствует, то вместо неё должен быть записан ноль.

struct DISKFUNC

strucsize dd ?

close dd ?

closemedia dd ?

querymedia dd ?

read dd ?

write dd ?

flush dd ?

adjust_cache_size dd ?

LoadTray dd ?

ends

; Error codes for callback functions.

DISK_STATUS_OK = 0 ; success

DISK_STATUS_GENERAL_ERROR = -1; if no other code is suitable

DISK_STATUS_INVALID_CALL = 1 ; invalid input parameters

DISK_STATUS_NO_MEDIA = 2 ; no media present

DISK_STATUS_END_OF_MEDIA = 3 ; end of media while reading/writing data

DISK_STATUS_NO_MEMORY = 4 ; insufficient memory for driver operation

</syntaxhighlight>

void close(void* userdata);

</syntaxhighlight>

Необязательная функция. Функция которая освобождает все ресурсы, зависящие от драйвера, для диска.

void closemedia(void* userdata);

</syntaxhighlight>

Необязательная функция, может отсутствовать если носитель не является съемным. Функция, вызов которой информирует драйвер о том, что ядро завершило всю обработку с текущим носителем. Если носитель удален, драйвер должен отклонять все запросы к этому носителю с помощью команды DISK_STATUS_NO_MEDIA, даже если вставлен новый носитель, до тех пор, пока не будет вызвана эта функция. Если носитель удален, новый вызов 'disk_media_changed' не разрешен до тех пор, пока не будет вызвана эта функция.

int querymedia(void* userdata, DISKMEDIAINFO* info);

; Media flags. Represent bits in DISKMEDIAINFO.Flags.

DISK_MEDIA_READONLY = 1

~~== Мьютексы и семафоры ==~~

struct DISKMEDIAINFO

Flags dd ? ; Combination of DISK_MEDIA_* bits.

SectorSize dd ? ; Size of the sector.

Capacity dq ? ; Size of the media in sectors.

LastSessionSector dd ? ; Number last session sectors for CDFS

ends

~~== Работа с подсистемой событий ==~~

</syntaxhighlight>

Обязательная функция, которая производит заполнение структуры DISKMEDIAINFO и возвращает DISK_STATUS_* код.

=~~= Интерфейс работы~~ с ~~дисковой подсистемой ==~~

int read(void* userdata, void* buffer, __int64 startsector, int* numsectors);

</syntaxhighlight>

Обязательная функция. Функция для чтения секторов диска в буфер "buffer", начиная с сектора "startsector". Количество считываемых секторов находится по указателю "numsectors". Функция должна возвращать DISK_STATUS_* код и записать количество успешно прочитанных секторов по указателю "numsectors". Указатель на буфер является виртуальным адресом.

== Интерфейс работы со встроенными устройствами ==

; int write(void* userdata, void* buffer, __int64 startsector, int* numsectors);

</syntaxhighlight>

Необязательная функция. Функция для записи секторов диска из буфера "buffer", начиная с сектора "startsector". Количество записываемых секторов находится по указателю "numsectors".Функция должна возвращать DISK_STATUS_* код и записать количество успешно записанных секторов по указателю "numsectors". Указатель на буфер является виртуальным адресом.

int flush(void* userdata);

</syntaxhighlight>

Необязательная функция. Функция очищает внутренний кэш устройства и возвращает DISK_STATUS_* код. Обратите внимание, что функции чтения/записи вызываются менеджером кэша, поэтому драйвер не должен создавать программный кэш. Эта функция реализована для очистки аппаратного кэша, если он существует.

unsigned int adjust_cache_size(void* userdata, unsigned int suggested_size);

</syntaxhighlight>