USB device core support

The new USB device support is experimental and under development. It consists of low level USB device controller (UDC) driver API, USB device stack (core) and different functions implementing specific classes. The device stack and driver API bring multiple device support for the (rare) case that a board has multiple USB device controllers. Device stack has support for multiple configurations and a class instance can be added or removed at runtime to a configuration. The stack provides a specific API for implementing the functions (classes). This takes over the configuration of the class interfaces and endpoints, and also the communication with the stack and driver API. The stack can be enabled by the CONFIG_USB_DEVICE_STACK_NEXT.

The first time there will be only one sample for the new USB support, USB support shell sample, with all available USB support shell commands. The sample is mainly to help test the capabilities of the stack and correct implementation of the USB controller drivers.

USB device stack core API reference

group usbd_api

New USB device stack core API.

Defines

USBD_DEVICE_DEFINE(device_name, uhc_dev, vid, pid)
USBD_CONFIGURATION_DEFINE(name, attrib, power)
USBD_DESC_LANG_DEFINE(name)
USBD_DESC_STRING_DEFINE(d_name, d_string, d_idx)
USBD_DEFINE_CLASS(class_name, class_api, class_data)
VENDOR_REQ_DEFINE(_reqs, _len)

Helper to declare request table of usbd_cctx_vendor_req.

Parameters:

  • _reqs – Pointer to the vendor request field

  • _len – Number of supported vendor requests

USBD_VENDOR_REQ(_reqs...)

Helper to declare supported vendor requests.

Parameters:

  • _reqs – Variable number of vendor requests

Functions

int usbd_add_descriptor(struct usbd_contex *uds_ctx, struct usbd_desc_node *dn)

Add common USB descriptor.

Add common descriptor like string or bos.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • dn – [in] Pointer to USB descriptor node

Returns:

0 on success, other values on fail.

int usbd_add_configuration(struct usbd_contex *uds_ctx, struct usbd_config_node *cd)

Add a USB device configuration.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • cd – [in] Pointer to USB configuration node

Returns:

0 on success, other values on fail.

int usbd_register_class(struct usbd_contex *uds_ctx, const char *name, uint8_t cfg)

Register an USB class instance.

An USB class implementation can have one or more instances. To identify the instances we use device drivers API. Device names have a prefix derived from the name of the class, for example CDC_ACM for CDC ACM class instance, and can also be easily identified in the shell. Class instance can only be registered when the USB device stack is disabled. Registered instances are initialized at initialization of the USB device stack, and the interface descriptors of each instance are adapted to the whole context.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • name – [in] Class instance name

  • cfg – [in] Configuration value (similar to bConfigurationValue)

Returns:

0 on success, other values on fail.

int usbd_unregister_class(struct usbd_contex *uds_ctx, const char *name, uint8_t cfg)

Unregister an USB class instance.

USB class instance will be removed and will not appear on the next start of the stack. Instance can only be unregistered when the USB device stack is disabled.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • name – [in] Class instance name

  • cfg – [in] Configuration value (similar to bConfigurationValue)

Returns:

0 on success, other values on fail.

int usbd_init(struct usbd_contex *uds_ctx)

Initialize USB device.

Initialize USB device descriptors and configuration, initialize USB device controller. Class instances should be registered before they are involved. However, the stack should also initialize without registered instances, even if the host would complain about missing interfaces.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

Returns:

0 on success, other values on fail.

int usbd_enable(struct usbd_contex *uds_ctx)

Enable the USB device support and registered class instances.

This function enables the USB device support.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

Returns:

0 on success, other values on fail.

int usbd_disable(struct usbd_contex *uds_ctx)

Disable the USB device support.

This function disables the USB device support.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

Returns:

0 on success, other values on fail.

int usbd_shutdown(struct usbd_contex *const uds_ctx)

Shutdown the USB device support.

This function completely disables the USB device support.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

Returns:

0 on success, other values on fail.

int usbd_ep_set_halt(struct usbd_contex *uds_ctx, uint8_t ep)

Halt endpoint.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • ep – [in] Endpoint address

Returns:

0 on success, or error from udc_ep_set_halt()

int usbd_ep_clear_halt(struct usbd_contex *uds_ctx, uint8_t ep)

Clear endpoint halt.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • ep – [in] Endpoint address

Returns:

0 on success, or error from udc_ep_clear_halt()

bool usbd_ep_is_halted(struct usbd_contex *uds_ctx, uint8_t ep)

Checks whether the endpoint is halted.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • ep – [in] Endpoint address

Returns:

true if endpoint is halted, false otherwise

struct net_buf *usbd_ep_ctrl_buf_alloc(struct usbd_contex *const uds_ctx, const uint8_t ep, const size_t size)

Allocate buffer for USB device control request.

Allocate a new buffer from controller’s driver buffer pool.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • ep – [in] Endpoint address

  • size – [in] Size of the request buffer

Returns:

pointer to allocated request or NULL on error.

struct net_buf *usbd_ep_buf_alloc(const struct usbd_class_node *const c_nd, const uint8_t ep, const size_t size)

Allocate buffer for USB device request.

Allocate a new buffer from controller’s driver buffer pool.

Parameters:

  • c_nd – [in] Pointer to USB device class node

  • ep – [in] Endpoint address

  • size – [in] Size of the request buffer

Returns:

pointer to allocated request or NULL on error.

int usbd_ep_ctrl_enqueue(struct usbd_contex *const uds_ctx, struct net_buf *const buf)

Queue USB device control request.

Add control request to the queue.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • buf – [in] Pointer to UDC request buffer

Returns:

0 on success, all other values should be treated as error.

int usbd_ep_enqueue(const struct usbd_class_node *const c_nd, struct net_buf *const buf)

Queue USB device request.

Add request to the queue.

Parameters:

  • c_nd – [in] Pointer to USB device class node

  • buf – [in] Pointer to UDC request buffer

Returns:

0 on success, or error from udc_ep_enqueue()

int usbd_ep_dequeue(struct usbd_contex *uds_ctx, const uint8_t ep)

Remove all USB device controller requests from endpoint queue.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • ep – [in] Endpoint address

Returns:

0 on success, or error from udc_ep_dequeue()

int usbd_ep_buf_free(struct usbd_contex *uds_ctx, struct net_buf *buf)

Free USB device request buffer.

Put the buffer back into the request buffer pool.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • buf – [in] Pointer to UDC request buffer

Returns:

0 on success, all other values should be treated as error.

bool usbd_is_suspended(struct usbd_contex *uds_ctx)

Checks whether the USB device controller is suspended.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

Returns:

true if endpoint is halted, false otherwise

int usbd_wakeup_request(struct usbd_contex *uds_ctx)

Initiate the USB remote wakeup (TBD)

Returns:

0 on success, other values on fail.

int usbd_device_set_bcd(struct usbd_contex *const uds_ctx, const uint16_t bcd)

Set USB device descriptor value bcdUSB.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • bcd – [in] bcdUSB value

Returns:

0 on success, other values on fail.

int usbd_device_set_vid(struct usbd_contex *const uds_ctx, const uint16_t vid)

Set USB device descriptor value idVendor.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • vid – [in] idVendor value

Returns:

0 on success, other values on fail.

int usbd_device_set_pid(struct usbd_contex *const uds_ctx, const uint16_t pid)

Set USB device descriptor value idProduct.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • pid – [in] idProduct value

Returns:

0 on success, other values on fail.

int usbd_device_set_class(struct usbd_contex *const uds_ctx, const uint8_t value)

Set USB device descriptor value bDeviceClass.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • value – [in] bDeviceClass value

Returns:

0 on success, other values on fail.

int usbd_device_set_subclass(struct usbd_contex *const uds_ctx, const uint8_t value)

Set USB device descriptor value bDeviceSubClass.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • value – [in] bDeviceSubClass value

Returns:

0 on success, other values on fail.

int usbd_device_set_proto(struct usbd_contex *const uds_ctx, const uint8_t value)

Set USB device descriptor value bDeviceProtocol.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • value – [in] bDeviceProtocol value

Returns:

0 on success, other values on fail.

int usbd_config_attrib_rwup(struct usbd_contex *const uds_ctx, const uint8_t cfg, const bool enable)

Setup USB device configuration attribute Remote Wakeup.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • cfg – [in] Configuration number

  • enable – [in] Sets attribute if true, clears it otherwise

Returns:

0 on success, other values on fail.

int usbd_config_attrib_self(struct usbd_contex *const uds_ctx, const uint8_t cfg, const bool enable)

Setup USB device configuration attribute Self-powered.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • cfg – [in] Configuration number

  • enable – [in] Sets attribute if true, clears it otherwise

Returns:

0 on success, other values on fail.

int usbd_config_maxpower(struct usbd_contex *const uds_ctx, const uint8_t cfg, const uint8_t power)

Setup USB device configuration power consumption.

Parameters:

  • uds_ctx – [in] Pointer to USB device support context

  • cfg – [in] Configuration number

  • power – [in] Maximum power consumption value (bMaxPower)

Returns:

0 on success, other values on fail.

UDC driver API reference

The new USB device controller (UDC) driver API implements the low level layer to interface with USB device controller. UDC driver API is experimental and is subject to change without notice, it is described in include/drivers/usb/udc.h.

group udc_api

New USB device controller (UDC) driver API.

Functions

static inline bool udc_is_initialized(const struct device *dev)

Checks whether the controller is initialized.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

Returns:

true if controller is initialized, false otherwise

static inline bool udc_is_enabled(const struct device *dev)

Checks whether the controller is enabled.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

Returns:

true if controller is enabled, false otherwise

static inline bool udc_is_suspended(const struct device *dev)

Checks whether the controller is suspended.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

Returns:

true if controller is suspended, false otherwise

int udc_init(const struct device *dev, udc_event_cb_t event_cb)

Initialize USB device controller.

Initialize USB device controller and control IN/OUT endpoint. After initialization controller driver should be able to detect power state of the bus and signal power state changes.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

  • event_cb – [in] Event callback from the higher layer (USB device stack)

Return values:

  • -EINVAL – on parameter error (no callback is passed)

  • -EALREADY – already initialized

Returns:

0 on success, all other values should be treated as error.

int udc_enable(const struct device *dev)

Enable USB device controller.

Enable powered USB device controller and allow host to recognize and enumerate the device.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

Return values:

  • -EPERM – controller is not initialized

  • -EALREADY – already enabled

Returns:

0 on success, all other values should be treated as error.

int udc_disable(const struct device *dev)

Disable USB device controller.

Disable enabled USB device controller. The driver should continue to detect power state changes.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

Return values:

-EALREADY – already disabled

Returns:

0 on success, all other values should be treated as error.

int udc_shutdown(const struct device *dev)

Poweroff USB device controller.

Shut down the controller completely to reduce energy consumption or to change the role of the controller.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

Return values:

-EALREADY – controller is not initialized

Returns:

0 on success, all other values should be treated as error.

static inline struct udc_device_caps udc_caps(const struct device *dev)

Get USB device controller capabilities.

Obtain the capabilities of the controller such as full speed (FS), high speed (HS), and more.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

Returns:

USB device controller capabilities.

enum udc_bus_speed udc_device_speed(const struct device *dev)

Get actual USB device speed.

The function should be called after the reset event to determine the actual bus speed.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

Returns:

USB device controller capabilities.

static inline int udc_set_address(const struct device *dev, const uint8_t addr)

Set USB device address.

Set address of enabled USB device.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

  • addr – [in] USB device address

Return values:

-EPERM – controller is not enabled (or not initialized)

Returns:

0 on success, all other values should be treated as error.

static inline int udc_host_wakeup(const struct device *dev)

Initiate host wakeup procedure.

Initiate host wakeup. Only possible when the bus is suspended.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

Return values:

-EPERM – controller is not enabled (or not initialized)

Returns:

0 on success, all other values should be treated as error.

int udc_ep_try_config(const struct device *dev, const uint8_t ep, const uint8_t attributes, uint16_t *const mps, const uint8_t interval)

Try an endpoint configuration.

Try an endpoint configuration based on endpoint descriptor. This function may modify wMaxPacketSize descriptor fields of the endpoint. All properties of the descriptor, such as direction, and transfer type, should be set correctly. If wMaxPacketSize value is zero, it will be updated to maximum buffer size of the enpoint.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

  • ep – [in] Endpoint address (same as bEndpointAddress)

  • attributes – [in] Endpoint attributes (same as bmAttributes)

  • mps – [in] Maximum packet size (same as wMaxPacketSize)

  • interval – [in] Polling interval (same as bInterval)

Return values:

  • -EINVAL – on wrong parameter

  • -ENOTSUP – endpoint configuration not supported

  • -ENODEV – no endpoints available

Returns:

0 on success, all other values should be treated as error.

int udc_ep_enable(const struct device *dev, const uint8_t ep, const uint8_t attributes, const uint16_t mps, const uint8_t interval)

Configure and enable endpoint.

Configure and make an endpoint ready for use. Valid for all endpoints except control IN/OUT.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

  • ep – [in] Endpoint address (same as bEndpointAddress)

  • attributes – [in] Endpoint attributes (same as bmAttributes)

  • mps – [in] Maximum packet size (same as wMaxPacketSize)

  • interval – [in] Polling interval (same as bInterval)

Return values:

  • -EINVAL – on wrong parameter (control IN/OUT endpoint)

  • -EPERM – controller is not initialized

  • -ENODEV – endpoint configuration not found

  • -EALREADY – endpoint is already enabled

Returns:

0 on success, all other values should be treated as error.

int udc_ep_disable(const struct device *dev, const uint8_t ep)

Disable endpoint.

Valid for all endpoints except control IN/OUT.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

  • ep – [in] Endpoint address

Return values:

  • -EINVAL – on wrong parameter (control IN/OUT endpoint)

  • -ENODEV – endpoint configuration not found

  • -EALREADY – endpoint is already disabled

  • -EPERM – controller is not initialized

Returns:

0 on success, all other values should be treated as error.

int udc_ep_set_halt(const struct device *dev, const uint8_t ep)

Halt endpoint.

Valid for all endpoints.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

  • ep – [in] Endpoint address

Return values:

  • -ENODEV – endpoint configuration not found

  • -ENOTSUP – not supported (e.g. isochronous endpoint)

  • -EPERM – controller is not enabled

Returns:

0 on success, all other values should be treated as error.

int udc_ep_clear_halt(const struct device *dev, const uint8_t ep)

Clear endpoint halt.

Valid for all endpoints.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

  • ep – [in] Endpoint address

Return values:

  • -ENODEV – endpoint configuration not found

  • -ENOTSUP – not supported (e.g. isochronous endpoint)

  • -EPERM – controller is not enabled

Returns:

0 on success, all other values should be treated as error.

int udc_ep_enqueue(const struct device *dev, struct net_buf *const buf)

Queue USB device controller request.

Add request to the queue. If the queue is empty, the request buffer can be claimed by the controller immediately.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

  • buf – [in] Pointer to UDC request buffer

Return values:

  • -ENODEV – endpoint configuration not found

  • -EACCES – endpoint is not enabled (TBD)

  • -EBUSY – request can not be queued

  • -EPERM – controller is not initialized

Returns:

0 on success, all other values should be treated as error.

int udc_ep_dequeue(const struct device *dev, const uint8_t ep)

Remove all USB device controller requests from endpoint queue.

UDC_EVT_EP_REQUEST event will be generated when the driver releases claimed buffer, no new requests will be claimed, all requests in the queue will passed as chained list of the event variable buf. The endpoint queue is empty after that.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

  • ep – [in] Endpoint address

Return values:

  • -ENODEV – endpoint configuration not found

  • -EACCES – endpoint is not disabled

  • -EPERM – controller is not initialized

Returns:

0 on success, all other values should be treated as error.

struct net_buf *udc_ep_buf_alloc(const struct device *dev, const uint8_t ep, const size_t size)

Allocate UDC request buffer.

Allocate a new buffer from common request buffer pool.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

  • ep – [in] Endpoint address

  • size – [in] Size of the request buffer

Returns:

pointer to allocated request or NULL on error.

int udc_ep_buf_free(const struct device *dev, struct net_buf *const buf)

Free UDC request buffer.

Put the buffer back into the request buffer pool.

Parameters:

  • dev – [in] Pointer to device struct of the driver instance

  • buf – [in] Pointer to UDC request buffer

Returns:

0 on success, all other values should be treated as error.

static inline void udc_ep_buf_set_zlp(struct net_buf *const buf)

Set ZLP flag in requests metadata.

The controller should send a ZLP at the end of the transfer.

Parameters:

  • buf – [in] Pointer to UDC request buffer

static inline struct udc_buf_info *udc_get_buf_info(const struct net_buf *const buf)

Get requests metadata.

Parameters:

  • buf – [in] Pointer to UDC request buffer

Returns:

pointer to metadata structure.