00001 /* ---------------------------------------------------------------------------- 00002 * ATMEL Microcontroller Software Support 00003 * ---------------------------------------------------------------------------- 00004 * Copyright (c) 2014, Atmel Corporation 00005 * 00006 * All rights reserved. 00007 * 00008 * Redistribution and use in source and binary forms, with or without 00009 * modification, are permitted provided that the following conditions are met: 00010 * 00011 * - Redistributions of source code must retain the above copyright notice, 00012 * this list of conditions and the disclaimer below. 00013 * 00014 * Atmel's name may not be used to endorse or promote products derived from 00015 * this software without specific prior written permission. 00016 * 00017 * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR 00018 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 00019 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 00020 * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, 00021 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 00022 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 00023 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 00024 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 00025 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 00026 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00027 * ---------------------------------------------------------------------------- 00028 */ 00029 00030 /** 00031 * \dir usb/device 00032 * 00033 * \section Purpose 00034 * 00035 * This directory provides definitions, structs and functions for USB device 00036 * applications with Atmel AT91 microcontrollers and USB device framework. 00037 * 00038 * You can develop your own USB device products based on the class-specific 00039 * driver code provided, or just take them as a reference. 00040 * 00041 * \section Contents 00042 * There are two groups for the implement: 00043 * -# The hardware interface driver for USB peripheral on AT91 00044 * microcontrollers (UDP or UDPHS), this is a part of the 00045 * \ref usbd_lib "USBD Library" (\ref usbd_framework). 00046 * - "core": hardware interface driver for AT91 USB peripheral 00047 * -# The device class driver to class-specific device. 00048 * - "audio-speaker" 00049 * - "ccid" 00050 * - "cdc-serial" 00051 * - "hid-keyboard" 00052 * - "massstorage" 00053 * - "composite" 00054 * 00055 * For more information about what a particular group contains, please refer to 00056 * its documentation page. 00057 * 00058 */ 00059 00060 /** 00061 \page usbd_api USBD API 00062 00063 See also \subpage usbd_api_struct "USBD API Structures" and 00064 \subpage usbd_api_method "USBD API Methods". 00065 00066 \section usbd_api_struct_sec USBD API Structs 00067 00068 Several specific structures are used by the USBD API to perform various 00069 operations, such as invoking callbacks or accessing the USBD controller. 00070 00071 There are two main structures: 00072 - \ref USBDDriver : 00073 It is the main structure of the USB API. It should be instantiated 00074 in class-specific USB device driver or user application. 00075 - \ref USBDDriverDescriptors : 00076 It is a list of all descriptors used by a USB device driver. It 00077 should be instantiated in class-specific USB device driver or 00078 user application and passed to USBD by USBDDriver_Initialize. 00079 00080 \section usbd_api_method_sec USBD API Methods 00081 00082 The USB API provides several methods to perform the following operations: 00083 - Changing the device state 00084 - \ref USBD_Init 00085 - \ref USBD_Connect, \ref USBD_Disconnect 00086 - \ref USBD_SetAddress 00087 - \ref USBD_SetConfiguration 00088 - \ref USBD_GetState 00089 - \ref usbd_state_diagram "USB Device State Diagram" 00090 - Handling events coming from the USB controller 00091 - \ref USBD_IrqHandler 00092 - Modifying the behavior of an endpoint 00093 - \ref USBD_ConfigureEndpoint 00094 - \ref USBD_Stall 00095 - \ref USBD_Halt 00096 - \ref USBD_Unhalt 00097 - \ref USBD_IsHalted 00098 - Transferring data 00099 - \ref USBD_Write 00100 - \ref USBD_Read 00101 - USBD_IsoWrite 00102 - Special functions 00103 - \ref USBD_RemoteWakeUp 00104 00105 See \ref usbd_api_method "USBD API Methods" for detailed informations. 00106 00107 */ 00108 00109 /** 00110 \page usbd_api_struct USBD API Structures 00111 00112 \section struct USBD API Structures 00113 00114 Several specific structures are used by the USBD API to perform various 00115 operations, such as invoking callbacks or accessing the USBD controller. 00116 00117 There are two main structures: 00118 - USBDDriver: 00119 It is the main structure of the USB API. It should be instantiated 00120 in class-specific USB device driver or user application. 00121 - USBDDriverDescriptors: 00122 It is a list of all descriptors used by a USB device driver. It 00123 should be instantiated in class-specific USB device driver or 00124 user application and passed to USBD by USBDDriver_Initialize. 00125 00126 */ 00127 00128 /** 00129 \page usbd_api_method USBD API Methods 00130 00131 \section api_fun USBD API methods 00132 00133 The USB API provides serveral methods to perform the following operations: 00134 - Changing the device state 00135 - \ref USBD_Init 00136 - \ref usbd_conn_api "USBD_Connect, USBD_Disconnect" 00137 - \ref USBD_SetAddress 00138 - \ref USBD_SetConfiguration 00139 - \ref USBD_GetState 00140 - \ref usbd_state_diagram "USB Device State Diagram" 00141 - Handling events coming from the USB controller 00142 - \ref USBD_IrqHandler 00143 - Modifying the behavior of an endpoint 00144 - \ref USBD_ConfigureEndpoint 00145 - \ref USBD_Stall 00146 - \ref usbd_halt_api "USBD_Halt, USBD_Unhalt, USBD_IsHalted" 00147 - Transferring data 00148 - \ref USBD_Write 00149 - \ref USBD_Read 00150 - USBD_IsoWrite 00151 - Special functions 00152 - \ref USBD_RemoteWakeUp 00153 00154 \section ctrl_state Controlling the Device State 00155 00156 Chapter 9 of the USB specification 2.0 describes the various states a device 00157 can be in. Most of the methods of this API are used to change between those 00158 states. 00159 00160 \subsection USBD_Init 00161 00162 \ref USBD_Init is the first method to call in a user application. Technically, 00163 it must occur just before entering the Attached state. It performs the 00164 following actions: 00165 - USB Device driver and endpoint state initialization 00166 - D+ pull-up configuration and disabling 00167 - UDP hardware initialization (Peripheral and clock init) 00168 00169 A USB device uses a pull-up on the D+ line to signal its connection to the 00170 host. Depending on the USB controller present on the chip, either an 00171 internal or external pull-up is used. In both cases, its configuration is 00172 performed directly by this method. Please refer to the documentation of a 00173 particular controller for more information about the D+ pull-up. 00174 00175 The ini callback has to perform several mandatory operations at this point. 00176 You can find the default operations in USBDCallbacks_Initialized. 00177 00178 \subsection usbd_conn_api USBD_Connect, USBD_Disconnect 00179 00180 These two methods control the state of the D+ upll-up. This makes it possible 00181 to connect of disconnect the device by software when needed. \ref USBD_Connect 00182 changes the device state from Powered to Default, while \ref USBD_Disconnect 00183 changes from either Default, Address or Configured to Powered. 00184 00185 \subsection USBD_SetAddress 00186 00187 \ref USBD_SetAddress extracts the information from the last received 00188 SETUP packet to either change the device state from Default to 00189 Address or from Address to Default. The difference is made 00190 depending on the value of the wValue field of the request. 00191 00192 This method must only be called right after the SET_ADDRESS 00193 request is received. 00194 00195 \subsection USBD_SetConfiguration 00196 00197 This function operates in a way similar to \ref USBD_SetAddress. When the 00198 SETUP packet containing a SET_CONFIGURATION request is received, 00199 \ref USBD_SetConfiguration should be called to extract the new configuration 00200 value to adopt. If the wValue field of the request is non-zero, then the 00201 device must adopt the new configuration and enter the Configuration state; 00202 otherwise, it returns (or stays) in the Address state. 00203 00204 \subsection USBD_GetState 00205 00206 As its name implies, USBD_GetState simply returns the current state of the USB 00207 driver. See state definitions on \ref usbd_states "USB device states". 00208 - \ref USBD_STATE_SUSPENDED 00209 - \ref USBD_STATE_ATTACHED 00210 - \ref USBD_STATE_POWERED 00211 - \ref USBD_STATE_DEFAULT 00212 - \ref USBD_STATE_ADDRESS 00213 - \ref USBD_STATE_CONFIGURED 00214 00215 \subsection Device State Diagram 00216 See \subpage usbd_state_diagram "USB Device State Diagram" 00217 00218 \section event_hdl Event Handling (\ref USBD_IrqHandler) 00219 Several events can occur at the USB controller level: 00220 - End of bus reset 00221 - Reception of a SETUP packet 00222 - Change of bus activity (active -> idle -> active ..) 00223 - Completin of an endpoint operation 00224 - ... 00225 00226 Whenever such an event occurs, it must be forwarded to the USBD API to be 00227 handled in an appropriate way. The USBD_IrqHandler performs this 00228 functionality, so the controller interrupt must be configured to call it. 00229 00230 Several <b>callbacks</b> can be triggered depending on the event notified by 00231 the controller: 00232 - Suspend, when the bus is idle 00233 - Resume, when the bus becomes active again 00234 - NewRequest, when a setup packet is received on a control endpoint 00235 - StartOfFrame, every 1 ms (for full-speed controllers) or 125us (for high- 00236 speed controllers) 00237 00238 More information about these callbacks and their expected behavior can be 00239 found in \ref usbd_callback_api "USBD Callback API". 00240 00241 \section ep_fun Endpoint Behavior Modification 00242 00243 The USBD API offers following functions to control how an endpoint operates. 00244 - \ref USBD_ConfigureEndpoint 00245 - \ref USBD_Stall 00246 - \ref USBD_Halt 00247 - \ref USBD_Unhalt 00248 - \ref USBD_IsHalted 00249 00250 \subsection USBD_ConfigureEndpoint 00251 \ref USBD_ConfigureEndpoint is used to configure an endpoint at the USB 00252 controller level. An appropriate endpoint descriptor must be provided to 00253 do that. The descriptor is used to configure the endpoint type (either 00254 Control, Bulk, Interrupt or Isochronous), direction (IN or OUT) and address. 00255 00256 Control endpoint 0 is automatically configured by the USBD API when the End of 00257 bus reset event is signalled by the USB controller. Therefore, there is no need 00258 to do it manually. 00259 00260 \subsection USBD_Stall 00261 The \ref USBD_Stall method causes and endpoint to acknowledge its next received 00262 packet with a STALL handshake. Further packets are then handled normally. 00263 00264 Most of the time, this method should be used with endpoint 0 to signal the 00265 host that the device cannot process a command. 00266 00267 \subsection usbd_halt_api USBD_Halt, USBD_Unhalt, USBD_IsHalted 00268 \ref USBD_Halt sets the Halt status of an endpoint. When in Halt mode, every 00269 received packet is acknowledged with a STALL handshake instead of being 00270 handled normally. 00271 00272 <i>USB_Halt</i> can be called either with the USB_SET_FEATURE, USB_CLEAR_FEATURE 00273 or USB_GET_STATUS parameter to modify the endpoint Halt state. 00274 00275 \ref USBD_Unhalt clears the Halt status of an endpoint. 00276 00277 \ref USBD_IsHalted gets the Halt status of an endpoint. 00278 00279 \section data_tran Data Transfer 00280 Data transfer (IN or OUT) on an endpoint can be performed by calling two 00281 methods, USBD_Write and USBD_Read. 00282 00283 \subsection USBD_Write 00284 The USBD_Write function sends a data payload on a specific endpoint. If the 00285 data payload equals or exceeds the maximum packet size of the endpoint, then 00286 several IN transactions are necessary. This method should only be called on an 00287 IN or Control endpoint. 00288 00289 The write is performed <b>asynchronously</b>, i.e., the function returns 00290 immediately without waiting for the transfer to finish. When the transfer is 00291 complete, an optional user-provided callback function is called. This makes it 00292 possible to create an <b>OS-friendly synchronous function</b> by locking and 00293 unlocking a semaphore before and after each write. 00294 00295 This function handles double-buffering, if it is supported by the USB 00296 controller and if it has been enabled for the endpoint. Do not forget that 00297 using double-buffering is mandatory for isochronous transactions. 00298 00299 - <b>Note</b> 00300 The double-buffering this function supported is only in period of each 00301 write action. That is, when the function is invoked to start transfer 00302 trunk of data, the data is automatically splitted to several IN 00303 transactions and ping-pong is started on the 2nd transaction. But when 00304 all the data of the trunk is finished the ping-pong is stopped. So it can 00305 not process the list of buffer that should use double-buffering all the 00306 time. See USBD_IsoWrite for such kind of operations. 00307 00308 \subsection USBD_Read 00309 The \ref USBD_Read reads incoming data on an endpoint. The transfer stops either 00310 when the provided buffer is full, or a short packet (size inferior to the 00311 endpoint maximum packet size) is received. This method must only be called on 00312 an OUT or Control endpoint. 00313 00314 The read is performed <b>asynchronously</b>, i.e., the function returns 00315 immediately without waiting for the transfer to finish. When the transfer is 00316 complete, an optional user-provided callback function is called. This makes it 00317 possible to create an <b>OS-friendly synchronous function</b> by locking and 00318 unlocking a semaphore before and after each read. 00319 00320 This function handles <b>double-buffering</b>, if it is supported by the USB 00321 controller and if it has been enabled for the endpoint. Do not forget that 00322 using double-buffering is mandatory for isochronous transactions. 00323 00324 \subsection USBD_IsoWrite 00325 The \ref USBD_IsoWrite function sends a buffer list on a specific endpoint. The 00326 each buffer's payload should be equals or less than the maximum packet size of 00327 the endpoint. The transfer ends when all buffera are sent out. And the buffer 00328 is previously sent can be filled with new data before the transfer ends. To 00329 maitain a ring buffer for the outgoing stream. This method should only be 00330 called on an ISO IN endpoint. 00331 00332 The write is performed <b>asynchronously</b>, i.e., the function returns immediately 00333 without waiting for the transfer to finish. When the transfer is complete, an 00334 optional user-provided callback function is called. This makes it possible to 00335 create an <b>OS-friendly synchronous function</b> by locking and unlocking a 00336 semaphore before and after each write. 00337 00338 This function handles double-buffering, if it is supported by the USB 00339 controller and if it has been enabled for the endpoint. Do not forget that 00340 using double-buffering is mandatory for isochronous transactions. 00341 00342 \section special_fun Special Functions 00343 00344 - USBD_RemoteWakeUp() : This method starts a remote wakeup procedure. This makes 00345 it possible for a suspended device to wake a host with may itself be 00346 suspended. 00347 00348 */ 00349 00350 /** 00351 \page usbd_state_diagram USB Device State Diagram 00352 00353 \image html USBDeviceStateDiagram.png "Changing the Device State" 00354 00355 */ 00356 00357 /* (Image Link Backup) 00358 <img src="USBDeviceStateDiagram.png" border=0 alt="USBDeviceStateDiagram.png" usemap="#USBD_ST_DIA"> 00359 <MAP NAME="USBD_ST_DIA"> 00360 <AREA shape="poly" coords="172,0,330,0,330,26,172,26,172,0" onmouseover="link('_member','core/USBD_Init53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_Init (void )',CAPTION,'<strong>Brief description</strong><BR>Initializes the specified USB driver This<BR>function initializes the current FIFO bank of<BR>endpoints, configures the pull-up and VBus<BR>lines, disconnects the pull-up and then<BR>trigger the Init callback.');" onmouseout="return nd();"> 00361 <AREA shape="poly" coords="269,390,425,390,425,416,269,416,269,390" onmouseover="link('_member','core/USBD_SetAddress2593655934',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_SetAddress (unsigned char address)',CAPTION,'<strong>Brief description</strong><BR>Sets the device address.');" onmouseout="return nd();"> 00362 <AREA shape="poly" coords="76,390,233,390,233,416,76,416,76,390" onmouseover="link('_member','core/USBD_SetAddress2593655934',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_SetAddress (0)',CAPTION,'<strong>Brief description</strong><BR>Unsets the device address.');" onmouseout="return nd();"> 00363 <AREA shape="poly" coords="76,509,233,509,233,535,76,535,76,509" onmouseover="link('_member','core/USBD_SetConfiguration2593655934',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_SetConfiguration (0)',CAPTION,'<strong>Brief description</strong><BR>Changes the device state from Configured to Address.');" onmouseout="return nd();"> 00364 <AREA shape="poly" coords="261,509,418,509,418,535,261,535,261,509" onmouseover="link('_member','core/USBD_SetConfiguration2593655934',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_SetConfiguration (unsigned char cfgnum)',CAPTION,'<strong>Brief description</strong><BR>Changes the device state from Address to Configured.');" onmouseout="return nd();"> 00365 <AREA shape="poly" coords="284,242,440,242,440,269,284,269,284,242" onmouseover="link('_member','core/USBD_Connect53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_Connect (void )',CAPTION,'<strong>Brief description</strong><BR>Enables the pull-up on the D+ line to connect the device to the USB.');" onmouseout="return nd();"> 00366 <AREA shape="poly" coords="60,242,217,242,217,269,60,269,60,242" onmouseover="link('_member','core/USBD_Disconnect53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_Disconnect (void )',CAPTION,'<strong>Brief description</strong><BR>Disables the pull-up on the D+ line to disconnect the<BR>device from the bus.');" onmouseout="return nd();"> 00367 </MAP> 00368 00369 <MAP NAME="usbd_cb_invo_fc"> 00370 <AREA shape="poly" coords="436,739,600,739,600,765,436,765,436,739" onmouseover="link('_member','core/USBDCallbacks_Resumed53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBDCallbacks_Resumed (void )',CAPTION,'<strong>Brief description</strong><BR>Invoked when the USB device leaves the Suspended state.');" onmouseout="return nd();"> 00371 <AREA shape="poly" coords="436,406,600,406,600,432,436,432,436,406" onmouseover="link('_member','core/USBDCallbacks_Resumed53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBDCallbacks_Resumed (void )',CAPTION,'<strong>Brief description</strong><BR>Invoked when the USB device leaves the Suspended state.');" onmouseout="return nd();"> 00372 <AREA shape="poly" coords="436,605,600,605,600,632,436,632,436,605" onmouseover="link('_member','core/USBDCallbacks_Suspended53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBDCallbacks_Suspended (void )',CAPTION,'<strong>Brief description</strong><BR>Invoked when the USB device gets suspended. By default,<BR>turns off all LEDs.');" onmouseout="return nd();"> 00373 <AREA shape="poly" coords="436,339,600,339,600,365,436,365,436,339" onmouseover="link('_member','coreUSBDCallbacks_Suspended53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBDCallbacks_Suspended (void )',CAPTION,'<strong>Brief description</strong><BR>Invoked when the USB device gets suspended. By default,<BR>turns off all LEDs.');" onmouseout="return nd();"> 00374 <AREA shape="poly" coords="436,272,600,272,600,299,436,299,436,272" onmouseover="link('_member','core/USBDCallbacks_RequestReceived2520836348',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBDCallbacks_RequestReceived (const USBGenericRequest * request)',CAPTION,'<strong>Brief description</strong><BR>Triggered when the USB host emits a new SETUP request.');" onmouseout="return nd();"> 00375 <AREA shape="poly" coords="436,206,600,206,600,232,436,232,436,206" onmouseover="link('_member','core/USBDCallbacks_Reset53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBDCallbacks_Reset ( void )',CAPTION,'<strong>Brief description</strong><BR>Triggered when the USB host emits a RESET.')"> 00376 <AREA shape="poly" coords="436,102,600,102,600,129,436,129,436,102" onmouseover="link('_member','core/USBDCallbacks_Initialized53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBDCallbacks_Initialized (void )',CAPTION,'<strong>Brief description</strong><BR>Invoked after the USB driver has been initialized.');" onmouseout="return nd();"> 00377 <AREA shape="poly" coords="221,374,384,374,384,400,221,400,221,374" onmouseover="link('_member','core/USBD_IrqHandler53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_IrqHandler (void )',CAPTION,'<strong>Brief description</strong><BR>UDP interrupt handler. Manages device status changes.');" onmouseout="return nd();"> 00378 <AREA shape="poly" coords="221,307,384,307,384,333,221,333,221,307" onmouseover="link('_member','core/USBD_IrqHandler53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_IrqHandler (void )',CAPTION,'<strong>Brief description</strong><BR>UDP interrupt handler. Manages device status changes.');" onmouseout="return nd();"> 00379 <AREA shape="poly" coords="221,240,384,240,384,266,221,266,221,240" onmouseover="link('_member','core/USBD_IrqHandler53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_IrqHandler (void )',CAPTION,'<strong>Brief description</strong><BR>UDP interrupt handler. Manages device status changes.');" onmouseout="return nd();"> 00380 <AREA shape="poly" coords="221,173,384,173,384,199,221,199,221,173" onmouseover="link('_member','core/USBD_IrqHandler53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_IrqHandler (void )',CAPTION,'<strong>Brief description</strong><BR>UDP interrupt handler. Manages device status changes.');" onmouseout="return nd();"> 00381 <AREA shape="poly" coords="221,36,384,36,384,62,221,62,221,36" onmouseover="link('_member','core/USBD_Init53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_Init (void )',CAPTION,'<strong>Brief description</strong><BR>Initializes the USB driver.');" onmouseout="return nd();"> 00382 <AREA shape="poly" coords="0,407,163,407,163,434,0,434,0,407" onmouseover="overLibDiagram();return overlib('UDP_ISR: AT91C_UDP_SOFINT')" onmouseout="return nd();"> 00383 <AREA shape="poly" coords="0,340,163,340,163,367,0,367,0,340" onmouseover="overLibDiagram();return overlib('UDP_ISR: AT91C_UDP_WAKEUP | AT91C_UDP_RXRSM')" onmouseout="return nd();"> 00384 <AREA shape="poly" coords="0,273,163,273,163,300,0,300,0,273" onmouseover="overLibDiagram();return overlib('UDP_ISR: AT91C_UDP_RXSUSP')" onmouseout="return nd();"> 00385 <AREA shape="poly" coords="0,139,163,139,163,165,0,165,0,139" onmouseover="overLibDiagram();return overlib('UDP_ISR: AT91C_UDP_ENDBUSRES')" onmouseout="return nd();"> 00386 <AREA shape="poly" coords="0,206,163,206,163,232,0,232,0,206" onmouseover="overLibDiagram();return overlib('UDP_CSR: AT91C_UDP_RXSETUP')" onmouseout="return nd();"> 00387 <AREA shape="poly" coords="436,672,600,672,600,698,436,698,436,672" title="ISR_Vbus"> 00388 <AREA shape="poly" coords="436,539,600,539,600,565,436,565,436,539" title="ISR_Vbus"> 00389 <AREA shape="poly" coords="482,0,554,0,554,13,482,13,482,0" title="Applications"> 00390 <AREA shape="poly" coords="278,0,331,0,331,13,278,13,278,0" title="USBD API"> 00391 <AREA shape="poly" coords="36,0,128,0,128,13,36,13,36,0" title="UDP_, UDPHS_"> 00392 </MAP> 00393 <IMG SRC="USBDCallbackInvocationFlowchart.png" border=0 ALT="USBDCallbackInvocationFlowchart.png" usemap="#usbd_cb_invo_fc"> 00394 */ 00395 00396 /** 00397 \page usbd_callback_api USBD Callback API 00398 00399 \section cb_api Callback API 00400 00401 The callback API is a means of communication between the user application and 00402 the USBD API. When particular operations must be performed, the USB driver 00403 calls serveral external functions, refferred to as <b>callbacks</b>. They can also 00404 be invoked to notify the user application of pending events. 00405 00406 Defining all callbacks is not mandatory. For example, if the device shall not 00407 enter low-power mode, then it is appropriate not to provide a Suspend callback. 00408 If a callback is mandatory, this is notified in its description. 00409 00410 See USBDCallbacks.h for callback definitions. 00411 00412 \section Callback Invocation 00413 The following events can trigger a callback: 00414 - USB initialization: \ref USBDCallbacks_Initialized 00415 - End of bus reset: \ref USBDCallbacks_Reset 00416 - Device suspend: \ref USBDCallbacks_Suspended 00417 - Device resume: \ref USBDCallbacks_Resumed 00418 - SETUP request received: \ref USBDCallbacks_RequestReceived 00419 - Start of a new USB frame 00420 00421 \image html USBDCallbackInvocationFlowchart.png "Callback Invocation Flowchart" 00422 00423 \subsection Init 00424 The \ref USBDCallbacks_Initialized callback is invoked when the \ref USBD_Init method is 00425 called. It has to perform several mandatory steps to make it possible to use 00426 the API: 00427 - If an OS is used, perform any specific operation to install the driver 00428 - Configure USB controller interrupt 00429 - Configure Vbus monitoring PIO and interrupt ( but it's in app layer now ) 00430 The USB controller interrupt must be configured to <b>call the 00431 USBD_IrqHandler</b> API function when triggered. This is necessary to have 00432 events happening at the USB controller level handled appropriately by the API. 00433 00434 If a PIO pin is connected to VBus, it is possible to monitor it by configuring 00435 the pin as an input and enabling the PIO interrupt. The interrupt service 00436 routine should simply check the Vbus status and then call the \ref USBD_Connect 00437 and \ref USBD_Disconnect function to put device into right state. 00438 00439 Finally, if an OS is being used, then the driver should probably be installed 00440 prior to use. Interrupt configuration may also be done differently. Please 00441 refer to the documentation of the OS for more information. 00442 00443 This callback is <b>mandatory</b>. 00444 00445 \subsection Reset 00446 When an End of bus reset has been detected, the USBDCallbacks_Reset callback 00447 is triggered. The callback should perform <b>initialization</b> or <b>re- 00448 initialization</b> of the user-level application. For example, a class driver 00449 like MSD should re-initialize its internal state when a USB reset is performed. 00450 00451 \subsection Suspend 00452 When the USB device enters the Suspended state, the USB API notifies this state 00453 change by invoking the \ref USBDCallbacks_Suspended callback. This can happen either 00454 when the bus is idle or when the device is disconnected from the USB. 00455 00456 If the device should enter low-power mode when suspended, then this callback 00457 must perform the required operations to do so, e.g., switching to a slow clock, 00458 disabling PLLs, etc. 00459 00460 - <i>Note: The electrical specification of the USB 2.0 defines a maximum current 00461 consumption of 500uA for suspended device. This includes the current passing 00462 through pull-ups and upll-downs.</i> 00463 00464 \subsection Resume 00465 The \ref USBDCallbacks_Resumed callback is invoked when the USB device leaves the 00466 Suspended state and returns to its previous state (either Powered, Default, 00467 Address or Configured). This may happen when activity is detected on the USB, 00468 or when the device gets connected. 00469 00470 If the device was in low-power mode because of the Suspend callback, then this 00471 callback must perform the necessary poerations to return the device into a 00472 normal operation mode, e.g., switching to a fast clock. 00473 00474 \subsection NewRequest 00475 When a SETUP request is received on a control endpoint, the USBD API layer 00476 triggers the USBDCallbacks_RequestReceived callback to notify the user 00477 application. The received request can then be accessed through the 00478 corresponding USBGenericRequest structure. 00479 00480 SETUP packets are used for class-specific requests (e.g. <i>GetMaxLUN</i> in MSD) 00481 as well as standard USB requests (e.g. <i>SetConfiguration</i>). The former are 00482 described in <i>USB Device Class Documents</i>, such as the <i>Mass Storage Bulk 00483 Only 1.0</i>, the latter are defined in the USB Specification 2.0. 00484 00485 - <i>Note: that SETUP requests which are not understood by the device should 00486 be acknowledged with a STALL handshake. This notifies the host that the 00487 device cannot process the command.</i> 00488 00489 This callback is <b>mandatory</b>. 00490 00491 \subsection StartOfFrame 00492 Every 1ms (for a full-speed device) or 125us (for a high-speed device) a 00493 new USB frame starts. A callback can be invoked whenever this occurs. 00494 00495 Because the start-of-frame interrupt %puts some stress on the processor 00496 (since it is called a lot), it is only activated the corresponding 00497 callback is defined (<b>now it's NOT defined in current framework</b>). 00498 00499 */ 00500 00501 /** 00502 \page usbd_std_req_handler USBD Standard Request Handler 00503 00504 \section Standard Request Handler 00505 00506 Chapter 9 of the USB specification 2.0 defines a set of standard requests 00507 which have to be implemented by all devices. Since most class drivers treat 00508 those requests in the standard way, the USB framework provides a way to easily 00509 do that. 00510 00511 \section USBDDriver_RequestHandler 00512 00513 \ref USBDDriver_RequestHandler handles the standard requests in an appropriate way. 00514 It can answer the following commands: 00515 00516 - GET_DESCRIPTOR 00517 - SET_ADDRESS 00518 - SET_CONFIGURATION 00519 - GET_CONFIGURATION 00520 - CLEAR_FEATURE 00521 - SET_FEATURE 00522 - GET_STATUS 00523 00524 Simply using this standard request handler enables a device to be enumerated 00525 correctly. 00526 00527 \subsection get_dsc Get Descriptor 00528 The GET_DESCRIPTOR request is used by the host to retrieve information about 00529 the device by means of several descriptors. 00530 00531 The standard request handler simply sends the corresponding descriptor to the 00532 host. How these descriptors are provided to the function is discussed in 00533 Structures. 00534 00535 \subsection set_addr Set Address 00536 Whenever the host wants to change the device state from Default to Address, or 00537 vice-versa, it sends a SET_ADDRESS request. The wValue field contains the new 00538 address of the device; if it is null, then the device returns to the Default 00539 state. 00540 00541 The \ref USBD_SetAddress function is called to perform this operation. Note that a 00542 zero-length packet must be sent prior to doing that, to acknowledge the SETUP 00543 transfer. 00544 00545 \subsection cfg Set Configuration & GetConfiguration 00546 The SET_CONFIGURATION request makes it possible for the host to select between 00547 one or more configurations for the device. GET_CONFIGURATION is used to 00548 retrieve the currently selected one. 00549 00550 Those two requests are handled in a very basic way by 00551 USBDDriver_RequestHandler() : it assumes that the device has only one 00552 configuration. Therefore, the SET_CONFIGURATION request is simply acknowledged 00553 with a zero-length packet, and GET_CONFIGURATION is answered with either 0 00554 or 1. If the user application needs more than one configuration, it will be 00555 the duty of the class driver handler to service those requests. 00556 00557 In addition, when the SET_CONFIGURATION request causes the device to enter the 00558 Configured state, the standard request handler calls the USBD_ConfigureEndpoint 00559 method for each endpoint used by the device; 00560 00561 \subsection feature Clear Feature, Set Feature & Get Status 00562 Several features of a device can either be activated or deactivated by the USB 00563 host: 00564 - Remote wakeup 00565 - Endpoint Halt state 00566 Three requests can be used to either set, clear or get the status of these two 00567 features: SET_FEATURE, CLEAR_FEATURE and GET_STATUS. 00568 00569 The \ref USBDDriver_RequestHandler method answers a Halt state operation by calling 00570 the \ref USBD_Halt method on the endpoint with the request. 00571 00572 \section Structures 00573 Several pieces of information must be known to the \ref USBDDriver_RequestHandler 00574 to be able to process some SETUP commands. For example, all the descriptors 00575 (configuration, etc.) used by the device are needed since they must be sent 00576 to the host when a GET_DESCRIPTOR is received. 00577 00578 The \ref USBGenericRequest structure is a "standard USB class driver" object used 00579 to hold the required information. It must be passed as an argument to the 00580 \ref USBDDriver_RequestHandler method. Another structure, \ref USBDDriverDescriptors, is 00581 used to store the descriptors list. 00582 00583 \section Usage 00584 The NewRequest callback is used to notify the user application that a new SETUP 00585 request has been received. SETUP request can either be class-specific or 00586 standard. 00587 00588 The correct way to handle incoming requests is to first process class-specific 00589 requests using a class handler. For example, a Mass Storage implementation will 00590 define the NewRequest callback to call \ref MSDDriver_RequestHandler. This function 00591 will handle the necessary requests, and forward the rest to 00592 \ref USBDDriver_RequestHandler. 00593 00594 If a request cannot be processed, \ref USBDDriver_RequestHandler will STALL control 00595 endpoint 0. 00596 00597 */ 00598 00599 /** 00600 \page usbd_id_str USBD VID, PID, SN & Strings 00601 00602 This page collects the definition for USB device to indicate the Vendor and 00603 Product information. 00604 00605 00606 If you need only the functions in demo %driver, you can easily modify these 00607 definitions to change your device's Identification and Display strings. 00608 00609 They are defined in the driver c code file that suffixed with 00610 "DriverDescriptors" under the driver directory. 00611 00612 \section usbd_id_str_desc VID, PID & SN in Device Descriptor 00613 00614 Defined as const and used in \ref USBDeviceDescriptor instance initialization. 00615 Gives identivication to the USB device by VID and PID. The INF installation 00616 file should mach the VID & PID so that the device can be installed. 00617 00618 \code 00619 const USBDeviceDescriptor deviceDescriptor = {...}; 00620 \endcode 00621 00622 - audio-speaker: "Audio Speaker Device Codes" 00623 - ccid: "CCID Device IDs" 00624 - cdc-serial: "CDC Serial Device IDs" 00625 - hid-keyboard: "HID Device Descriptor IDs" 00626 - massstorage: "MSD Device Descriptor IDs" 00627 00628 \section Strings 00629 00630 The strings gives additional information on the USB device, normally string 00631 description about the vendor, product and serial number. 00632 00633 The strings are defined as a list to initialize the driver's 00634 \ref USBDDriverDescriptors instance: 00635 00636 - audio-speaker: auddSpeakerDriverDescriptors 00637 - ccid: ccidDriverDescriptors 00638 - cdc-serial: cdcdSerialDriverDescriptors 00639 - hid-keyboard: hiddKeyboardDriverDescriptors 00640 - massstorage: msdDriverDescriptors 00641 00642 \code 00643 // String descriptors 00644 const unsigned char *stringDescriptors[] = { 00645 00646 languageIdDescriptor, 00647 manufacturerDescriptor, 00648 productDescriptor, 00649 serialNumberDescriptor, 00650 }; 00651 \endcode 00652 */