Unit DWCOTG

From Ultibo.org
Revision as of 05:31, 19 October 2016 by Ultibo (Talk | contribs)

Jump to: navigation, search

Return to Unit Reference


Description

This is a USB Host Controller Driver (HCD) that interfaces with the Synopsys DesignWare Hi-Speed USB 2.0 On-The-Go Controller, henceforth abbreviated as "DWC". This is the USB Host Controller used on the BCM2835 SoC used on the Raspberry Pi.

Please note that there is no publicly available official documentation for this particular piece of hardware, and it uses its own custom host controller interface rather than a standard one such as EHCI. Therefore, this driver was written on a best-effort basis using several sources to glean the necessary hardware details, including the extremely complicated and difficult to understand vendor provided Linux driver.

This file implements the Host Controller Driver Interface defined in TUSBHost. Most importantly, it implements a function to power on and start the host controller (HostStart) and a function to send and receive messages over the USB (HostSubmit).

The DWC is controlled by reading and writing to/from memory-mapped registers. The most important registers are the host channel registers. On this particular hardware, a "host channel", or simply "channel", is a set of registers to which software can read and write to cause transactions to take place on the USB. A fixed number of host channels exist, on the Raspberry Pi there are 8. From the software's perspective, transactions using different host channels can be executed at the same time.

Some of the host channel registers, as well as other registers, deal with interrupts. This driver makes heavy use of these and performs all USB transfers in an interrupt-driven manner. However, due to design flaws in this hardware and in USB 2.0 itself, "interrupt" and "isochronous" transfers still need to make use of software polling when checking for new data, even though each individual transfer is itself interrupt-driven. This means that, for example, if your USB mouse specifies a polling rate of 100 times per second, then it will, unfortunately, be polled 100 times per second in software. For more detail about how interrupts can be controlled on this particular hardware, see the comment above DWCSetupInterrupts. Another important concept is the idea of "packets", "transactions", and "transfers". A USB transfer, such as a single control message or bulk request, may need to be split into multiple packets if it exceeds the endpoint's maximum packet size. Unfortunately, this has to be dealt with explicitly in this code, as this hardware doesn't do it for us. But at least, from the viewpoint of this software, a "transaction" is essentially the same as a "packet".

The "On-The-Go" in the name of this hardware means that it supports the USB On-The-Go protocol, which allows it to act either as a host or a device. However, we only are concerned with it acting as a host, which simplifies our driver.

To simplify the USB core software, a useful design technique (as recommended by the USB 2.0 standard and used in other implementations such as Linux's) is to have the HCD present the root hub as a standard USB hub, even if the root hub is integrated with the host controller and does not appear as a standard hub at the hardware level. This is the case with the DWC, and we implement this design. Therefore, some code in this file deals with faking requests sent to the root hub.

Constants

To be documented

Type definitions

To be documented

Public variables

To be documented

Function declarations


Initialization functions 

procedure DWCInit;
Description: To be documented
Note None documented


DWCOTG functions 

function DWCHostStart(Host:PUSBHost):LongWord;
Description: Implementation of USBHostStart for the DesignWare Hi-Speed USB 2.0 On-The-Go Controller
Note See usb.pas for the documentation of this interface of the Host Controller Driver 


function DWCHostStop(Host:PUSBHost):LongWord;
Description: Implementation of USBHostStop for the DesignWare Hi-Speed USB 2.0 On-The-Go Controller
Note See usb.pas for the documentation of this interface of the Host Controller Driver 


function DWCHostReset(Host:PUSBHost):LongWord;
Description: Performs a software reset of the DWC OTG Controller
Note None documented 


function DWCHostResetEx(Host:PDWCUSBHost):LongWord;
Description: Performs a software reset of the DWC OTG Controller
Note Caller must hold the Host lock 


function DWCHostSubmit(Host:PUSBHost; Request:PUSBRequest):LongWord;
Description: Implementation of USBHostSubmit for the DesignWare Hi-Speed USB 2.0 On-The-Go Controller
Return USB_STATUS_SUCCESS if completed or another error code on failure
Note See usb.pas for the documentation of this interface of the Host Controller Driver

This Host Controller Driver implements this interface asynchronously, as intended. Furthermore, it uses a simplistic scheduling algorithm where it places requests into a single queue and executes them in the order they were submitted. Transfers that need to be retried, including periodic transfers that receive a NAK reply and split transactions that receive a NYET reply when doing the Complete Split transaction, are scheduled to be retried at an appropriate time by separate code that shortcuts the main queue when the timer expires.
Caller must hold the device lock. 


function DWCHostCancel(Host:PUSBHost; Request:PUSBRequest):LongWord;
Description: Implementation of USBHostCancel for the DesignWare Hi-Speed USB 2.0 On-The-Go Controller
Return USB_STATUS_SUCCESS if completed or another error code on failure
Note See usb.pas for the documentation of thisinterface of the Host Controller Driver

Caller must hold the device lock 


function DWCHostResubmit(Host:PDWCUSBHost; Request:PUSBRequest):LongWord;
Description: Called when a USB transfer needs to be retried at a later time due to no data being available from the endpoint
Request USB transfer to resubmit
Return USB_STATUS_SUCCESS if completed or another error code on failure
Note For periodic transfers (e.g. polling an interrupt endpoint), the exact time at which the transfer must be retried is specified by the bInterval member of the endpoint descriptor. For low and full-speed devices, bInterval specifies the number of millisconds to wait before the next poll, while for high-speed devices it specifies the exponent (plus one) of a power-of-two number of milliseconds to wait before the next poll.

To actually implement delaying a transfer, we associate each transfer with a thread created on-demand. Each such thread simply enters a loop where it calls sleep() for the appropriate number of milliseconds, then retries the transfer. A semaphore is needed to make the thread do nothing until the request has actually been resubmitted.
This code gets used to scheduling polling of IN interrupt endpoints, including those on hubs and HID devices. Thus, polling of these devices for status changes (in the case of hubs) or new input (in the case of HID devices) is done in software. This wakes up the CPU a lot and wastes time and energy. But with USB 2.0, there is no way around this, other than by suspending the USB device which we don't support. 


function DWCHostPowerOn(Host:PDWCUSBHost):LongWord;
Description: Power on the DWCOTG Host controller
Host The DWCOTG host to power on
Return USB_STATUS_SUCCESS if completed or another error code on failure 


function DWCHostPowerOff(Host:PDWCUSBHost):LongWord;
Description: Powers off the DWCOTG Host controller
Host The DWCOTG host to power off
Return USB_STATUS_SUCCESS if completed or another error code on failure 


function DWCHostCheck(Host:PDWCUSBHost):LongWord;
Description: Check the DWC OTG USB Host Controller to confirm it is valid
Return USB_STATUS_SUCCESS if completed or another error code on failure 


function DWCHostInit(Host:PDWCUSBHost):LongWord;
Description: Initialize the DWC OTG USB Host Controller with core USB settings and perform a host reset
Return USB_STATUS_SUCCESS if completed or another error code on failure 


function DWCHostSetup(Host:PDWCUSBHost):LongWord;
Description: Configure the DWC OTG USB Host Controller with....
Note None documented 


function DWCHostSetupDMA(Host:PDWCUSBHost):LongWord;
Description: Set up the DWC OTG USB Host Controller for DMA (direct memory access). This makes it possible for the Host Controller to directly access in-memory buffers when performing USB transfers.
Note None documented 


function DWCHostSetupInterrupts(Host:PDWCUSBHost):LongWord;
Description: Performs initial setup of the Synopsys Designware USB 2.0 On-The-Go Controller (DWC) interrupts
Note The DWC contains several levels of interrupt registers, detailed in the following list. Note that for each level, each bit of the "interrupt" register contains the state of a pending interrupt (1 means interrupt pending; write 1 to clear), while the "interrupt mask" register has the same format but is used to turn the corresponding interrupt on or off (1 means on; write 1 to turn on; write 0 to turn off).

- The AHB configuration register contains a mask bit used to enable/disable all interrupts whatsoever from the DWC hardware.
- The "Core" interrupt and interrupt mask registers control top-level interrupts. For example, a single bit in these registers corresponds to all channel interrupts.
- The "Host All Channels" interrupt and interrupt mask registers control all interrupts on each channel.
- The "Channel" interrupt and interrupt mask registers, of which one copy exists for each channel, control individual interrupt types on that channel.
We can assume that an interrupt only occurs if it is enabled in all the places listed above. Furthermore, it only seems to work to clear interrupts at the lowest level; for example, a channel interrupt must be cleared in its individual channel interrupt register rather than in one of the higher level interrupt registers.
The above just covers the DWC-specific interrupt registers. In addition to those, the system will have other ways to control interrupts. For example, on the BCM2835 (Raspberry Pi), the interrupt line going to the DWC is just one of many dozen and can be enabled/disabled using the interrupt controller. In the code below we enable this interrupt line and register a handler function so that we can actually get interrupts from the DWC.
And all that's in addition to the CPSR of the ARM processor itself, or the equivalent on other CPUs. So all in all, you literally have to enable interrupts in 6 different places to get an interrupt when a USB transfer has completed 


function DWCHostStartFrameInterrupt(Host:PDWCUSBHost; Enable:Boolean):LongWord;
Description: To be documented
Note None documented 


function DWCAllocateChannel(Host:PDWCUSBHost):LongWord;
Description: Get the next available host channel on the supplied DWC host
Host The DWC host to get available channel from
Return Channel number of the next available channel 


function DWCReleaseChannel(Host:PDWCUSBHost; Channel:LongWord):LongWord;
Description: Mark the specified host channel on the supplied DWC host as available
Host The DWC host to mark available channel on
Channel The channel number to mark as available
Return USB_STATUS_SUCCESS if completed or another error code on failure 


function DWCChannelStartTransfer(Host:PDWCUSBHost; Channel:LongWord; Request:PUSBRequest):LongWord;
Description: Start or restart a USB request on a channel of the supplied DWC host
Host The DWC host to start the request on
Channel The channel number to start the request on
Request USB request to start
Note Caller must hold the host lock

Can be called by the interrupt handler 


function DWCChannelStartTransaction(Host:PDWCUSBHost; Channel:LongWord; Request:PUSBRequest):LongWord;
Description: Start a USB transaction on a channel of the supplied DWC host
Host The DWC host to start the transaction on
Channel The host channel number to start the transaction on
Request USB request set up for the next transaction
Note Caller must hold the host lock

Can be called by the interrupt handler 


function DWCHostPortReset(Host:PDWCUSBHost):LongWord;
Description: Resets the DWC host port (The USB port that is attached to the root hub)
Note Caller must hold the Host lock 


function DWCHostPortPowerOn(Host:PDWCUSBHost):LongWord;
Description: Powers on the DWC host port (The USB port that is attached to the root hub)
Note Caller must hold the Host lock 


function DWCHostPortGetStatus(Host:PDWCUSBHost):LongWord;
Description: Read the Host Port Control and Status register with the intention of modifying it. Due to the inconsistent design of the bits in this register, this requires zeroing the write-clear bits so they aren't unintentionally cleared by writing back 1's to them.
Note Caller must hold the Host lock 


function DWCHostPortSetFeature(Host:PDWCUSBHost; Feature:Word):LongWord;
Description: Handle a SetPortFeature request on the port attached to the root hub
Note Caller must hold the Host lock 


function DWCHostPortClearFeature(Host:PDWCUSBHost; Feature:Word):LongWord;
Description: Handle a ClearPortFeature request on the port attached to the root hub
Note Caller must hold the Host lock 


procedure DWCHostPortStatusChanged(Host:PDWCUSBHost);
Description: Complete any outstanding IN interrupt status change request
Host The DWCOTG host for the change request
Note Caller must hold the Host lock

Can be called by the interrupt handler 


function DWCRootHubRequest(Host:PDWCUSBHost; Request:PUSBRequest):LongWord;
Description: Perform a request to the root hub
Host The DWCOTG host for the request
Request The USB request to perform
Return USB_STATUS_SUCCESS if completed or another error code on failure
Note Caller must hold the Host lock 


function DWCRootHubControlRequest(Host:PDWCUSBHost; Request:PUSBRequest):LongWord;
Description: Perform a control request to or from the root hub
Host The DWCOTG host for the request
Request The USB request to perform
Return USB_STATUS_SUCCESS if completed or another error code on failure
Note Caller must hold the Host lock 


function DWCRootHubClassRequest(Host:PDWCUSBHost; Request:PUSBRequest):LongWord;
Description: Perform a hub specific control request to the root hub
Host The DWCOTG host for the request
Request Hub specific request to the root hub
Return USB_STATUS_SUCCESS if completed or another error code on failure
Note Caller must hold the Host lock 


function DWCRootHubStandardRequest(Host:PDWCUSBHost; Request:PUSBRequest):LongWord;
Description: Perform a standard (non hub specific) control request to the root hub
Host The DWCOTG host for the request
Request Standard request to the root hub
Return USB_STATUS_SUCCESS if completed or another error code on failure
Note Caller must hold the Host lock 


function DWCSchedulerStart(Host:PDWCUSBHost):LongWord;
Description: Initialize a bitmask and semaphore that keep track of the Free/Used status of the host channels and a queue in which to place submitted USB transfer requests, then start the USB request scheduler thread
Note None documented 


function DWCSchedulerExecute(Host:PDWCUSBHost):PtrInt;
Description: USB request scheduler thread
Host USB host to service submitted requests for
Note This thread receives requests that have been submitted and schedules them on the next available channel.

This is a very simplistic scheduler that does not take into account bandwidth requirements or which endpoint a transfer is for. 


function DWCCompletionExecute(Host:PDWCUSBHost):PtrInt;
Description: USB request completion thread
Host USB host to service completed requests for
Note This thread receives completed requests which have either succeeded or failed and calls the completion handler which will call the registered callback for the request.

This thread also receives requests that need to be resubmitted and resubmits them for later processing by another thread.
Message contents are as follows:
Msg = Request to be completed
wParam = Channel that the request executed on (or INVALID_HANDLE_VALUE if no channel was allocated)
lParam = Status of the channel interrupt 


function DWCResubmitExecute(Request:PUSBRequest):PtrInt;
Description: USB request resubmit thread
Request USB request to resubmit
Note An instance of this thread is created for each request that needs to be resubmitted, this thread then either waits for a predetermined number of milliseconds before scheduling the request on the next available channel or waits for a signal from the interrupt handler to indicate a start of frame before scheduling the request on the allocated channel.

Once the request has been resubmitted the thread waits for the semaphore to be signaled again. If the request is a periodic polling of an endpoint then it will be resubmitted continuously at the predetermined interval, otherwise the semaphore will be destroyed by the completion handler and the thread will terminate. 


procedure DWCInterruptHandler(Host:PDWCUSBHost);
Description: Interrupt handler for the DWCOTG controller
Host The DWC host where the interrupt occurred 


function DWCChannelInterrupt(Host:PDWCUSBHost; Channel:LongWord):LongWord;
Description: Handle a channel interrupt on the specified channel
Host The DWC host where the interrupt occurred
Channel DWC host channel where the channel interrupt occurred
Return USB_STATUS_SUCCESS if completed or another error code on failure
Note Only called by DWCInterruptHandler

Caller must hold the host lock 


function DWCChannelCompleted(Host:PDWCUSBHost; Request:PUSBRequest; Channel,Interrupts:LongWord):LongWord;
Description: Handle a channel interrupt where no error occurred
Request The USB request currently scheduled on this channel
Host The DWC host where the interrupt occurred
Channel DWC host channel where the channel interrupt occurred
Interrupts The currently pending interrupts on this channel
Note Only called by DWCChannelInterrupt

Caller must hold the host lock


DWCOTG helper functions 

function DWCDivRoundUp(Number,Denominator:LongWord):LongWord;
Description: To be documented
Note None documented 


function DWCCalculateFrameInterval(Host:PDWCUSBHost):LongWord;
Description: Calculate the frame interval register value based on USB configuration and port speed
Host The DWCOTG host to calculate the interval for
Note The host frame interval register can only be modified when the port enabled bit is set in the host port control and status register

Caller must hold the Host lock


Return to Unit Reference

Retrieved from "https://ultibo.org/mediawiki_ultibo_org/index.php?title=Unit_DWCOTG&oldid=1412"