WebSVN – Kolibri OS – Diff – /kernel/branches/Kolibri-acpi/bus/usb/hub.inc


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;                                                              ;;
;; Copyright (C) KolibriOS team 2013-2015. All rights reserved. ;;
;; Distributed under terms of the GNU General Public License    ;;
;;                                                              ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
$Revision: 5363 $
 
 
; Support for USB (non-root) hubs:
; powering up/resetting/disabling ports,
; watching for adding/removing devices.
 
; =============================================================================
; ================================= Constants =================================
; =============================================================================
; Hub constants
; USB hub descriptor type
USB_HUB_DESCRIPTOR = 29h
 
; Features for CLEAR_FEATURE commands to the hub.
C_HUB_LOCAL_POWER   = 0
C_HUB_OVER_CURRENT  = 1
 
; Bits in result of GET_STATUS command for a port.
; Also suitable for CLEAR_FEATURE/SET_FEATURE commands, where applicable,
; except TEST/INDICATOR.
PORT_CONNECTION     = 0
PORT_ENABLE         = 1
PORT_SUSPEND        = 2
PORT_OVER_CURRENT   = 3
PORT_RESET          = 4
PORT_POWER          = 8
PORT_LOW_SPEED      = 9
PORT_HIGH_SPEED     = 10
PORT_TEST_BIT       = 11
PORT_INDICATOR_BIT  = 12
C_PORT_CONNECTION   = 16
C_PORT_ENABLE       = 17
C_PORT_SUSPEND      = 18
C_PORT_OVER_CURRENT = 19
C_PORT_RESET        = 20
PORT_TEST_FEATURE   = 21
PORT_INDICATOR_FEATURE = 22
 
; Internal constants
; Bits in usb_hub.Actions
HUB_WAIT_POWERED      = 1
; ports were powered, wait until power is stable
HUB_WAIT_CONNECT      = 2
; some device was connected, wait initial debounce interval
HUB_RESET_IN_PROGRESS = 4
; reset in progress, so buffer for config requests is owned
; by reset process; this includes all stages from initial disconnect test
; to end of setting address (fail on any stage should lead to disabling port,
; which requires a config request)
HUB_RESET_WAITING     = 8
; the port is ready for reset, but another device somewhere on the bus
; is resetting. Implies HUB_RESET_IN_PROGRESS
HUB_RESET_SIGNAL      = 10h
; reset signalling is active for some port in the hub
; Implies HUB_RESET_IN_PROGRESS
HUB_RESET_RECOVERY    = 20h
; reset recovery is active for some port in the hub
; Implies HUB_RESET_IN_PROGRESS
 
; Well, I think that those 5 flags WAIT_CONNECT and RESET_* require additional
; comments. So that is the overview of what happens with a new device assuming
; no errors.
; * device is connected;
; * hub notifies us about connect event; after some processing
;   usb_hub_port_change finally processes that event, setting the flag
;   HUB_WAIT_CONNECT and storing time when the device was connected;
; * 100 ms delay;
; * usb_hub_process_deferred clears HUB_WAIT_CONNECT,
;   sets HUB_RESET_IN_PROGRESS, stores the port index in ConfigBuffer and asks
;   the hub whether there was a disconnect event for that port during those
;   100 ms (on the hardware level notifications are obtained using polling
;   with some intervals, so it is possible that the corresponding notification
;   has not arrived yet);
; * usb_hub_connect_port_status checks that there was no disconnect event
;   and sets HUB_RESET_WAITING flag (HUB_RESET_IN_PROGRESS is still set,
;   ConfigBuffer still contains the port index);
; * usb_hub_process_deferred checks whether there is another device currently
;   resetting. If so, it waits until reset is done
;   (with HUB_RESET_WAITING and HUB_RESET_IN_PROGRESS bits set);
; * usb_hub_process_deferred clears HUB_RESET_WAITING, sets HUB_RESET_SIGNAL
;   and initiates reset signalling on the port;
; * usb_hub_process_deferred checks the status every tick;
;   when reset signalling is stopped by the hub, usb_hub_resetting_port_status
;   callback clears HUB_RESET_SIGNAL and sets HUB_RESET_RECOVERY;
; * 10 ms (at least) delay;
; * usb_hub_process_deferred clears HUB_RESET_RECOVERY and notifies other code
;   that the new device is ready to be configured;
; * when it is possible to reset another device, the protocol layer
;   clears HUB_RESET_IN_PROGRESS bit.
 
; =============================================================================
; ================================ Structures =================================
; =============================================================================
; This structure contains all used data for one hub.
struct usb_hub
; All configured hubs are organized in the global usb_hub_list.
; Two following fields give next/prev items in that list.
; While the hub is unconfigured, they point to usb_hub itself.
Next                    dd      ?
Prev                    dd      ?
Controller              dd      ?
; Pointer to usb_controller for the bus.
;
; Handles of two pipes: configuration control pipe for zero endpoint opened by
; the common code and status interrupt pipe opened by us.
ConfigPipe              dd      ?
StatusPipe              dd      ?
NumPorts                dd      ?
; Number of downstream ports; from 1 to 255.
MaxPacketSize           dd      ?
; Maximum packet size for interrupt endpoint.
; Usually equals ceil((1+NumPorts)/8), but some hubs give additional bytes.
Actions                 dd      ?
; Bitfield with HUB_* constants.
PoweredOnTime           dd      ?
; Time (in ticks) when all downstream ports were powered up.
ResetTime               dd      ?
; Time (in ticks) when the current port was reset;
; when a port is resetting, contains the last tick of status check;
; when reset recovery for a port is active, contains the time when
; reset was completed.
;
; There are two possible reasons for configuration requests:
; synchronous, when certain time is passed after something,
; and asynchronous, when the hub is notifying about some change and
; config request needs to be issued in order to query details.
; Use two different buffers to avoid unnecessary dependencies.
ConfigBuffer            rb      8
; Buffer for configuration requests for synchronous events.
ChangeConfigBuffer      rb      8
; Buffer for configuration requests for status changes.
AccStatusChange         db      ?
; Accumulated status change. See 11.12.3 of USB2 spec or comments in code.
HubCharacteristics      dw      ?
; Copy of usb_hub_descr.wHubCharacteristics.
PowerOnInterval         db      ?
; Copy of usb_hub_descr.bPwrOn2PwrGood.
;
; Two following fields are written at once by GET_STATUS request
; and must remain in this order.
StatusData              dw      ?
; Bitfield with 1 shl PORT_* indicating status of the current port.
StatusChange            dw      ?
; Bitfield with 1 shl PORT_* indicating change in status of the current port.
; Two following fields are written at once by GET_STATUS request
; and must remain in this order.
; The meaning is the same as of StatusData/StatusChange; two following fields
; are used by the synchronous requests to avoid unnecessary interactions with
; the asynchronous handler.
ResetStatusData         dw      ?
ResetStatusChange       dw      ?
StatusChangePtr         dd      ?
; Pointer to StatusChangeBuf.
ConnectedDevicesPtr     dd      ?
; Pointer to ConnectedDevices.
ConnectedTimePtr        dd      ?
; Pointer to ConnectedTime.
;
; Variable-length parts:
; DeviceRemovable rb (NumPorts+8)/8
;  Bit i+1 = device at port i (zero-based) is non-removable.
; StatusChangeBuf rb (NumPorts+8)/8
;  Buffer for status interrupt pipe. Bit 0 = hub status change,
;  other bits = status change of the corresponding ports.
; ConnectedDevices rd NumPorts
;  Pointers to config pipes for connected devices or zero if no device connected.
; ConnectedTime rd NumPorts
;  For initial debounce interval:
;   time (in ticks) when a device was connected at that port.
;  Normally: -1
ends
 
; Hub descriptor.
struct usb_hub_descr usb_descr
bNbrPorts               db      ?
; Number of downstream ports.
wHubCharacteristics     dw      ?
; Bit 0: 0 = all ports are powered at once, 1 = individual port power switching
; Bit 1: reserved, must be zero
; Bit 2: 1 = the hub is part of a compound device
; Bits 3-4: 00 = global overcurrent protection,
;           01 = individual port overcurrent protection,
;           1x = no overcurrent protection
; Bits 5-6: Transaction Translator Think Time, 8*(value+1) full-speed bit times
; Bit 7: 1 = port indicators supported
; Other bits are reserved.
bPwrOn2PwrGood          db      ?
; Time in 2ms intervals between powering up a port and a port becoming ready.
bHubContrCurrent        db      ?
; Maximum current requirements of the Hub Controller electronics in mA.
; DeviceRemovable - variable length
;  Bit 0 is reserved, bit i+1 = device at port i is non-removable.
; PortPwrCtrlMask - variable length
;  Obsolete, exists for compatibility. We ignore it.
ends
 
iglobal
align 4
; Implementation of struct USBFUNC for hubs.
usb_hub_callbacks:
        dd      usb_hub_callbacks_end - usb_hub_callbacks
        dd      usb_hub_init
        dd      usb_hub_disconnect
usb_hub_callbacks_end:
usb_hub_pseudosrv       dd      usb_hub_callbacks
endg
 
; This procedure is called when new hub is detected.
; It initializes the device.
; Technically, initialization implies sending several USB queries,
; so it is split in several procedures. The first is usb_hub_init,
; other are callbacks which will be called at some time in the future,
; when the device will respond.
; edx = usb_interface_descr, ecx = length rest
proc usb_hub_init
        push    ebx esi         ; save used registers to be stdcall
virtual at esp
                rd      2       ; saved registers
                dd      ?       ; return address
.pipe           dd      ?       ; handle of the config pipe
.config         dd      ?       ; pointer to usb_config_descr
.interface      dd      ?       ; pointer to usb_interface_descr
end virtual
; 1. Check that the maximal nesting is not exceeded:
; 5 non-root hubs is the maximum according to the spec.
        mov     ebx, [.pipe]
        push    5
        mov     eax, ebx
.count_parents:
        mov     eax, [eax+usb_pipe.DeviceData]
        mov     eax, [eax+usb_device_data.Hub]
        test    eax, eax
        jz      .depth_ok
        mov     eax, [eax+usb_hub.ConfigPipe]
        dec     dword [esp]
        jnz     .count_parents
        pop     eax
        dbgstr 'Hub chain is too long'
        jmp     .return0
.depth_ok:
        pop     eax
; Hubs use one IN interrupt endpoint for polling the device
; 2. Locate the descriptor of the interrupt endpoint.
; Loop over all descriptors owned by this interface.
.lookep:
; 2a. Skip the current descriptor.
        movzx   eax, [edx+usb_descr.bLength]
        add     edx, eax
        sub     ecx, eax
        jb      .errorep
; 2b. Length of data left must be at least sizeof.usb_endpoint_descr.
        cmp     ecx, sizeof.usb_endpoint_descr
        jb      .errorep
; 2c. If we have found another interface descriptor but not found our endpoint,
; this is an error: all subsequent descriptors belong to that interface
; (or further interfaces).
        cmp     [edx+usb_endpoint_descr.bDescriptorType], USB_INTERFACE_DESCR
        jz      .errorep
; 2d. Ignore all interface-related descriptors except endpoint descriptor.
        cmp     [edx+usb_endpoint_descr.bDescriptorType], USB_ENDPOINT_DESCR
        jnz     .lookep
; 2e. Length of endpoint descriptor must be at least sizeof.usb_endpoint_descr.
        cmp     [edx+usb_endpoint_descr.bLength], sizeof.usb_endpoint_descr
        jb      .errorep
; 2f. Ignore all endpoints except for INTERRUPT IN.
        cmp     [edx+usb_endpoint_descr.bEndpointAddress], 0
        jge     .lookep
        mov     al, [edx+usb_endpoint_descr.bmAttributes]
        and     al, 3
        cmp     al, INTERRUPT_PIPE
        jnz     .lookep
; We have located the descriptor for INTERRUPT IN endpoint,
; the pointer is in edx.
; 3. Allocate memory for the hub descriptor.
; Maximum length (assuming 255 downstream ports) is 40 bytes.
; Allocate 4 extra bytes to keep wMaxPacketSize.
; 3a. Save registers.
        push    edx
; 3b. Call the allocator.
        movi    eax, 44
        call    malloc
; 3c. Restore registers.
        pop     ecx
; 3d. If failed, say something to the debug board and return error.
        test    eax, eax
        jz      .nomemory
; 3e. Store the pointer in esi. xchg eax,r32 is one byte shorter than mov.
        xchg    esi, eax
; 4. Open a pipe for the status endpoint with descriptor found in step 1.
        movzx   eax, [ecx+usb_endpoint_descr.bEndpointAddress]
        movzx   edx, [ecx+usb_endpoint_descr.bInterval]
        movzx   ecx, [ecx+usb_endpoint_descr.wMaxPacketSize]
        test    ecx, (1 shl 11) - 1
        jz      .free
        push    ecx
        stdcall usb_open_pipe, ebx, eax, ecx, INTERRUPT_PIPE, edx
        pop     ecx
; If failed, free the memory allocated in step 3,
; say something to the debug board and return error.
        test    eax, eax
        jz      .free
; 5. Send control query for the hub descriptor,
; pass status pipe as a callback parameter,
; allow short packets.
        and     ecx, (1 shl 11) - 1
        mov     [esi+40], ecx
        mov     dword [esi], 0xA0 + \   ; class-specific request
                (USB_GET_DESCRIPTOR shl 8) + \
                (0 shl 16) + \          ; descriptor index 0
                (USB_HUB_DESCRIPTOR shl 24)
        mov     dword [esi+4], 40 shl 16
        stdcall usb_control_async, ebx, esi, esi, 40, usb_hub_got_config, eax, 1
; 6. If failed, free the memory allocated in step 3,
; say something to the debug board and return error.
        test    eax, eax
        jz      .free
; Otherwise, return 1. usb_hub_got_config will overwrite it later.
        xor     eax, eax
        inc     eax
        jmp     .nothing
.free:
        xchg    eax, esi
        call    free
        jmp     .return0
.errorep:
        dbgstr 'Invalid config descriptor for a hub'
        jmp     .return0
.nomemory:
        dbgstr 'No memory for USB hub data'
.return0:
        xor     eax, eax
.nothing:
        pop     esi ebx         ; restore used registers to be stdcall
        retn    12
endp
 
; This procedure is called when the request for the hub descriptor initiated
; by usb_hub_init is finished, either successfully or unsuccessfully.
proc usb_hub_got_config stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
        push    ebx             ; save used registers to be stdcall
; 1. If failed, say something to the debug board, free the buffer
; and stop the initialization.
        cmp     [status], 0
        jnz     .invalid
; 2. The length must be at least sizeof.usb_hub_descr.
; Note that [length] includes 8 bytes of setup packet.
        cmp     [length], 8 + sizeof.usb_hub_descr
        jb      .invalid
; 3. Sanity checks for the hub descriptor.
        mov     eax, [buffer]
if USB_DUMP_DESCRIPTORS
        mov     ecx, [length]
        sub     ecx, 8
        DEBUGF 1,'K : hub config:'
        push    eax
@@:
        DEBUGF 1,' %x',[eax]:2
        inc     eax
        dec     ecx
        jnz     @b
        DEBUGF 1,'\n'
        pop     eax
end if
        cmp     [eax+usb_hub_descr.bLength], sizeof.usb_hub_descr
        jb      .invalid
        cmp     [eax+usb_hub_descr.bDescriptorType], USB_HUB_DESCRIPTOR
        jnz     .invalid
        movzx   ecx, [eax+usb_hub_descr.bNbrPorts]
        test    ecx, ecx
        jz      .invalid
; 4. We use sizeof.usb_hub_descr bytes plus DeviceRemovable info;
; size of DeviceRemovable is (NumPorts+1) bits, this gives
; floor(NumPorts/8)+1 bytes. Check that all data are present in the
; descriptor and were successfully read.
        mov     edx, ecx
        shr     edx, 3
        add     edx, sizeof.usb_hub_descr + 1
        cmp     [eax+usb_hub_descr.bLength], dl
        jb      .invalid
        sub     [length], 8
        cmp     [length], edx
        jb      .invalid
; 5. Allocate the memory for usb_hub structure.
; Total size of variable-length data is ALIGN_UP(floor(NumPorts/8)+1+MaxPacketSize,4)+8*NumPorts.
        add     edx, [eax+40]
        add     edx, sizeof.usb_hub - sizeof.usb_hub_descr + 3
        and     edx, not 3
        lea     eax, [edx+ecx*8]
        push    ecx edx
        call    malloc
        pop     edx ecx
        test    eax, eax
        jz      .nomemory
        xchg    eax, ebx
; 6. Fill usb_hub structure.
        mov     [ebx+usb_hub.NumPorts], ecx
        add     edx, ebx
        mov     [ebx+usb_hub.ConnectedDevicesPtr], edx
        mov     eax, [pipe]
        mov     [ebx+usb_hub.ConfigPipe], eax
        mov     edx, [eax+usb_pipe.Controller]
        mov     [ebx+usb_hub.Controller], edx
        mov     eax, [calldata]
        mov     [ebx+usb_hub.StatusPipe], eax
        push    esi edi
        mov     esi, [buffer]
        mov     eax, [esi+40]
        mov     [ebx+usb_hub.MaxPacketSize], eax
; The following commands load bNbrPorts, wHubCharacteristics, bPwrOn2PwrGood.
        mov     edx, dword [esi+usb_hub_descr.bNbrPorts]
        mov     dl, 0
; The following command zeroes AccStatusChange and stores
; HubCharacteristics and PowerOnInterval.
        mov     dword [ebx+usb_hub.AccStatusChange], edx
        xor     eax, eax
        mov     [ebx+usb_hub.Actions], eax
; Copy DeviceRemovable data.
        lea     edi, [ebx+sizeof.usb_hub]
        add     esi, sizeof.usb_hub_descr
        mov     edx, ecx
        shr     ecx, 3
        inc     ecx
        rep movsb
        mov     [ebx+usb_hub.StatusChangePtr], edi
; Zero ConnectedDevices.
        mov     edi, [ebx+usb_hub.ConnectedDevicesPtr]
        mov     ecx, edx
        rep stosd
        mov     [ebx+usb_hub.ConnectedTimePtr], edi
; Set ConnectedTime to -1.
        dec     eax
        mov     ecx, edx
        rep stosd
        pop     edi esi
; 7. Replace value of 1 returned from usb_hub_init to the real value.
; Note: hubs are part of the core USB code, so this code can work with
; internals of other parts. Another way, the only possible one for external
; drivers, is to use two memory allocations: one (returned from AddDevice and
; fixed after that) for pointer, another for real data. That would work also,
; but wastes one allocation.
        mov     eax, [pipe]
        mov     eax, [eax+usb_pipe.DeviceData]
        add     eax, [eax+usb_device_data.Interfaces]
.scan:
        cmp     [eax+usb_interface_data.DriverData], 1
        jnz     @f
        cmp     [eax+usb_interface_data.DriverFunc], usb_hub_pseudosrv - USBSRV.usb_func
        jz      .scan_found
@@:
        add     eax, sizeof.usb_interface_data
        jmp     .scan
.scan_found:
        mov     [eax+usb_interface_data.DriverData], ebx
; 8. Insert the hub structure to the tail of the overall list of all hubs.
        mov     ecx, usb_hubs_list
        mov     edx, [ecx+usb_hub.Prev]
        mov     [ecx+usb_hub.Prev], ebx
        mov     [edx+usb_hub.Next], ebx
        mov     [ebx+usb_hub.Prev], edx
        mov     [ebx+usb_hub.Next], ecx
; 9. Start powering up all ports.
        DEBUGF 1,'K : found hub with %d ports\n',[ebx+usb_hub.NumPorts]
        lea     eax, [ebx+usb_hub.ConfigBuffer]
        xor     ecx, ecx
        mov     dword [eax], 23h + \    ; class-specific request to hub port
                (USB_SET_FEATURE shl 8) + \
                (PORT_POWER shl 16)
        mov     edx, [ebx+usb_hub.NumPorts]
        mov     dword [eax+4], edx
        stdcall usb_control_async, [ebx+usb_hub.ConfigPipe], eax, ecx, ecx, usb_hub_port_powered, ebx, ecx
.freebuf:
; 10. Free the buffer for hub descriptor and return.
        mov     eax, [buffer]
        call    free
        pop     ebx             ; restore used registers to be stdcall
        ret
.nomemory:
        dbgstr 'No memory for USB hub data'
        jmp     .freebuf
.invalid:
        dbgstr 'Invalid hub descriptor'
        jmp     .freebuf
endp
 
; This procedure is called when the request to power up some port is completed,
; either successfully or unsuccessfully.
proc usb_hub_port_powered stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
; 1. Check whether the operation was successful.
; If not, say something to the debug board and ssstop the initialization.
        cmp     [status], 0
        jnz     .invalid
; 2. Check whether all ports were powered.
; If so, go to 4. Otherwise, proceed to 3.
        mov     eax, [calldata]
        dec     dword [eax+usb_hub.ConfigBuffer+4]
        jz      .done
; 3. Power up the next port and return.
        lea     edx, [eax+usb_hub.ConfigBuffer]
        xor     ecx, ecx
        stdcall usb_control_async, [eax+usb_hub.ConfigPipe], edx, ecx, ecx, usb_hub_port_powered, eax, ecx
.nothing:
        ret
.done:
; 4. All ports were powered.
; The hub requires some delay until power will be stable, the delay value
; is provided in the hub descriptor; we have copied that value to
; usb_hub.PowerOnInterval. Note the time and set the corresponding flag
; for usb_hub_process_deferred.
        mov     ecx, [timer_ticks]
        mov     [eax+usb_hub.PoweredOnTime], ecx
        or      [eax+usb_hub.Actions], HUB_WAIT_POWERED
        jmp     .nothing
.invalid:
        dbgstr 'Error while powering hub ports'
        jmp     .nothing
endp
 
; Requests notification about any changes in hub/ports configuration.
; Called when initial configuration is done and when a previous notification
; has been processed.
proc usb_hub_wait_change
        stdcall usb_normal_transfer_async, [eax+usb_hub.StatusPipe], \
                [eax+usb_hub.StatusChangePtr], [eax+usb_hub.MaxPacketSize], usb_hub_changed, eax, 1
        ret
endp
 
; This procedure is called when something has changed on the hub.
proc usb_hub_changed stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
;       DEBUGF 1,'K : [%d] int pipe for hub %x\n',[timer_ticks],[calldata]
; 1. Check whether our request has failed.
; If so, say something to the debug board and stop processing notifications.
        xor     ecx, ecx
        cmp     [status], ecx
        jnz     .failed
; 2. If no data were retrieved, restart waiting.
        mov     eax, [calldata]
        cmp     [length], ecx
        jz      .continue
; 3. If size of data retrieved is less than maximal, pad with zeroes;
; this corresponds to 'state of other ports was not changed'
        mov     ecx, [eax+usb_hub.NumPorts]
        shr     ecx, 3
        inc     ecx
        sub     ecx, [length]
        jbe     .restart
        push    eax edi
        mov     edi, [buffer]
        add     edi, [length]
        xor     eax, eax
        rep stosb
        pop     edi eax
.restart:
; State of some elements of the hub was changed.
; Find the first element that was changed,
; ask the hub about nature of the change,
; clear the corresponding change,
; reask the hub about status+change (it is possible that another change
; occurs between the first ask and clearing the change; we won't see that
; change, so we need to query the status after clearing the change),
; continue two previous steps until nothing changes,
; process all changes which were registered.
; When all changes for one element will be processed, return to here and look
; for other changed elements.
        mov     edx, [eax+usb_hub.StatusChangePtr]
; We keep all observed changes in the special var usb_hub.AccStatusChange;
; it will be logical OR of all observed StatusChange's.
; 4. No observed changes yet, zero usb_hub.AccStatusChange.
        xor     ecx, ecx
        mov     [eax+usb_hub.AccStatusChange], cl
; 5. Test whether there was a change in the hub itself.
; If so, query hub state.
        btr     dword [edx], ecx
        jnc     .no_hub_change
.next_hub_change:
;       DEBUGF 1,'K : [%d] querying status of hub %x\n',[timer_ticks],eax
        lea     edx, [eax+usb_hub.ChangeConfigBuffer]
        lea     ecx, [eax+usb_hub.StatusData]
        mov     dword [edx], 0A0h + \   ; class-specific request from hub itself
                (USB_GET_STATUS shl 8)
        mov     dword [edx+4], 4 shl 16 ; get 4 bytes
        stdcall usb_control_async, [eax+usb_hub.ConfigPipe], edx, ecx, 4, usb_hub_status, eax, 0
        jmp     .nothing
.no_hub_change:
; 6. Find the first port with changed state and clear the corresponding bit
; (so next scan after .restart will not consider this port again).
; If found, go to 8. Otherwise, advance to 7.
        inc     ecx
.test_port_change:
        btr     [edx], ecx
        jc      .found_port_change
        inc     ecx
        cmp     ecx, [eax+usb_hub.NumPorts]
        jbe     .test_port_change
.continue:
; 7. All changes have been processed. Wait for next notification.
        call    usb_hub_wait_change
.nothing:
        ret
.found_port_change:
        mov     dword [eax+usb_hub.ChangeConfigBuffer+4], ecx
.next_port_change:
; 8. Query port state. Continue work in usb_hub_port_status callback.
;       movzx   ecx, [eax+usb_hub.ChangeConfigBuffer+4]
;       dec     ecx
;       DEBUGF 1,'K : [%d] querying status of hub %x port %d\n',[timer_ticks],eax,ecx
        lea     edx, [eax+usb_hub.ChangeConfigBuffer]
        mov     dword [edx], 0A3h + \   ; class-specific request from hub port
                (USB_GET_STATUS shl 8)
        mov     byte [edx+6], 4         ; data length = 4 bytes
        lea     ecx, [eax+usb_hub.StatusData]
        stdcall usb_control_async, [eax+usb_hub.ConfigPipe], edx, ecx, 4, usb_hub_port_status, eax, 0
        jmp     .nothing
.failed:
        cmp     [status], USB_STATUS_CLOSED
        jz      .nothing
        dbgstr 'Querying hub notification failed'
        jmp     .nothing
endp
 
; This procedure is called when the request of hub status is completed,
; either successfully or unsuccessfully.
proc usb_hub_status stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
; 1. Check whether our request has failed.
; If so, say something to the debug board and stop processing notifications.
        cmp     [status], 0
        jnz     .failed
; 2. Accumulate observed changes.
        mov     eax, [calldata]
        mov     dl, byte [eax+usb_hub.StatusChange]
        or      [eax+usb_hub.AccStatusChange], dl
.next_change:
; 3. Find the first change. If found, advance to 4. Otherwise, go to 5.
        mov     cl, C_HUB_OVER_CURRENT
        btr     dword [eax+usb_hub.StatusChange], 1
        jc      .clear_hub_change
        mov     cl, C_HUB_LOCAL_POWER
        btr     dword [eax+usb_hub.StatusChange], 0
        jnc     .final
.clear_hub_change:
; 4. Clear the change and continue in usb_hub_change_cleared callback.
        lea     edx, [eax+usb_hub.ChangeConfigBuffer]
        mov     dword [edx], 20h + \    ; class-specific request to hub itself
                (USB_CLEAR_FEATURE shl 8)
        mov     [edx+2], cl     ; feature selector
        and     dword [edx+4], 0
        stdcall usb_control_async, [eax+usb_hub.ConfigPipe], edx, 0, 0, usb_hub_change_cleared, eax, 0
.nothing:
        ret
.final:
; 5. All changes cleared and accumulated, now process them.
; Note: that needs work.
        DEBUGF 1,'K : hub status %x\n',[eax+usb_hub.AccStatusChange]:2
        test    [eax+usb_hub.AccStatusChange], 1
        jz      .no_local_power
        test    [eax+usb_hub.StatusData], 1
        jz      .local_power_lost
        dbgstr 'Hub local power is now good'
        jmp     .no_local_power
.local_power_lost:
        dbgstr 'Hub local power is now lost'
.no_local_power:
        test    [eax+usb_hub.AccStatusChange], 2
        jz      .no_overcurrent
        test    [eax+usb_hub.StatusData], 2
        jz      .no_overcurrent
        dbgstr 'Hub global overcurrent'
.no_overcurrent:
; 6. Process possible changes for other ports.
        jmp     usb_hub_changed.restart
.failed:
        dbgstr 'Querying hub status failed'
        jmp     .nothing
endp
 
; This procedure is called when the request to clear hub change is completed,
; either successfully or unsuccessfully.
proc usb_hub_change_cleared stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
; 1. Check whether our request has failed.
; If so, say something to the debug board and stop processing notifications.
        cmp     [status], 0
        jnz     .failed
; 2. If there is a change which was observed, but not yet cleared,
; go to the code which clears it.
        mov     eax, [calldata]
        cmp     [eax+usb_hub.StatusChange], 0
        jnz     usb_hub_status.next_change
; 3. Otherwise, go to the code which queries the status.
        jmp     usb_hub_changed.next_hub_change
.failed:
        dbgstr 'Clearing hub change failed'
        ret
endp
 
; This procedure is called when the request of port status is completed,
; either successfully or unsuccessfully.
proc usb_hub_port_status stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
; 1. Check whether our request has failed.
; If so, say something to the debug board and stop processing notifications.
        cmp     [status], 0
        jnz     .failed
; 2. Accumulate observed changes.
        mov     eax, [calldata]
;       movzx   ecx, [eax+usb_hub.ChangeConfigBuffer+4]
;       dec     ecx
;       DEBUGF 1,'K : [%d] hub %x port %d status %x change %x\n',[timer_ticks],eax,ecx,[eax+usb_hub.StatusData]:4,[eax+usb_hub.StatusChange]:4
        mov     dl, byte [eax+usb_hub.StatusChange]
        or      [eax+usb_hub.AccStatusChange], dl
.next_change:
; 3. Find the first change. If found, advance to 4. Otherwise, go to 5.
; Ignore change in reset status; it is cleared by synchronous code
; (usb_hub_process_deferred), so avoid unnecessary interference.
;       mov     cl, C_PORT_RESET
        btr     dword [eax+usb_hub.StatusChange], PORT_RESET
;       jc      .clear_port_change
        mov     cl, C_PORT_OVER_CURRENT
        btr     dword [eax+usb_hub.StatusChange], PORT_OVER_CURRENT
        jc      .clear_port_change
        mov     cl, C_PORT_SUSPEND
        btr     dword [eax+usb_hub.StatusChange], PORT_SUSPEND
        jc      .clear_port_change
        mov     cl, C_PORT_ENABLE
        btr     dword [eax+usb_hub.StatusChange], PORT_ENABLE
        jc      .clear_port_change
        mov     cl, C_PORT_CONNECTION
        btr     dword [eax+usb_hub.StatusChange], PORT_CONNECTION
        jnc     .final
.clear_port_change:
; 4. Clear the change and continue in usb_hub_port_changed callback.
        call    usb_hub_clear_port_change
        jmp     .nothing
.final:
; All changes cleared and accumulated, now process them.
        movzx   ecx, byte [eax+usb_hub.ChangeConfigBuffer+4]
        dec     ecx
        DEBUGF 1,'K : final: hub %x port %d status %x change %x\n',eax,ecx,[eax+usb_hub.StatusData]:4,[eax+usb_hub.AccStatusChange]:2
; 5. Process connect/disconnect events.
; 5a. Test whether there is such event.
        test    byte [eax+usb_hub.AccStatusChange], 1 shl PORT_CONNECTION
        jz      .nodisconnect
; 5b. If there was a connected device, notify the main code about disconnect.
        push    ebx
        mov     edx, [eax+usb_hub.ConnectedDevicesPtr]
        xor     ebx, ebx
        xchg    ebx, [edx+ecx*4]
        test    ebx, ebx
        jz      @f
        push    eax ecx
        call    usb_device_disconnected
        pop     ecx eax
@@:
        pop     ebx
; 5c. If the disconnect event corresponds to the port which is currently
; resetting, then another request from synchronous code could be in the fly,
; so aborting reset immediately would lead to problems with those requests.
; Thus, just set the corresponding status and let the synchronous code process.
        test    byte [eax+usb_hub.Actions], (HUB_RESET_SIGNAL or HUB_RESET_RECOVERY)
        jz      @f
        mov     edx, [eax+usb_hub.Controller]
        cmp     [edx+usb_controller.ResettingPort], cl
        jnz     @f
        mov     [edx+usb_controller.ResettingStatus], -1
@@:
; 5d. If the current status is 'connected', store the current time as connect
; time and set the corresponding bit for usb_hub_process_deferred.
; Otherwise, set connect time to -1.
; If current time is -1, pretend that the event occured one tick later and
; store zero.
        mov     edx, [eax+usb_hub.ConnectedTimePtr]
        test    byte [eax+usb_hub.StatusData], 1 shl PORT_CONNECTION
        jz      .disconnected
        or      [eax+usb_hub.Actions], HUB_WAIT_CONNECT
        push    eax
        call    usb_hub_store_connected_time
        pop     eax
        jmp     @f
.disconnected:
        or      dword [edx+ecx*4], -1
@@:
.nodisconnect:
; 6. Process port disabling.
        test    [eax+usb_hub.AccStatusChange], 1 shl PORT_ENABLE
        jz      .nodisable
        test    byte [eax+usb_hub.StatusData], 1 shl PORT_ENABLE
        jnz     .nodisable
; Note: that needs work.
        dbgstr 'Port disabled'
.nodisable:
; 7. Process port overcurrent.
        test    [eax+usb_hub.AccStatusChange], 1 shl PORT_OVER_CURRENT
        jz      .noovercurrent
        test    byte [eax+usb_hub.StatusData], 1 shl PORT_OVER_CURRENT
        jz      .noovercurrent
; Note: that needs work.
        dbgstr 'Port over-current'
.noovercurrent:
; 8. Process possible changes for other ports.
        jmp     usb_hub_changed.restart
.failed:
        dbgstr 'Querying port status failed'
.nothing:
        ret
endp
 
; Helper procedure to store current time in ConnectedTime,
; advancing -1 to zero if needed.
proc usb_hub_store_connected_time
        mov     eax, [timer_ticks]
; transform -1 to 0, leave other values as is
        cmp     eax, -1
        sbb     eax, -1
        mov     [edx+ecx*4], eax
        ret
endp
 
; Helper procedure for several parts of hub code.
; Sends a request to clear the given feature of the port.
; eax -> usb_hub, cl = feature;
; as is should be called from async code, sync code should set
; edx to ConfigBuffer and call usb_hub_clear_port_change.buffer;
; port number (1-based) should be filled in [edx+4] by previous requests.
proc usb_hub_clear_port_change
        lea     edx, [eax+usb_hub.ChangeConfigBuffer]
.buffer:
;       push    edx
;       movzx   edx, byte [edx+4]
;       dec     edx
;       DEBUGF 1,'K : [%d] hub %x port %d clear feature %d\n',[timer_ticks],eax,edx,cl
;       pop     edx
        mov     dword [edx], 23h + \    ; class-specific request to hub port
                (USB_CLEAR_FEATURE shl 8)
        mov     byte [edx+2], cl
        and     dword [edx+4], 0xFF
        stdcall usb_control_async, [eax+usb_hub.ConfigPipe], edx, edx, 0, usb_hub_port_changed, eax, 0
        ret
endp
 
; This procedure is called when the request to clear port change is completed,
; either successfully or unsuccessfully.
proc usb_hub_port_changed stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
; 1. Check whether our request has failed.
; If so, say something to the debug board and stop processing notifications.
        cmp     [status], 0
        jnz     .failed
; 2. If the request was originated by synchronous code, no further processing
; is required.
        mov     eax, [calldata]
        lea     edx, [eax+usb_hub.ConfigBuffer]
        cmp     [buffer], edx
        jz      .nothing
; 3. If there is a change which was observed, but not yet cleared,
; go to the code which clears it.
        cmp     [eax+usb_hub.StatusChange], 0
        jnz     usb_hub_port_status.next_change
; 4. Otherwise, go to the code which queries the status.
        jmp     usb_hub_changed.next_port_change
.failed:
        dbgstr 'Clearing port change failed'
.nothing:
        ret
endp
 
; This procedure is called in the USB thread from usb_thread_proc,
; contains synchronous code which should be activated at certain time
; (e.g. reset a recently connected device after debounce interval 100ms).
; Returns the number of ticks when it should be called next time.
proc usb_hub_process_deferred
; 1. Top-of-stack will contain return value; initialize to infinite timeout.
        push    -1
; 2. If wait for stable power is active, then
; either reschedule wakeup (if time is not over)
; or start processing notifications.
        test    byte [esi+usb_hub.Actions], HUB_WAIT_POWERED
        jz      .no_powered
        movzx   eax, [esi+usb_hub.PowerOnInterval]
; three following instructions are equivalent to edx = ceil(eax / 5) + 1
; 1 extra tick is added to make sure that the interval is at least as needed
; (it is possible that PoweredOnTime was set just before timer interrupt, and
; this test goes on just after timer interrupt)
        add     eax, 9
; two following instructions are equivalent to edx = floor(eax / 5)
; for any 0 <= eax < 40000000h
        mov     ecx, 33333334h
        mul     ecx
        mov     eax, [timer_ticks]
        sub     eax, [esi+usb_hub.PoweredOnTime]
        sub     eax, edx
        jge     .powered_on
        neg     eax
        pop     ecx
        push    eax
        jmp     .no_powered
.powered_on:
        and     [esi+usb_hub.Actions], not HUB_WAIT_POWERED
        mov     eax, esi
        call    usb_hub_wait_change
.no_powered:
; 3. If reset is pending, check whether we can start it and start it, if so.
        test    byte [esi+usb_hub.Actions], HUB_RESET_WAITING
        jz      .no_wait_reset
        mov     eax, [esi+usb_hub.Controller]
        cmp     [eax+usb_controller.ResettingPort], -1
        jnz     .no_wait_reset
        call    usb_hub_initiate_reset
.no_wait_reset:
; 4. If reset signalling is active, wait for end of reset signalling
; and schedule wakeup in 1 tick.
        test    byte [esi+usb_hub.Actions], HUB_RESET_SIGNAL
        jz      .no_resetting_port
; It has no sense to query status several times per tick.
        mov     eax, [timer_ticks]
        cmp     eax, [esi+usb_hub.ResetTime]
        jz      @f
        mov     [esi+usb_hub.ResetTime], eax
        movzx   ecx, byte [esi+usb_hub.ConfigBuffer+4]
        mov     eax, usb_hub_resetting_port_status
        call    usb_hub_query_port_status
@@:
        pop     eax
        push    1
.no_resetting_port:
; 5. If reset recovery is active and time is not over, reschedule wakeup.
        test    byte [esi+usb_hub.Actions], HUB_RESET_RECOVERY
        jz      .no_reset_recovery
        mov     eax, [timer_ticks]
        sub     eax, [esi+usb_hub.ResetTime]
        sub     eax, USB_RESET_RECOVERY_TIME
        jge     .reset_done
        neg     eax
        cmp     [esp], eax
        jb      @f
        mov     [esp], eax
@@:
        jmp     .no_reset_recovery
.reset_done:
; 6. If reset recovery is active and time is over, clear 'reset recovery' flag,
; notify other code about a new device and let it do further steps.
; If that fails, stop reset process for this port and disable that port.
        and     [esi+usb_hub.Actions], not HUB_RESET_RECOVERY
; Bits 9-10 of port status encode port speed.
; If PORT_LOW_SPEED is set, the device is low-speed. Otherwise,
; PORT_HIGH_SPEED bit distinguishes full-speed and high-speed devices.
; This corresponds to values of USB_SPEED_FS=0, USB_SPEED_LS=1, USB_SPEED_HS=2.
        mov     eax, dword [esi+usb_hub.ResetStatusData]
        shr     eax, PORT_LOW_SPEED
        and     eax, 3
        test    al, 1
        jz      @f
        mov     al, 1
@@:
;       movzx   ecx, [esi+usb_hub.ConfigBuffer+4]
;       dec     ecx
;       DEBUGF 1,'K : [%d] hub %x port %d speed %d\n',[timer_ticks],esi,ecx,eax
        push    esi
        mov     esi, [esi+usb_hub.Controller]
        cmp     [esi+usb_controller.ResettingStatus], -1
        jz      .disconnected_while_reset
        mov     edx, [esi+usb_controller.HardwareFunc]
        call    [edx+usb_hardware_func.NewDevice]
        pop     esi
        test    eax, eax
        jnz     .no_reset_recovery
        mov     eax, esi
        call    usb_hub_disable_resetting_port
        jmp     .no_reset_recovery
.disconnected_while_reset:
        pop     esi
        mov     eax, esi
        call    usb_hub_reset_aborted
.no_reset_recovery:
; 7. Handle recent connection events.
; Note: that should be done after step 6, because step 6 can clear
; HUB_RESET_IN_PROGRESS flag.
; 7a. Test whether there is such an event pending. If no, skip this step.
        test    byte [esi+usb_hub.Actions], HUB_WAIT_CONNECT
        jz      .no_wait_connect
; 7b. If we have started reset process for another port in the same hub,
; skip this step: the buffer for config requests can be used for that port.
        test    byte [esi+usb_hub.Actions], HUB_RESET_IN_PROGRESS
        jnz     .no_wait_connect
; 7c. Clear flag 'there are connection events which should be processed'.
; If there are another connection events, this flag will be set again.
        and     [esi+usb_hub.Actions], not HUB_WAIT_CONNECT
; 7d. Prepare for loop over all ports.
        xor     ecx, ecx
.test_wait_connect:
; 7e. For every port test for recent connection event.
; If none, continue the loop for the next port.
        mov     edx, [esi+usb_hub.ConnectedTimePtr]
        mov     eax, [edx+ecx*4]
        cmp     eax, -1
        jz      .next_wait_connect
        or      [esi+usb_hub.Actions], HUB_WAIT_CONNECT
; 7f. Test whether initial delay is over.
        sub     eax, [timer_ticks]
        neg     eax
        sub     eax, USB_CONNECT_DELAY
        jge     .connect_delay_over
; 7g. The initial delay is not over;
; set the corresponding flag again, reschedule wakeup and continue the loop.
        neg     eax
        cmp     [esp], eax
        jb      @f
        mov     [esp], eax
@@:
        jmp     .next_wait_connect
.connect_delay_over:
; The initial delay is over.
; It is possible that there was disconnect event during that delay, probably
; with connect event after that. If so, we should restart the waiting. However,
; on the hardware level connect/disconnect events from hubs are implemented
; using polling with interval selected by the hub, so it is possible that
; we have not yet observed that disconnect event.
; Thus, we query port status+change data before all further processing.
; 7h. Send the request for status+change data.
        push    ecx
; Hub requests expect 1-based port number, not zero-based we operate with.
        inc     ecx
        mov     eax, usb_hub_connect_port_status
        call    usb_hub_query_port_status
        pop     ecx
; 3i. If request has been submitted successfully, set the flag
; 'reset in progress, config buffer is owned by reset process' and break
; from the loop.
        test    eax, eax
        jz      .next_wait_connect
        or      [esi+usb_hub.Actions], HUB_RESET_IN_PROGRESS
        jmp     .no_wait_connect
.next_wait_connect:
; 7j. Continue the loop for next port.
        inc     ecx
        cmp     ecx, [esi+usb_hub.NumPorts]
        jb      .test_wait_connect
.no_wait_connect:
; 8. Pop return value from top-of-stack and return.
        pop     eax
        ret
endp
 
; Helper procedure for other code. Called when reset process is aborted.
proc usb_hub_reset_aborted
; Clear 'reset in progress' flag and test for other devices which could be
; waiting for reset.
        and     [eax+usb_hub.Actions], not HUB_RESET_IN_PROGRESS
        push    esi
        mov     esi, [eax+usb_hub.Controller]
        call    usb_test_pending_port
        pop     esi
        ret
endp
 
; Helper procedure for usb_hub_process_deferred.
; Sends a request to query port status.
; esi -> usb_hub, eax = callback, ecx = 1-based port.
proc usb_hub_query_port_status
;       dec     ecx
;       DEBUGF 1,'K : [%d] [main] hub %x port %d query status\n',[timer_ticks],esi,ecx
;       inc     ecx
        add     ecx, 4 shl 16           ; data length = 4
        lea     edx, [esi+usb_hub.ConfigBuffer]
        mov     dword [edx], 0A3h + \   ; class-specific request from hub port
                (USB_GET_STATUS shl 8)
        mov     dword [edx+4], ecx
        lea     ecx, [esi+usb_hub.ResetStatusData]
        stdcall usb_control_async, [esi+usb_hub.ConfigPipe], edx, ecx, 4, eax, esi, 0
        ret
endp
 
; This procedure is called when the request to query port status
; initiated by usb_hub_process_deferred for testing connection is completed,
; either successfully or unsuccessfully.
proc usb_hub_connect_port_status stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
        push    esi     ; save used register to be stdcall
        mov     eax, [calldata]
        mov     esi, [pipe]
;       movzx   ecx, [eax+usb_hub.ConfigBuffer+4]
;       dec     ecx
;       DEBUGF 1,'K : [%d] [connect test] hub %x port %d status %x change %x\n',[timer_ticks],eax,ecx,[eax+usb_hub.ResetStatusData]:4,[eax+usb_hub.ResetStatusChange]:4
; 1. In any case, clear 'reset in progress' flag.
; If everything is ok, it would be set again.
        and     [eax+usb_hub.Actions], not HUB_RESET_IN_PROGRESS
; 2. If the request has failed, stop reset process.
        cmp     [status], 0
        jnz     .nothing
        mov     edx, [eax+usb_hub.ConnectedTimePtr]
        movzx   ecx, byte [eax+usb_hub.ConfigBuffer+4]
        dec     ecx
; 3. Test whether there was a disconnect event.
        test    byte [eax+usb_hub.ResetStatusChange], 1 shl PORT_CONNECTION
        jz      .reset
; 4. There was a disconnect event.
; There is another handler of connect/disconnect events, usb_hub_port_status.
; However, we do not know whether it has already processed this event
; or it will process it sometime later.
; If ConnectedTime is -1, then another handler has already run,
; there was no connection event, so just leave the value as -1.
; Otherwise, there are two possibilities: either another handler has not yet
; run (which is quite likely), or there was a connection event and the other
; handler has run exactly while our request was processed (otherwise our
; request would not been submitted; this is quite unlikely due to timing
; requirements, but not impossible). In this case, set ConnectedTime to the
; current time: in the likely case it prevents usb_hub_process_deferred from immediate
; issuing of another requests (which would be just waste of time);
; in the unlikely case it is still correct (although slightly increases
; the debounce interval).
        cmp     dword [edx+ecx*4], -1
        jz      .nothing
        call    usb_hub_store_connected_time
        jmp     .nothing
.reset:
; 5. The device remained connected for the entire debounce interval;
; we can proceed with initialization.
; Clear connected time for this port and notify usb_hub_process_deferred that
; the new port is waiting for reset.
        or      dword [edx+ecx*4], -1
        or      [eax+usb_hub.Actions], HUB_RESET_IN_PROGRESS + HUB_RESET_WAITING
.nothing:
        pop     esi     ; restore used register to be stdcall
        ret
endp
 
; This procedure is called when the request to query port status
; initiated by usb_hub_process_deferred for testing reset status is completed,
; either successfully or unsuccessfully.
proc usb_hub_resetting_port_status stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
; 1. If the request has failed, do nothing.
        cmp     [status], 0
        jnz     .nothing
; 2. If reset signalling is still active, do nothing.
        mov     eax, [calldata]
;       movzx   ecx, [eax+usb_hub.ConfigBuffer+4]
;       dec     ecx
;       DEBUGF 1,'K : hub %x port %d ResetStatusData = %x change = %x\n',eax,ecx,[eax+usb_hub.ResetStatusData]:4,[eax+usb_hub.ResetStatusChange]:4
        test    byte [eax+usb_hub.ResetStatusData], 1 shl PORT_RESET
        jnz     .nothing
; 3. Store the current time to start reset recovery interval
; and clear 'reset signalling active' flag.
        mov     edx, [timer_ticks]
        mov     [eax+usb_hub.ResetTime], edx
        and     [eax+usb_hub.Actions], not HUB_RESET_SIGNAL
; 4. If the device has not been disconnected, set 'reset recovery active' bit.
; Otherwise, terminate reset process.
        test    byte [eax+usb_hub.ResetStatusChange], 1 shl PORT_CONNECTION
        jnz     .disconnected
        or      [eax+usb_hub.Actions], HUB_RESET_RECOVERY
.common:
; In any case, clear change of resetting status.
        lea     edx, [eax+usb_hub.ConfigBuffer]
        mov     cl, C_PORT_RESET
        call    usb_hub_clear_port_change.buffer
.nothing:
        ret
.disconnected:
        call    usb_hub_reset_aborted
        jmp     .common
endp
 
; Helper procedure for usb_hub_process_deferred. Initiates reset signalling
; on the current port (given by 1-based value [ConfigBuffer+4]).
; esi -> usb_hub, eax -> usb_controller
proc usb_hub_initiate_reset
; 1. Store hub+port data in the controller structure.
        movzx   ecx, [esi+usb_hub.ConfigBuffer+4]
        dec     ecx
        mov     [eax+usb_controller.ResettingPort], cl
        mov     [eax+usb_controller.ResettingHub], esi
; 2. Store the current time and set 'reset signalling active' flag.
        mov     eax, [timer_ticks]
        mov     [esi+usb_hub.ResetTime], eax
        and     [esi+usb_hub.Actions], not HUB_RESET_WAITING
        or      [esi+usb_hub.Actions], HUB_RESET_SIGNAL
; 3. Send request to the hub to initiate request signalling.
        lea     edx, [esi+usb_hub.ConfigBuffer]
;       DEBUGF 1,'K : [%d] hub %x port %d initiate reset\n',[timer_ticks],esi,ecx
        mov     dword [edx], 23h + \
                (USB_SET_FEATURE shl 8) + \
                (PORT_RESET shl 16)
        and     dword [edx+4], 0xFF
        stdcall usb_control_async, [esi+usb_hub.ConfigPipe], edx, 0, 0, usb_hub_reset_started, esi, 0
        test    eax, eax
        jnz     @f
        mov     eax, esi
        call    usb_hub_reset_aborted
@@:
        ret
endp
 
; This procedure is called when the request to start reset signalling initiated
; by usb_hub_initiate_reset is completed, either successfully or unsuccessfully.
proc usb_hub_reset_started stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
; If the request is successful, do nothing.
; Otherwise, clear 'reset signalling' flag and abort reset process.
        mov     eax, [calldata]
;       movzx   ecx, [eax+usb_hub.ConfigBuffer+4]
;       dec     ecx
;       DEBUGF 1,'K : [%d] hub %x port %d reset started\n',[timer_ticks],eax,ecx
        cmp     [status], 0
        jz      .nothing
        and     [eax+usb_hub.Actions], not HUB_RESET_SIGNAL
        dbgstr 'Failed to reset hub port'
        call    usb_hub_reset_aborted
.nothing:
        ret
endp
 
; This procedure is called by the protocol layer if something has failed during
; initial stages of the configuration process, so the device should be disabled
; at hub level.
proc usb_hub_disable_resetting_port
        and     [eax+usb_hub.Actions], not HUB_RESET_IN_PROGRESS
;       movzx   ecx, [eax+usb_hub.ConfigBuffer+4]
;       dec     ecx
;       DEBUGF 1,'K : [%d] hub %x port %d disable\n',[timer_ticks],eax,ecx
        lea     edx, [eax+usb_hub.ConfigBuffer]
        mov     cl, PORT_ENABLE
        jmp     usb_hub_clear_port_change.buffer
endp
 
; This procedure is called when the hub is disconnected.
proc usb_hub_disconnect
virtual at esp
                dd      ?       ; return address
.hubdata        dd      ?
end virtual
; 1. If the hub is disconnected during initial configuration,
; 1 is stored as hub data and there is nothing to do.
        mov     eax, [.hubdata]
        cmp     eax, 1
        jz      .nothing
; 2. Remove the hub from the overall list.
        mov     ecx, [eax+usb_hub.Next]
        mov     edx, [eax+usb_hub.Prev]
        mov     [ecx+usb_hub.Prev], edx
        mov     [edx+usb_hub.Next], ecx
; 3. If some child is in reset process, abort reset.
        push    esi
        mov     esi, [eax+usb_hub.Controller]
        cmp     [esi+usb_controller.ResettingHub], eax
        jnz     @f
        cmp     [esi+usb_controller.ResettingPort], -1
        jz      @f
        push    eax
        call    usb_test_pending_port
        pop     eax
@@:
        pop     esi
; 4. Loop over all children and notify other code that they were disconnected.
        push    ebx
        xor     ecx, ecx
.disconnect_children:
        mov     ebx, [eax+usb_hub.ConnectedDevicesPtr]
        mov     ebx, [ebx+ecx*4]
        test    ebx, ebx
        jz      @f
        push    eax ecx
        call    usb_device_disconnected
        pop     ecx eax
@@:
        inc     ecx
        cmp     ecx, [eax+usb_hub.NumPorts]
        jb      .disconnect_children
; 4. Free memory allocated for the hub data.
        call    free
        pop     ebx
.nothing:
        retn    4
endp
 
; Helper function for USB2 scheduler.
; in: eax -> usb_hub
; out: ecx = TT think time for the hub in FS-bytes
proc usb_get_tt_think_time
        movzx   ecx, [eax+usb_hub.HubCharacteristics]
        shr     ecx, 5
        and     ecx, 3
        inc     ecx
        ret
endp

Rev 5201	Rev 5565
1	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;	1	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2	;; ;;	2	;; ;;
3	;; Copyright (C) KolibriOS team 2013-2014. All rights reserved. ;;	3	;; Copyright (C) KolibriOS team 2013-2015. All rights reserved. ;;
4	;; Distributed under terms of the GNU General Public License ;;	4	;; Distributed under terms of the GNU General Public License ;;
5	;; ;;	5	;; ;;
6	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;	6	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
7		7
8	$Revision: 4850 $	8	$Revision: 5363 $
9		9
10		10
11	; Support for USB (non-root) hubs:	11	; Support for USB (non-root) hubs:
12	; powering up/resetting/disabling ports,	12	; powering up/resetting/disabling ports,
13	; watching for adding/removing devices.	13	; watching for adding/removing devices.
14		14
15	; =============================================================================	15	; =============================================================================
16	; ================================= Constants =================================	16	; ================================= Constants =================================
17	; =============================================================================	17	; =============================================================================
18	; Hub constants	18	; Hub constants
19	; USB hub descriptor type	19	; USB hub descriptor type
20	USB_HUB_DESCRIPTOR = 29h	20	USB_HUB_DESCRIPTOR = 29h
21		21
22	; Features for CLEAR_FEATURE commands to the hub.	22	; Features for CLEAR_FEATURE commands to the hub.
23	C_HUB_LOCAL_POWER = 0	23	C_HUB_LOCAL_POWER = 0
24	C_HUB_OVER_CURRENT = 1	24	C_HUB_OVER_CURRENT = 1
25		25
26	; Bits in result of GET_STATUS command for a port.	26	; Bits in result of GET_STATUS command for a port.
27	; Also suitable for CLEAR_FEATURE/SET_FEATURE commands, where applicable,	27	; Also suitable for CLEAR_FEATURE/SET_FEATURE commands, where applicable,
28	; except TEST/INDICATOR.	28	; except TEST/INDICATOR.
29	PORT_CONNECTION = 0	29	PORT_CONNECTION = 0
30	PORT_ENABLE = 1	30	PORT_ENABLE = 1
31	PORT_SUSPEND = 2	31	PORT_SUSPEND = 2
32	PORT_OVER_CURRENT = 3	32	PORT_OVER_CURRENT = 3
33	PORT_RESET = 4	33	PORT_RESET = 4
34	PORT_POWER = 8	34	PORT_POWER = 8
35	PORT_LOW_SPEED = 9	35	PORT_LOW_SPEED = 9
36	PORT_HIGH_SPEED = 10	36	PORT_HIGH_SPEED = 10
37	PORT_TEST_BIT = 11	37	PORT_TEST_BIT = 11
38	PORT_INDICATOR_BIT = 12	38	PORT_INDICATOR_BIT = 12
39	C_PORT_CONNECTION = 16	39	C_PORT_CONNECTION = 16
40	C_PORT_ENABLE = 17	40	C_PORT_ENABLE = 17
41	C_PORT_SUSPEND = 18	41	C_PORT_SUSPEND = 18
42	C_PORT_OVER_CURRENT = 19	42	C_PORT_OVER_CURRENT = 19
43	C_PORT_RESET = 20	43	C_PORT_RESET = 20
44	PORT_TEST_FEATURE = 21	44	PORT_TEST_FEATURE = 21
45	PORT_INDICATOR_FEATURE = 22	45	PORT_INDICATOR_FEATURE = 22
46		46
47	; Internal constants	47	; Internal constants
48	; Bits in usb_hub.Actions	48	; Bits in usb_hub.Actions
49	HUB_WAIT_POWERED = 1	49	HUB_WAIT_POWERED = 1
50	; ports were powered, wait until power is stable	50	; ports were powered, wait until power is stable
51	HUB_WAIT_CONNECT = 2	51	HUB_WAIT_CONNECT = 2
52	; some device was connected, wait initial debounce interval	52	; some device was connected, wait initial debounce interval
53	HUB_RESET_IN_PROGRESS = 4	53	HUB_RESET_IN_PROGRESS = 4
54	; reset in progress, so buffer for config requests is owned	54	; reset in progress, so buffer for config requests is owned
55	; by reset process; this includes all stages from initial disconnect test	55	; by reset process; this includes all stages from initial disconnect test
56	; to end of setting address (fail on any stage should lead to disabling port,	56	; to end of setting address (fail on any stage should lead to disabling port,
57	; which requires a config request)	57	; which requires a config request)
58	HUB_RESET_WAITING = 8	58	HUB_RESET_WAITING = 8
59	; the port is ready for reset, but another device somewhere on the bus	59	; the port is ready for reset, but another device somewhere on the bus
60	; is resetting. Implies HUB_RESET_IN_PROGRESS	60	; is resetting. Implies HUB_RESET_IN_PROGRESS
61	HUB_RESET_SIGNAL = 10h	61	HUB_RESET_SIGNAL = 10h
62	; reset signalling is active for some port in the hub	62	; reset signalling is active for some port in the hub
63	; Implies HUB_RESET_IN_PROGRESS	63	; Implies HUB_RESET_IN_PROGRESS
64	HUB_RESET_RECOVERY = 20h	64	HUB_RESET_RECOVERY = 20h
65	; reset recovery is active for some port in the hub	65	; reset recovery is active for some port in the hub
66	; Implies HUB_RESET_IN_PROGRESS	66	; Implies HUB_RESET_IN_PROGRESS
67		67
68	; Well, I think that those 5 flags WAIT_CONNECT and RESET_* require additional	68	; Well, I think that those 5 flags WAIT_CONNECT and RESET_* require additional
69	; comments. So that is the overview of what happens with a new device assuming	69	; comments. So that is the overview of what happens with a new device assuming
70	; no errors.	70	; no errors.
71	; * device is connected;	71	; * device is connected;
72	; * hub notifies us about connect event; after some processing	72	; * hub notifies us about connect event; after some processing
73	; usb_hub_port_change finally processes that event, setting the flag	73	; usb_hub_port_change finally processes that event, setting the flag
74	; HUB_WAIT_CONNECT and storing time when the device was connected;	74	; HUB_WAIT_CONNECT and storing time when the device was connected;
75	; * 100 ms delay;	75	; * 100 ms delay;
76	; * usb_hub_process_deferred clears HUB_WAIT_CONNECT,	76	; * usb_hub_process_deferred clears HUB_WAIT_CONNECT,
77	; sets HUB_RESET_IN_PROGRESS, stores the port index in ConfigBuffer and asks	77	; sets HUB_RESET_IN_PROGRESS, stores the port index in ConfigBuffer and asks
78	; the hub whether there was a disconnect event for that port during those	78	; the hub whether there was a disconnect event for that port during those
79	; 100 ms (on the hardware level notifications are obtained using polling	79	; 100 ms (on the hardware level notifications are obtained using polling
80	; with some intervals, so it is possible that the corresponding notification	80	; with some intervals, so it is possible that the corresponding notification
81	; has not arrived yet);	81	; has not arrived yet);
82	; * usb_hub_connect_port_status checks that there was no disconnect event	82	; * usb_hub_connect_port_status checks that there was no disconnect event
83	; and sets HUB_RESET_WAITING flag (HUB_RESET_IN_PROGRESS is still set,	83	; and sets HUB_RESET_WAITING flag (HUB_RESET_IN_PROGRESS is still set,
84	; ConfigBuffer still contains the port index);	84	; ConfigBuffer still contains the port index);
85	; * usb_hub_process_deferred checks whether there is another device currently	85	; * usb_hub_process_deferred checks whether there is another device currently
86	; resetting. If so, it waits until reset is done	86	; resetting. If so, it waits until reset is done
87	; (with HUB_RESET_WAITING and HUB_RESET_IN_PROGRESS bits set);	87	; (with HUB_RESET_WAITING and HUB_RESET_IN_PROGRESS bits set);
88	; * usb_hub_process_deferred clears HUB_RESET_WAITING, sets HUB_RESET_SIGNAL	88	; * usb_hub_process_deferred clears HUB_RESET_WAITING, sets HUB_RESET_SIGNAL
89	; and initiates reset signalling on the port;	89	; and initiates reset signalling on the port;
90	; * usb_hub_process_deferred checks the status every tick;	90	; * usb_hub_process_deferred checks the status every tick;
91	; when reset signalling is stopped by the hub, usb_hub_resetting_port_status	91	; when reset signalling is stopped by the hub, usb_hub_resetting_port_status
92	; callback clears HUB_RESET_SIGNAL and sets HUB_RESET_RECOVERY;	92	; callback clears HUB_RESET_SIGNAL and sets HUB_RESET_RECOVERY;
93	; * 10 ms (at least) delay;	93	; * 10 ms (at least) delay;
94	; * usb_hub_process_deferred clears HUB_RESET_RECOVERY and notifies other code	94	; * usb_hub_process_deferred clears HUB_RESET_RECOVERY and notifies other code
95	; that the new device is ready to be configured;	95	; that the new device is ready to be configured;
96	; * when it is possible to reset another device, the protocol layer	96	; * when it is possible to reset another device, the protocol layer
97	; clears HUB_RESET_IN_PROGRESS bit.	97	; clears HUB_RESET_IN_PROGRESS bit.
98		98
99	; =============================================================================	99	; =============================================================================
100	; ================================ Structures =================================	100	; ================================ Structures =================================
101	; =============================================================================	101	; =============================================================================
102	; This structure contains all used data for one hub.	102	; This structure contains all used data for one hub.
103	struct usb_hub	103	struct usb_hub
104	; All configured hubs are organized in the global usb_hub_list.	104	; All configured hubs are organized in the global usb_hub_list.
105	; Two following fields give next/prev items in that list.	105	; Two following fields give next/prev items in that list.
106	; While the hub is unconfigured, they point to usb_hub itself.	106	; While the hub is unconfigured, they point to usb_hub itself.
107	Next dd ?	107	Next dd ?
108	Prev dd ?	108	Prev dd ?
109	Controller dd ?	109	Controller dd ?
110	; Pointer to usb_controller for the bus.	110	; Pointer to usb_controller for the bus.
111	;	111	;
112	; Handles of two pipes: configuration control pipe for zero endpoint opened by	112	; Handles of two pipes: configuration control pipe for zero endpoint opened by
113	; the common code and status interrupt pipe opened by us.	113	; the common code and status interrupt pipe opened by us.
114	ConfigPipe dd ?	114	ConfigPipe dd ?
115	StatusPipe dd ?	115	StatusPipe dd ?
116	NumPorts dd ?	116	NumPorts dd ?
117	; Number of downstream ports; from 1 to 255.	117	; Number of downstream ports; from 1 to 255.
118	MaxPacketSize dd ?	118	MaxPacketSize dd ?
119	; Maximum packet size for interrupt endpoint.	119	; Maximum packet size for interrupt endpoint.
120	; Usually equals ceil((1+NumPorts)/8), but some hubs give additional bytes.	120	; Usually equals ceil((1+NumPorts)/8), but some hubs give additional bytes.
121	Actions dd ?	121	Actions dd ?
122	; Bitfield with HUB_* constants.	122	; Bitfield with HUB_* constants.
123	PoweredOnTime dd ?	123	PoweredOnTime dd ?
124	; Time (in ticks) when all downstream ports were powered up.	124	; Time (in ticks) when all downstream ports were powered up.
125	ResetTime dd ?	125	ResetTime dd ?
126	; Time (in ticks) when the current port was reset;	126	; Time (in ticks) when the current port was reset;
127	; when a port is resetting, contains the last tick of status check;	127	; when a port is resetting, contains the last tick of status check;
128	; when reset recovery for a port is active, contains the time when	128	; when reset recovery for a port is active, contains the time when
129	; reset was completed.	129	; reset was completed.
130	;	130	;
131	; There are two possible reasons for configuration requests:	131	; There are two possible reasons for configuration requests:
132	; synchronous, when certain time is passed after something,	132	; synchronous, when certain time is passed after something,
133	; and asynchronous, when the hub is notifying about some change and	133	; and asynchronous, when the hub is notifying about some change and
134	; config request needs to be issued in order to query details.	134	; config request needs to be issued in order to query details.
135	; Use two different buffers to avoid unnecessary dependencies.	135	; Use two different buffers to avoid unnecessary dependencies.
136	ConfigBuffer rb 8	136	ConfigBuffer rb 8
137	; Buffer for configuration requests for synchronous events.	137	; Buffer for configuration requests for synchronous events.
138	ChangeConfigBuffer rb 8	138	ChangeConfigBuffer rb 8
139	; Buffer for configuration requests for status changes.	139	; Buffer for configuration requests for status changes.
140	AccStatusChange db ?	140	AccStatusChange db ?
141	; Accumulated status change. See 11.12.3 of USB2 spec or comments in code.	141	; Accumulated status change. See 11.12.3 of USB2 spec or comments in code.
142	HubCharacteristics dw ?	142	HubCharacteristics dw ?
143	; Copy of usb_hub_descr.wHubCharacteristics.	143	; Copy of usb_hub_descr.wHubCharacteristics.
144	PowerOnInterval db ?	144	PowerOnInterval db ?
145	; Copy of usb_hub_descr.bPwrOn2PwrGood.	145	; Copy of usb_hub_descr.bPwrOn2PwrGood.
146	;	146	;
147	; Two following fields are written at once by GET_STATUS request	147	; Two following fields are written at once by GET_STATUS request
148	; and must remain in this order.	148	; and must remain in this order.
149	StatusData dw ?	149	StatusData dw ?
150	; Bitfield with 1 shl PORT_* indicating status of the current port.	150	; Bitfield with 1 shl PORT_* indicating status of the current port.
151	StatusChange dw ?	151	StatusChange dw ?
152	; Bitfield with 1 shl PORT_* indicating change in status of the current port.	152	; Bitfield with 1 shl PORT_* indicating change in status of the current port.
153	; Two following fields are written at once by GET_STATUS request	153	; Two following fields are written at once by GET_STATUS request
154	; and must remain in this order.	154	; and must remain in this order.
155	; The meaning is the same as of StatusData/StatusChange; two following fields	155	; The meaning is the same as of StatusData/StatusChange; two following fields
156	; are used by the synchronous requests to avoid unnecessary interactions with	156	; are used by the synchronous requests to avoid unnecessary interactions with
157	; the asynchronous handler.	157	; the asynchronous handler.
158	ResetStatusData dw ?	158	ResetStatusData dw ?
159	ResetStatusChange dw ?	159	ResetStatusChange dw ?
160	StatusChangePtr dd ?	160	StatusChangePtr dd ?
161	; Pointer to StatusChangeBuf.	161	; Pointer to StatusChangeBuf.
162	ConnectedDevicesPtr dd ?	162	ConnectedDevicesPtr dd ?
163	; Pointer to ConnectedDevices.	163	; Pointer to ConnectedDevices.
164	ConnectedTimePtr dd ?	164	ConnectedTimePtr dd ?
165	; Pointer to ConnectedTime.	165	; Pointer to ConnectedTime.
166	;	166	;
167	; Variable-length parts:	167	; Variable-length parts:
168	; DeviceRemovable rb (NumPorts+8)/8	168	; DeviceRemovable rb (NumPorts+8)/8
169	; Bit i+1 = device at port i (zero-based) is non-removable.	169	; Bit i+1 = device at port i (zero-based) is non-removable.
170	; StatusChangeBuf rb (NumPorts+8)/8	170	; StatusChangeBuf rb (NumPorts+8)/8
171	; Buffer for status interrupt pipe. Bit 0 = hub status change,	171	; Buffer for status interrupt pipe. Bit 0 = hub status change,
172	; other bits = status change of the corresponding ports.	172	; other bits = status change of the corresponding ports.
173	; ConnectedDevices rd NumPorts	173	; ConnectedDevices rd NumPorts
174	; Pointers to config pipes for connected devices or zero if no device connected.	174	; Pointers to config pipes for connected devices or zero if no device connected.
175	; ConnectedTime rd NumPorts	175	; ConnectedTime rd NumPorts
176	; For initial debounce interval:	176	; For initial debounce interval:
177	; time (in ticks) when a device was connected at that port.	177	; time (in ticks) when a device was connected at that port.
178	; Normally: -1	178	; Normally: -1
179	ends	179	ends
180		180
181	; Hub descriptor.	181	; Hub descriptor.
182	struct usb_hub_descr usb_descr	182	struct usb_hub_descr usb_descr
183	bNbrPorts db ?	183	bNbrPorts db ?
184	; Number of downstream ports.	184	; Number of downstream ports.
185	wHubCharacteristics dw ?	185	wHubCharacteristics dw ?
186	; Bit 0: 0 = all ports are powered at once, 1 = individual port power switching	186	; Bit 0: 0 = all ports are powered at once, 1 = individual port power switching
187	; Bit 1: reserved, must be zero	187	; Bit 1: reserved, must be zero
188	; Bit 2: 1 = the hub is part of a compound device	188	; Bit 2: 1 = the hub is part of a compound device
189	; Bits 3-4: 00 = global overcurrent protection,	189	; Bits 3-4: 00 = global overcurrent protection,
190	; 01 = individual port overcurrent protection,	190	; 01 = individual port overcurrent protection,
191	; 1x = no overcurrent protection	191	; 1x = no overcurrent protection
192	; Bits 5-6: Transaction Translator Think Time, 8*(value+1) full-speed bit times	192	; Bits 5-6: Transaction Translator Think Time, 8*(value+1) full-speed bit times
193	; Bit 7: 1 = port indicators supported	193	; Bit 7: 1 = port indicators supported
194	; Other bits are reserved.	194	; Other bits are reserved.
195	bPwrOn2PwrGood db ?	195	bPwrOn2PwrGood db ?
196	; Time in 2ms intervals between powering up a port and a port becoming ready.	196	; Time in 2ms intervals between powering up a port and a port becoming ready.
197	bHubContrCurrent db ?	197	bHubContrCurrent db ?
198	; Maximum current requirements of the Hub Controller electronics in mA.	198	; Maximum current requirements of the Hub Controller electronics in mA.
199	; DeviceRemovable - variable length	199	; DeviceRemovable - variable length
200	; Bit 0 is reserved, bit i+1 = device at port i is non-removable.	200	; Bit 0 is reserved, bit i+1 = device at port i is non-removable.
201	; PortPwrCtrlMask - variable length	201	; PortPwrCtrlMask - variable length
202	; Obsolete, exists for compatibility. We ignore it.	202	; Obsolete, exists for compatibility. We ignore it.
203	ends	203	ends
204		204
205	iglobal	205	iglobal
206	align 4	206	align 4
207	; Implementation of struct USBFUNC for hubs.	207	; Implementation of struct USBFUNC for hubs.
208	usb_hub_callbacks:	208	usb_hub_callbacks:
209	dd usb_hub_callbacks_end - usb_hub_callbacks	209	dd usb_hub_callbacks_end - usb_hub_callbacks
210	dd usb_hub_init	210	dd usb_hub_init
211	dd usb_hub_disconnect	211	dd usb_hub_disconnect
212	usb_hub_callbacks_end:	212	usb_hub_callbacks_end:
213	usb_hub_pseudosrv dd usb_hub_callbacks	213	usb_hub_pseudosrv dd usb_hub_callbacks
214	endg	214	endg
215		215
216	; This procedure is called when new hub is detected.	216	; This procedure is called when new hub is detected.
217	; It initializes the device.	217	; It initializes the device.
218	; Technically, initialization implies sending several USB queries,	218	; Technically, initialization implies sending several USB queries,
219	; so it is split in several procedures. The first is usb_hub_init,	219	; so it is split in several procedures. The first is usb_hub_init,
220	; other are callbacks which will be called at some time in the future,	220	; other are callbacks which will be called at some time in the future,
221	; when the device will respond.	221	; when the device will respond.
222	; edx = usb_interface_descr, ecx = length rest	222	; edx = usb_interface_descr, ecx = length rest
223	proc usb_hub_init	223	proc usb_hub_init
224	push ebx esi ; save used registers to be stdcall	224	push ebx esi ; save used registers to be stdcall
225	virtual at esp	225	virtual at esp
226	rd 2 ; saved registers	226	rd 2 ; saved registers
227	dd ? ; return address	227	dd ? ; return address
228	.pipe dd ? ; handle of the config pipe	228	.pipe dd ? ; handle of the config pipe
229	.config dd ? ; pointer to usb_config_descr	229	.config dd ? ; pointer to usb_config_descr
230	.interface dd ? ; pointer to usb_interface_descr	230	.interface dd ? ; pointer to usb_interface_descr
231	end virtual	231	end virtual
232	; 1. Check that the maximal nesting is not exceeded:	232	; 1. Check that the maximal nesting is not exceeded:
233	; 5 non-root hubs is the maximum according to the spec.	233	; 5 non-root hubs is the maximum according to the spec.
234	mov ebx, [.pipe]	234	mov ebx, [.pipe]
235	push 5	235	push 5
236	mov eax, ebx	236	mov eax, ebx
237	.count_parents:	237	.count_parents:
238	mov eax, [eax+usb_pipe.DeviceData]	238	mov eax, [eax+usb_pipe.DeviceData]
239	mov eax, [eax+usb_device_data.Hub]	239	mov eax, [eax+usb_device_data.Hub]
240	test eax, eax	240	test eax, eax
241	jz .depth_ok	241	jz .depth_ok
242	mov eax, [eax+usb_hub.ConfigPipe]	242	mov eax, [eax+usb_hub.ConfigPipe]
243	dec dword [esp]	243	dec dword [esp]
244	jnz .count_parents	244	jnz .count_parents
245	pop eax	245	pop eax
246	dbgstr 'Hub chain is too long'	246	dbgstr 'Hub chain is too long'
247	jmp .return0	247	jmp .return0
248	.depth_ok:	248	.depth_ok:
249	pop eax	249	pop eax
250	; Hubs use one IN interrupt endpoint for polling the device	250	; Hubs use one IN interrupt endpoint for polling the device
251	; 2. Locate the descriptor of the interrupt endpoint.	251	; 2. Locate the descriptor of the interrupt endpoint.
252	; Loop over all descriptors owned by this interface.	252	; Loop over all descriptors owned by this interface.
253	.lookep:	253	.lookep:
254	; 2a. Skip the current descriptor.	254	; 2a. Skip the current descriptor.
255	movzx eax, [edx+usb_descr.bLength]	255	movzx eax, [edx+usb_descr.bLength]
256	add edx, eax	256	add edx, eax
257	sub ecx, eax	257	sub ecx, eax
258	jb .errorep	258	jb .errorep
259	; 2b. Length of data left must be at least sizeof.usb_endpoint_descr.	259	; 2b. Length of data left must be at least sizeof.usb_endpoint_descr.
260	cmp ecx, sizeof.usb_endpoint_descr	260	cmp ecx, sizeof.usb_endpoint_descr
261	jb .errorep	261	jb .errorep
262	; 2c. If we have found another interface descriptor but not found our endpoint,	262	; 2c. If we have found another interface descriptor but not found our endpoint,
263	; this is an error: all subsequent descriptors belong to that interface	263	; this is an error: all subsequent descriptors belong to that interface
264	; (or further interfaces).	264	; (or further interfaces).
265	cmp [edx+usb_endpoint_descr.bDescriptorType], USB_INTERFACE_DESCR	265	cmp [edx+usb_endpoint_descr.bDescriptorType], USB_INTERFACE_DESCR
266	jz .errorep	266	jz .errorep
267	; 2d. Ignore all interface-related descriptors except endpoint descriptor.	267	; 2d. Ignore all interface-related descriptors except endpoint descriptor.
268	cmp [edx+usb_endpoint_descr.bDescriptorType], USB_ENDPOINT_DESCR	268	cmp [edx+usb_endpoint_descr.bDescriptorType], USB_ENDPOINT_DESCR
269	jnz .lookep	269	jnz .lookep
270	; 2e. Length of endpoint descriptor must be at least sizeof.usb_endpoint_descr.	270	; 2e. Length of endpoint descriptor must be at least sizeof.usb_endpoint_descr.
271	cmp [edx+usb_endpoint_descr.bLength], sizeof.usb_endpoint_descr	271	cmp [edx+usb_endpoint_descr.bLength], sizeof.usb_endpoint_descr
272	jb .errorep	272	jb .errorep
273	; 2f. Ignore all endpoints except for INTERRUPT IN.	273	; 2f. Ignore all endpoints except for INTERRUPT IN.
274	cmp [edx+usb_endpoint_descr.bEndpointAddress], 0	274	cmp [edx+usb_endpoint_descr.bEndpointAddress], 0
275	jge .lookep	275	jge .lookep
276	mov al, [edx+usb_endpoint_descr.bmAttributes]	276	mov al, [edx+usb_endpoint_descr.bmAttributes]
277	and al, 3	277	and al, 3
278	cmp al, INTERRUPT_PIPE	278	cmp al, INTERRUPT_PIPE
279	jnz .lookep	279	jnz .lookep
280	; We have located the descriptor for INTERRUPT IN endpoint,	280	; We have located the descriptor for INTERRUPT IN endpoint,
281	; the pointer is in edx.	281	; the pointer is in edx.
282	; 3. Allocate memory for the hub descriptor.	282	; 3. Allocate memory for the hub descriptor.
283	; Maximum length (assuming 255 downstream ports) is 40 bytes.	283	; Maximum length (assuming 255 downstream ports) is 40 bytes.
284	; Allocate 4 extra bytes to keep wMaxPacketSize.	284	; Allocate 4 extra bytes to keep wMaxPacketSize.
285	; 3a. Save registers.	285	; 3a. Save registers.
286	push edx	286	push edx
287	; 3b. Call the allocator.	287	; 3b. Call the allocator.
288	movi eax, 44	288	movi eax, 44
289	call malloc	289	call malloc
290	; 3c. Restore registers.	290	; 3c. Restore registers.
291	pop ecx	291	pop ecx
292	; 3d. If failed, say something to the debug board and return error.	292	; 3d. If failed, say something to the debug board and return error.
293	test eax, eax	293	test eax, eax
294	jz .nomemory	294	jz .nomemory
295	; 3e. Store the pointer in esi. xchg eax,r32 is one byte shorter than mov.	295	; 3e. Store the pointer in esi. xchg eax,r32 is one byte shorter than mov.
296	xchg esi, eax	296	xchg esi, eax
297	; 4. Open a pipe for the status endpoint with descriptor found in step 1.	297	; 4. Open a pipe for the status endpoint with descriptor found in step 1.
298	movzx eax, [ecx+usb_endpoint_descr.bEndpointAddress]	298	movzx eax, [ecx+usb_endpoint_descr.bEndpointAddress]
299	movzx edx, [ecx+usb_endpoint_descr.bInterval]	299	movzx edx, [ecx+usb_endpoint_descr.bInterval]
300	movzx ecx, [ecx+usb_endpoint_descr.wMaxPacketSize]	300	movzx ecx, [ecx+usb_endpoint_descr.wMaxPacketSize]
301	test ecx, (1 shl 11) - 1	301	test ecx, (1 shl 11) - 1
302	jz .free	302	jz .free
303	push ecx	303	push ecx
304	stdcall usb_open_pipe, ebx, eax, ecx, INTERRUPT_PIPE, edx	304	stdcall usb_open_pipe, ebx, eax, ecx, INTERRUPT_PIPE, edx
305	pop ecx	305	pop ecx
306	; If failed, free the memory allocated in step 3,	306	; If failed, free the memory allocated in step 3,
307	; say something to the debug board and return error.	307	; say something to the debug board and return error.
308	test eax, eax	308	test eax, eax
309	jz .free	309	jz .free
310	; 5. Send control query for the hub descriptor,	310	; 5. Send control query for the hub descriptor,
311	; pass status pipe as a callback parameter,	311	; pass status pipe as a callback parameter,
312	; allow short packets.	312	; allow short packets.
313	and ecx, (1 shl 11) - 1	313	and ecx, (1 shl 11) - 1
314	mov [esi+40], ecx	314	mov [esi+40], ecx
315	mov dword [esi], 0xA0 + \ ; class-specific request	315	mov dword [esi], 0xA0 + \ ; class-specific request
316	(USB_GET_DESCRIPTOR shl 8) + \	316	(USB_GET_DESCRIPTOR shl 8) + \
317	(0 shl 16) + \ ; descriptor index 0	317	(0 shl 16) + \ ; descriptor index 0
318	(USB_HUB_DESCRIPTOR shl 24)	318	(USB_HUB_DESCRIPTOR shl 24)
319	mov dword [esi+4], 40 shl 16	319	mov dword [esi+4], 40 shl 16
320	stdcall usb_control_async, ebx, esi, esi, 40, usb_hub_got_config, eax, 1	320	stdcall usb_control_async, ebx, esi, esi, 40, usb_hub_got_config, eax, 1
321	; 6. If failed, free the memory allocated in step 3,	321	; 6. If failed, free the memory allocated in step 3,
322	; say something to the debug board and return error.	322	; say something to the debug board and return error.
323	test eax, eax	323	test eax, eax
324	jz .free	324	jz .free
325	; Otherwise, return 1. usb_hub_got_config will overwrite it later.	325	; Otherwise, return 1. usb_hub_got_config will overwrite it later.
326	xor eax, eax	326	xor eax, eax
327	inc eax	327	inc eax
328	jmp .nothing	328	jmp .nothing
329	.free:	329	.free:
330	xchg eax, esi	330	xchg eax, esi
331	call free	331	call free
332	jmp .return0	332	jmp .return0
333	.errorep:	333	.errorep:
334	dbgstr 'Invalid config descriptor for a hub'	334	dbgstr 'Invalid config descriptor for a hub'
335	jmp .return0	335	jmp .return0
336	.nomemory:	336	.nomemory:
337	dbgstr 'No memory for USB hub data'	337	dbgstr 'No memory for USB hub data'
338	.return0:	338	.return0:
339	xor eax, eax	339	xor eax, eax
340	.nothing:	340	.nothing:
341	pop esi ebx ; restore used registers to be stdcall	341	pop esi ebx ; restore used registers to be stdcall
342	retn 12	342	retn 12
343	endp	343	endp
344		344
345	; This procedure is called when the request for the hub descriptor initiated	345	; This procedure is called when the request for the hub descriptor initiated
346	; by usb_hub_init is finished, either successfully or unsuccessfully.	346	; by usb_hub_init is finished, either successfully or unsuccessfully.
347	proc usb_hub_got_config stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword	347	proc usb_hub_got_config stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
348	push ebx ; save used registers to be stdcall	348	push ebx ; save used registers to be stdcall
349	; 1. If failed, say something to the debug board, free the buffer	349	; 1. If failed, say something to the debug board, free the buffer
350	; and stop the initialization.	350	; and stop the initialization.
351	cmp [status], 0	351	cmp [status], 0
352	jnz .invalid	352	jnz .invalid
353	; 2. The length must be at least sizeof.usb_hub_descr.	353	; 2. The length must be at least sizeof.usb_hub_descr.
354	; Note that [length] includes 8 bytes of setup packet.	354	; Note that [length] includes 8 bytes of setup packet.
355	cmp [length], 8 + sizeof.usb_hub_descr	355	cmp [length], 8 + sizeof.usb_hub_descr
356	jb .invalid	356	jb .invalid
357	; 3. Sanity checks for the hub descriptor.	357	; 3. Sanity checks for the hub descriptor.
358	mov eax, [buffer]	358	mov eax, [buffer]
359	if USB_DUMP_DESCRIPTORS	359	if USB_DUMP_DESCRIPTORS
360	mov ecx, [length]	360	mov ecx, [length]
361	sub ecx, 8	361	sub ecx, 8
362	DEBUGF 1,'K : hub config:'	362	DEBUGF 1,'K : hub config:'
363	push eax	363	push eax
364	@@:	364	@@:
365	DEBUGF 1,' %x',[eax]:2	365	DEBUGF 1,' %x',[eax]:2
366	inc eax	366	inc eax
367	dec ecx	367	dec ecx
368	jnz @b	368	jnz @b
369	DEBUGF 1,'\n'	369	DEBUGF 1,'\n'
370	pop eax	370	pop eax
371	end if	371	end if
372	cmp [eax+usb_hub_descr.bLength], sizeof.usb_hub_descr	372	cmp [eax+usb_hub_descr.bLength], sizeof.usb_hub_descr
373	jb .invalid	373	jb .invalid
374	cmp [eax+usb_hub_descr.bDescriptorType], USB_HUB_DESCRIPTOR	374	cmp [eax+usb_hub_descr.bDescriptorType], USB_HUB_DESCRIPTOR
375	jnz .invalid	375	jnz .invalid
376	movzx ecx, [eax+usb_hub_descr.bNbrPorts]	376	movzx ecx, [eax+usb_hub_descr.bNbrPorts]
377	test ecx, ecx	377	test ecx, ecx
378	jz .invalid	378	jz .invalid
379	; 4. We use sizeof.usb_hub_descr bytes plus DeviceRemovable info;	379	; 4. We use sizeof.usb_hub_descr bytes plus DeviceRemovable info;
380	; size of DeviceRemovable is (NumPorts+1) bits, this gives	380	; size of DeviceRemovable is (NumPorts+1) bits, this gives
381	; floor(NumPorts/8)+1 bytes. Check that all data are present in the	381	; floor(NumPorts/8)+1 bytes. Check that all data are present in the
382	; descriptor and were successfully read.	382	; descriptor and were successfully read.
383	mov edx, ecx	383	mov edx, ecx
384	shr edx, 3	384	shr edx, 3
385	add edx, sizeof.usb_hub_descr + 1	385	add edx, sizeof.usb_hub_descr + 1
386	cmp [eax+usb_hub_descr.bLength], dl	386	cmp [eax+usb_hub_descr.bLength], dl
387	jb .invalid	387	jb .invalid
388	sub [length], 8	388	sub [length], 8
389	cmp [length], edx	389	cmp [length], edx
390	jb .invalid	390	jb .invalid
391	; 5. Allocate the memory for usb_hub structure.	391	; 5. Allocate the memory for usb_hub structure.
392	; Total size of variable-length data is ALIGN_UP(floor(NumPorts/8)+1+MaxPacketSize,4)+8*NumPorts.	392	; Total size of variable-length data is ALIGN_UP(floor(NumPorts/8)+1+MaxPacketSize,4)+8*NumPorts.
393	add edx, [eax+40]	393	add edx, [eax+40]
394	add edx, sizeof.usb_hub - sizeof.usb_hub_descr + 3	394	add edx, sizeof.usb_hub - sizeof.usb_hub_descr + 3
395	and edx, not 3	395	and edx, not 3
396	lea eax, [edx+ecx*8]	396	lea eax, [edx+ecx*8]
397	push ecx edx	397	push ecx edx
398	call malloc	398	call malloc
399	pop edx ecx	399	pop edx ecx
400	test eax, eax	400	test eax, eax
401	jz .nomemory	401	jz .nomemory
402	xchg eax, ebx	402	xchg eax, ebx
403	; 6. Fill usb_hub structure.	403	; 6. Fill usb_hub structure.
404	mov [ebx+usb_hub.NumPorts], ecx	404	mov [ebx+usb_hub.NumPorts], ecx
405	add edx, ebx	405	add edx, ebx
406	mov [ebx+usb_hub.ConnectedDevicesPtr], edx	406	mov [ebx+usb_hub.ConnectedDevicesPtr], edx
407	mov eax, [pipe]	407	mov eax, [pipe]
408	mov [ebx+usb_hub.ConfigPipe], eax	408	mov [ebx+usb_hub.ConfigPipe], eax
409	mov edx, [eax+usb_pipe.Controller]	409	mov edx, [eax+usb_pipe.Controller]
410	mov [ebx+usb_hub.Controller], edx	410	mov [ebx+usb_hub.Controller], edx
411	mov eax, [calldata]	411	mov eax, [calldata]
412	mov [ebx+usb_hub.StatusPipe], eax	412	mov [ebx+usb_hub.StatusPipe], eax
413	push esi edi	413	push esi edi
414	mov esi, [buffer]	414	mov esi, [buffer]
415	mov eax, [esi+40]	415	mov eax, [esi+40]
416	mov [ebx+usb_hub.MaxPacketSize], eax	416	mov [ebx+usb_hub.MaxPacketSize], eax
417	; The following commands load bNbrPorts, wHubCharacteristics, bPwrOn2PwrGood.	417	; The following commands load bNbrPorts, wHubCharacteristics, bPwrOn2PwrGood.
418	mov edx, dword [esi+usb_hub_descr.bNbrPorts]	418	mov edx, dword [esi+usb_hub_descr.bNbrPorts]
419	mov dl, 0	419	mov dl, 0
420	; The following command zeroes AccStatusChange and stores	420	; The following command zeroes AccStatusChange and stores
421	; HubCharacteristics and PowerOnInterval.	421	; HubCharacteristics and PowerOnInterval.
422	mov dword [ebx+usb_hub.AccStatusChange], edx	422	mov dword [ebx+usb_hub.AccStatusChange], edx
423	xor eax, eax	423	xor eax, eax
424	mov [ebx+usb_hub.Actions], eax	424	mov [ebx+usb_hub.Actions], eax
425	; Copy DeviceRemovable data.	425	; Copy DeviceRemovable data.
426	lea edi, [ebx+sizeof.usb_hub]	426	lea edi, [ebx+sizeof.usb_hub]
427	add esi, sizeof.usb_hub_descr	427	add esi, sizeof.usb_hub_descr
428	mov edx, ecx	428	mov edx, ecx
429	shr ecx, 3	429	shr ecx, 3
430	inc ecx	430	inc ecx
431	rep movsb	431	rep movsb
432	mov [ebx+usb_hub.StatusChangePtr], edi	432	mov [ebx+usb_hub.StatusChangePtr], edi
433	; Zero ConnectedDevices.	433	; Zero ConnectedDevices.
434	mov edi, [ebx+usb_hub.ConnectedDevicesPtr]	434	mov edi, [ebx+usb_hub.ConnectedDevicesPtr]
435	mov ecx, edx	435	mov ecx, edx
436	rep stosd	436	rep stosd
437	mov [ebx+usb_hub.ConnectedTimePtr], edi	437	mov [ebx+usb_hub.ConnectedTimePtr], edi
438	; Set ConnectedTime to -1.	438	; Set ConnectedTime to -1.
439	dec eax	439	dec eax
440	mov ecx, edx	440	mov ecx, edx
441	rep stosd	441	rep stosd
442	pop edi esi	442	pop edi esi
443	; 7. Replace value of 1 returned from usb_hub_init to the real value.	443	; 7. Replace value of 1 returned from usb_hub_init to the real value.
444	; Note: hubs are part of the core USB code, so this code can work with	444	; Note: hubs are part of the core USB code, so this code can work with
445	; internals of other parts. Another way, the only possible one for external	445	; internals of other parts. Another way, the only possible one for external
446	; drivers, is to use two memory allocations: one (returned from AddDevice and	446	; drivers, is to use two memory allocations: one (returned from AddDevice and
447	; fixed after that) for pointer, another for real data. That would work also,	447	; fixed after that) for pointer, another for real data. That would work also,
448	; but wastes one allocation.	448	; but wastes one allocation.
449	mov eax, [pipe]	449	mov eax, [pipe]
450	mov eax, [eax+usb_pipe.DeviceData]	450	mov eax, [eax+usb_pipe.DeviceData]
451	add eax, [eax+usb_device_data.Interfaces]	451	add eax, [eax+usb_device_data.Interfaces]
452	.scan:	452	.scan:
453	cmp [eax+usb_interface_data.DriverData], 1	453	cmp [eax+usb_interface_data.DriverData], 1
454	jnz @f	454	jnz @f
455	cmp [eax+usb_interface_data.DriverFunc], usb_hub_pseudosrv - USBSRV.usb_func	455	cmp [eax+usb_interface_data.DriverFunc], usb_hub_pseudosrv - USBSRV.usb_func
456	jz .scan_found	456	jz .scan_found
457	@@:	457	@@:
458	add eax, sizeof.usb_interface_data	458	add eax, sizeof.usb_interface_data
459	jmp .scan	459	jmp .scan
460	.scan_found:	460	.scan_found:
461	mov [eax+usb_interface_data.DriverData], ebx	461	mov [eax+usb_interface_data.DriverData], ebx
462	; 8. Insert the hub structure to the tail of the overall list of all hubs.	462	; 8. Insert the hub structure to the tail of the overall list of all hubs.
463	mov ecx, usb_hubs_list	463	mov ecx, usb_hubs_list
464	mov edx, [ecx+usb_hub.Prev]	464	mov edx, [ecx+usb_hub.Prev]
465	mov [ecx+usb_hub.Prev], ebx	465	mov [ecx+usb_hub.Prev], ebx
466	mov [edx+usb_hub.Next], ebx	466	mov [edx+usb_hub.Next], ebx
467	mov [ebx+usb_hub.Prev], edx	467	mov [ebx+usb_hub.Prev], edx
468	mov [ebx+usb_hub.Next], ecx	468	mov [ebx+usb_hub.Next], ecx
469	; 9. Start powering up all ports.	469	; 9. Start powering up all ports.
470	DEBUGF 1,'K : found hub with %d ports\n',[ebx+usb_hub.NumPorts]	470	DEBUGF 1,'K : found hub with %d ports\n',[ebx+usb_hub.NumPorts]
471	lea eax, [ebx+usb_hub.ConfigBuffer]	471	lea eax, [ebx+usb_hub.ConfigBuffer]
472	xor ecx, ecx	472	xor ecx, ecx
473	mov dword [eax], 23h + \ ; class-specific request to hub port	473	mov dword [eax], 23h + \ ; class-specific request to hub port
474	(USB_SET_FEATURE shl 8) + \	474	(USB_SET_FEATURE shl 8) + \
475	(PORT_POWER shl 16)	475	(PORT_POWER shl 16)
476	mov edx, [ebx+usb_hub.NumPorts]	476	mov edx, [ebx+usb_hub.NumPorts]
477	mov dword [eax+4], edx	477	mov dword [eax+4], edx
478	stdcall usb_control_async, [ebx+usb_hub.ConfigPipe], eax, ecx, ecx, usb_hub_port_powered, ebx, ecx	478	stdcall usb_control_async, [ebx+usb_hub.ConfigPipe], eax, ecx, ecx, usb_hub_port_powered, ebx, ecx
479	.freebuf:	479	.freebuf:
480	; 10. Free the buffer for hub descriptor and return.	480	; 10. Free the buffer for hub descriptor and return.
481	mov eax, [buffer]	481	mov eax, [buffer]
482	call free	482	call free
483	pop ebx ; restore used registers to be stdcall	483	pop ebx ; restore used registers to be stdcall
484	ret	484	ret
485	.nomemory:	485	.nomemory:
486	dbgstr 'No memory for USB hub data'	486	dbgstr 'No memory for USB hub data'
487	jmp .freebuf	487	jmp .freebuf
488	.invalid:	488	.invalid:
489	dbgstr 'Invalid hub descriptor'	489	dbgstr 'Invalid hub descriptor'
490	jmp .freebuf	490	jmp .freebuf
491	endp	491	endp
492		492
493	; This procedure is called when the request to power up some port is completed,	493	; This procedure is called when the request to power up some port is completed,
494	; either successfully or unsuccessfully.	494	; either successfully or unsuccessfully.
495	proc usb_hub_port_powered stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword	495	proc usb_hub_port_powered stdcall, pipe:dword, status:dword, buffer:dword, length:dword, calldata:dword
496	; 1. Check whether the operation was successful.	496	; 1. Check whether the operation was successful.
497	; If not, say something to the debug board and ssstop the initialization.	497	; If not, say something to the debug board and ssstop the initialization.
498	cmp [status], 0	498	cmp [status], 0
499	jnz .invalid	499	jnz .invalid
500	; 2. Check whether all ports were powered.	500	; 2. Check whether all ports were powered.

Subversion Repositories Kolibri OS

(root)/kernel/branches/Kolibri-acpi/bus/usb/hub.inc – Rev 5201 → 5565