forked from KolibriOS/kolibrios
249 lines
16 KiB
Plaintext
249 lines
16 KiB
Plaintext
Когда ядро обнаруживает подключенное устройство USB, оно настраивает его
|
||
согласно USB-протокола - SET_ADDRESS + SET_CONFIGURATION. Всегда
|
||
устанавливается первая конфигурация. Ядро также читает дескриптор
|
||
устройства, чтобы показать некоторую информацию, читает и анализирует
|
||
дескриптор конфигурации. Для каждого интерфейса ядро будет искать класс этого
|
||
интерфейса и попытается загрузить соответствующий драйвер COFF. В настоящее
|
||
время соответствие кодов классов и имен драйверов жестко прописано в коде ядра
|
||
и выглядит следующим образом:
|
||
3 = usbhid.obj,
|
||
7 = usbprint.obj,
|
||
8 = usbstor.obj,
|
||
9 = поддерживаются самим ядром,
|
||
другие = usbother.obj.
|
||
|
||
Драйвер должен быть стандартным драйвером в формате COFF, экспортирующим
|
||
процедуру под названием "START" и переменную "version". Загрузчик вызывает
|
||
процедуру "START" как STDCALL с одним параметром DRV_ENTRY = 1. При завершении
|
||
работы системы, если инициализация драйвера была успешна, "START" процедуру
|
||
также вызывает код остановки системы с одним параметром DRV_EXIT = -1.
|
||
|
||
Драйвер должен зарегистрировать себя в качестве драйвера USB в процедуре
|
||
"START". Это делается путем вызова экспортируемой ядром функции RegUSBDriver и
|
||
возврата её результата в качестве результата "START" процедуры.
|
||
|
||
void* __stdcall RegUSBDriver(
|
||
const char* name,
|
||
void* handler,
|
||
const USBFUNC* usbfunc
|
||
);
|
||
|
||
Параметр 'name' должен совпадать с именем драйвера, например "usbhid" для
|
||
usbhid.obj.
|
||
|
||
Параметр 'handler' является необязательным. Если он не NULL, то он должен
|
||
указывать на стандартный обработчик IOCTL интерфейса, как в обычном (не-USB)
|
||
драйвере.
|
||
|
||
Параметр "Usbfunc" представляет собой указатель на следующую структуру:
|
||
|
||
struc USBFUNC
|
||
{
|
||
.strucsize dd ? ; размер структуры, включая это поле
|
||
.add_device dd ? ; указатель на AddDevice процедуру в драйвере
|
||
; (необходимо)
|
||
.device_disconnect dd ? ; указатель на DeviceDisconnected процедуру в драйвере
|
||
; опционально, может быть NULL
|
||
; В будущем могут быть добавлены другие функции
|
||
}
|
||
|
||
Драйвер ДОЛЖЕН реализовать функцию:
|
||
|
||
void* __stdcall AddDevice(
|
||
void* pipe0,
|
||
void* configdescr,
|
||
void* interfacedescr
|
||
);
|
||
|
||
Параметр "Pipe0" - хэндл контрольного канала для нулевой конечной точки
|
||
устройства. Он может быть использован в качестве аргумента для
|
||
USBControlTransferAsync (см. далее).
|
||
|
||
Параметр 'configdescr' указывает на дескриптор конфигурации и все связанные с
|
||
ним данные, представленные так, как их возвращает запрос GET_DESCRIPTOR.
|
||
Полный размер данных содержится в поле Length самого дескриптора.
|
||
(см. USB2.0 spec.)
|
||
|
||
Параметр 'interfacedescr' указывает на дескриптор интерфейса инициализируемого
|
||
в данный момент. Это указатель на данные находящиеся внутри структуры
|
||
"configdescr". (Помним, что структура INTERFACE_DESCRIPTOR, находится внутри
|
||
структуры CONFIGURATION_DESCRIPTOR. См. USB2.0 Spec.) Обратите внимание, что
|
||
одно устройство может реализовывать много интерфейсов и AddDevice может быть
|
||
вызвана несколько раз с одним "configdescr" но разными "interfacedescr".
|
||
|
||
Возвращенное значение NULL показывает, что инициализация не была успешной.
|
||
Любое другое значение означает инициализацию устройства. Ядро не делает попыток
|
||
как-то интерпретировать это значение. Это может быть, например, указатель на
|
||
внутренние данные драйвера в памяти, выделенной с помощью Kmalloc или индексом
|
||
в какой-то своей таблице. (Помните, что Kmalloc() НЕ stdcall-функция! Она
|
||
портит регистр ebx!)
|
||
|
||
Драйвер МОЖЕТ реализовать функцию:
|
||
|
||
void __stdcall DeviceDisconnected(
|
||
void* devicedata
|
||
);
|
||
|
||
Если данная функция реализована, то ядро вызывает её, когда устройство
|
||
отключено, посылая ей в качестве параметра "devicedata" то, что было возвращено
|
||
ему функцией "AddDevice" при старте драйвера.
|
||
|
||
Драйвер может использовать следующие функции экспортируемые ядром:
|
||
|
||
void* __stdcall USBOpenPipe(
|
||
void* pipe0,
|
||
int endpoint,
|
||
int maxpacketsize,
|
||
int type,
|
||
int interval
|
||
);
|
||
|
||
Параметр "Pipe0" - хэндл контрольного канала для нулевой конечной точки
|
||
устройства. Используется для идентификации устройства.
|
||
|
||
Параметр "endpoint" номер конечной точки USB. Младшие 4 бита, собственно, номер
|
||
точки, а бит 7 имеет следующее значение: 0 - для OUT точки, 1 - для IN точки.
|
||
Остальные биты должны быть равны нулю.
|
||
|
||
Параметр "maxpacketsize" устанавливает максимальный размер пакета для канала.
|
||
|
||
Параметр "type" устанавливает тип передачи для конечной точки, как это прописано
|
||
в USB спецификации:
|
||
|
||
0 = control,
|
||
1 = isochronous (сейчас не поддерживается),
|
||
2 = bulk,
|
||
3 = interrupt.
|
||
|
||
Параметр "interval" игнорируется для control и bulk передач. Для конечных точек
|
||
по прерываниям устанавливает периодичность опроса в миллисекундах.
|
||
|
||
Функция возвращает хэндл канала при успешном его открытии либо NULL при ошибке.
|
||
Хэндл канала обращается в NULL когда:
|
||
а) канал будет явно закрыт функцией USBClosePipe (см. ниже);
|
||
б) была выполнена предоставленная драйвером функция "DeviceDisconnected".
|
||
|
||
void __stdcall USBClosePipe(
|
||
void* pipe
|
||
);
|
||
|
||
Освобождает все ресурсы, связанные с выбранным каналом. Единственный параметр -
|
||
указатель на хэндл, который был возвращен функцией USBOpenPipe при открытии
|
||
канала. Когда устройство отключается, все связанные с ним каналы закрываются
|
||
ядром; нет необходимости в самостоятельном вызове этой функции.
|
||
|
||
void* __stdcall USBNormalTransferAsync(
|
||
void* pipe,
|
||
void* buffer,
|
||
int size,
|
||
void* callback,
|
||
void* calldata,
|
||
int flags
|
||
);
|
||
void* __stdcall USBControlTransferAsync(
|
||
void* pipe,
|
||
void* setup,
|
||
void* buffer,
|
||
int size,
|
||
void* callback,
|
||
void* calldata,
|
||
int flags
|
||
);
|
||
|
||
Первая функция ставит в очередь bulk или interrupt передачу для выбранного
|
||
канала. Тип и направление передачи фиксированы для bulk и interrupt типов
|
||
конечных точек, как это было выбрано функцией USBOpenPipe.
|
||
Вторая функция ставит в очередь control передачу для выбранного канала.
|
||
Направление этой передачи определяется битом 7 байта 0 пакета "setup"
|
||
(0 - для OUT, 1 - для IN передачи). Эта функция возвращает управление немедленно.
|
||
По окончании передачи вызывается функция "callback" заданная как аргумент
|
||
USB______TransferAsync.
|
||
|
||
Параметр "pipe" - хэндл, возвращенный функцией USBOpenPipe.
|
||
|
||
Параметр 'setup' функции USBControlTransferAsync указывает на 8-байтный
|
||
конфигурационный пакет (см. USB2.0 Spec).
|
||
|
||
Параметр "buffer" - это указатель на буфер. Для IN передач он будет заполнен
|
||
принятыми данными. Для OUT передач он должен быть заполнен данными, которые мы
|
||
хотим передать. Указатель может быть NULL для пустых передач, либо для передач
|
||
control, если дополнительных данных не требуется.
|
||
|
||
Параметр "size" - это размер данных для передачи. Он может быть равен 0 для
|
||
пустых передач, либо для передач control, если дополнительных данных не требуется.
|
||
|
||
Параметр "callback" - это указатель на функцию, которая будет вызвана по
|
||
окончании передачи.
|
||
|
||
Параметр "calldata" будет передан функции "callback" вызываемой по окончании
|
||
передачи. Например, он может быть NULL или указывать на данные устройства или
|
||
указывать на данные используемые как дополнительные параметры, передаваемые от
|
||
вызывающей USB_____TransferAsync функции в callback функцию.
|
||
|
||
Другие данные, связанные с передачей, могут быть помещены до буфера (по смещению)
|
||
или после него. Они могут быть использованы из callback-функции, при необходимости.
|
||
|
||
Параметр "flags" - это битовое поле. Бит 0 игнорируется для OUT передач. Для IN
|
||
передач он означает, может ли устройство передать меньше данных (бит=1), чем
|
||
определено в "size" или нет (бит=0). Остальные биты не используются и должны
|
||
быть равны 0.
|
||
|
||
Возвращаемое функциями значение равно NULL в случае ошибки и не NULL если
|
||
передача успешно поставлена в очередь. Если происходит ошибка при передаче, то
|
||
callback функция будет об этом оповещена.
|
||
|
||
void __stdcall CallbackFunction(
|
||
void* pipe,
|
||
int status,
|
||
void* buffer,
|
||
int length,
|
||
void* calldata
|
||
);
|
||
|
||
Параметры 'pipe', 'buffer', 'calldata' значат то же, что и для
|
||
USB_____TransferAsync.
|
||
|
||
Параметр "length" это счетчик переданных байт. Для control передач он отражает
|
||
дополнительные 8 байт этапа SETUP. Т.е. 0 означает ошибку на этапе SETUP, а
|
||
"size"+8 успешную передачу.
|
||
|
||
Параметр "status" не равен 0 в случае ошибки:
|
||
USB_STATUS_OK = 0 ; без ошибок
|
||
USB_STATUS_CRC = 1 ; ошибка контрольной суммы
|
||
USB_STATUS_BITSTUFF = 2 ; ошибка инверсии битов (bitstuffing)
|
||
USB_STATUS_TOGGLE = 3 ; data toggle mismatch
|
||
; (Нарушение последовательности DAT0/DAT1)
|
||
USB_STATUS_STALL = 4 ; устройство возвратило STALL статус (остановлено)
|
||
USB_STATUS_NORESPONSE = 5 ; устройство не отвечает
|
||
USB_STATUS_PIDCHECK = 6 ; ошибка в поле PacketID (PID)
|
||
USB_STATUS_WRONGPID = 7 ; неожидаемое PacketID (PID) значение
|
||
USB_STATUS_OVERRUN = 8 ; слишком много данных от конечной точки
|
||
USB_STATUS_UNDERRUN = 9 ; слишком мало данных от конечной точки
|
||
USB_STATUS_BUFOVERRUN = 12 ; переполнение внутреннего буфера контроллера
|
||
; возможна только для изохронных передач
|
||
USB_STATUS_BUFUNDERRUN = 13 ; опустошение внутреннего буфера контроллера
|
||
; возможна только для изохронных передач
|
||
USB_STATUS_CLOSED = 16 ; канал закрыт либо через ClosePipe, либо в
|
||
; результате отключения устройства
|
||
|
||
Если несколько передач были поставлены в очередь для одного канала, то callback
|
||
функции для них будут вызываться в порядке постановки передач в очередь.
|
||
Если канал был закрыт ввиду USBClosePipe или отключения устройства, то callback
|
||
функции (если очередь передач не пуста) получат USB_STATUS_CLOSED.
|
||
Вызов DeviceDisconnected() последует после отработки всех оставшихся в очереди
|
||
callback функций.
|
||
|
||
void* __stdcall USBGetParam(void* pipe0, int param);
|
||
|
||
Возвращает указатель на некоторые параметры устройства запомненные ядром при
|
||
инициализации первой конфигурации. Не передает ничего устройству по шине.
|
||
|
||
pipe0 - хэндл контрольного канала для нулевой конечной точки устройства.
|
||
|
||
param - выбор возвращаемого параметра:
|
||
0 - возвратить указатель на дескриптор устройства;
|
||
1 - возвратить указатель на дескриптор конфигурации;
|
||
2 - возвратить режим шины устройства:
|
||
USB_SPEED_FS = 0 ; full-speed
|
||
USB_SPEED_LS = 1 ; low-speed
|
||
USB_SPEED_HS = 2 ; high-speed |