Subversion Repositories Kolibri OS

; Code for EHCI controllers.

; Standard driver stuff

format PE DLL native

entry start

__DEBUG__ equ 1

__DEBUG_LEVEL__ equ 1

section '.reloc' data readable discardable fixups

section '.text' code readable executable

include '../proc32.inc'

include '../struct.inc'

include '../macros.inc'

include '../fdo.inc'

include '../../kernel/trunk/bus/usb/common.inc'

; =============================================================================

; ================================= Constants =================================

; =============================================================================

; EHCI register declarations.

; Part 1. Capability registers.

; Base is MMIO from the PCI space.

EhciCapLengthReg    = 0

EhciVersionReg      = 2

EhciStructParamsReg = 4

EhciCapParamsReg    = 8

EhciPortRouteReg    = 0Ch

; Part 2. Operational registers.

; Base is (base for part 1) + (value of EhciCapLengthReg).

EhciCommandReg      = 0

EhciStatusReg       = 4

EhciInterruptReg    = 8

EhciFrameIndexReg   = 0Ch

EhciCtrlDataSegReg  = 10h

EhciPeriodicListReg = 14h

EhciAsyncListReg    = 18h

EhciConfigFlagReg   = 40h

EhciPortsReg        = 44h

; Possible values of ehci_pipe.NextQH.Type bitfield.

EHCI_TYPE_ITD  = 0 ; isochronous transfer descriptor

EHCI_TYPE_QH   = 1 ; queue head

EHCI_TYPE_SITD = 2 ; split-transaction isochronous TD

EHCI_TYPE_FSTN = 3 ; frame span traversal node

; =============================================================================

; ================================ Structures =================================

; =============================================================================

; Hardware part of EHCI general transfer descriptor.

struct ehci_hardware_td

NextTD          dd      ?

; Bit 0 is Terminate bit, 1 = there is no next TD.

; Bits 1-4 must be zero.

; With masked 5 lower bits, this is the physical address of the next TD, if any.

AlternateNextTD dd      ?

; Similar to NextTD, used if the transfer terminates with a short packet.

Token           dd      ?

; 1. Lower byte is Status field:

; bit 0 = ping state for USB2 endpoints, ERR handshake signal for USB1 endpoints

; bit 1 = split transaction state, meaningless for USB2 endpoints

; bit 2 = missed micro-frame

; bit 3 = transaction error

; bit 4 = babble detected

; bit 5 = data buffer error

; bit 6 = halted

; bit 7 = active

; 2. Next two bits (bits 8-9) are PID code, 0 = OUT, 1 = IN, 2 = SETUP.

; 3. Next two bits (bits 10-11) is ErrorCounter. Initialized as 3, decremented

;    on each error; if it goes to zero, transaction is stopped.

; 4. Next 3 bits (bits 12-14) are CurrentPage field.

; 5. Next bit (bit 15) is InterruptOnComplete bit.

; 6. Next 15 bits (bits 16-30) are TransferLength field,

;    number of bytes to transfer.

; 7. Upper bit (bit 31) is DataToggle bit.

BufferPointers  rd      5

; The buffer to be transferred can be spanned on up to 5 physical pages.

; The first item of this array is the physical address of the first byte in

; the buffer, other items are physical addresses of next pages. Lower 12 bits

; in other items must be set to zero; ehci_pipe.Overlay reuses some of them.

BufferPointersHigh      rd      5

; Upper dwords of BufferPointers for controllers with 64-bit memory access.

; Always zero.

ends

; EHCI general transfer descriptor.

; * The structure describes transfers to be performed on Control, Bulk or

;   Interrupt endpoints.

; * The structure includes two parts, the hardware part and the software part.

; * The hardware part consists of first 52 bytes and corresponds to

;   the Queue Element Transfer Descriptor from EHCI specification.

; * The hardware requires 32-bytes alignment of the hardware part, so

;   the entire descriptor must be 32-bytes aligned. Since the allocator

;   (usb_allocate_common) allocates memory sequentially from page start

;   (aligned on 0x1000 bytes), block size for the allocator must be divisible

;   by 32; ehci_alloc_td ensures this.

; * The hardware also requires that the hardware part must not cross page

;   boundary; the allocator satisfies this automatically.

struct ehci_gtd ehci_hardware_td

Flags                   dd      ?

; Copy of flags from the call to usb_*_transfer_async.

ends

; EHCI-specific part of a pipe descriptor.

; * This structure corresponds to the Queue Head from the EHCI specification.

; * The hardware requires 32-bytes alignment of the hardware part.

;   Since the allocator (usb_allocate_common) allocates memory sequentially

;   from page start (aligned on 0x1000 bytes), block size for the allocator

;   must be divisible by 32; ehci_alloc_pipe ensures this.

; * The hardware requires also that the hardware part must not cross page

;   boundary; the allocator satisfies this automatically.

struct ehci_pipe

NextQH                  dd      ?

; 1. First bit (bit 0) is Terminate bit, 1 = there is no next QH.

; 2. Next two bits (bits 1-2) are Type field of the next QH,

;    one of EHCI_TYPE_* constants.

; 3. Next two bits (bits 3-4) are reserved, must be zero.

; 4. With masked 5 lower bits, this is the physical address of the next object

;    to be processed, usually next QH.

Token                   dd      ?

; 1. Lower 7 bits are DeviceAddress field. This is the address of the

;    target device on the USB bus.

; 2. Next bit (bit 7) is Inactivate-on-next-transaction bit. Can be nonzero

;    only for interrupt/isochronous USB1 endpoints.

; 3. Next 4 bits (bits 8-11) are Endpoint field. This is the target endpoint

;    number.

; 4. Next 2 bits (bits 12-13) are EndpointSpeed field, one of EHCI_SPEED_*.

; 5. Next bit (bit 14) is DataToggleControl bit,

;    0 = use DataToggle bit from QH, 1 = from TD.

; 6. Next bit (bit 15) is Head-of-reclamation-list. The head of Control list

;    has 1 here, all other QHs have zero.

; 7. Next 11 bits (bits 16-26) are MaximumPacketLength field for the target

;    endpoint.

; 8. Next bit (bit 27) is ControlEndpoint bit, must be 1 for USB1 control

;    endpoints and 0 for all others.

; 9. Upper 4 bits (bits 28-31) are NakCountReload field.

;    Zero for USB1 endpoints, zero for periodic endpoints.

;    For control/bulk USB2 endpoints, the code sets it to 4,

;    which is rather arbitrary.

Flags                   dd      ?

; 1. Lower byte is S-mask, each bit corresponds to one microframe per frame;

;    bit is set <=> enable transactions in this microframe.

; 2. Next byte is C-mask, each bit corresponds to one microframe per frame;

;    bit is set <=> enable complete-split transactions in this microframe.

;    Meaningful only for USB1 endpoints.

; 3. Next 14 bits give address of the target device as hub:port, bits 16-22

;    are the USB address of the hub, bits 23-29 are the port number.

;    Meaningful only for USB1 endpoints.

; 4. Upper 2 bits define number of consequetive transactions per micro-frame

;    which host is allowed to permit for this endpoint.

;    For control/bulk endpoints, it must be 1.

;    For periodic endpoints, the value is taken from the endpoint descriptor.

HeadTD                  dd      ?

; The physical address of the first TD for this pipe.

; Lower 5 bits must be zero.

Overlay                 ehci_hardware_td        ?

; Working area for the current TD, if there is any.

; When TD is retired, it is written to that TD and Overlay is loaded

; from the new TD, if any.

ends

; This structure describes the static head of every list of pipes.

; The hardware requires 32-bytes alignment of this structure.

; All instances of this structure are located sequentially in ehci_controller,

; ehci_controller is page-aligned, so it is sufficient to make this structure

; 32-bytes aligned and verify that the first instance is 32-bytes aligned

; inside ehci_controller.

; The hardware also requires that 44h bytes (size of 64-bit Queue Head

; Descriptor) starting at the beginning of this structure must not cross page

; boundary. If not, most hardware still behaves correctly (in fact, the last

; dword can have any value and this structure is never written), but on some

; hardware some things just break in mysterious ways.

struct ehci_static_ep

; Hardware fields are the same as in ehci_pipe.

; Only NextQH and Overlay.Token are actually used.

; NB: some emulators ignore Token.Halted bit (probably assuming that it is set

; only when device fails and emulation never fails) and always follow

; [Alternate]NextTD when they see that OverlayToken.Active bit is zero;

; so it is important to also set [Alternate]NextTD to 1.

NextQH          dd      ?

Token           dd      ?

Flags           dd      ?

HeadTD          dd      ?

NextTD          dd      ?

AlternateNextTD dd      ?

OverlayToken    dd      ?

NextList        dd      ?

SoftwarePart    rd      sizeof.usb_static_ep/4

Bandwidths      rw      8

                dd      ?

ends

if sizeof.ehci_static_ep mod 32

.err ehci_static_ep must be 32-bytes aligned

end if

if ehci_static_ep.OverlayToken <> ehci_pipe.Overlay.Token

.err ehci_static_ep.OverlayToken misplaced

end if

; EHCI-specific part of controller data.

; * The structure includes two parts, the hardware part and the software part.

; * The hardware part consists of first 4096 bytes and corresponds to

;   the Periodic Frame List from the EHCI specification.

; * The hardware requires page-alignment of the hardware part, so

;   the entire descriptor must be page-aligned.

;   This structure is allocated with kernel_alloc (see usb_init_controller),

;   this gives page-aligned data.

; * The controller is described by both ehci_controller and usb_controller

;   structures, for each controller there is one ehci_controller and one

;   usb_controller structure. These structures are located sequentially

;   in the memory: beginning from some page start, there is ehci_controller

;   structure - this enforces hardware alignment requirements - and then

;   usb_controller structure.

; * The code keeps pointer to usb_controller structure. The ehci_controller

;   structure is addressed as [ptr + ehci_controller.field - sizeof.ehci_controller].

struct ehci_controller

; ------------------------------ hardware fields ------------------------------

FrameList               rd      1024

; Entry n corresponds to the head of the frame list to be executed in

; the frames n,n+1024,n+2048,n+3072,...

; The first bit of each entry is Terminate bit, 1 = the frame is empty.

; Bits 1-2 are Type field, one of EHCI_TYPE_* constants.

; Bits 3-4 must be zero.

; With masked 5 lower bits, the entry is a physical address of the first QH/TD

; to be executed.

; ------------------------------ software fields ------------------------------

; Every list has the static head, which is an always halted QH.

; The following fields are static heads, one per list:

; 32+16+8+4+2+1 = 63 for Periodic lists, 1 for Control list and 1 for Bulk list.

IntEDs                  ehci_static_ep

                        rb      62 * sizeof.ehci_static_ep

; Beware.

; Two following strings ensure that 44h bytes at any static head

; do not cross page boundary. Without that, the code "works on my machine"...

; but fails on some hardware in seemingly unrelated ways.

; One hardware TD (without any software fields) fit in the rest of the page.

ehci_controller.ControlDelta = 2000h - (ehci_controller.IntEDs + 63 * sizeof.ehci_static_ep)

StopQueueTD             ehci_hardware_td

; Used as AlternateNextTD for transfers when short packet is considered

; as an error; short packet must stop the queue in this case, not advance

; to the next transfer.

                        rb      ehci_controller.ControlDelta - sizeof.ehci_hardware_td

; Padding for page-alignment.

ControlED               ehci_static_ep

Bulk