SAM3S8/SD8 Software Package: libraries/usb/device/device.dir Source File

SAM3S8/SD8 Software Package 1.2

# device.dir

    00001 /* ----------------------------------------------------------------------------
    00002  *         ATMEL Microcontroller Software Support
    00003  * ----------------------------------------------------------------------------
    00004  * Copyright (c) 2008, 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 refference.
    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 instanciated
    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 instanciated 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 serveral 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 instanciated
    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 instanciated 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