SAMV71 Xplained Ultra Software Package 1.3

device.dir

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&nbsp;&nbsp;USBD_Init&nbsp;&nbsp;(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&nbsp;&nbsp;USBD_SetAddress&nbsp;&nbsp;(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&nbsp;&nbsp;USBD_SetAddress&nbsp;&nbsp;(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&nbsp;&nbsp;USBD_SetConfiguration&nbsp;&nbsp;(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&nbsp;&nbsp;USBD_SetConfiguration&nbsp;&nbsp;(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&nbsp;&nbsp;USBD_Connect&nbsp;&nbsp;(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&nbsp;&nbsp;USBD_Disconnect&nbsp;&nbsp;(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&nbsp;&nbsp;USBDCallbacks_Resumed&nbsp;&nbsp;(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&nbsp;&nbsp;USBDCallbacks_Resumed&nbsp;&nbsp;(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&nbsp;&nbsp;USBDCallbacks_Suspended&nbsp;&nbsp;(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&nbsp;&nbsp;USBDCallbacks_Suspended&nbsp;&nbsp;(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&nbsp;&nbsp;USBDCallbacks_RequestReceived&nbsp;&nbsp;(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&nbsp;&nbsp;USBDCallbacks_Reset&nbsp;&nbsp;( 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&nbsp;&nbsp;USBDCallbacks_Initialized&nbsp;&nbsp;(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&nbsp;&nbsp;USBD_IrqHandler&nbsp;&nbsp;(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&nbsp;&nbsp;USBD_IrqHandler&nbsp;&nbsp;(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&nbsp;&nbsp;USBD_IrqHandler&nbsp;&nbsp;(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&nbsp;&nbsp;USBD_IrqHandler&nbsp;&nbsp;(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&nbsp;&nbsp;USBD_Init&nbsp;&nbsp;(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 */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines