USBD Interface Functions

USB device drivers interact with the peripherals that they control by using the USBD interface functions. These functions, which are provided by the USBD module, constitute the core of a USB device driver’s functionality. There are several categories of USBD interface functions, each related to a different aspect of interacting with a USB device, including transfer, pipe, frame, and configuration functions, as well as functions for performing other miscellaneous tasks.

Transfer functions are the most important category since they handle sending data to and receiving data from a USB device. There are four basic types of transfer: control, bulk, interrupt, and isochronous. For convenience, there are several special transfer functions that provide common types of control transfer, such as device configuration and setup requests. All transfer functions have an optional callback parameter. If a callback function is provided, the transfer functions return immediately, or asynchronously, without waiting for the transfer request to complete. When the transfer request finishes, the transfer function calls the function pointed to by the callback parameter. Additionally, a USB device driver can use the USB_NO_WAIT flag to cause the transfer functions to return asynchronously, even if no callback is specified. USB device drivers typically do this in situations when they queue several requests to the device and wait for only the last one to finish. In such cases, the device driver is still responsible for closing all transfer handles. If the USB device driver provides no callback function and does not use the USB_NO_WAIT flag, the transfer function blocks until the transfer is complete.

The USBD module calls the callback function in a context that may block other USB operations. Therefore, these callback functions should perform very minimal processing, preferably just setting some state variables and signaling an event so that any substantial post-processing can be handled by another thread. In particular, such callback functions cannot call any USBD interface functions. See the HID and mouse sample drivers for examples of using callback functions.

Internally, the USB system is optimized for a page size of 4 KB. If a platform has a different page size, the USB system allocates an internal, contiguous 4-KB buffer to use for data transfers. However, copying data into and out of this buffer may impose an unacceptable limit on the performance of a USB device driver. In such cases, the driver may pass an optional physical memory address that the USB system uses directly for data transfers. A driver-specific buffer used in this way must be contiguous within 4-KB segments and must not be accessed by the USB device driver during transfer operations. The LockPages function can be used to obtain physical address information.

The following table shows the transfer functions.

• The following table shows the pipe functions that open and close communication channels between a USBD and a USB device.

• The following table shows the frame functions that control how the USBD module packages data into frames for transmission on the bus.

• The following table shows device configuration functions for specific kinds of data transfers defined in the Universal Serial Bus Specification.

• The following tables shows miscellaneous functions for tasks related to interacting with USB implementation.