diff options
Diffstat (limited to 'hal/documentation/usb_device_async.rst')
| -rw-r--r-- | hal/documentation/usb_device_async.rst | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/hal/documentation/usb_device_async.rst b/hal/documentation/usb_device_async.rst new file mode 100644 index 0000000..647eec0 --- /dev/null +++ b/hal/documentation/usb_device_async.rst @@ -0,0 +1,195 @@ +The USB Device Asynchronous Driver +================================== + +Universal Serial Bus (USB) is an industry standard that defines the cables, +connectors and communication protocols used in a bus for connection, +communication, and power supply between computers and electronic devices. + +The USB device driver provides necessary APIs to support USB Device states and +USB data flow. So that the USB Device enumeration, class and vendor support can +be implemented base on it. The driver is asynchronous, which means that all USB +data processing is done in callbacks.. + +To be recognized by a host, a USB device must handle a subset of the USB events. +The USB device should build up control communication to report its descriptors +to the host and accept host's requests. An application or upper stack that uses +the USB device driver should have its descriptors prepared, catch the callbacks, +monitor the control requests and handle them correctly. +Usually, a USB device application that can be enumerated may use the following +sequence: + +* Initialize +* Register callback and handle Reset event, where: + + * Initialize endpoint 0 + * Register callbacks for endpoint 0, where some of the standard requests + defined in Chapter 9, USB specification + (see `USB 2.0 Documents <http://www.usb.org/developers/docs/usb20_docs>`_) + are handled + + * Setup request handling callback + + * On *GetDeviceDescriptor* request, sends device descriptor + * On *GetConfigurationDescriptor* request, sends configuration descriptors + * On *SetAddress* request sends no data, just goes to status phase + * On *SetConfigure* request initialize and enable other endpoints, sends + no data, just goes to status phase + * Transfer done handling callback + + * On *SetAddress* request apply the new address + * On *SetConfigure* request a global variable can be set to indicates + that the host driver is loaded and device is ready to work + * Enable endpoint 0 +* Enable +* Attach device + +To support USB transfer on endpoints, endpoints information is stored +by the driver internally, including control request data, endpoint status, +callbacks and transfer data pointers. The number of endpoints that the driver +can support is defined through configuration. To optimize RAM usage, the +number of endpoints the driver needs to support should be minimized. + +Features +-------- + +* Initialization/de-initialization +* Enabling/disabling +* USB device attachment/detachment +* USB device address control +* USB working speed status +* USB device frame number and micro frame number status +* Sending remote wakeup to host +* Callback management for following USB events: + + * Start of Frame (SOF) + * Other USB events: + + * VBus change + * Reset + * Wakeup + * Linked Power Management (LPM) Suspend + * Suspend + * Error +* Endpoints management: + + * Endpoint initialization/de-initialization + * Endpoint enabling/disabling + * Control endpoint setup request packet + * Data transfer and abort + * Endpoint halt state control + * Endpoint status, including: + + * Endpoint address + * Last transfer result status code + * Last error status code + * Current transfer state + * Transfer size and done count + * Endpoint callback management for endpoint and its transfer events: + + * In case a setup request received on control endpoint + * In case transfer finished with/without error + +Applications +------------ + +USB Device stack, to monitor USB events, handle control requests and process +data. + +Dependencies +------------ + +* USB device capable hardware +* 48MHz clock for low-speed and full-speed and 480MHz clock for high-speed + +Concurrency +----------- + +N/A + +Limitations +----------- + +* When a buffer is used by a USB endpoint to transfer data, it must be kept + unchanged while the transfer is in progress. +* After receiving a request that has no data expected, the transfer function + must be called with data length zero to complete control status phase. + +Known issues and workarounds +---------------------------- + +N/A + +Considerations for D21 USB +-------------------------- + +Clocks +^^^^^^ + +DFLL must be used to generate 48MHz clock for USB device with either of the +following mode: + +* USB Clock Recovery Mode + + * Set "DFLL Enable", "Bypass Coarse Lock", "Chill Cycle Disable", + "USB Clock Recovery Mode", "Stable DFLL Frequency" + * Clear "Wait Lock" + * Leave "Operating Mode Selection" to "Closed Loop Mode" + +* Closed Loop Mode + + * Set "DFLL Enable" + * Clear "USB Clock Recovery Mode", "Stable DFLL Frequency" + * Select "Closed Loop Mode" of "Operating Mode Selection" + * Set "DFLL Multiply Factor" to 1464 or 1465 (48000000/32768) + * Select "Reference Clock Source" to use 32768Hz source, e.g., use GCLK1 and + for GCLK1 settings: + + * Set "Generic Clock Generator Enable" + * Select "XOSC32K" of "Generic clock generator 1 source", and for XOSC32K + settings: + + * Set "External 32K Oscillator Enable", "Enable 32KHz Output", + "Enable XTAL" + * Set a right value for "Startup time for the 32K Oscillator", e.g., + 1125092 us + +Endpoints +^^^^^^^^^ + +Each USB device endpoint number supports two endpoint addresses, corresponding +to IN and OUT endpoint. E.g., for endpoint 1, the endpoint IN has address 0x81 +and endpoint OUT has address 0x01. Thus, the possible supported endpoint +addresses are almost two times of max endpoint number (endpoint 0 must be used +as control endpoint instead of dedicated IN and OUT endpoints). + +Buffering and RAM usage optimization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When transferring data through USB device endpoints, buffer pointers can be +used to let endpoint get access to the buffer, but there are some limits: + +* For control endpoint there must always be a buffer available to put received + setup packet. +* For IN endpoint (transmit to host) the data must in RAM. +* For OUT endpoint (receive from host) the data pointer must be aligned, and + the data size must be aligned by max endpoint size and not zero. + +The driver has option for each endpoint to allocate internal static buffer as +cache to buffer input/output data, to remove upper limits. The configuration +affects the parameter check of transfer functions, and the RAM usage. + +* For control endpoints, cache buffer must be enabled to fill setup packet. + In addition, to support unaligned OUT packet and IN packet inside flash, the + buffer size must be equal to or larger than max endpoint size. +* For OUT endpoints, if the cache is allocated, it's possible to pass unaligned + buffer address and buffer size to transfer function. Else the transfer + function only accepts aligned buffer with it's size multiple of endpoint + packet size. +* For IN endpoints, if the cache is allocated, it's possible to pass buffer + pointer to internal flash or other memory part other than RAM to the transfer + function. + +To optimize the RAM usage, the configuration of max endpoint number, max number +of endpoints supported and the buffer usage of used input and/or output +endpoints can be adjusted. + |