Kévin Redon | 69b92d9 | 2019-01-24 16:39:20 +0100 | [diff] [blame] | 1 | The USB Device Asynchronous Driver |
| 2 | ================================== |
| 3 | |
| 4 | Universal Serial Bus (USB) is an industry standard that defines the cables, |
| 5 | connectors and communication protocols used in a bus for connection, |
| 6 | communication, and power supply between computers and electronic devices. |
| 7 | |
| 8 | The USB device driver provides necessary APIs to support USB Device states and |
| 9 | USB data flow. So that the USB Device enumeration, class and vendor support can |
| 10 | be implemented base on it. The driver is asynchronous, which means that all USB |
| 11 | data processing is done in callbacks.. |
| 12 | |
| 13 | To be recognized by a host, a USB device must handle a subset of the USB events. |
| 14 | The USB device should build up control communication to report its descriptors |
| 15 | to the host and accept host's requests. An application or upper stack that uses |
| 16 | the USB device driver should have its descriptors prepared, catch the callbacks, |
| 17 | monitor the control requests and handle them correctly. |
| 18 | Usually, a USB device application that can be enumerated may use the following |
| 19 | sequence: |
| 20 | |
| 21 | * Initialize |
| 22 | * Register callback and handle Reset event, where: |
| 23 | |
| 24 | * Initialize endpoint 0 |
| 25 | * Register callbacks for endpoint 0, where some of the standard requests |
| 26 | defined in Chapter 9, USB specification |
| 27 | (see `USB 2.0 Documents <http://www.usb.org/developers/docs/usb20_docs>`_) |
| 28 | are handled |
| 29 | |
| 30 | * Setup request handling callback |
| 31 | |
| 32 | * On *GetDeviceDescriptor* request, sends device descriptor |
| 33 | * On *GetConfigurationDescriptor* request, sends configuration descriptors |
| 34 | * On *SetAddress* request sends no data, just goes to status phase |
| 35 | * On *SetConfigure* request initialize and enable other endpoints, sends |
| 36 | no data, just goes to status phase |
| 37 | * Transfer done handling callback |
| 38 | |
| 39 | * On *SetAddress* request apply the new address |
| 40 | * On *SetConfigure* request a global variable can be set to indicates |
| 41 | that the host driver is loaded and device is ready to work |
| 42 | * Enable endpoint 0 |
| 43 | * Enable |
| 44 | * Attach device |
| 45 | |
| 46 | To support USB transfer on endpoints, endpoints information is stored |
| 47 | by the driver internally, including control request data, endpoint status, |
| 48 | callbacks and transfer data pointers. The number of endpoints that the driver |
| 49 | can support is defined through configuration. To optimize RAM usage, the |
| 50 | number of endpoints the driver needs to support should be minimized. |
| 51 | |
| 52 | Features |
| 53 | -------- |
| 54 | |
| 55 | * Initialization/de-initialization |
| 56 | * Enabling/disabling |
| 57 | * USB device attachment/detachment |
| 58 | * USB device address control |
| 59 | * USB working speed status |
| 60 | * USB device frame number and micro frame number status |
| 61 | * Sending remote wakeup to host |
| 62 | * Callback management for following USB events: |
| 63 | |
| 64 | * Start of Frame (SOF) |
| 65 | * Other USB events: |
| 66 | |
| 67 | * VBus change |
| 68 | * Reset |
| 69 | * Wakeup |
| 70 | * Linked Power Management (LPM) Suspend |
| 71 | * Suspend |
| 72 | * Error |
| 73 | * Endpoints management: |
| 74 | |
| 75 | * Endpoint initialization/de-initialization |
| 76 | * Endpoint enabling/disabling |
| 77 | * Control endpoint setup request packet |
| 78 | * Data transfer and abort |
| 79 | * Endpoint halt state control |
| 80 | * Endpoint status, including: |
| 81 | |
| 82 | * Endpoint address |
| 83 | * Last transfer result status code |
| 84 | * Last error status code |
| 85 | * Current transfer state |
| 86 | * Transfer size and done count |
| 87 | * Endpoint callback management for endpoint and its transfer events: |
| 88 | |
| 89 | * In case a setup request received on control endpoint |
| 90 | * In case transfer finished with/without error |
| 91 | |
| 92 | Applications |
| 93 | ------------ |
| 94 | |
| 95 | USB Device stack, to monitor USB events, handle control requests and process |
| 96 | data. |
| 97 | |
| 98 | Dependencies |
| 99 | ------------ |
| 100 | |
| 101 | * USB device capable hardware |
| 102 | * 48MHz clock for low-speed and full-speed and 480MHz clock for high-speed |
| 103 | |
| 104 | Concurrency |
| 105 | ----------- |
| 106 | |
| 107 | N/A |
| 108 | |
| 109 | Limitations |
| 110 | ----------- |
| 111 | |
| 112 | * When a buffer is used by a USB endpoint to transfer data, it must be kept |
| 113 | unchanged while the transfer is in progress. |
| 114 | * After receiving a request that has no data expected, the transfer function |
| 115 | must be called with data length zero to complete control status phase. |
| 116 | |
| 117 | Known issues and workarounds |
| 118 | ---------------------------- |
| 119 | |
| 120 | N/A |
| 121 | |
| 122 | Considerations for D21 USB |
| 123 | -------------------------- |
| 124 | |
| 125 | Clocks |
| 126 | ^^^^^^ |
| 127 | |
| 128 | DFLL must be used to generate 48MHz clock for USB device with either of the |
| 129 | following mode: |
| 130 | |
| 131 | * USB Clock Recovery Mode |
| 132 | |
| 133 | * Set "DFLL Enable", "Bypass Coarse Lock", "Chill Cycle Disable", |
| 134 | "USB Clock Recovery Mode", "Stable DFLL Frequency" |
| 135 | * Clear "Wait Lock" |
| 136 | * Leave "Operating Mode Selection" to "Closed Loop Mode" |
| 137 | |
| 138 | * Closed Loop Mode |
| 139 | |
| 140 | * Set "DFLL Enable" |
| 141 | * Clear "USB Clock Recovery Mode", "Stable DFLL Frequency" |
| 142 | * Select "Closed Loop Mode" of "Operating Mode Selection" |
| 143 | * Set "DFLL Multiply Factor" to 1464 or 1465 (48000000/32768) |
| 144 | * Select "Reference Clock Source" to use 32768Hz source, e.g., use GCLK1 and |
| 145 | for GCLK1 settings: |
| 146 | |
| 147 | * Set "Generic Clock Generator Enable" |
| 148 | * Select "XOSC32K" of "Generic clock generator 1 source", and for XOSC32K |
| 149 | settings: |
| 150 | |
| 151 | * Set "External 32K Oscillator Enable", "Enable 32KHz Output", |
| 152 | "Enable XTAL" |
| 153 | * Set a right value for "Startup time for the 32K Oscillator", e.g., |
| 154 | 1125092 us |
| 155 | |
| 156 | Endpoints |
| 157 | ^^^^^^^^^ |
| 158 | |
| 159 | Each USB device endpoint number supports two endpoint addresses, corresponding |
| 160 | to IN and OUT endpoint. E.g., for endpoint 1, the endpoint IN has address 0x81 |
| 161 | and endpoint OUT has address 0x01. Thus, the possible supported endpoint |
| 162 | addresses are almost two times of max endpoint number (endpoint 0 must be used |
| 163 | as control endpoint instead of dedicated IN and OUT endpoints). |
| 164 | |
| 165 | Buffering and RAM usage optimization |
| 166 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 167 | |
| 168 | When transferring data through USB device endpoints, buffer pointers can be |
| 169 | used to let endpoint get access to the buffer, but there are some limits: |
| 170 | |
| 171 | * For control endpoint there must always be a buffer available to put received |
| 172 | setup packet. |
| 173 | * For IN endpoint (transmit to host) the data must in RAM. |
| 174 | * For OUT endpoint (receive from host) the data pointer must be aligned, and |
| 175 | the data size must be aligned by max endpoint size and not zero. |
| 176 | |
| 177 | The driver has option for each endpoint to allocate internal static buffer as |
| 178 | cache to buffer input/output data, to remove upper limits. The configuration |
| 179 | affects the parameter check of transfer functions, and the RAM usage. |
| 180 | |
| 181 | * For control endpoints, cache buffer must be enabled to fill setup packet. |
| 182 | In addition, to support unaligned OUT packet and IN packet inside flash, the |
| 183 | buffer size must be equal to or larger than max endpoint size. |
| 184 | * For OUT endpoints, if the cache is allocated, it's possible to pass unaligned |
| 185 | buffer address and buffer size to transfer function. Else the transfer |
| 186 | function only accepts aligned buffer with it's size multiple of endpoint |
| 187 | packet size. |
| 188 | * For IN endpoints, if the cache is allocated, it's possible to pass buffer |
| 189 | pointer to internal flash or other memory part other than RAM to the transfer |
| 190 | function. |
| 191 | |
| 192 | To optimize the RAM usage, the configuration of max endpoint number, max number |
| 193 | of endpoints supported and the buffer usage of used input and/or output |
| 194 | endpoints can be adjusted. |
| 195 | |