SAMV71 Xplained Ultra Software Package 1.4

USBD API Methods

USBD API methods

The USB API provides serveral methods to perform the following operations:

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:

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.

State Diagram

See USB Device State Diagram

Event Handling (\ref USBD_IrqHandler)

Several events can occur at the USB controller level:

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:

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_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.

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

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines