Description
device.dir::USBD API Methods
USB API methods
The USB API provides serveral methods to perform the following operations:
- Changing the device state
- Handling events coming from the USB controller
- Modifying the behavior of an endpoint
- Transferring data
- Special functions
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".
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)
Endpoint Behavior Modification
The USBD API offers following functions to control how an endpoint operates.
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.
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.
Source
The documentation for this Page was generated from the following file:
device.dir