kolibrios-gitea/kernel/trunk/bus/usb/hccommon.inc

; USB Host Controller support code: hardware-independent part,
; common for all controller types.

; =============================================================================
; ================================= Constants =================================
; =============================================================================
; USB device must have at least 100ms of stable power before initializing can
; proceed; one timer tick is 10ms, so enforce delay in 10 ticks
USB_CONNECT_DELAY = 10
; USB requires at least 10 ms for reset signalling. Normally, this is one timer
; tick. However, it is possible that we start reset signalling in the end of
; interval between timer ticks and then we test time in the start of the next
; interval; in this case, the delta between [timer_ticks] is 1, but the real
; time passed is significantly less than 10 ms. To avoid this, we add an extra
; tick; this guarantees that at least 10 ms have passed.
USB_RESET_TIME = 2
; USB requires at least 10 ms of reset recovery, a delay between reset
; signalling and any commands to device. Add an extra tick for the same reasons
; as with the previous constant.
USB_RESET_RECOVERY_TIME = 2

; =============================================================================
; ================================ Structures =================================
; =============================================================================
; Controller descriptor.
; This structure represents the common (controller-independent) part
; of a controller for the USB code. The corresponding controller-dependent
; part *hci_controller is located immediately before usb_controller.
struct usb_controller
; Two following fields organize all controllers in the global linked list.
Next            dd      ?
Prev            dd      ?
HardwareFunc    dd      ?
; Pointer to usb_hardware_func structure with controller-specific functions.
NumPorts        dd      ?
; Number of ports in the root hub.
SetAddressBuffer        rb      8
; Buffer for USB control command SET_ADDRESS.
ExistingAddresses       rd      128/32
; Bitmask for 128 bits; bit i is cleared <=> address i is free for allocating
; for new devices. Bit 0 is always set.
;
; The hardware is allowed to cache some data from hardware structures.
; Regular operations are designed considering this,
; but sometimes it is required to wait for synchronization of hardware cache
; with modified structures in memory.
; The code keeps two queues of pipes waiting for synchronization,
; one for asynchronous (bulk/control) pipes, one for periodic pipes, hardware
; cache is invalidated under different conditions for those types.
; Both queues are organized in the same way, as single-linked lists.
; There are three special positions: the head of list (new pipes are added
; here), the first pipe to be synchronized at the current iteration,
; the tail of list (all pipes starting from here are synchronized).
WaitPipeListAsync       dd      ?
WaitPipeListPeriodic    dd      ?
; List heads.
WaitPipeRequestAsync    dd      ?
WaitPipeRequestPeriodic dd      ?
; Pending request to hardware to refresh cache for items from WaitPipeList*.
; (Pointers to some items in WaitPipeList* or NULLs).
ReadyPipeHeadAsync      dd      ?
ReadyPipeHeadPeriodic   dd      ?
; Items of RemovingList* which were released by hardware and are ready
; for further processing.
; (Pointers to some items in WaitPipeList* or NULLs).
NewConnected    dd      ?
; bit mask of recently connected ports of the root hub,
; bit set = a device was recently connected to the corresponding port;
; after USB_CONNECT_DELAY ticks of stable status these ports are moved to
; PendingPorts
NewDisconnected dd      ?
; bit mask of disconnected ports of the root hub,
; bit set = a device in the corresponding port was disconnected,
; disconnect processing is required.
PendingPorts    dd      ?
; bit mask of ports which are ready to be initialized
ControlLock     MUTEX   ?
; mutex which guards all operations with control queue
BulkLock        MUTEX   ?
; mutex which guards all operations with bulk queue
PeriodicLock    MUTEX   ?
; mutex which guards all operations with periodic queues
WaitSpinlock:
; spinlock guarding WaitPipeRequest/ReadyPipeHead (but not WaitPipeList)
StartWaitFrame  dd      ?
; USB frame number when WaitPipeRequest* was registered.
ResettingHub    dd      ?
; Pointer to usb_hub responsible for the currently resetting port, if any.
; NULL for the root hub.
ResettingPort   db      ?
; Port that is currently resetting, 0-based.
ResettingSpeed  db      ?
; Speed of currently resetting device.
ResettingStatus db      ?
; Status of port reset. 0 = no port is resetting, -1 = reset failed,
; 1 = reset in progress, 2 = reset recovery in progress.
                rb      1       ; alignment
ResetTime       dd      ?
; Time when reset signalling or reset recovery has been started.
ConnectedTime   rd      16
; Time, in timer ticks, when the port i has signalled the connect event.
; Valid only if bit i in NewConnected is set.
DevicesByPort   rd      16
; Pointer to usb_pipe for zero endpoint (which serves as device handle)
; for each port.
ends

; Interface-specific data. Several interfaces of one device can operate
; independently, each is controlled by some driver and is identified by
; some driver-specific data passed as is to the driver.
struct usb_interface_data
DriverData      dd      ?
; Passed as is to the driver.
DriverFunc      dd      ?
; Pointer to USBSRV structure for the driver.
ends

; Device-specific data.
struct usb_device_data
PipeListLock    MUTEX
; Lock guarding OpenedPipeList. Must be the first item of the structure,
; the code passes pointer to usb_device_data as is to mutex_lock/unlock.
OpenedPipeList  rd      2
; List of all opened pipes for the device.
; Used when the device is disconnected, so all pipes should be closed.
ClosedPipeList  rd      2
; List of all closed, but still valid pipes for the device.
; A pipe closed with USBClosePipe is just deallocated,
; but a pipe closed due to disconnect must remain valid until driver-provided
; disconnect handler returns; this list links all such pipes to deallocate them
; after disconnect processing.
NumPipes        dd      ?
; Number of not-yet-closed pipes.
Hub             dd      ?
; NULL if connected to the root hub, pointer to usb_hub otherwise.
TTHub           dd      ?
; Pointer to usb_hub for (the) hub with Transaction Translator for the device,
; NULL if the device operates in the same speed as the controller.
Port            db      ?
; Port on the hub, zero-based.
TTPort          db      ?
; Port on the TTHub, zero-based.
DeviceDescrSize db      ?
; Size of device descriptor.
Speed           db      ?
; Device speed, one of USB_SPEED_*.
NumInterfaces   dd      ?
; Number of interfaces.
ConfigDataSize  dd      ?
; Total size of data associated with the configuration descriptor
; (including the configuration descriptor itself).
Interfaces      dd      ?
; Offset from the beginning of this structure to Interfaces field.
; Variable-length fields:
; DeviceDescriptor:
;  device descriptor starts here
; ConfigDescriptor = DeviceDescriptor + DeviceDescrSize
;  configuration descriptor with all associated data
; Interfaces = ALIGN_UP(ConfigDescriptor + ConfigDataSize, 4)
;  array of NumInterfaces elements of type usb_interface_data
ends

usb_device_data.DeviceDescriptor = sizeof.usb_device_data

; Description of controller-specific data and functions.
struct usb_hardware_func
ID              dd      ?       ; '*HCI'
DataSize        dd      ?       ; sizeof(*hci_controller)
Init            dd      ?
; Initialize controller-specific part of controller data.
; in: eax -> *hci_controller to initialize, [ebp-4] = (bus shl 8) + devfn
; out: eax = 0 <=> failed, otherwise eax -> usb_controller
ProcessDeferred dd      ?
; Called regularly from the main loop of USB thread
; (either due to timeout from a previous call, or due to explicit wakeup).
; in: esi -> usb_controller
; out: eax = maximum timeout for next call (-1 = infinity)
SetDeviceAddress        dd      ?
; in: esi -> usb_controller, ebx -> usb_pipe, cl = address
GetDeviceAddress        dd      ?
; in: esi -> usb_controller, ebx -> usb_pipe
; out: eax = address
PortDisable             dd      ?
; Disable the given port in the root hub.
; in: esi -> usb_controller, ecx = port (zero-based)
InitiateReset           dd      ?
; Start reset signalling on the given port.
; in: esi -> usb_controller, ecx = port (zero-based)
SetEndpointPacketSize   dd      ?
; in: esi -> usb_controller, ebx -> usb_pipe, ecx = packet size
AllocPipe               dd      ?
; out: eax = pointer to allocated usb_pipe
FreePipe                dd      ?
; void stdcall with one argument = pointer to previously allocated usb_pipe
InitPipe                dd      ?
; in: edi -> usb_pipe for target, ecx -> usb_pipe for config pipe,
; esi -> usb_controller, eax -> usb_gtd for the first TD,
; [ebp+12] = endpoint, [ebp+16] = maxpacket, [ebp+20] = type
UnlinkPipe              dd      ?
; esi -> usb_controller, ebx -> usb_pipe
AllocTD                 dd      ?
; out: eax = pointer to allocated usb_gtd
FreeTD                  dd      ?
; void stdcall with one argument = pointer to previously allocated usb_gtd
AllocTransfer           dd      ?
; Allocate and initialize one stage of a transfer.
; ebx -> usb_pipe, other parameters are passed through the stack:
; buffer,size = data to transfer
; flags = same as in usb_open_pipe:
;   bit 0 = allow short transfer, other bits reserved
; td = pointer to the current end-of-queue descriptor
; direction =
;   0000b for normal transfers,
;   1000b for control SETUP transfer,
;   1101b for control OUT transfer,
;   1110b for control IN transfer
; returns eax = pointer to the new end-of-queue descriptor
; (not included in the queue itself) or 0 on error
InsertTransfer          dd      ?
; Activate previously initialized transfer (maybe with multiple stages).
; esi -> usb_controller, ebx -> usb_pipe,
; [esp+4] -> first usb_gtd for the transfer,
; ecx -> last descriptor for the transfer
NewDevice               dd      ?
; Initiate configuration of a new device (create pseudo-pipe describing that
; device and call usb_new_device).
; esi -> usb_controller, eax = speed (one of USB_SPEED_* constants).
ends

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

; Initializes one controller, called by usb_init for every controller.
; edi -> usb_hardware_func, eax -> PCIDEV structure for the device.
proc usb_init_controller
        push    ebp
        mov     ebp, esp
; 1. Store in the stack PCI coordinates and save pointer to PCIDEV:
; make [ebp-4] = (bus shl 8) + devfn, used by controller-specific Init funcs.
        push    dword [eax+PCIDEV.devfn]
        push    eax
; 2. Allocate *hci_controller + usb_controller.
        mov     ebx, [edi+usb_hardware_func.DataSize]
        add     ebx, sizeof.usb_controller
        stdcall kernel_alloc, ebx
        test    eax, eax
        jz      .nothing
; 3. Zero-initialize both structures.
        push    edi eax
        mov     ecx, ebx
        shr     ecx, 2
        xchg    edi, eax
        xor     eax, eax
        rep stosd
; 4. Initialize usb_controller structure,
; except data known only to controller-specific code (like NumPorts)
; and link fields
; (this structure will be inserted to the overall list at step 6).
        dec     eax
        mov     [edi+usb_controller.ExistingAddresses+4-sizeof.usb_controller], eax
        mov     [edi+usb_controller.ExistingAddresses+8-sizeof.usb_controller], eax
        mov     [edi+usb_controller.ExistingAddresses+12-sizeof.usb_controller], eax
        mov     [edi+usb_controller.ResettingPort-sizeof.usb_controller], al    ; no resetting port
        dec     eax     ; don't allocate zero address
        mov     [edi+usb_controller.ExistingAddresses-sizeof.usb_controller], eax
        lea     ecx, [edi+usb_controller.PeriodicLock-sizeof.usb_controller]
        call    mutex_init
        add     ecx, usb_controller.ControlLock - usb_controller.PeriodicLock
        call    mutex_init
        add     ecx, usb_controller.BulkLock - usb_controller.ControlLock
        call    mutex_init
        pop     eax edi
        mov     [eax+ebx-sizeof.usb_controller+usb_controller.HardwareFunc], edi
        push    eax
; 5. Call controller-specific initialization.
; If failed, free memory allocated in step 2 and return.
        call    [edi+usb_hardware_func.Init]
        test    eax, eax
        jz      .fail
        pop     ecx
; 6. Insert the controller to the global list.
        xchg    eax, ebx
        mov     ecx, usb_controllers_list_mutex
        call    mutex_lock
        mov     edx, usb_controllers_list
        mov     eax, [edx+usb_controller.Prev]
        mov     [ebx+usb_controller.Next], edx
        mov     [ebx+usb_controller.Prev], eax
        mov     [edx+usb_controller.Prev], ebx
        mov     [eax+usb_controller.Next], ebx
        call    mutex_unlock
; 7. Wakeup USB thread to call ProcessDeferred.
        call    usb_wakeup
.nothing:
; 8. Restore pointer to PCIDEV saved in step 1 and return.
        pop     eax
        leave
        ret
.fail:
        call    kernel_free
        jmp     .nothing
endp

; Helper function, calculates physical address including offset in page.
proc get_phys_addr
        push    ecx
        mov     ecx, eax
        and     ecx, 0xFFF
        call    get_pg_addr
        add     eax, ecx
        pop     ecx
        ret
endp

; Put the given control pipe in the wait list;
; called when the pipe structure is changed and a possible hardware cache
; needs to be synchronized. When it will be known that the cache is updated,
; usb_subscription_done procedure will be called.
proc usb_subscribe_control
        cmp     [ebx+usb_pipe.NextWait], -1
        jnz     @f
        mov     eax, [esi+usb_controller.WaitPipeListAsync]
        mov     [ebx+usb_pipe.NextWait], eax
        mov     [esi+usb_controller.WaitPipeListAsync], ebx
@@:
        ret
endp

; Called after synchronization of hardware cache with software changes.
; Continues process of device enumeration based on when it was delayed
; due to call to usb_subscribe_control.
proc usb_subscription_done
        mov     eax, [ebx+usb_pipe.DeviceData]
        cmp     [eax+usb_device_data.DeviceDescrSize], 0
        jz      usb_after_set_address
        jmp     usb_after_set_endpoint_size
endp

; This function is called when a new device has either passed
; or failed first stages of configuration, so the next device
; can enter configuration process.
proc usb_test_pending_port
        mov     [esi+usb_controller.ResettingPort], -1
        cmp     [esi+usb_controller.PendingPorts], 0
        jz      .nothing
        bsf     ecx, [esi+usb_controller.PendingPorts]
        btr     [esi+usb_controller.PendingPorts], ecx
        mov     eax, [esi+usb_controller.HardwareFunc]
        jmp     [eax+usb_hardware_func.InitiateReset]
.nothing:
        ret
endp

; This procedure is regularly called from controller-specific ProcessDeferred,
; it checks whether there are disconnected events and if so, process them.
proc usb_disconnect_stage2
        bsf     ecx, [esi+usb_controller.NewDisconnected]
        jz      .nothing
        lock btr [esi+usb_controller.NewDisconnected], ecx
        btr     [esi+usb_controller.PendingPorts], ecx
        xor     ebx, ebx
        xchg    ebx, [esi+usb_controller.DevicesByPort+ecx*4]
        test    ebx, ebx
        jz      usb_disconnect_stage2
        call    usb_device_disconnected
        jmp     usb_disconnect_stage2
.nothing:
        ret
endp

; Initial stage of disconnect processing: called when device is disconnected.
proc usb_device_disconnected
; Loop over all pipes, close everything, wait until hardware reacts.
; The final handling is done in usb_pipe_closed.
        push    ebx
        mov     ecx, [ebx+usb_pipe.DeviceData]
        call    mutex_lock
        lea     eax, [ecx+usb_device_data.OpenedPipeList-usb_pipe.NextSibling]
        push    eax
        mov     ebx, [eax+usb_pipe.NextSibling]
.pipe_loop:
        call    usb_close_pipe_nolock
        mov     ebx, [ebx+usb_pipe.NextSibling]
        cmp     ebx, [esp]
        jnz     .pipe_loop
        pop     eax
        pop     ebx
        mov     ecx, [ebx+usb_pipe.DeviceData]
        call    mutex_unlock
        ret
endp

; Called from controller-specific ProcessDeferred,
; processes wait-pipe-done notifications,
; returns whether there are more items in wait queues.
; in: esi -> usb_controller
; out: eax = bitmask of pipe types with non-empty wait queue
proc usb_process_wait_lists
        xor     edx, edx
        push    edx
        call    usb_process_one_wait_list
        jnc     @f
        or      byte [esp], 1 shl CONTROL_PIPE
@@:
        movi    edx, 4
        call    usb_process_one_wait_list
        jnc     @f
        or      byte [esp], 1 shl INTERRUPT_PIPE
@@:
        xor     edx, edx
        call    usb_process_one_wait_list
        jnc     @f
        or      byte [esp], 1 shl CONTROL_PIPE
@@:
        pop     eax
        ret
endp

; Helper procedure for usb_process_wait_lists;
; does the same for one wait queue.
; in: esi -> usb_controller,
; edx=0 for *Async, edx=4 for *Periodic list
; out: CF = issue new request
proc usb_process_one_wait_list
; 1. Check whether there is a pending request. If so, do nothing.
        mov     ebx, [esi+usb_controller.WaitPipeRequestAsync+edx]
        cmp     ebx, [esi+usb_controller.ReadyPipeHeadAsync+edx]
        clc
        jnz     .nothing
; 2. Check whether there are new data. If so, issue a new request.
        cmp     ebx, [esi+usb_controller.WaitPipeListAsync+edx]
        stc
        jnz     .nothing
        test    ebx, ebx
        jz      .nothing
; 3. Clear all lists.
        xor     ecx, ecx
        mov     [esi+usb_controller.WaitPipeListAsync+edx], ecx
        mov     [esi+usb_controller.WaitPipeRequestAsync+edx], ecx
        mov     [esi+usb_controller.ReadyPipeHeadAsync+edx], ecx
; 4. Loop over all pipes from the wait list.
.pipe_loop:
; For every pipe:
; 5. Save edx and next pipe in the list.
        push    edx
        push    [ebx+usb_pipe.NextWait]
; 6. If USB_FLAG_EXTRA_WAIT is set, reinsert the pipe to the list and continue.
        test    [ebx+usb_pipe.Flags], USB_FLAG_EXTRA_WAIT
        jz      .process
        mov     eax, [esi+usb_controller.WaitPipeListAsync+edx]
        mov     [ebx+usb_pipe.NextWait], eax
        mov     [esi+usb_controller.WaitPipeListAsync+edx], ebx
        jmp     .continue
.process:
; 7. Call the handler depending on USB_FLAG_CLOSED.
        or      [ebx+usb_pipe.NextWait], -1
        test    [ebx+usb_pipe.Flags], USB_FLAG_CLOSED
        jz      .nodisconnect
        call    usb_pipe_closed
        jmp     .continue
.nodisconnect:
        call    usb_subscription_done
.continue:
; 8. Restore edx and next pipe saved in step 5 and continue the loop.
        pop     ebx
        pop     edx
        test    ebx, ebx
        jnz     .pipe_loop
.check_new_work:
; 9. Set CF depending on whether WaitPipeList* is nonzero.
        cmp     [esi+usb_controller.WaitPipeListAsync+edx], 1
        cmc
.nothing:
        ret
endp