📄 device.dir
字号:
!!!Event Handling (USBD_InterruptHandler)
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_InterruptHandler 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_InterruptHandler53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_InterruptHandler (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_InterruptHandler53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_InterruptHandler (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_InterruptHandler53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_InterruptHandler (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_InterruptHandler53616',this);overLibDiagram();return overlib('<strong>Syntax</strong><BR>void USBD_InterruptHandler (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_InterruptHandler# 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
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -