The latest development version of this page may be more current than this released 3.7.0 version.

USB device controller driver API

The USB device controller driver API is described in include/zephyr/drivers/usb/usb_dc.h and sometimes referred to as the usb_dc API.

This API has some limitations by design, it does not follow Device Driver Model and is being replaced by USB device controller (UDC) driver API.

API reference

group _usb_device_controller_api

USB Device Controller API.

Typedefs

typedef void (*usb_dc_ep_callback)(uint8_t ep, enum usb_dc_ep_cb_status_code cb_status): Callback function signature for the USB Endpoint status.

typedef void (*usb_dc_status_callback)(enum usb_dc_status_code cb_status, const uint8_t *param): Callback function signature for the device.

Enums

enum usb_dc_status_code

USB Driver Status Codes.

Status codes reported by the registered device status callback.

Values:

enumerator USB_DC_ERROR: USB error reported by the controller.

enumerator USB_DC_RESET: USB reset.

enumerator USB_DC_CONNECTED: USB connection established, hardware enumeration is completed.

enumerator USB_DC_CONFIGURED: USB configuration done.

enumerator USB_DC_DISCONNECTED: USB connection lost.

enumerator USB_DC_SUSPEND: USB connection suspended by the HOST.

enumerator USB_DC_RESUME: USB connection resumed by the HOST.

enumerator USB_DC_INTERFACE: USB interface selected.

enumerator USB_DC_SET_HALT: Set Feature ENDPOINT_HALT received.

enumerator USB_DC_CLEAR_HALT: Clear Feature ENDPOINT_HALT received.

enumerator USB_DC_SOF: Start of Frame received.

enumerator USB_DC_UNKNOWN: Initial USB connection status.

enum usb_dc_ep_cb_status_code

USB Endpoint Callback Status Codes.

Status Codes reported by the registered endpoint callback.

Values:

enumerator USB_DC_EP_SETUP: SETUP received.

enumerator USB_DC_EP_DATA_OUT: Out transaction on this EP, data is available for read.

enumerator USB_DC_EP_DATA_IN: In transaction done on this EP.

enum usb_dc_ep_transfer_type

USB Endpoint Transfer Type.

Values:

enumerator USB_DC_EP_CONTROL = 0: Control type endpoint.

enumerator USB_DC_EP_ISOCHRONOUS: Isochronous type endpoint.

enumerator USB_DC_EP_BULK: Bulk type endpoint.

enumerator USB_DC_EP_INTERRUPT: Interrupt type endpoint

enum usb_dc_ep_synchronozation_type

USB Endpoint Synchronization Type.

Note

Valid only for Isochronous Endpoints

Values:

enumerator USB_DC_EP_NO_SYNCHRONIZATION = (0U << 2U): No Synchronization.

enumerator USB_DC_EP_ASYNCHRONOUS = (1U << 2U): Asynchronous.

enumerator USB_DC_EP_ADAPTIVE = (2U << 2U): Adaptive.

enumerator USB_DC_EP_SYNCHRONOUS = (3U << 2U): Synchronous.

Functions

int usb_dc_attach(void)

Attach USB for device connection.

Function to attach USB for device connection. Upon success, the USB PLL is enabled, and the USB device is now capable of transmitting and receiving on the USB bus and of generating interrupts.

Returns:: 0 on success, negative errno code on fail.

int usb_dc_detach(void)

Detach the USB device.

Function to detach the USB device. Upon success, the USB hardware PLL is powered down and USB communication is disabled.

Returns:: 0 on success, negative errno code on fail.

int usb_dc_reset(void)

Reset the USB device.

This function returns the USB device and firmware back to it’s initial state. N.B. the USB PLL is handled by the usb_detach function

Returns:: 0 on success, negative errno code on fail.

int usb_dc_set_address(const uint8_t addr)

Set USB device address.

Parameters:

addr – [in] Device address

Returns:

0 on success, negative errno code on fail.

void usb_dc_set_status_callback(const usb_dc_status_callback cb)

Set USB device controller status callback.

Function to set USB device controller status callback. The registered callback is used to report changes in the status of the device controller. The status code are described by the usb_dc_status_code enumeration.

Parameters:

cb – [in] Callback function

int usb_dc_ep_check_cap(const struct usb_dc_ep_cfg_data *const cfg)

check endpoint capabilities

Function to check capabilities of an endpoint. usb_dc_ep_cfg_data structure provides the endpoint configuration parameters: endpoint address, endpoint maximum packet size and endpoint type. The driver should check endpoint capabilities and return 0 if the endpoint configuration is possible.

Parameters:

cfg – [in] Endpoint config

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_configure(const struct usb_dc_ep_cfg_data *const cfg)

Configure endpoint.

Function to configure an endpoint. usb_dc_ep_cfg_data structure provides the endpoint configuration parameters: endpoint address, endpoint maximum packet size and endpoint type.

Parameters:

cfg – [in] Endpoint config

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_set_stall(const uint8_t ep)

Set stall condition for the selected endpoint.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_clear_stall(const uint8_t ep)

Clear stall condition for the selected endpoint.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_is_stalled(const uint8_t ep, uint8_t *const stalled)

Check if the selected endpoint is stalled.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table
stalled – [out] Endpoint stall status

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_halt(const uint8_t ep)

Halt the selected endpoint.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_enable(const uint8_t ep)

Enable the selected endpoint.

Function to enable the selected endpoint. Upon success interrupts are enabled for the corresponding endpoint and the endpoint is ready for transmitting/receiving data.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_disable(const uint8_t ep)

Disable the selected endpoint.

Function to disable the selected endpoint. Upon success interrupts are disabled for the corresponding endpoint and the endpoint is no longer able for transmitting/receiving data.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_flush(const uint8_t ep)

Flush the selected endpoint.

This function flushes the FIFOs for the selected endpoint.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_write(const uint8_t ep, const uint8_t *const data, const uint32_t data_len, uint32_t *const ret_bytes)

Write data to the specified endpoint.

This function is called to write data to the specified endpoint. The supplied usb_ep_callback function will be called when data is transmitted out.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table
data – [in] Pointer to data to write
data_len – [in] Length of the data requested to write. This may be zero for a zero length status packet.
ret_bytes – [out] Bytes scheduled for transmission. This value may be NULL if the application expects all bytes to be written

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_read(const uint8_t ep, uint8_t *const data, const uint32_t max_data_len, uint32_t *const read_bytes)

Read data from the specified endpoint.

This function is called by the endpoint handler function, after an OUT interrupt has been received for that EP. The application must only call this function through the supplied usb_ep_callback function. This function clears the ENDPOINT NAK, if all data in the endpoint FIFO has been read, so as to accept more data from host.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table
data – [in] Pointer to data buffer to write to
max_data_len – [in] Max length of data to read
read_bytes – [out] Number of bytes read. If data is NULL and max_data_len is 0 the number of bytes available for read should be returned.

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_set_callback(const uint8_t ep, const usb_dc_ep_callback cb)

Set callback function for the specified endpoint.

Function to set callback function for notification of data received and available to application or transmit done on the selected endpoint, NULL if callback not required by application code. The callback status code is described by usb_dc_ep_cb_status_code.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table
cb – [in] Callback function

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_read_wait(uint8_t ep, uint8_t *data, uint32_t max_data_len, uint32_t *read_bytes)

Read data from the specified endpoint.

This is similar to usb_dc_ep_read, the difference being that, it doesn’t clear the endpoint NAKs so that the consumer is not bogged down by further upcalls till he is done with the processing of the data. The caller should reactivate ep by invoking usb_dc_ep_read_continue() do so.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table
data – [in] Pointer to data buffer to write to
max_data_len – [in] Max length of data to read
read_bytes – [out] Number of bytes read. If data is NULL and max_data_len is 0 the number of bytes available for read should be returned.

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_read_continue(uint8_t ep)

Continue reading data from the endpoint.

Clear the endpoint NAK and enable the endpoint to accept more data from the host. Usually called after usb_dc_ep_read_wait() when the consumer is fine to accept more data. Thus these calls together act as a flow control mechanism.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table

Returns:

0 on success, negative errno code on fail.

int usb_dc_ep_mps(uint8_t ep)

Get endpoint max packet size.

Parameters:

ep – [in] Endpoint address corresponding to the one listed in the device configuration table

Returns:

Endpoint max packet size (mps)

int usb_dc_wakeup_request(void)

Start the host wake up procedure.

Function to wake up the host if it’s currently in sleep mode.

Returns:: 0 on success, negative errno code on fail.

struct usb_dc_ep_cfg_data

#include <usb_dc.h>

USB Endpoint Configuration.

Structure containing the USB endpoint configuration.

Public Members

uint8_t ep_addr: The number associated with the EP in the device configuration structure IN EP = 0x80 | <endpoint number> OUT EP = 0x00 | <endpoint number>

uint16_t ep_mps: Endpoint max packet size.

enum usb_dc_ep_transfer_type ep_type

Endpoint Transfer Type.

May be Bulk, Interrupt, Control or Isochronous