; 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