diff options
Diffstat (limited to 'usb/device/device.dir')
| -rw-r--r-- | usb/device/device.dir | 655 |
1 files changed, 655 insertions, 0 deletions
diff --git a/usb/device/device.dir b/usb/device/device.dir new file mode 100644 index 0000000..2988e1e --- /dev/null +++ b/usb/device/device.dir @@ -0,0 +1,655 @@ +/* ----------------------------------------------------------------------------
+ * ATMEL Microcontroller Software Support
+ * ----------------------------------------------------------------------------
+ * Copyright (c) 2008, Atmel Corporation
+ *
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * - Redistributions of source code must retain the above copyright notice,
+ * this list of conditions and the disclaimer below.
+ *
+ * Atmel's name may not be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR
+ * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
+ * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+ * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+ * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * ----------------------------------------------------------------------------
+ */
+
+//------------------------------------------------------------------------------
+/// \dir
+/// !!!Purpose
+///
+/// This directory provides definitions, structs and functions for USB %device
+/// applications with Atmel AT91 microcontrollers and USB %device framework.
+///
+/// You can develop your own USB %device products based on the class-specific
+/// driver code provided, or just take them as a refference.
+///
+/// !!!Contents
+/// There are two groups for the implement:
+/// -# The hardware interface driver for USB peripheral on AT91
+/// microcontrollers (UDP or UDPHS), this is a part of the "AT91 USB
+/// framework".
+/// - "core": hardware interface driver for AT91 USB peripheral
+/// -# The %device class driver to class-specific %device.
+/// - "audio-speaker"
+/// - "ccid"
+/// - "cdc-serial"
+/// - "hid-keyboard"
+/// - "massstorage"
+///
+/// For more information about what a particular group contains, please refer to
+/// its documentation page.
+///
+/// \note
+/// Depending on the project, not all the subdirectories will be available
+/// (i.e. the #ccid# directory will not be in projects without USB CCID
+/// function).
+//------------------------------------------------------------------------------
+
+/**
+ \page "USBD API"
+
+ See "USBD API Structures" and "USBD API Methods".\n
+
+ !!!USBD API Structures
+
+ Several specific structures are used by the USBD API to perform various
+ operations, such as invoking callbacks or accessing the USBD controller.
+
+ There are two %main structures:
+ - USBDDriver:
+ It is the %main structure of the USB API. It should be instanciated
+ in class-specific USB %device driver or user application.
+ - USBDDriverDescriptors:
+ It is a list of all descriptors used by a USB %device driver. It
+ should be instanciated in class-specific USB %device driver or
+ user application and passed to USBD by USBDDriver_Initialize.
+
+ !!!USBD API Methods
+
+ The USB API provides serveral methods to perform the following operations:
+ - Changing the %device state
+ - USBD_Init
+ - USBD_Connect, USBD_Disconnect
+ - USBD_SetAddress
+ - USBD_SetConfiguration
+ - USBD_GetState
+ - "USB Device State Diagram"
+ - Handling events coming from the USB controller
+ - USBD_IrqHandler
+ - Modifying the behavior of an endpoint
+ - USBD_ConfigureEndpoint
+ - USBD_Stall
+ - USBD_Halt
+ - USBD_Unhalt
+ - USBD_IsHalted
+ - Transferring data
+ - USBD_Write
+ - USBD_Read
+ - USBD_IsoWrite
+ - Special functions
+ - USBD_RemoteWakeUp
+
+ See "USBD API Methods" for detailed informations.
+
+*/
+
+/**
+ \page "USBD API Structures"
+
+ !!!USBD API Structures
+
+ Several specific structures are used by the USBD API to perform various
+ operations, such as invoking callbacks or accessing the USBD controller.
+
+ There are two %main structures:
+ - USBDDriver:
+ It is the %main structure of the USB API. It should be instanciated
+ in class-specific USB %device driver or user application.
+ - USBDDriverDescriptors:
+ It is a list of all descriptors used by a USB %device driver. It
+ should be instanciated in class-specific USB %device driver or
+ user application and passed to USBD by USBDDriver_Initialize.
+
+ */
+
+/**
+ \page "USBD API Methods"
+
+ !!!USB API methods
+
+ The USB API provides serveral methods to perform the following operations:
+ - Changing the %device state
+ - USBD_Init
+ - USBD_Connect, USBD_Disconnect
+ - USBD_SetAddress
+ - USBD_SetConfiguration
+ - USBD_GetState
+ - "USB Device State Diagram"
+ - Handling events coming from the USB controller
+ - USBD_IrqHandler
+ - Modifying the behavior of an endpoint
+ - USBD_ConfigureEndpoint
+ - USBD_Stall
+ - USBD_Halt
+ - USBD_Unhalt
+ - USBD_IsHalted
+ - Transferring data
+ - USBD_Write
+ - USBD_Read
+ - USBD_IsoWrite
+ - Special functions
+ - USBD_RemoteWakeUp
+
+ !!!Controlling the Device State
+
+ Chapter 9 of the USB specification 2.0 describes the various states a %device
+ can be in. Most of the methods of this API are used to change between those
+ states.
+
+ !!USBD_Init
+
+ USBD_Init is the first method to call in a user application. Technically, it
+ must occur just before entering the Attached state. It performs the following
+ actions:
+ - USB Device driver and endpoint state initialization
+ - D+ pull-up configuration and disabling
+ - UDP hardware initialization (Peripheral and clock init)
+
+ A USB %device uses a pull-up on the D+ line to signal its connection to the
+ host. Depending on the USB controller present on the chip, either an
+ internal or external pull-up is used. In both cases, its configuration is
+ performed directly by this method. Please refer to the documentation of a
+ particular controller for more information about the D+ pull-up.
+
+ The ini callback has to perform several mandatory operations at this point.
+ You can find the default operations in USBDCallbacks_Initialized.
+
+ !!USBD_Connect, USBD_Disconnect
+
+ These two methods control the state of the D+ upll-up. This makes it possible
+ to connect of disconnect the %device by software when needed. USBD_Connect
+ changes the %device state from Powered to Default, while USBD_Disconnect
+ changes from either Default, Address or Configured to Powered.
+
+ !!USBD_SetAddress
+
+ USBD_SetAddress extracts the information from the last received
+ SETUP packet to either change the %device state from Default to
+ Address or from Address to Default. The difference is made
+ depending on the value of the wValue field of the request.
+
+ This method must only be called right after the SET_ADDRESS
+ request is received.
+
+ !!USBD_SetConfiguration
+
+ This function operates in a way similar to USBD_SetAddress. When the SETUP
+ packet containing a SET_CONFIGURATION request is received,
+ USBD_SetConfiguration should be called to extract the new configuration
+ value to adopt. If the wValue field of the request is non-zero, then the
+ %device must adopt the new configuration and enter the Configuration state;
+ otherwise, it returns (or stays) in the Address state.
+
+ !!USBD_GetState
+
+ As its name implies, USBD_GetState simply returns the current state of the USB
+ driver. See state definitions on "USB %device states".
+ - USBD_STATE_SUSPENDED
+ - USBD_STATE_ATTACHED
+ - USBD_STATE_POWERED
+ - USBD_STATE_DEFAULT
+ - USBD_STATE_ADDRESS
+ - USBD_STATE_CONFIGURED
+
+ !!Device State Diagram
+ See "USB Device State Diagram"
+
+ !!!Event Handling (USBD_IrqHandler)
+ Several events can occur at the USB controller level:
+ - End of bus reset
+ - Reception of a SETUP packet
+ - Change of bus activity (active -> idle -> active ..)
+ - Completin of an endpoint operation
+ - ...
+
+ Whenever such an event occurs, it must be forwarded to the USBD API to be
+ handled in an appropriate way. The USBD_IrqHandler performs this
+ functionality, so the controller interrupt must be configured to call it.
+
+ Several #callbacks# can be triggered depending on the event notified by
+ the controller:
+ - Suspend, when the bus is idle
+ - Resume, when the bus becomes active again
+ - NewRequest, when a setup packet is received on a control endpoint
+ - StartOfFrame, every 1 ms (for full-speed controllers) or 125us (for high-
+ speed controllers)
+
+ More information about these callbacks and their expected behavior can be
+ found in "USBD Callback API".
+
+ !!!Endpoint Behavior Modification
+
+ The USBD API offers following functions to control how an endpoint operates.
+ - USBD_ConfigureEndpoint
+ - USBD_Stall
+ - USBD_Halt
+ - USBD_Unhalt
+ - USBD_IsHalted
+
+ !!USBD_ConfigureEndpoint
+ USBD_ConfigureEndpoint is used to configure an endpoint at the USB controller
+ level. An appropriate endpoint descriptor must be provided to do that. The
+ descriptor is used to configure the endpoint type (either Control, Bulk,
+ Interrupt or Isochronous), direction (IN or OUT) and address.
+
+ Control endpoint 0 is automatically configured by the USBD API when the End of
+ bus reset event is signalled by the USB controller. Therefore, there is no need
+ to do it manually.
+
+ !!USBD_Stall
+ The USBD_Stall method causes and endpoint to acknowledge its next received
+ packet with a STALL handshake. Further packets are then handled normally.
+
+ Most of the time, this method should be used with endpoint 0 to signal the
+ host that the %device cannot process a command.
+
+ !!USBD_Halt, USBD_Unhalt, USBD_IsHalted
+ USBD_Halt sets the Halt status of an endpoint. When in Halt mode, every
+ received packet is acknowledged with a STALL handshake instead of being
+ handled normally.
+
+ #}USB_Halt#} can be called either with the USB_SET_FEATURE, USB_CLEAR_FEATURE
+ or USB_GET_STATUS parameter to modify the endpoint Halt state.
+
+ USBD_Unhalt clears the Halt status of an endpoint.
+
+ USBD_IsHalted gets the Halt status of an endpoint.
+
+ !!!Data Transfer
+ Data transfer (IN or OUT) on an endpoint can be performed by calling two
+ methods, USBD_Write and USBD_Read.
+
+ !!USBD_Write
+ The USBD_Write function sends a data payload on a specific endpoint. If the
+ data payload equals or exceeds the maximum packet size of the endpoint, then
+ several IN transactions are necessary. This method should only be called on an
+ IN or Control endpoint.
+
+ The write is performed #asynchronously#, i.e., the function returns immediately
+ without waiting for the transfer to finish. When the transfer is complete, an
+ optional user-provided callback function is called. This makes it possible to
+ create an #OS-friendly synchronous function# by locking and unlocking a
+ semaphore before and after each write.
+
+ This function handles double-buffering, if it is supported by the USB
+ controller and if it has been enabled for the endpoint. Do not forget that
+ using double-buffering is mandatory for isochronous transactions.
+
+ - #Note#
+ The double-buffering this function supported is only in period of each
+ write action. That is, when the function is invoked to start transfer
+ trunk of data, the data is automatically splitted to several IN
+ transactions and ping-pong is started on the 2nd transaction. But when
+ all the data of the trunk is finished the ping-pong is stopped. So it can
+ not process the list of buffer that should use double-buffering all the
+ time. See USBD_IsoWrite for such kind of operations.
+
+ !!USBD_Read
+ The USBD_Read reads incoming data on an endpoint. The transfer stops either
+ when the provided buffer is full, or a short packet (size inferior to the
+ endpoint maximum packet size) is received. This method must only be called on
+ an OUT or Control endpoint.
+
+ The read is performed #asynchronously#, i.e., the function returns immediately
+ without waiting for the transfer to finish. When the transfer is complete, an
+ optional user-provided callback function is called. This makes it possible to
+ create an #OS-friendly synchronous function# by locking and unlocking a
+ semaphore before and after each read.
+
+ This function handles #double-buffering#, if it is supported by the USB
+ controller and if it has been enabled for the endpoint. Do not forget that
+ using double-buffering is mandatory for isochronous transactions.
+
+ !!USBD_IsoWrite
+ The USBD_IsoWrite function sends a buffer list on a specific endpoint. The each
+ buffer's payload should be equals or less than the maximum packet size of the
+ endpoint. The transfer ends when all buffera are sent out. And the buffer is
+ previously sent can be filled with new data before the transfer ends. To
+ maitain a ring buffer for the outgoing stream. This method should only be
+ called on an ISO IN endpoint.
+
+ The write is performed #asynchronously#, i.e., the function returns immediately
+ without waiting for the transfer to finish. When the transfer is complete, an
+ optional user-provided callback function is called. This makes it possible to
+ create an #OS-friendly synchronous function# by locking and unlocking a
+ semaphore before and after each write.
+
+ This function handles double-buffering, if it is supported by the USB
+ controller and if it has been enabled for the endpoint. Do not forget that
+ using double-buffering is mandatory for isochronous transactions.
+
+ !!!Special Functions
+
+ - USBD_RemoteWakeUp: This method starts a remote wakeup procedure. This makes
+ it possible for a suspended %device to wake a host with may itself be
+ suspended.
+
+*/
+
+/**
+ \page "USB Device State Diagram"
+
+ \image USBDeviceStateDiagram.png "Changing the Device State"
+
+*/
+
+/* (Image Link Backup)
+<img src="USBDeviceStateDiagram.png" border=0 alt="USBDeviceStateDiagram.png" usemap="#USBD_ST_DIA">
+<MAP NAME="USBD_ST_DIA">
+<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();">
+<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();">
+<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();">
+<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();">
+<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();">
+<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();">
+<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();">
+</MAP>
+
+<MAP NAME="usbd_cb_invo_fc">
+<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();">
+<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();">
+<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();">
+<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();">
+<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();">
+<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.')">
+<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();">
+<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();">
+<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();">
+<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();">
+<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();">
+<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();">
+<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();">
+<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();">
+<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();">
+<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();">
+<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();">
+<AREA shape="poly" coords="436,672,600,672,600,698,436,698,436,672" title="ISR_Vbus">
+<AREA shape="poly" coords="436,539,600,539,600,565,436,565,436,539" title="ISR_Vbus">
+<AREA shape="poly" coords="482,0,554,0,554,13,482,13,482,0" title="Applications">
+<AREA shape="poly" coords="278,0,331,0,331,13,278,13,278,0" title="USBD API">
+<AREA shape="poly" coords="36,0,128,0,128,13,36,13,36,0" title="UDP_, UDPHS_">
+</MAP>
+<IMG SRC="USBDCallbackInvocationFlowchart.png" border=0 ALT="USBDCallbackInvocationFlowchart.png" usemap="#usbd_cb_invo_fc">
+*/
+
+/**
+ \page "USBD Callback API"
+
+ !!!Callback API
+
+ The callback API is a means of communication between the user application and
+ the USBD API. When particular operations must be performed, the USB driver
+ calls serveral external functions, refferred to as #callbacks#. They can also
+ be invoked to notify the user application of pending events.
+
+ Defining all callbacks is not mandatory. For example, if the %device shall not
+ enter low-power mode, then it is appropriate not to provide a Suspend callback.
+ If a callback is mandatory, this is notified in its description.
+
+ See USBDCallbacks.h for callback definitions.
+
+ !!!Callback Invocation
+ The following events can trigger a callback:
+ - USB initialization: USBDCallbacks_Initialized
+ - End of bus reset: USBDCallbacks_Reset
+ - Device suspend: USBDCallbacks_Suspended
+ - Device resume: USBDCallbacks_Resumed
+ - SETUP request received: USBDCallbacks_RequestReceived
+ - Start of a new USB frame
+
+ \image USBDCallbackInvocationFlowchart.png "Callback Invocation Flowchart"
+
+ !!Init
+ The USBDCallbacks_Initialized callback is invoked when the USBD_Init method is
+ called. It has to perform several mandatory steps to make it possible to use
+ the API:
+ - If an OS is used, perform any specific operation to install the driver
+ - Configure USB controller interrupt
+ - Configure Vbus monitoring PIO and interrupt ( but it's in app layer now )
+ The USB controller interrupt must be configured to #call the
+ USBD_IrqHandler# API function when triggered. This is necessary to have
+ events happening at the USB controller level handled appropriately by the API.
+
+ If a PIO pin is connected to VBus, it is possible to monitor it by configuring
+ the pin as an input and enabling the PIO interrupt. The interrupt service
+ routine should simply check the Vbus status and then %call the USBD_Connect
+ and USBD_Disconnect$ function to put %device into right state.
+
+ Finally, if an OS is being used, then the driver should probably be installed
+ prior to use. Interrupt configuration may also be done differently. Please
+ refer to the documentation of the OS for more information.
+
+ This callback is #mandatory#.
+
+ !!Reset
+ When an End of bus reset has been detected, the USBDCallbacks_Reset callback
+ is triggered. The callback should perform #initialization# or #re-
+ initialization# of the user-level application. For example, a class driver
+ like MSD should re-initialize its internal state when a USB reset is performed.
+
+ !!Suspend
+ When the USB %device enters the Suspended state, the USB API notifies this state
+ change by invoking the USBDCallbacks_Suspended callback. This can happen either
+ when the bus is idle or when the %device is disconnected from the USB.
+
+ If the %device should enter low-power mode when suspended, then this callback
+ must perform the required operations to do so, e.g., switching to a slow clock,
+ disabling PLLs, etc.
+
+ - }Note: The electrical specification of the USB 2.0 defines a maximum current
+ consumption of 500uA for suspended %device. This includes the current passing
+ through pull-ups and upll-downs.}
+
+ !!Resume
+ The USBDCallbacks_Resumed callback is invoked when the USB %device leaves the
+ Suspended state and returns to its previous state (either Powered, Default,
+ Address or Configured). This may happen when activity is detected on the USB,
+ or when the %device gets connected.
+
+ If the %device was in low-power mode because of the Suspend callback, then this
+ callback must perform the necessary poerations to return the %device into a
+ normal operation mode, e.g., switching to a fast clock.
+
+ !!NewRequest
+ When a SETUP request is received on a control endpoint, the USBD API layer
+ triggers the USBDCallbacks_RequestReceived callback to notify the user
+ application. The received request can then be accessed through the
+ corresponding USBGenericRequest structure.
+
+ SETUP packets are used for class-specific requests (e.g. }GetMaxLUN} in MSD)
+ as well as standard USB requests (e.g. }SetConfiguration}). The former are
+ described in }USB Device Class Documents}, such as the }Mass Storage Bulk
+ Only 1.0}, the latter are defined in the USB Specification 2.0.
+
+ - }Note: that SETUP requests which are not understood by the %device should
+ be acknowledged with a STALL handshake. This notifies the host that the
+ %device cannot process the command.}
+
+ This callback is #mandatory#.
+
+ !!StartOfFrame
+ Every 1ms (for a full-speed %device) or 125us (for a high-speed %device) a
+ new USB frame starts. A callback can be invoked whenever this occurs.
+
+ Because the start-of-frame interrupt %puts some stress on the processor
+ (since it is called a lot), it is only activated the corresponding
+ callback is defined (#now it's NOT defined in current framework#).
+
+*/
+
+/**
+ \page "USBD Standard Request Handler"
+
+ !!!Standard Request Handler
+
+ Chapter 9 of the USB specification 2.0 defines a set of standard requests
+ which have to be implemented by all devices. Since most class drivers treat
+ those requests in the standard way, the USB framework provides a way to easily
+ do that.
+
+ !!!USBDDriver_RequestHandler
+
+ USBDDriver_RequestHandler handles the standard requests in an appropriate way.
+ It can answer the following commands:
+
+ - GET_DESCRIPTOR
+ - SET_ADDRESS
+ - SET_CONFIGURATION
+ - GET_CONFIGURATION
+ - CLEAR_FEATURE
+ - SET_FEATURE
+ - GET_STATUS
+
+ Simply using this standard request handler enables a %device to be enumerated
+ correctly.
+
+ !!Get Descriptor
+ The GET_DESCRIPTOR request is used by the host to retrieve information about
+ the %device by means of several descriptors.
+
+ The standard request handler simply sends the corresponding descriptor to the
+ host. How these descriptors are provided to the function is discussed in
+ Structures.
+
+ !!Set Address
+ Whenever the host wants to change the %device state from Default to Address, or
+ vice-versa, it sends a SET_ADDRESS request. The wValue field contains the new
+ address of the %device; if it is null, then the %device returns to the Default
+ state.
+
+ The USBD_SetAddress function is called to perform this operation. Note that a
+ zero-length packet must be sent prior to doing that, to acknowledge the SETUP
+ transfer.
+
+ !!Set Configuration & GetConfiguration
+ The SET_CONFIGURATION request makes it possible for the host to select between
+ one or more configurations for the %device. GET_CONFIGURATION is used to
+ retrieve the currently selected one.
+
+ Those two requests are handled in a very basic way by
+ USBDDriver_RequestHandler: it assumes that the %device has only one
+ configuration. Therefore, the SET_CONFIGURATION request is simply acknowledged
+ with a zero-length packet, and GET_CONFIGURATION is answered with either 0
+ or 1. If the user application needs more than one configuration, it will be
+ the duty of the class driver handler to service those requests.
+
+ In addition, when the SET_CONFIGURATION request causes the %device to enter the
+ Configured state, the standard request handler calls the USBD_ConfigureEndpoint
+ method for each endpoint used by the %device;
+
+ !!Clear Feature, Set Feature & Get Status
+ Several features of a %device can either be activated or deactivated by the USB
+ host:
+ - Remote wakeup
+ - Endpoint Halt state
+ Three requests can be used to either set, clear or get the status of these two
+ features: SET_FEATURE, CLEAR_FEATURE and GET_STATUS.
+
+ The USBDDriver_RequestHandler method answers a Halt state operation by calling
+ the USBD_Halt method on the endpoint with the request.
+
+ !!!Structures
+ Several pieces of information must be known to the USBDDriver_RequestHandler
+ to be able to process some SETUP commands. For example, all the descriptors
+ (configuration, etc.) used by the %device are needed since they must be sent
+ to the host when a GET_DESCRIPTOR is received.
+
+ The USBGenericRequest structure is a "standard USB class driver" object used
+ to hold the required information. It must be passed as an argument to the
+ USBDDriver_RequestHandler method. Another structure, USBDDriverDescriptors, is
+ used to store the descriptors list.
+
+ !!!Usage
+ The NewRequest callback is used to notify the user application that a new SETUP
+ request has been received. SETUP request can either be class-specific or
+ standard.
+
+ The correct way to handle incoming requests is to first process class-specific
+ requests using a class handler. For example, a Mass Storage implementation will
+ define the NewRequest callback to call MSDDriver_RequestHandler. This function
+ will handle the necessary requests, and forward the rest to
+ USBDDriver_RequestHandler.
+
+ If a request cannot be processed, USBDDriver_RequestHandler will STALL control
+ endpoint 0.
+
+*/
+
+/**
+ \page "VID, PID, SN & Strings"
+
+ This page collects the definition for USB %device to indicate the Vendor and
+ Product information.
+
+
+ If you need only the functions in demo %driver, you can easily modify these
+ definitions to change your device's Identification and Display strings.
+
+ They are defined in the driver c code file that suffixed with
+ "DriverDescriptors" under the driver directory.
+
+ !!!VID, PID & SN in Device Descriptor
+
+ Defined as const and used in USBDeviceDescriptor instance initialization.
+ Gives identivication to the USB %device by VID and PID. The INF installation
+ file should mach the VID & PID so that the %device can be installed.
+
+\code
+const USBDeviceDescriptor deviceDescriptor = {...};
+\endcode
+
+ - "audio-speaker": "Audio Speaker Device Codes"
+ - ccid: "CCID Device IDs"
+ - "cdc-serial": "CDC Serial Device IDs"
+ - "hid-keyboard": "HID Device Descriptor IDs"
+ - massstorage: "MSD Device Descriptor IDs"
+
+ !!!Strings
+
+ The strings gives additional information on the USB %device, normally string
+ description about the vendor, product and serial number.
+
+ The strings are defined as a list to initialize the driver's
+ USBDDriverDescriptors instance:
+
+ - "audio-speaker": auddSpeakerDriverDescriptors
+ - ccid: ccidDriverDescriptors
+ - "cdc-serial": cdcdSerialDriverDescriptors
+ - "hid-keyboard": hiddKeyboardDriverDescriptors
+ - massstorage: msdDriverDescriptors
+
+\code
+// String descriptors
+const unsigned char *stringDescriptors[] = {
+
+ languageIdDescriptor,
+ manufacturerDescriptor,
+ productDescriptor,
+ serialNumberDescriptor,
+};
+\endcode
+*/
|