kolibrios/kernel/trunk/bus/usb/protocol.inc

; Implementation of the USB protocol for device enumeration.
; Manage a USB device when it becomes ready for USB commands:
; configure, enumerate, load the corresponding driver(s),
; pass device information to the driver.

; =============================================================================
; ================================= Constants =================================
; =============================================================================
; USB standard request codes
USB_GET_STATUS        = 0
USB_CLEAR_FEATURE     = 1
USB_SET_FEATURE       = 3
USB_SET_ADDRESS       = 5
USB_GET_DESCRIPTOR    = 6
USB_SET_DESCRIPTOR    = 7
USB_GET_CONFIGURATION = 8
USB_SET_CONFIGURATION = 9
USB_GET_INTERFACE     = 10
USB_SET_INTERFACE     = 11
USB_SYNCH_FRAME       = 12

; USB standard descriptor types
USB_DEVICE_DESCR             = 1
USB_CONFIG_DESCR             = 2
USB_STRING_DESCR             = 3
USB_INTERFACE_DESCR          = 4
USB_ENDPOINT_DESCR           = 5
USB_DEVICE_QUALIFIER_DESCR   = 6
USB_OTHER_SPEED_CONFIG_DESCR = 7
USB_INTERFACE_POWER_DESCR    = 8

; Compile-time setting. If set, the code will dump all descriptors as they are
; read to the debug board.
USB_DUMP_DESCRIPTORS = 1

; According to the USB specification (9.2.6.3),
; any device must response to SET_ADDRESS in 50 ms, or 5 timer ticks.
; Of course, our world is far from ideal.
; I have seen devices that just NAK everything when being reset from working
; state, but start to work after second reset.
; Our strategy is as follows: give 2 seconds for the first attempt,
; this should be enough for normal devices and not too long to detect buggy ones.
; If the device continues NAKing, reset it and retry several times,
; doubling the interval: 2s -> 4s -> 8s -> 16s. Give up after that.
; Numbers are quite arbitrary.
TIMEOUT_SET_ADDRESS_INITIAL = 200
TIMEOUT_SET_ADDRESS_LAST    = 1600

; =============================================================================
; ================================ Structures =================================
; =============================================================================
; USB descriptors. See USB specification for detailed explanations.
; First two bytes of every descriptor have the same meaning.
struct usb_descr
bLength                 db      ?
; Size of this descriptor in bytes
bDescriptorType         db      ?
; One of USB_*_DESCR constants.
ends

; USB device descriptor
struct usb_device_descr usb_descr
bcdUSB                  dw      ?
; USB Specification Release number in BCD, e.g. 110h = USB 1.1
bDeviceClass            db      ?
; USB Device Class Code
bDeviceSubClass         db      ?
; USB Device Subclass Code
bDeviceProtocol         db      ?
; USB Device Protocol Code
bMaxPacketSize0         db      ?
; Maximum packet size for zero endpoint
idVendor                dw      ?
; Vendor ID
idProduct               dw      ?
; Product ID
bcdDevice               dw      ?
; Device release number in BCD
iManufacturer           db      ?
; Index of string descriptor describing manufacturer
iProduct                db      ?
; Index of string descriptor describing product
iSerialNumber           db      ?
; Index of string descriptor describing serial number
bNumConfigurations      db      ?
; Number of possible configurations
ends

; USB configuration descriptor
struct usb_config_descr usb_descr
wTotalLength            dw      ?
; Total length of data returned for this configuration
bNumInterfaces          db      ?
; Number of interfaces in this configuration
bConfigurationValue     db      ?
; Value for SET_CONFIGURATION control request
iConfiguration          db      ?
; Index of string descriptor describing this configuration
bmAttributes            db      ?
; Bit 6 is SelfPowered, bit 5 is RemoteWakeupSupported,
; bit 7 must be 1, other bits must be 0
bMaxPower               db      ?
; Maximum power consumption from the bus in 2mA units
ends

; USB interface descriptor
struct usb_interface_descr usb_descr
; The following two fields work in pair. Sometimes one interface can work
; in different modes; e.g. videostream from web-cameras requires different
; bandwidth depending on resolution/quality/compression settings.
; Each mode of each interface has its own descriptor with its own endpoints
; following; all descriptors for one interface have the same bInterfaceNumber,
; and different bAlternateSetting.
; By default, any interface operates in mode with bAlternateSetting = 0.
; Often this is the only mode. If there are another modes, the active mode
; is selected by SET_INTERFACE(bAlternateSetting) control request.
bInterfaceNumber        db      ?
bAlternateSetting       db      ?
bNumEndpoints           db      ?
; Number of endpoints used by this interface, excluding zero endpoint
bInterfaceClass         db      ?
; USB Interface Class Code
bInterfaceSubClass      db      ?
; USB Interface Subclass Code
bInterfaceProtocol      db      ?
; USB Interface Protocol Code
iInterface              db      ?
; Index of string descriptor describing this interface
ends

; USB endpoint descriptor
struct usb_endpoint_descr usb_descr
bEndpointAddress        db      ?
; Lower 4 bits form endpoint number,
; upper bit is 0 for OUT endpoints and 1 for IN endpoints,
; other bits must be zero
bmAttributes            db      ?
; Lower 2 bits form transfer type, one of *_PIPE,
; other bits must be zero for non-isochronous endpoints;
; refer to the USB specification for meaning in isochronous case
wMaxPacketSize          dw      ?
; Lower 11 bits form maximum packet size,
; next two bits specify the number of additional transactions per microframe
; for high-speed periodic endpoints, other bits must be zero.
bInterval               db      ?
; Interval for polling endpoint for data transfers.
; Isochronous and high-speed interrupt endpoints: poll every 2^(bInterval-1)
; (micro)frames
; Full/low-speed interrupt endpoints: poll every bInterval frames
; High-speed bulk/control OUT endpoints: maximum NAK rate
ends

; =============================================================================
; =================================== Code ====================================
; =============================================================================

; When a new device is ready to be configured, a controller-specific code
; calls usb_new_device.
; The sequence of further actions:
; * open pipe for the zero endpoint (usb_new_device);
;   maximum packet size is not known yet, but it must be at least 8 bytes,
;   so it is safe to send packets with <= 8 bytes
; * issue SET_ADDRESS control request (usb_new_device)
; * set the new device address in the pipe (usb_set_address_callback)
; * notify a controller-specific code that initialization of other ports
;   can be started (usb_set_address_callback)
; * issue GET_DESCRIPTOR control request for first 8 bytes of device descriptor
;   (usb_after_set_address)
; * first 8 bytes of device descriptor contain the true packet size for zero
;   endpoint, so set the true packet size (usb_get_descr8_callback)
; * first 8 bytes of a descriptor contain the full size of this descriptor,
;   issue GET_DESCRIPTOR control request for the full device descriptor
;   (usb_after_set_endpoint_size)
; * issue GET_DESCRIPTOR control request for first 8 bytes of configuration
;   descriptor (usb_get_descr_callback)
; * issue GET_DESCRIPTOR control request for full configuration descriptor
;   (usb_know_length_callback)
; * issue SET_CONFIGURATION control request (usb_set_config_callback)
; * parse configuration descriptor, load the corresponding driver(s),
;   pass the configuration descriptor to the driver and let the driver do
;   the further work (usb_got_config_callback)

; This function is called from controller-specific part
; when a new device is ready to be configured.
; in: ecx -> pseudo-pipe, part of usb_pipe
; in: esi -> usb_controller
; in: [esi+usb_controller.ResettingHub] is the pointer to usb_hub for device,
;     NULL if the device is connected to the root hub
; in: [esi+usb_controller.ResettingPort] is the port for the device, zero-based
; in: [esi+usb_controller.ResettingSpeed] is the speed of the device, one of
;     USB_SPEED_xx.
; out: eax = 0 <=> failed, the caller should disable the port.
proc usb_new_device
        push    ebx edi         ; save used registers to be stdcall
; 1. Check whether we're here because we were trying to reset
; already-registered device in hope to fix something serious.
; If so, skip allocation and go to 6.
        movzx   eax, [esi+usb_controller.ResettingPort]
        mov     edx, [esi+usb_controller.ResettingHub]
        test    edx, edx
        jz      .test_roothub
        mov     edx, [edx+usb_hub.ConnectedDevicesPtr]
        mov     ebx, [edx+eax*4]
        jmp     @f
.test_roothub:
        mov     ebx, [esi+usb_controller.DevicesByPort+eax*4]
@@:
        test    ebx, ebx
        jnz     .try_set_address
; 2. Allocate resources. Any device uses the following resources:
; - device address in the bus
; - memory for device data
; - pipe for zero endpoint
; If some allocation fails, we must undo our actions. Closing the pipe
; is a hard task, so we avoid it and open the pipe as the last resource.
; The order for other two allocations is quite arbitrary.
; 2a. Allocate a bus address.
        push    ecx
        call    usb_set_address_request
        pop     ecx
; 2b. If failed, just return zero.
        test    eax, eax
        jz      .nothing
; 2c. Allocate memory for device data.
; For now, we need sizeof.usb_device_data and extra 8 bytes for GET_DESCRIPTOR
; input and output, see usb_after_set_address. Later we will reallocate it
; to actual size needed for descriptors.
        movi    eax, sizeof.usb_device_data + 8
        push    ecx
        call    malloc
        pop     ecx
; 2d. If failed, free the bus address and return zero.
        test    eax, eax
        jz      .nomemory
; 2e. Open pipe for endpoint zero.
; For now, we do not know the actual maximum packet size;
; for full-speed devices it can be any of 8, 16, 32, 64 bytes,
; low-speed devices must have 8 bytes, high-speed devices must have 64 bytes.
; Thus, we must use some fake "maximum packet size" until the actual size
; will be known. However, the maximum packet size must be at least 8, and
; initial stages of the configuration process involves only packets of <= 8
; bytes, they will be transferred correctly as long as
; the fake "maximum packet size" is also at least 8.
; Thus, any number >= 8 is suitable for actual hardware.
; However, software emulation of EHCI in VirtualBox assumes that high-speed
; control transfers are those originating from pipes with max packet size = 64,
; even on early stages of the configuration process. This is incorrect,
; but we have no specific preferences, so let VirtualBox be happy and use 64
; as the fake "maximum packet size".
        push    eax
; We will need many zeroes.
; "push edi" is one byte, "push 0" is two bytes; save space, use edi.
        xor     edi, edi
        stdcall usb_open_pipe, ecx, edi, 64, edi, edi
; Put pointer to pipe into ebx. "xchg eax,reg" is one byte, mov is two bytes.
        xchg    eax, ebx
        pop     eax
; 2f. If failed, free the memory, the bus address and return zero.
        test    ebx, ebx
        jz      .freememory
; 3. Store pointer to device data in the pipe structure.
        mov     [ebx+usb_pipe.DeviceData], eax
; 4. Init device data, using usb_controller.Resetting* variables.
        mov     [eax+usb_device_data.Timer], edi
        mov     dword [eax+usb_device_data.DeviceDescriptor], TIMEOUT_SET_ADDRESS_INITIAL
        mov     [eax+usb_device_data.TTHub], edi
        mov     [eax+usb_device_data.TTPort], 0
        mov     [eax+usb_device_data.NumInterfaces], edi
        mov     [eax+usb_device_data.DeviceDescrSize], 0
        mov     dl, [esi+usb_controller.ResettingSpeed]
        mov     [eax+usb_device_data.Speed], dl
        mov     [eax+usb_device_data.NumPipes], 1
        push    ebx
        cmp     dl, USB_SPEED_HS
        jz      .nott
        mov     ebx, [esi+usb_controller.ResettingHub]
        test    ebx, ebx
        jz      .nott
        mov     cl, [esi+usb_controller.ResettingPort]
        mov     edx, [ebx+usb_hub.ConfigPipe]
        mov     edx, [edx+usb_pipe.DeviceData]
        cmp     [edx+usb_device_data.TTHub], 0
        jz      @f
        mov     cl, [edx+usb_device_data.TTPort]
        mov     ebx, [edx+usb_device_data.TTHub]
        jmp     .has_tt
@@:
        cmp     [edx+usb_device_data.Speed], USB_SPEED_HS
        jnz     .nott
.has_tt:
        mov     [eax+usb_device_data.TTHub], ebx
        mov     [eax+usb_device_data.TTPort], cl
.nott:
        pop     ebx
        mov     [eax+usb_device_data.ConfigDataSize], edi
        mov     [eax+usb_device_data.Interfaces], edi
        movzx   ecx, [esi+usb_controller.ResettingPort]
        mov     [eax+usb_device_data.Port], cl
        mov     edx, [esi+usb_controller.ResettingHub]
        mov     [eax+usb_device_data.Hub], edx
; 5. Store pointer to the config pipe in the hub data.
; Config pipe serves as device identifier.
; Root hubs use the array inside usb_controller structure,
; non-root hubs use the array immediately after usb_hub structure.
        test    edx, edx
        jz      .roothub
        mov     edx, [edx+usb_hub.ConnectedDevicesPtr]
        mov     [edx+ecx*4], ebx
        jmp     @f
.roothub:
        mov     [esi+usb_controller.DevicesByPort+ecx*4], ebx
@@:
        call    usb_reinit_pipe_list
; 6. Issue SET_ADDRESS control request, using buffer filled in step 2a.
; 6a. Configure timer to force reset after timeout.
; Note: we can't use self-destructing timer, because we need to be able to cancel it,
; and for self-destructing timer we could have race condition in cancelling/destructing.
;        DEBUGF 1,'K : pipe %x\n',ebx
.try_set_address:
        xor     edi, edi
        mov     edx, [ebx+usb_pipe.DeviceData]
        stdcall timer_hs, [edx+usb_device_data.DeviceDescriptor], 7FFFFFFFh, usb_abort_pipe, ebx
        test    eax, eax
        jz      .nothing
        mov     edx, [ebx+usb_pipe.DeviceData]
        mov     [edx+usb_device_data.Timer], eax
; 6b. If it succeeded, setup timer to configure wait timeout.
        lea     eax, [esi+usb_controller.SetAddressBuffer]
        stdcall usb_control_async, ebx, eax, edi, edi, usb_set_address_callback, edi, edi
; Use the return value from usb_control_async as our return value;
; if it is zero, then something has failed.
.nothing:
; 7. Return.
        pop     edi ebx         ; restore used registers to be stdcall
        ret
; Handlers of failures in steps 2b, 2d, 2f.
.freememory:
        call    free
        jmp     .freeaddr
.nomemory:
        dbgstr 'No memory for device data'
.freeaddr:
        mov     ecx, dword [esi+usb_controller.SetAddressBuffer+2]
        bts     [esi+usb_controller.ExistingAddresses], ecx
        xor     eax, eax
        jmp     .nothing
endp

; Helper procedure for usb_new_device.
; Allocates a new USB address and fills usb_controller.SetAddressBuffer
; with data for SET_ADDRESS(allocated_address) request.
; out: eax = 0 <=> failed
; Destroys edi.
proc usb_set_address_request
; There are 128 bits, one for each possible address.
; Note: only the USB thread works with usb_controller.ExistingAddresses,
; so there is no need for synchronization.
; We must find a bit set to 1 and clear it.
; 1. Find the first dword which has a nonzero bit = which is nonzero.
        mov     ecx, 128/32
        lea     edi, [esi+usb_controller.ExistingAddresses]
        xor     eax, eax
        repz scasd
; 2. If all dwords are zero, return an error.
        jz      .error
; 3. The dword at [edi-4] is nonzero. Find the lowest nonzero bit.
        bsf     eax, [edi-4]
; Now eax = bit number inside the dword at [edi-4].
; 4. Clear the bit.
        btr     [edi-4], eax
; 5. Generate the address by edi = memory address and eax = bit inside dword.
; Address = eax + 8 * (edi-4 - (esi+usb_controller.ExistingAddress)).
        sub     edi, esi
        lea     edi, [eax+(edi-4-usb_controller.ExistingAddresses)*8]
; 6. Store the allocated address in SetAddressBuffer and fill remaining fields.
; Note that usb_controller is zeroed at allocation, so only command byte needs
; to be filled.
        mov     byte [esi+usb_controller.SetAddressBuffer+1], USB_SET_ADDRESS
        mov     dword [esi+usb_controller.SetAddressBuffer+2], edi
; 7. Return non-zero value in eax.
        inc     eax
.nothing:
        ret
.error:
        dbgstr 'cannot allocate USB address'
        xor     eax, eax
        jmp     .nothing
endp

; This procedure is called by USB stack when SET_ADDRESS request initiated by
; usb_new_device is completed, either successfully or unsuccessfully.
; Note that USB stack uses esi = pointer to usb_controller.
proc usb_set_address_callback stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
        push    ebx     ; save ebx to be stdcall
        mov     ebx, [pipe]
; 1. In any case, cancel the timer.
        mov     eax, [ebx+usb_pipe.DeviceData]
        stdcall cancel_timer_hs, [eax+usb_device_data.Timer]
        mov     eax, [ebx+usb_pipe.DeviceData]
        mov     [eax+usb_device_data.Timer], 0
; Load data to registers for further references.
        mov     ecx, dword [esi+usb_controller.SetAddressBuffer+2]
        mov     eax, [esi+usb_controller.HardwareFunc]
; 2. Check whether the device has accepted new address. If so, proceed to 3.
; Otherwise, go to 4 if killed by usb_set_address_timeout or to 5 otherwise.
        cmp     [status], USB_STATUS_CANCELLED
        jz      .timeout
        cmp     [status], 0
        jnz     .error
; 3. Address accepted.
; 3a. The controller-specific structure for the control pipe still uses
; zero address. Call the controller-specific function to change it to
; the actual address.
; Note that the hardware could cache the controller-specific structure,
; so setting the address could take some time until the cache is evicted.
; Thus, the call is asynchronous; meet us in usb_after_set_address when it will
; be safe to continue.
;        dbgstr 'address set in device'
        call    [eax+usb_hardware_func.SetDeviceAddress]
; 3b. If the port is in non-root hub, clear 'reset in progress' flag.
; In any case, proceed to 6.
        mov     eax, [esi+usb_controller.ResettingHub]
        test    eax, eax
        jz      .return
        and     [eax+usb_hub.Actions], not HUB_RESET_IN_PROGRESS
.return:
; 6. Address configuration done, we can proceed with other ports.
; Call the worker function for that.
        call    usb_test_pending_port
.wakeup:
        push    esi edi
        call    usb_wakeup
        pop     edi esi
.nothing:
        pop     ebx     ; restore ebx to be stdcall
        ret
.timeout:
; 4. Device continues to NAK the request. Reset it and retry.
        mov     edx, [ebx+usb_pipe.DeviceData]
        mov     ecx, [edx+usb_device_data.DeviceDescriptor]
        add     ecx, ecx
        cmp     ecx, TIMEOUT_SET_ADDRESS_LAST
        ja      .error
        mov     [edx+usb_device_data.DeviceDescriptor], ecx
        dbgstr 'Timeout in USB device initialization, trying to reset...'
        cmp     [esi+usb_controller.ResettingHub], 0
        jz      .reset_roothub
        push    esi
        mov     esi, [esi+usb_controller.ResettingHub]
        call    usb_hub_initiate_reset
        pop     esi
        jmp     .nothing
.reset_roothub:
        movzx   ecx, [esi+usb_controller.ResettingPort]
        call    [eax+usb_hardware_func.InitiateReset]
        jmp     .wakeup
.error:
; 5. Device error: device not responding, disconnect etc.
        DEBUGF 1,'K : error %d in SET_ADDRESS, USB device disabled\n',[status]
; 5a. The address has not been accepted. Mark it as free.
        bts     dword [esi+usb_controller.ExistingAddresses], ecx
; 5b. Disable the port with bad device.
; For the root hub, call the controller-specific function and go to 6.
; For non-root hubs, let the hub code do its work and return (the request
; could take some time, the hub code is responsible for proceeding).
        cmp     [esi+usb_controller.ResettingHub], 0
        jz      .roothub
        mov     eax, [esi+usb_controller.ResettingHub]
        call    usb_hub_disable_resetting_port
        jmp     .nothing
.roothub:
        movzx   ecx, [esi+usb_controller.ResettingPort]
        call    [eax+usb_hardware_func.PortDisable]
        jmp     .return
endp

; This procedure is called from usb_subscription_done when the hardware cache
; is cleared after request from usb_set_address_callback.
; in: ebx -> usb_pipe
proc usb_after_set_address
;        dbgstr 'address set for controller'
; Issue control transfer GET_DESCRIPTOR(DEVICE_DESCR) for first 8 bytes.
; Remember, we still do not know the actual packet size;
; 8-bytes-request is safe.
; usb_new_device has allocated 8 extra bytes besides sizeof.usb_device_data;
; use them for both input and output.
        mov     eax, [ebx+usb_pipe.DeviceData]
        add     eax, usb_device_data.DeviceDescriptor
        mov     dword [eax], \
                80h + \         ; device-to-host, standard, device-wide
                (USB_GET_DESCRIPTOR shl 8) + \  ; request
                (0 shl 16) + \  ; descriptor index: there is only one
                (USB_DEVICE_DESCR shl 24)       ; descriptor type
        mov     dword [eax+4], 8 shl 16         ; data length
        stdcall usb_control_async, ebx, eax, eax, 8, usb_get_descr8_callback, eax, 0
        ret
endp

; This procedure is called by USB stack when GET_DESCRIPTOR(DEVICE_DESCR)
; request initiated by usb_after_set_address is completed, either successfully
; or unsuccessfully.
; Note that USB stack uses esi = pointer to usb_controller.
proc usb_get_descr8_callback stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
;       mov     eax, [buffer]
;       DEBUGF 1,'K : descr8: l=%x; %x %x %x %x %x %x %x %x\n',[length],\
;               [eax]:2,[eax+1]:2,[eax+2]:2,[eax+3]:2,[eax+4]:2,[eax+5]:2,[eax+6]:2,[eax+7]:2
        push    edi ebx         ; save used registers to be stdcall
        mov     ebx, [pipe]
; 1. Check whether the operation was successful.
; If not, say something to the debug board and stop the initialization.
        cmp     [status], 0
        jnz     .error
; 2. Length of descriptor must be at least sizeof.usb_device_descr bytes.
; If not, say something to the debug board and stop the initialization.
        mov     eax, [ebx+usb_pipe.DeviceData]
        cmp     [eax+usb_device_data.DeviceDescriptor+usb_device_descr.bLength], sizeof.usb_device_descr
        jb      .error
; 3. Now first 8 bytes of device descriptor are known;
; set DeviceDescrSize accordingly.
        mov     [eax+usb_device_data.DeviceDescrSize], 8
; 4. The controller-specific structure for the control pipe still uses
; the fake "maximum packet size". Call the controller-specific function to
; change it to the actual packet size from the device.
; Note that the hardware could cache the controller-specific structure,
; so changing it could take some time until the cache is evicted.
; Thus, the call is asynchronous; meet us in usb_after_set_endpoint_size
; when it will be safe to continue.
        movzx   ecx, [eax+usb_device_data.DeviceDescriptor+usb_device_descr.bMaxPacketSize0]
        mov     eax, [esi+usb_controller.HardwareFunc]
        call    [eax+usb_hardware_func.SetEndpointPacketSize]
.nothing:
; 5. Return.
        pop     ebx edi         ; restore used registers to be stdcall
        ret
.error:
        dbgstr 'error with USB device descriptor'
        jmp     .nothing
endp

; This procedure is called from usb_subscription_done when the hardware cache
; is cleared after request from usb_get_descr8_callback.
; in: ebx -> usb_pipe
proc usb_after_set_endpoint_size
; 1. Reallocate memory for device data:
; add memory for now-known size of device descriptor and extra 8 bytes
; for further actions.
; 1a. Allocate new memory.
        mov     eax, [ebx+usb_pipe.DeviceData]
        movzx   eax, [eax+usb_device_data.DeviceDescriptor+usb_device_descr.bLength]
; save length for step 2
        push    eax
        add     eax, sizeof.usb_device_data + 8
        call    malloc
; 1b. If failed, say something to the debug board and stop the initialization.
        test    eax, eax
        jz      .nomemory
; 1c. Copy data from old memory to new memory and switch the pointer in usb_pipe.
        push    eax
        push    esi edi
        mov     esi, [ebx+usb_pipe.DeviceData]
        mov     [ebx+usb_pipe.DeviceData], eax
        mov     edi, eax
        mov     eax, esi
        mov     ecx, sizeof.usb_device_data / 4
        rep movsd
        pop     edi esi
        call    usb_reinit_pipe_list
; 1d. Free the old memory.
        call    free
        pop     eax
; 2. Issue control transfer GET_DESCRIPTOR(DEVICE) for full descriptor.
; restore length saved in step 1a
        pop     edx
        add     eax, sizeof.usb_device_data
        mov     dword [eax], \
                80h + \         ; device-to-host, standard, device-wide
                (USB_GET_DESCRIPTOR shl 8) + \  ; request
                (0 shl 16) + \  ; descriptor index: there is only one
                (USB_DEVICE_DESCR shl 24)       ; descriptor type
        and     dword [eax+4], 0
        mov     [eax+6], dl     ; data length
        stdcall usb_control_async, ebx, eax, eax, edx, usb_get_descr_callback, eax, 0
; 3. Return.
        ret
.nomemory:
        dbgstr 'No memory for device data'
        ret
endp

; This procedure is called by USB stack when GET_DESCRIPTOR(DEVICE)
; request initiated by usb_after_set_endpoint_size is completed,
; either successfully or unsuccessfully.
proc usb_get_descr_callback stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
; Note: the prolog is the same as in usb_get_descr8_callback.
        push    edi ebx         ; save used registers to be stdcall
; 1. Check whether the operation was successful.
; If not, say something to the debug board and stop the initialization.
        cmp     [status], 0
        jnz     usb_get_descr8_callback.error
; The full descriptor is known, dump it if specified by compile-time option.
if USB_DUMP_DESCRIPTORS
        mov     eax, [buffer]
        mov     ecx, [length]
        sub     ecx, 8
        jbe     .skipdebug
        DEBUGF 1,'K : device descriptor:'
@@:
        DEBUGF 1,' %x',[eax]:2
        inc     eax
        dec     ecx
        jnz     @b
        DEBUGF 1,'\n'
.skipdebug:
end if
; 2. Check that bLength is the same as was in the previous request.
; If not, say something to the debug board and stop the initialization.
; It is important, because usb_after_set_endpoint_size has allocated memory
; according to the old bLength. Note that [length] for control transfers
; includes 8 bytes of setup packet, so data length = [length] - 8.
        mov     eax, [buffer]
        movzx   ecx, [eax+usb_device_descr.bLength]
        add     ecx, 8
        cmp     [length], ecx
        jnz     usb_get_descr8_callback.error
; Amuse the user if she is watching the debug board.
        mov     cl, [eax+usb_device_descr.bNumConfigurations]
        DEBUGF 1,'K : found USB device with ID %x:%x, %d configuration(s)\n',\
                [eax+usb_device_descr.idVendor]:4,\
                [eax+usb_device_descr.idProduct]:4,\
                cl
; 3. If there are no configurations, stop the initialization.
        cmp     [eax+usb_device_descr.bNumConfigurations], 0
        jz      .nothing
; 4. Copy length of device descriptor to device data structure.
        movzx   edx, [eax+usb_device_descr.bLength]
        mov     [eax+usb_device_data.DeviceDescrSize-usb_device_data.DeviceDescriptor], dl
; 5. Issue control transfer GET_DESCRIPTOR(CONFIGURATION). We do not know
; the full length of that descriptor, so start with first 8 bytes, they contain
; the full length.
; usb_after_set_endpoint_size has allocated 8 extra bytes after the
; device descriptor, use them for both input and output.
        add     eax, edx
        mov     dword [eax], \
                80h + \         ; device-to-host, standard, device-wide
                (USB_GET_DESCRIPTOR shl 8) + \  ; request
                (0 shl 16) + \  ; descriptor index: there is only one
                (USB_CONFIG_DESCR shl 24)       ; descriptor type
        mov     dword [eax+4], 8 shl 16         ; data length
        stdcall usb_control_async, [pipe], eax, eax, 8, usb_know_length_callback, eax, 0
.nothing:
; 6. Return.
        pop     ebx edi         ; restore used registers to be stdcall
        ret
endp

; This procedure is called by USB stack when GET_DESCRIPTOR(CONFIGURATION)
; request initiated by usb_get_descr_callback is completed,
; either successfully or unsuccessfully.
proc usb_know_length_callback stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
        push    ebx             ; save used registers to be stdcall
; 1. Check whether the operation was successful.
; If not, say something to the debug board and stop the initialization.
        cmp     [status], 0
        jnz     .error
; 2. Get the total length of data associated with config descriptor and store
; it in device data structure. The total length must be at least
; sizeof.usb_config_descr bytes; if not, say something to the debug board and
; stop the initialization.
        mov     eax, [buffer]
        mov     edx, [pipe]
        movzx   ecx, [eax+usb_config_descr.wTotalLength]
        mov     eax, [edx+usb_pipe.DeviceData]
        cmp     ecx, sizeof.usb_config_descr
        jb      .error
        mov     [eax+usb_device_data.ConfigDataSize], ecx
; 3. Reallocate memory for device data:
; include usb_device_data structure, device descriptor,
; config descriptor with all associated data, and extra bytes
; sufficient for 8 bytes control packet and for one usb_interface_data struc.
; Align extra bytes to dword boundary.
if sizeof.usb_interface_data > 8
.extra_size = sizeof.usb_interface_data
else
.extra_size = 8
end if
; 3a. Allocate new memory.
        movzx   edx, [eax+usb_device_data.DeviceDescrSize]
        lea     eax, [ecx+edx+sizeof.usb_device_data+.extra_size+3]
        and     eax, not 3
        push    eax
        call    malloc
        pop     edx
; 3b. If failed, say something to the debug board and stop the initialization.
        test    eax, eax
        jz      .nomemory
; 3c. Copy data from old memory to new memory and switch the pointer in usb_pipe.
        push    eax
        mov     ebx, [pipe]
        push    esi edi
        mov     esi, [ebx+usb_pipe.DeviceData]
        mov     edi, eax
        mov     [ebx+usb_pipe.DeviceData], eax
        mov     eax, esi
        movzx   ecx, [esi+usb_device_data.DeviceDescrSize]
        sub     edx, .extra_size
        mov     [esi+usb_device_data.Interfaces], edx
        add     ecx, sizeof.usb_device_data + 8
        mov     edx, ecx
        shr     ecx, 2
        and     edx, 3
        rep movsd
        mov     ecx, edx
        rep movsb
        pop     edi esi
        call    usb_reinit_pipe_list
; 3d. Free old memory.
        call    free
        pop     eax
; 4. Issue control transfer GET_DESCRIPTOR(DEVICE) for full descriptor.
        movzx   ecx, [eax+usb_device_data.DeviceDescrSize]
        mov     edx, [eax+usb_device_data.ConfigDataSize]
        lea     eax, [eax+ecx+sizeof.usb_device_data]
        mov     dword [eax], \
                80h + \         ; device-to-host, standard, device-wide
                (USB_GET_DESCRIPTOR shl 8) + \  ; request
                (0 shl 16) + \  ; descriptor index: there is only one
                (USB_CONFIG_DESCR shl 24)       ; descriptor type
        and     dword [eax+4], 0
        mov     word [eax+6], dx        ; data length
        stdcall usb_control_async, [pipe], eax, eax, edx, usb_set_config_callback, eax, 0
.nothing:
; 5. Return.
        pop     ebx             ; restore used registers to be stdcall
        ret
.error:
        dbgstr 'error with USB configuration descriptor'
        jmp     .nothing
.nomemory:
        dbgstr 'No memory for device data'
        jmp     .nothing
endp

; This procedure is called by USB stack when GET_DESCRIPTOR(CONFIGURATION)
; request initiated by usb_know_length_callback is completed,
; either successfully or unsuccessfully.
proc usb_set_config_callback stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
; Note that the prolog is the same as in usb_know_length_callback.
        push    ebx             ; save used registers to be stdcall
; 1. Check whether the operation was successful.
; If not, say something to the debug board and stop the initialization.
        xor     ecx, ecx
        mov     ebx, [pipe]
        cmp     [status], ecx
        jnz     usb_know_length_callback.error
; The full descriptor is known, dump it if specified by compile-time option.
if USB_DUMP_DESCRIPTORS
        mov     eax, [buffer]
        mov     ecx, [length]
        sub     ecx, 8
        jbe     .skip_debug
        DEBUGF 1,'K : config descriptor:'
@@:
        DEBUGF 1,' %x',[eax]:2
        inc     eax
        dec     ecx
        jnz     @b
        DEBUGF 1,'\n'
.skip_debug:
        xor     ecx, ecx
end if
; 2. Issue control transfer SET_CONFIGURATION to activate this configuration.
; Usually this is the only configuration.
; Use extra bytes allocated by usb_know_length_callback;
; offset from device data start is stored in Interfaces.
        mov     eax, [ebx+usb_pipe.DeviceData]
        mov     edx, [buffer]
        add     eax, [eax+usb_device_data.Interfaces]
        mov     dl, [edx+usb_config_descr.bConfigurationValue]
        mov     dword [eax], USB_SET_CONFIGURATION shl 8
        mov     dword [eax+4], ecx
        mov     byte [eax+2], dl
        stdcall usb_control_async, [pipe], eax, ecx, ecx, usb_got_config_callback, [buffer], ecx
        pop     ebx             ; restore used registers to be stdcall
        ret
endp

; This procedure is called by USB stack when SET_CONFIGURATION
; request initiated by usb_set_config_callback is completed,
; either successfully or unsuccessfully.
; If successfully, the device is configured and ready to work,
; pass the device to the corresponding driver(s).
proc usb_got_config_callback stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
locals
InterfacesData  dd      ?
NumInterfaces   dd      ?
driver          dd      ?
endl
; 1. If there was an error, say something to the debug board and stop the
; initialization.
        cmp     [status], 0
        jz      @f
        dbgstr 'USB error in SET_CONFIGURATION'
        ret
@@:
        push    ebx edi         ; save used registers to be stdcall
; 2. Sanity checks: the total length must be the same as before (because we
; have allocated memory assuming the old value), length of config descriptor
; must be at least sizeof.usb_config_descr (we use fields from it),
; there must be at least one interface.
        mov     ebx, [pipe]
        mov     ebx, [ebx+usb_pipe.DeviceData]
        mov     eax, [calldata]
        mov     edx, [ebx+usb_device_data.ConfigDataSize]
        cmp     [eax+usb_config_descr.wTotalLength], dx
        jnz     .invalid
        cmp     [eax+usb_config_descr.bLength], 9
        jb      .invalid
        movzx   edx, [eax+usb_config_descr.bNumInterfaces]
        test    edx, edx
        jnz     @f
.invalid:
        dbgstr 'error: invalid configuration descriptor'
        jmp     .nothing
@@:
; 3. Store the number of interfaces in device data structure.
        mov     [ebx+usb_device_data.NumInterfaces], edx
; 4. If there is only one interface (which happens quite often),
; the memory allocated in usb_know_length_callback is sufficient.
; Otherwise (which also happens quite often), reallocate device data.
; 4a. Check whether there is only one interface. If so, skip this step.
        cmp     edx, 1
        jz      .has_memory
; 4b. Allocate new memory.
        mov     eax, [ebx+usb_device_data.Interfaces]
        lea     eax, [eax+edx*sizeof.usb_interface_data]
        call    malloc
; 4c. If failed, say something to the debug board and
; stop the initialization.
        test    eax, eax
        jnz     @f
        dbgstr 'No memory for device data'
        jmp     .nothing
@@:
; 4d. Copy data from old memory to new memory and switch the pointer in usb_pipe.
        push    eax
        push    esi
        mov     ebx, [pipe]
        mov     edi, eax
        mov     esi, [ebx+usb_pipe.DeviceData]
        mov     [ebx+usb_pipe.DeviceData], eax
        mov     eax, esi
        mov     ecx, [esi+usb_device_data.Interfaces]
        shr     ecx, 2
        rep movsd
        pop     esi
        call    usb_reinit_pipe_list
; 4e. Free old memory.
        call    free
        pop     ebx
.has_memory:
; 5. Initialize interfaces table: zero all contents.
        mov     edi, [ebx+usb_device_data.Interfaces]
        add     edi, ebx
        mov     [InterfacesData], edi
        mov     ecx, [ebx+usb_device_data.NumInterfaces]
if sizeof.usb_interface_data <> 8
You have changed sizeof.usb_interface_data? Modify this place too.
end if
        add     ecx, ecx
        xor     eax, eax
        rep stosd
; No interfaces are found yet.
        mov     [NumInterfaces], eax
; 6. Get the pointer to config descriptor data.
; Note: if there was reallocation, [buffer] is not valid anymore,
; so calculate value based on usb_device_data.
        movzx   eax, [ebx+usb_device_data.DeviceDescrSize]
        lea     eax, [eax+ebx+sizeof.usb_device_data]
        mov     [calldata], eax
        mov     ecx, [ebx+usb_device_data.ConfigDataSize]
; 7. Loop over all descriptors,
; scan for interface descriptors with bAlternateSetting = 0,
; load the corresponding driver, call its AddDevice function.
.descriptor_loop:
; While in loop: eax points to the current descriptor,
; ecx = number of bytes left, the iteration starts only if ecx is nonzero,
; edx = size of the current descriptor.
; 7a. The first byte is always accessible; it contains the length of
; the current descriptor. Validate that the length is at least 2 bytes,
; and the entire descriptor is readable (the length is at most number of
; bytes left).
        movzx   edx, [eax+usb_descr.bLength]
        cmp     edx, sizeof.usb_descr
        jb      .invalid
        cmp     ecx, edx
        jb      .invalid
; 7b. Check descriptor type. Ignore all non-INTERFACE descriptor.
        cmp     byte [eax+usb_descr.bDescriptorType], USB_INTERFACE_DESCR
        jz      .interface
.next_descriptor:
; 7c. Advance pointer, decrease length left, if there is still something left,
; continue the loop.
        add     eax, edx
        sub     ecx, edx
        jnz     .descriptor_loop
.done:
.nothing:
        pop     edi ebx         ; restore used registers to be stdcall
        ret
.interface:
; 7d. Validate the descriptor length.
        cmp     edx, sizeof.usb_interface_descr
        jb      .next_descriptor
; 7e. If bAlternateSetting is nonzero, this descriptor actually describes
; another mode of already known interface and belongs to the already loaded
; driver; amuse the user and continue to 7c.
        cmp     byte [eax+usb_interface_descr.bAlternateSetting], 0
        jz      @f
        DEBUGF 1,'K : note: alternate setting with %x/%x/%x\n',\
                [eax+usb_interface_descr.bInterfaceClass]:2,\
                [eax+usb_interface_descr.bInterfaceSubClass]:2,\
                [eax+usb_interface_descr.bInterfaceProtocol]:2
        jmp     .next_descriptor
@@:
; 7f. Check that the new interface does not overflow allocated table.
        mov     edx, [NumInterfaces]
        inc     edx
        cmp     edx, [ebx+usb_device_data.NumInterfaces]
        ja      .invalid
; 7g. We have found a new interface. Advance bookkeeping vars.
        mov     [NumInterfaces], edx
        add     [InterfacesData], sizeof.usb_interface_data
; 7h. Save length left and pointer to the current interface descriptor.
        push    ecx eax
; Amuse the user if she is watching the debug board.
        DEBUGF 1,'K : USB interface class/subclass/protocol = %x/%x/%x\n',\
                [eax+usb_interface_descr.bInterfaceClass]:2,\
                [eax+usb_interface_descr.bInterfaceSubClass]:2,\
                [eax+usb_interface_descr.bInterfaceProtocol]:2
; 7i. Select the correct driver based on interface class.
; For hubs, go to 7j. Otherwise, go to 7k.
; Note: this should be rewritten as table-based lookup when more drivers will
; be available.
        cmp     byte [eax+usb_interface_descr.bInterfaceClass], 9
        jz      .found_hub
        mov     edx, usb_hid_name
        cmp     byte [eax+usb_interface_descr.bInterfaceClass], 3
        jz      .load_driver
        mov     edx, usb_print_name
        cmp     byte [eax+usb_interface_descr.bInterfaceClass], 7
        jz      .load_driver
        mov     edx, usb_stor_name
        cmp     byte [eax+usb_interface_descr.bInterfaceClass], 8
        jz      .load_driver
        mov     edx, usb_other_name
        jmp     .load_driver
.found_hub:
; 7j. Hubs are a part of USB stack, thus, integrated into the kernel.
; Use the pointer to hub callbacks and go to 7m.
        mov     eax, usb_hub_pseudosrv - USBSRV.usb_func
        jmp     .driver_loaded
.load_driver:
; 7k. Load the corresponding driver.
        push    ebx esi edi
        stdcall get_service, edx
        pop     edi esi ebx
; 7l. If failed, say something to the debug board and go to 7p.
        test    eax, eax
        jnz     .driver_loaded
        dbgstr 'failed to load class driver'
        jmp     .next_descriptor2
.driver_loaded:
; 7m. Call AddDevice function of the driver.
; Note that top of stack contains a pointer to the current interface,
; saved by step 7h.
        mov     [driver], eax
        mov     eax, [eax+USBSRV.usb_func]
        pop     edx
        push    edx
; Note: usb_hub_init assumes that edx points to usb_interface_descr,
; ecx = length rest; if you change the code, modify usb_hub_init also.
        stdcall [eax+USBFUNC.add_device], [pipe], [calldata], edx
; 7n. If failed, say something to the debug board and go to 7p.
        test    eax, eax
        jnz     .store_data
        dbgstr 'USB device initialization failed'
        jmp     .next_descriptor2
.store_data:
; 7o. Store the returned value and the driver handle to InterfacesData.
; Note that step 7g has already advanced InterfacesData.
        mov     edx, [InterfacesData]
        mov     [edx+usb_interface_data.DriverData-sizeof.usb_interface_data], eax
        mov     eax, [driver]
        mov     [edx+usb_interface_data.DriverFunc-sizeof.usb_interface_data], eax
.next_descriptor2:
; 7p. Restore registers saved in step 7h, get the descriptor length and
; continue to 7c.
        pop     eax ecx
        movzx   edx, byte [eax+usb_descr.bLength]
        jmp     .next_descriptor
endp

; Driver names, see step 7i of usb_got_config_callback.
iglobal
usb_hid_name    db      'usbhid',0
usb_stor_name   db      'usbstor',0
usb_print_name  db      'usbprint',0
usb_other_name  db      'usbother',0
endg