Subversion Repositories Kolibri OS

; standard driver stuff

format MS COFF

DEBUG = 1

; this is for DEBUGF macro from 'fdo.inc'

__DEBUG__ = 1

__DEBUG_LEVEL__ = 1

include '../proc32.inc'

include '../imports.inc'

include '../fdo.inc'

include '../../struct.inc'

public START

public version

; Compile-time settings.

; If set, the code will dump all descriptors as they are read to the debug board.

USB_DUMP_DESCRIPTORS = 1

; If set, the code will dump any unclaimed input to the debug board.

HID_DUMP_UNCLAIMED = 1

; USB constants

DEVICE_DESCR_TYPE           = 1

CONFIG_DESCR_TYPE           = 2

STRING_DESCR_TYPE           = 3

INTERFACE_DESCR_TYPE        = 4

ENDPOINT_DESCR_TYPE         = 5

DEVICE_QUALIFIER_DESCR_TYPE = 6

CONTROL_PIPE     = 0

ISOCHRONOUS_PIPE = 1

BULK_PIPE        = 2

INTERRUPT_PIPE   = 3

; USB HID constants

HID_DESCR_TYPE      = 21h

REPORT_DESCR_TYPE   = 22h

PHYSICAL_DESCR_TYPE = 23h

; USB structures

struct config_descr

bLength                 db      ?

bDescriptorType         db      ?

wTotalLength            dw      ?

bNumInterfaces          db      ?

bConfigurationValue     db      ?

iConfiguration          db      ?

bmAttributes            db      ?

bMaxPower               db      ?

ends

struct interface_descr

bLength                 db      ?

bDescriptorType         db      ?

bInterfaceNumber        db      ?

bAlternateSetting       db      ?

bNumEndpoints           db      ?

bInterfaceClass         db      ?

bInterfaceSubClass      db      ?

bInterfaceProtocol      db      ?

iInterface              db      ?

ends

struct endpoint_descr

bLength                 db      ?

bDescriptorType         db      ?

bEndpointAddress        db      ?

bmAttributes            db      ?

wMaxPacketSize          dw      ?

bInterval               db      ?

ends

; USB HID structures

struct hid_descr

bLength                 db      ?

bDescriptorType         db      ?

bcdHID                  dw      ?

bCountryCode            db      ?

bNumDescriptors         db      ?

base_sizeof     rb      0

; now two fields are repeated .bNumDescriptors times:

subDescriptorType       db      ?

subDescriptorLength     dw      ?

ends

; Include macro for parsing report descriptors/data.

macro workers_globals

{}

include 'report.inc'

; Driver data for all devices

struct usb_device_data

hid                     hid_data        ; data of HID layer

epdescr                 dd      ?       ; endpoint descriptor

hiddescr                dd      ?       ; HID descriptor

interface_number        dd      ?       ; copy of interface_descr.bInterfaceNumber

configpipe              dd      ?       ; config pipe handle

intpipe                 dd      ?       ; interrupt pipe handle

input_transfer_size     dd      ?       ; input transfer size

input_buffer            dd      ?       ; buffer for input transfers

control                 rb      8       ; control packet to device

ends

section '.flat' code readable align 16

; The start procedure.

proc START

virtual at esp

        dd      ?       ; return address

.reason dd      ?

end virtual

; 1. Test whether the procedure is called with the argument DRV_ENTRY.

; If not, return 0.

        xor     eax, eax        ; initialize return value

        cmp     [.reason], 1    ; compare the argument

        jnz     .nothing

; 2. Register self as a USB driver.

; The name is my_driver = 'usbhid'; IOCTL interface is not supported;

; usb_functions is an offset of a structure with callback functions.

        stdcall RegUSBDriver, my_driver, eax, usb_functions

; 3. Return the returned value of RegUSBDriver.

.nothing:

        ret     4

endp

; This procedure is called when new HID device is detected.

; It initializes the device.

proc AddDevice

        push    ebx esi edi     ; save used registers to be stdcall

virtual at esp

                rd      3       ; saved registers

                dd      ?       ; return address

.config_pipe    dd      ?

.config_descr   dd      ?

.interface      dd      ?

end virtual

        DEBUGF 1,'K : USB HID device detected\n'

; 1. Allocate memory for device data.

        movi    eax, sizeof.usb_device_data

        call    Kmalloc

        test    eax, eax

        jnz     @f

        mov     esi, nomemory_msg

        call    SysMsgBoardStr

        jmp     .return0

@@:

; zero-initialize it

        mov     edi, eax

        xchg    eax, ebx

        xor     eax, eax

        movi    ecx, sizeof.usb_device_data / 4

        rep stosd

        mov     edx, [.interface]

; HID devices use one IN interrupt endpoint for polling the device

; and an optional OUT interrupt endpoint. We do not use the later,

; but must locate the first. Look for the IN interrupt endpoint.

; Also, look for the HID descriptor; according to HID spec, it must be

; located before endpoint descriptors.

; 2. Get the upper bound of all descriptors' data.

        mov     eax, [.config_descr]

        movzx   ecx, [eax+config_descr.wTotalLength]

        add     eax, ecx

; 3. Loop over all descriptors until

; either end-of-data reached - this is fail

; or interface descriptor found - this is fail, all further data

;    correspond to that interface

; or endpoint descriptor for IN endpoint is found

; (HID descriptor must be located before the endpoint descriptor).

; 3a. Loop start: edx points to the interface descriptor.

.lookep:

; 3b. Get next descriptor.

        movzx   ecx, byte [edx] ; the first byte of all descriptors is length

        test    ecx, ecx

        jz      .cfgerror

        add     edx, ecx

; 3c. Check that at least two bytes are readable. The opposite is an error.

        inc     edx

        cmp     edx, eax

        jae     .cfgerror

        dec     edx

; 3d. Check that this descriptor is not interface descriptor. The opposite is

; an error.

        cmp     [edx+endpoint_descr.bDescriptorType], INTERFACE_DESCR_TYPE

        jz      .cfgerror

; 3e. For HID descriptor, proceed to 4.

; For endpoint descriptor, go to 5.

; For other descriptors, continue the loop.

; Note: bDescriptorType is in the same place in all descriptors.

        cmp     [edx+endpoint_descr.bDescriptorType], ENDPOINT_DESCR_TYPE

        jz      .foundep

        cmp     [edx+endpoint_descr.bDescriptorType], HID_DESCR_TYPE

        jnz     .lookep

; 4a. Check that the descriptor contains all required data and all data are

; readable. The opposite is an error.

        movzx   ecx, [edx+hid_descr.bLength]

        cmp     ecx, hid_descr.base_sizeof + 3

        jb      .cfgerror

        add     ecx, edx

        cmp     ecx, eax

        ja      .cfgerror

; 4b. Store the pointer in usb_device_data structure for further references.

        mov     [ebx+usb_device_data.hiddescr], edx

; 4c. Continue the loop.

        jmp     .lookep

.foundep:

; 5a. Check that the descriptor contains all required data and all data are

; readable. The opposite is an error.

        cmp     byte [edx+endpoint_descr.bLength], sizeof.endpoint_descr

        jb      .cfgerror

        lea     ecx, [edx+sizeof.endpoint_descr]

        cmp     ecx, eax

        jbe     @f

; 6. An error occured during processing endpoint descriptor.

.cfgerror:

; 6a. Print a message.

        mov     esi, invalid_config_descr_msg

        call    SysMsgBoardStr

; 6b. Free memory allocated for device data.

.free:

        xchg    eax, ebx

        call    Kfree

.return0:

; 6c. Return an error.

        xor     eax, eax

.nothing:

        pop     edi esi ebx     ; restore used registers to be stdcall

        ret     12

@@:

; 5b. If this is not IN interrupt endpoint, ignore it and continue the loop.

        test    [edx+endpoint_descr.bEndpointAddress], 80h

        jz      .lookep

        mov     cl, [edx+endpoint_descr.bmAttributes]

        and     cl, 3

        cmp     cl, INTERRUPT_PIPE

        jnz     .lookep

; 5c. Store the pointer in usb_device_data structure for futher references.

        mov     [ebx+usb_device_data.epdescr], edx

; 5d. Check that HID descriptor was found. If not, go to 6.

        cmp     [ebx+usb_device_data.hiddescr], 0

        jz      .cfgerror

.descriptors_found:

; 6. Configuration descriptor seems to be ok.

; Send SET_IDLE command disabling auto-repeat feature (it is quite useless)

; and continue configuring in SET_IDLE callback.

        lea     edx, [ebx+usb_device_data.control]

        mov     eax, [.interface]

        mov     dword [edx], 21h + \    ; Class-specific request to Interface

                (0Ah shl 8) + \         ; SET_IDLE

                (0 shl 16) + \          ; apply to all input reports

                (0 shl 24)              ; disable auto-repeat

        movzx   eax, [eax+interface_descr.bInterfaceNumber]

        mov     [ebx+usb_device_data.interface_number], eax

        mov     [edx+4], eax            ; set interface number, zero length

        mov     eax, [.config_pipe]

        mov     [ebx+usb_device_data.configpipe], eax

        xor     ecx, ecx

        stdcall USBControlTransferAsync, eax, edx, ecx, ecx, idle_set, ebx, ecx

; 7. Return pointer to usb_device_data.

        xchg    eax, ebx

        jmp     .nothing

endp

; This procedure is called by USB stack when SET_IDLE request initiated by

; AddDevice is completed, either successfully or unsuccessfully.

proc idle_set

        push    ebx esi         ; save used registers to be stdcall

virtual at esp

                rd      2       ; saved registers

                dd      ?       ; return address

.pipe           dd      ?

.status         dd      ?

.buffer         dd      ?

.length         dd      ?

.calldata       dd      ?

end virtual

; Ignore status. Support for SET_IDLE is optional, so the device is free to

; STALL the request; config pipe should remain functional without explicit cleanup.

        mov     ebx, [.calldata]

; 1. HID descriptor contains length of Report descriptor. Parse it.

        mov     esi, [ebx+usb_device_data.hiddescr]

        movzx   ecx, [esi+hid_descr.bNumDescriptors]

        lea     eax, [hid_descr.base_sizeof+ecx*3]

        cmp     eax, 100h

        jae     .cfgerror

        cmp     al, [esi+hid_descr.bLength]

        jb      .cfgerror

.look_report:

        dec     ecx

        js      .cfgerror

        cmp     [esi+hid_descr.subDescriptorType], REPORT_DESCR_TYPE

        jz      .found_report

        add     esi, 3

        jmp     .look_report

.cfgerror:

        mov     esi, invalid_config_descr_msg

.abort_with_msg:

        call    SysMsgBoardStr

        jmp     .nothing

.found_report:

; 2. Send request for the Report descriptor.

; 2a. Allocate memory.

        movzx   eax, [esi+hid_descr.subDescriptorLength]

        test    eax, eax

        jz      .cfgerror

        push    eax

        call    Kmalloc

        pop     ecx

; If failed, say a message and stop initialization.

        mov     esi, nomemory_msg

        test    eax, eax

        jz      .abort_with_msg

; 2b. Submit the request.

        xchg    eax, esi

        lea     edx, [ebx+usb_device_data.control]

        mov     eax, [ebx+usb_device_data.interface_number]

        mov     dword [edx], 81h + \    ; Standard request to Interface

                (6 shl 8) + \           ; GET_DESCRIPTOR

                (0 shl 16) + \          ; descriptor index: there is only one report descriptor

                (REPORT_DESCR_TYPE shl 24); descriptor type

        mov     [edx+4], ax             ; Interface number

        mov     [edx+6], cx             ; descriptor length

        stdcall USBControlTransferAsync, [ebx+usb_device_data.configpipe], \

                edx, esi, ecx, got_report, ebx, 0

; 2c. If failed, free the buffer and stop initialization.

        test    eax, eax

        jnz     .nothing

        xchg    eax, esi

        call    Kfree

.nothing:

        pop     esi ebx         ; restore used registers to be stdcall

        ret     20

endp

; This procedure is called by USB stack when the report descriptor queried

; by idle_set is completed, either successfully or unsuccessfully.

proc got_report stdcall uses ebx esi edi, pipe, status, buffer, length, calldata

locals

parse_descr_locals

if ~HID_DUMP_UNCLAIMED

has_driver      db      ?

                rb      3

end if

endl

; 1. Check the status; if the request has failed, say something to the debug board

; and stop initialization.

        cmp     [status], 0

        jnz     .generic_fail

; 2. Subtract size of setup packet from the total length;

; the rest is length of the descriptor, and it must be nonzero.

        sub     [length], 8

        ja      .has_something

.generic_fail:

        push    esi

        mov     esi, reportfail

        call    SysMsgBoardStr

        pop     esi

        jmp     .exit

.has_something:

; 3. Process descriptor.

; 3a. Dump it to the debug board, if enabled in compile-time setting.

if USB_DUMP_DESCRIPTORS

        mov     eax, [buffer]

        mov     ecx, [length]

        DEBUGF 1,'K : report descriptor:'

@@:

        DEBUGF 1,' %x',[eax]:2

        inc     eax

        dec     ecx

        jnz     @b

        DEBUGF 1,'\n'

end if

; 3b. Call the HID layer.

        parse_descr

        cmp     [report_ok], 0

        jz      got_report.exit

        mov     ebx, [calldata]

        postprocess_descr

; 4. Stop initialization if no driver is assigned.

if ~HID_DUMP_UNCLAIMED

        cmp     [has_driver], 0

        jz      got_report.exit

end if

; 5. Open interrupt IN pipe. If failed, stop initialization.

        mov     edx, [ebx+usb_device_data.epdescr]

        movzx   ecx, [edx+endpoint_descr.bEndpointAddress]

        movzx   eax, [edx+endpoint_descr.bInterval]

        movzx   edx, [edx+endpoint_descr.wMaxPacketSize]

        stdcall USBOpenPipe, [ebx+usb_device_data.configpipe], ecx, edx, INTERRUPT_PIPE, eax

        test    eax, eax

        jz      got_report.exit

        mov     [ebx+usb_device_data.intpipe], eax

; 6. Initialize buffer for input packet.

; 6a. Find the length of input packet.

; This is the maximal length of all input reports.

        mov     edx, [ebx+usb_device_data.hid.input.first_report]

        xor     eax, eax

.find_input_size:

        test    edx, edx

        jz      .found_input_size

        cmp     eax, [edx+report.size]

        jae     @f

        mov     eax, [edx+report.size]

@@:

        mov     edx, [edx+report.next]

        jmp     .find_input_size

.found_input_size:

; report.size is in bits, transform it to bytes

        add     eax, 7

        shr     eax, 3

; if reports are numbered, the first byte is report ID, include it

        cmp     [ebx+usb_device_data.hid.input.numbered], 0

        jz      @f

        inc     eax

@@:

        mov     [ebx+usb_device_data.input_transfer_size], eax

; 6b. Allocate memory for input packet: dword-align and add additional dword

; for extract_field_value.

        add     eax, 4+3

        and     eax, not 3

        call    Kmalloc

        test    eax, eax

        jnz     @f

        mov     esi, nomemory_msg

        call    SysMsgBoardStr

        jmp     got_report.exit

@@:

        mov     [ebx+usb_device_data.input_buffer], eax

; 7. Submit a request for input packet and wait for input.

        call    ask_for_input

got_report.exit:

        mov     eax, [buffer]

        call    Kfree

        ret

endp

; Helper procedure for got_report and got_input.

; Submits a request for the next input packet.

proc ask_for_input

; just call USBNormalTransferAsync with correct parameters,

; allow short packets

        stdcall USBNormalTransferAsync, \

                [ebx+usb_device_data.intpipe], \

                [ebx+usb_device_data.input_buffer], \

                [ebx+usb_device_data.input_transfer_size], \

                got_input, ebx, \

                1

        ret

endp

; This procedure is called by USB stack when a HID device responds with input

; data packet.

proc got_input stdcall uses ebx esi edi, pipe, status, buffer, length, calldata

locals

parse_input_locals

endl

; 1. Validate parameters: fail on error, ignore zero-length transfers.

        mov     ebx, [calldata]

        cmp     [status], 0

        jnz     .fail

        cmp     [length], 0

        jz      .done

; 2. Get pointer to report in esi.

; 2a. If there are no report IDs, use hid.input.data.

        mov     eax, [buffer]

        mov     esi, [ebx+usb_device_data.hid.input.data]

        cmp     [ebx+usb_device_data.hid.input.numbered], 0

        jz      .report_found

; 2b. Otherwise, the first byte of report is report ID;

; locate the report by its ID, advance buffer+length to one byte.

        movzx   eax, byte [eax]

        mov     esi, [esi+eax*4]

        inc     [buffer]

        dec     [length]

.report_found:

; 3. Validate: ignore transfers with unregistered report IDs

; and transfers which are too short for the corresponding report.

        test    esi, esi

        jz      .done

        mov     eax, [esi+report.size]

        add     eax, 7

        shr     eax, 3

        cmp     eax, [length]

        ja      .done

; 4. Pass everything to HID layer.

        parse_input

.done:

; 5. Query the next input.

        mov     ebx, [calldata]

        call    ask_for_input

.nothing:

        ret

.fail:

        mov     esi, transfer_error_msg

        call    SysMsgBoardStr

        jmp     .nothing

endp

; This function is called by the USB subsystem when a device is disconnected.

proc DeviceDisconnected

        push    ebx esi edi     ; save used registers to be stdcall

virtual at esp

                rd      3       ; saved registers

                dd      ?       ; return address

.device_data    dd      ?

end virtual

; 1. Say a message.

        mov     ebx, [.device_data]

        mov     esi, disconnectmsg

        stdcall SysMsgBoardStr

; 2. Ask HID layer to release all HID-related resources.

        hid_cleanup

; 3. Free the device data.

        xchg    eax, ebx

        call    Kfree

; 4. Return.

.nothing:

        pop     edi esi ebx     ; restore used registers to be stdcall

        ret     4       ; purge one dword argument to be stdcall

endp

include 'sort.inc'

include 'unclaimed.inc'

include 'mouse.inc'

include 'keyboard.inc'

; strings

my_driver       db      'usbhid',0

nomemory_msg    db      'K : no memory',13,10,0

invalid_config_descr_msg db 'K : invalid config descriptor',13,10,0

reportfail      db      'K : failed to read report descriptor',13,10,0

transfer_error_msg db   'K : USB transfer error, disabling HID device',13,10,0

disconnectmsg   db      'K : USB HID device disconnected',13,10,0

invalid_report_msg db   'K : report descriptor is invalid',13,10,0

delimiter_note  db      'K : note: alternate usage ignored',13,10,0

; Exported variable: kernel API version.

align 4

version dd      50005h

; Structure with callback functions.

usb_functions:

        dd      12

        dd      AddDevice

        dd      DeviceDisconnected

; for DEBUGF macro

include_debug_strings

; Workers data

workers_globals

; for uninitialized data

;section '.data' data readable writable align 16