USB device stack (next) API

New USB device stack API is experimental and is subject to change without notice.

API reference

Related code samples

Console over USB CDC ACM: Output "Hello World!" to the console over USB CDC ACM.
USB Audio asynchronous explicit feedback sample: USB Audio 2 explicit feedback sample playing audio on I2S.
USB CDC-ACM: Use USB CDC-ACM driver to implement a serial port echo.
USB HID keyboard: Implement a basic HID keyboard device.
USB Mass Storage: Expose board's RAM or FLASH as a USB disk using USB Mass Storage driver.
USB shell: Use shell commands to interact with USB device stack.

group usbd_api

New USB device stack core API.

Defines

USB_BSTRING_LENGTH(s)

USB_STRING_DESCRIPTOR_LENGTH(s)

USBD_NUMOF_INTERFACES_MAX

USBD_CCTX_REGISTERED: USB Class instance registered flag.

USBD_DEVICE_DEFINE(device_name, udc_dev, vid, pid)

Define USB device context structure.

Macro defines a USB device structure needed by the stack to manage its properties and runtime data. The vid and pid parameters can also be changed using usbd_device_set_vid() and usbd_device_set_pid().

Example of use:

USBD_DEVICE_DEFINE(sample_usbd,
                   DEVICE_DT_GET(DT_NODELABEL(zephyr_udc0)),
                   YOUR_VID, YOUR_PID);

Parameters:

device_name – USB device context name
udc_dev – Pointer to UDC device structure
vid – Vendor ID
pid – Product ID

USBD_CONFIGURATION_DEFINE(name, attrib, power)

Define USB device configuration.

USB device requires at least one configuration instance per supported speed. attrib is a combination of USB_SCD_SELF_POWERED or USB_SCD_REMOTE_WAKEUP, depending on which characteristic the USB device should have in this configuration.

Parameters:

name – Configuration name
attrib – Configuration characteristics. Attributes can also be updated with usbd_config_attrib_rwup() and usbd_config_attrib_self()
power – bMaxPower value in 2 mA units. This value can also be set with usbd_config_maxpower()

USBD_DESC_LANG_DEFINE(name)

Create a string descriptor node and language string descriptor.

This macro defines a descriptor node and a string descriptor that, when added to the device context, is automatically used as the language string descriptor zero. Both descriptor node and descriptor are defined with static-storage-class specifier. Default and currently only supported language ID is 0x0409 English (United States). If string descriptors are used, it is necessary to add this descriptor as the first one to the USB device context.

Parameters:

name – Language string descriptor node identifier.

USBD_DESC_STRING_DEFINE(d_name, d_string, d_utype)

Create a string descriptor.

This macro defines a descriptor node and a string descriptor. The string literal passed to the macro should be in the ASCII7 format. It is converted to UTF16LE format on the host request.

Parameters:

d_name – Internal string descriptor node identifier name
d_string – ASCII7 encoded string literal
d_utype – String descriptor usage type

USBD_DESC_MANUFACTURER_DEFINE(d_name, d_string)

Create a string descriptor node and manufacturer string descriptor.

This macro defines a descriptor node and a string descriptor that, when added to the device context, is automatically used as the manufacturer string descriptor. Both descriptor node and descriptor are defined with static-storage-class specifier.

Parameters:

d_name – String descriptor node identifier.
d_string – ASCII7 encoded manufacturer string literal

USBD_DESC_PRODUCT_DEFINE(d_name, d_string)

Create a string descriptor node and product string descriptor.

This macro defines a descriptor node and a string descriptor that, when added to the device context, is automatically used as the product string descriptor. Both descriptor node and descriptor are defined with static-storage-class specifier.

Parameters:

d_name – String descriptor node identifier.
d_string – ASCII7 encoded product string literal

USBD_DESC_SERIAL_NUMBER_DEFINE(d_name)

Create a string descriptor node and serial number string descriptor.

This macro defines a descriptor node that, when added to the device context, is automatically used as the serial number string descriptor. A valid serial number is generated from HWID (HWINFO= whenever this string descriptor is requested.

Parameters:

d_name – String descriptor node identifier.

USBD_DESC_BOS_DEFINE(name, len, subset)

Define BOS Device Capability descriptor node.

The application defines a BOS capability descriptor node for descriptors such as USB 2.0 Extension Descriptor.

Parameters:

name – Descriptor node identifier
len – Device Capability descriptor length
subset – Pointer to a Device Capability descriptor

USBD_DEFINE_CLASS(class_name, class_api, class_priv, class_v_reqs)

Define USB device support class data.

Macro defines class (function) data, as well as corresponding node structures used internally by the stack.

Parameters:

class_name – Class name
class_api – Pointer to struct usbd_class_api
class_priv – Class private data
class_v_reqs – Pointer to struct usbd_cctx_vendor_req

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

Typedefs

typedef void (*usbd_msg_cb_t)(struct usbd_context *const ctx, const struct usbd_msg *const msg)

Callback type definition for USB device message delivery.

The implementation uses the system workqueue, and a callback provided and registered by the application. The application callback is called in the context of the system workqueue. Notification messages are stored in a queue and delivered to the callback in sequence.

Param ctx:: [in] Pointer to USB device support context
Param msg:: [in] Pointer to USB device message

Enums

enum usbd_ch9_state

USB device support middle layer runtime state.

Part of USB device states without suspended and powered states, as it is better to track them separately.

Values:

enumerator USBD_STATE_DEFAULT = 0

enumerator USBD_STATE_ADDRESS

enumerator USBD_STATE_CONFIGURED

enum usbd_speed

USB device speed.

Values:

enumerator USBD_SPEED_FS: Device supports or is connected to a full speed bus.

enumerator USBD_SPEED_HS: Device supports or is connected to a high speed bus

enumerator USBD_SPEED_SS: Device supports or is connected to a super speed bus.

Functions

static inline struct usbd_context *usbd_class_get_ctx(const struct usbd_class_data *const c_data)

Get the USB device runtime context under which the class is registered.

The class implementation must use this function and not access the members of the struct directly.

Parameters:

c_data – [in] Pointer to USB device class data

Returns:

Pointer to USB device runtime context

static inline void *usbd_class_get_private(const struct usbd_class_data *const c_data)

Get class implementation private data.

The class implementation must use this function and not access the members of the struct directly.

Parameters:

c_data – [in] Pointer to USB device class data

Returns:

Pointer to class implementation private data

int usbd_add_descriptor(struct usbd_context *uds_ctx, struct usbd_desc_node *dn)

Add common USB descriptor.

Add common descriptor like string or BOS Device Capability.

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.

uint8_t usbd_str_desc_get_idx(const struct usbd_desc_node *const desc_nd)

Get USB string descriptor index from descriptor node.

Parameters:

desc_nd – [in] Pointer to USB descriptor node

Returns:

Descriptor index, 0 if descriptor is not part of any device

void usbd_remove_descriptor(struct usbd_desc_node *const desc_nd)

Remove USB string descriptor.

Remove linked USB string descriptor from any list.

Parameters:

desc_nd – [in] Pointer to USB descriptor node

int usbd_add_configuration(struct usbd_context *uds_ctx, const enum usbd_speed speed, struct usbd_config_node *cd)

Add a USB device configuration.

Parameters:

uds_ctx – [in] Pointer to USB device support context
speed – [in] Speed at which this configuration operates
cd – [in] Pointer to USB configuration node

Returns:

0 on success, other values on fail.

int usbd_register_class(struct usbd_context *uds_ctx, const char *name, const enum usbd_speed speed, 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
speed – [in] Configuration speed
cfg – [in] Configuration value (bConfigurationValue)

Returns:

0 on success, other values on fail.

int usbd_register_all_classes(struct usbd_context *uds_ctx, const enum usbd_speed speed, uint8_t cfg)

Register all available USB class instances.

Register all available instances. Like usbd_register_class, but does not take the instance name and instead registers all available instances.

Note

This cannot be combined. If your application calls usbd_register_class for any device, configuration number, or instance, either usbd_register_class or this function will fail.

Parameters:

uds_ctx – [in] Pointer to USB device support context
speed – [in] Configuration speed
cfg – [in] Configuration value (bConfigurationValue)

Returns:

0 on success, other values on fail.

int usbd_unregister_class(struct usbd_context *uds_ctx, const char *name, const enum usbd_speed speed, 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
speed – [in] Configuration speed
cfg – [in] Configuration value (bConfigurationValue)

Returns:

0 on success, other values on fail.

int usbd_unregister_all_classes(struct usbd_context *uds_ctx, const enum usbd_speed speed, uint8_t cfg)

Unregister all available USB class instances.

Unregister all available instances. Like usbd_unregister_class, but does not take the instance name and instead unregisters all available instances.

Parameters:

uds_ctx – [in] Pointer to USB device support context
speed – [in] Configuration speed
cfg – [in] Configuration value (bConfigurationValue)

Returns:

0 on success, other values on fail.

int usbd_msg_register_cb(struct usbd_context *const uds_ctx, const usbd_msg_cb_t cb)

Register USB notification message callback.

Parameters:

uds_ctx – [in] Pointer to USB device support context
cb – [in] Pointer to message callback function

Returns:

0 on success, other values on fail.

int usbd_init(struct usbd_context *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_context *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_context *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_context *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_context *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_context *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_context *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_buf_alloc(const struct usbd_class_data *const c_data, 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_data – [in] Pointer to USB device class data
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_context *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_data *const c_data, struct net_buf *const buf)

Queue USB device request.

Add request to the queue.

Parameters:

c_data – [in] Pointer to USB device class data
buf – [in] Pointer to UDC request buffer

Returns:

0 on success, or error from udc_ep_enqueue()

int usbd_ep_dequeue(struct usbd_context *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_context *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_context *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_context *uds_ctx)

Initiate the USB remote wakeup (TBD)

Returns:: 0 on success, other values on fail.

enum usbd_speed usbd_bus_speed(const struct usbd_context *const uds_ctx)

Get actual device speed.

Parameters:

uds_ctx – [in] Pointer to a device context

Returns:

Actual device speed

enum usbd_speed usbd_caps_speed(const struct usbd_context *const uds_ctx)

Get highest speed supported by the controller.

Parameters:

uds_ctx – [in] Pointer to a device context

Returns:

Highest supported speed

int usbd_device_set_bcd(struct usbd_context *const uds_ctx, const enum usbd_speed speed, const uint16_t bcd)

Set USB device descriptor value bcdUSB.

Parameters:

uds_ctx – [in] Pointer to USB device support context
speed – [in] Speed for which the bcdUSB should be set
bcd – [in] bcdUSB value

Returns:

0 on success, other values on fail.

int usbd_device_set_vid(struct usbd_context *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_context *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_code_triple(struct usbd_context *const uds_ctx, const enum usbd_speed speed, const uint8_t base_class, const uint8_t subclass, const uint8_t protocol)

Set USB device descriptor code triple Base Class, SubClass, and Protocol.

Parameters:

uds_ctx – [in] Pointer to USB device support context
speed – [in] Speed for which the code triple should be set
base_class – [in] bDeviceClass value
subclass – [in] bDeviceSubClass value
protocol – [in] bDeviceProtocol value

Returns:

0 on success, other values on fail.

int usbd_config_attrib_rwup(struct usbd_context *const uds_ctx, const enum usbd_speed speed, const uint8_t cfg, const bool enable)

Setup USB device configuration attribute Remote Wakeup.

Parameters:

uds_ctx – [in] Pointer to USB device support context
speed – [in] Configuration speed
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_context *const uds_ctx, const enum usbd_speed speed, const uint8_t cfg, const bool enable)

Setup USB device configuration attribute Self-powered.

Parameters:

uds_ctx – [in] Pointer to USB device support context
speed – [in] Configuration speed
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_context *const uds_ctx, const enum usbd_speed speed, const uint8_t cfg, const uint8_t power)

Setup USB device configuration power consumption.

Parameters:

uds_ctx – [in] Pointer to USB device support context
speed – [in] Configuration speed
cfg – [in] Configuration number
power – [in] Maximum power consumption value (bMaxPower)

Returns:

0 on success, other values on fail.

bool usbd_can_detect_vbus(struct usbd_context *const uds_ctx)

Check that the controller can detect the VBUS state change.

This can be used in a generic application to explicitly handle the VBUS detected event after usbd_init(). For example, to call usbd_enable() after a short delay to give the PMIC time to detect the bus, or to handle cases where usbd_enable() can only be called after a VBUS detected event.

Parameters:

uds_ctx – [in] Pointer to USB device support context

Returns:

true if controller can detect VBUS state change, false otherwise

struct usbd_str_desc_data

#include <usbd.h>

Used internally to keep descriptors in order.

USBD string descriptor data

Public Members

uint8_t idx: Descriptor index, required for string descriptors.

enum usbd_str_desc_utype utype: Descriptor usage type (not bDescriptorType)

unsigned int ascii7: The string descriptor is in ASCII7 format.

unsigned int use_hwinfo: Device stack obtains SerialNumber using the HWINFO API.

struct usbd_bos_desc_data

#include <usbd.h>

USBD BOS Device Capability descriptor data.

Public Members

enum usbd_bos_desc_utype utype: Descriptor usage type (not bDescriptorType)

struct usbd_desc_node

#include <usbd.h>

Descriptor node.

Descriptor node is used to manage descriptors that are not directly part of a structure, such as string or BOS capability descriptors.

Public Members

sys_dnode_t node: slist node struct

const void *const ptr: Opaque pointer to a descriptor payload.

uint8_t bLength: Descriptor size in bytes.

uint8_t bDescriptorType: Descriptor type.

struct usbd_config_node

#include <usbd.h>

Device configuration node.

Configuration node is used to manage device configurations, at least one configuration is required. It does not have an index, instead bConfigurationValue of the descriptor is used for identification.

Public Members

sys_snode_t node: slist node struct

void *desc: Pointer to configuration descriptor.

sys_slist_t class_list: List of registered classes (functions)

struct usbd_ch9_data

#include <usbd.h>

USB device support middle layer runtime data.

Public Members

struct usb_setup_packet setup: Setup packet, up-to-date for the respective control request.

int ctrl_type: Control type, internally used for stage verification.

enum usbd_ch9_state state: Protocol state of the USB device stack.

uint32_t ep_halt: Halted endpoints bitmap.

uint8_t configuration: USB device stack selected configuration.

bool post_status

Post status stage work required, e.g.

set new device address

uint8_t alternate[16U]: Array to track interfaces alternate settings.

struct usbd_status

#include <usbd.h>

USB device support status.

Public Members

unsigned int initialized: USB device support is initialized.

unsigned int enabled: USB device support is enabled.

unsigned int suspended: USB device is suspended.

unsigned int rwup: USB remote wake-up feature is enabled.

enum usbd_speed speed: USB device speed.

struct usbd_context

#include <usbd.h>

USB device support runtime context.

Main structure that organizes all descriptors, configuration, and interfaces. An UDC device must be assigned to this structure.

Public Members

const char *name: Name of the USB device.

struct k_mutex mutex: Access mutex.

const struct device *dev: Pointer to UDC device.

usbd_msg_cb_t msg_cb: Notification message recipient callback.

struct usbd_ch9_data ch9_data: Middle layer runtime data.

sys_dlist_t descriptors: slist to manage descriptors like string, BOS

sys_slist_t fs_configs: slist to manage Full-Speed device configurations

sys_slist_t hs_configs: slist to manage High-Speed device configurations

struct usbd_status status: Status of the USB device support.

void *fs_desc: Pointer to Full-Speed device descriptor.

void *hs_desc: Pointer to High-Speed device descriptor.

struct usbd_cctx_vendor_req

#include <usbd.h>

Vendor Requests Table.

Public Members

const uint8_t *reqs: Array of vendor requests supported by the class.

uint8_t len: Length of the array.

struct usbd_class_api

#include <usbd.h>

USB device support class instance API.

Public Members

void (*feature_halt)(struct usbd_class_data *const c_data, uint8_t ep, bool halted): Feature halt state update handler.

void (*update)(struct usbd_class_data *const c_data, uint8_t iface, uint8_t alternate): Configuration update handler.

int (*control_to_dev)(struct usbd_class_data *const c_data, const struct usb_setup_packet *const setup, const struct net_buf *const buf): USB control request handler to device.

int (*control_to_host)(struct usbd_class_data *const c_data, const struct usb_setup_packet *const setup, struct net_buf *const buf): USB control request handler to host.

int (*request)(struct usbd_class_data *const c_data, struct net_buf *buf, int err): Endpoint request completion event handler.

void (*suspended)(struct usbd_class_data *const c_data): USB power management handler suspended.

void (*resumed)(struct usbd_class_data *const c_data): USB power management handler resumed.

void (*sof)(struct usbd_class_data *const c_data): Start of Frame.

void (*enable)(struct usbd_class_data *const c_data): Class associated configuration is selected.

void (*disable)(struct usbd_class_data *const c_data): Class associated configuration is disabled.

int (*init)(struct usbd_class_data *const c_data): Initialization of the class implementation.

void (*shutdown)(struct usbd_class_data *const c_data): Shutdown of the class implementation.

void *(*get_desc)(struct usbd_class_data *const c_data, const enum usbd_speed speed): Get function descriptor based on speed parameter.

struct usbd_class_data

#include <usbd.h>

USB device support class data.

Public Members

const char *name: Name of the USB device class instance.

struct usbd_context *uds_ctx: Pointer to USB device stack context structure.

const struct usbd_class_api *api: Pointer to device support class API.

const struct usbd_cctx_vendor_req *v_reqs: Supported vendor request table, can be NULL.

void *priv: Pointer to private data.

group usbd_msg_api

Enums

enum usbd_msg_type

USB device support message types.

The first set of message types map to event types from the UDC driver API.

Values:

enumerator USBD_MSG_VBUS_READY: VBUS ready message (optional)

enumerator USBD_MSG_VBUS_REMOVED: VBUS removed message (optional)

enumerator USBD_MSG_RESUME: Device resume message.

enumerator USBD_MSG_SUSPEND: Device suspended message.

enumerator USBD_MSG_RESET: Bus reset detected.

enumerator USBD_MSG_UDC_ERROR: Non-correctable UDC error message

enumerator USBD_MSG_STACK_ERROR: Unrecoverable device stack error message

enumerator USBD_MSG_CDC_ACM_LINE_CODING: CDC ACM Line Coding update.

enumerator USBD_MSG_CDC_ACM_CONTROL_LINE_STATE: CDC ACM Line State update.

enumerator USBD_MSG_MAX_NUMBER: Maximum number of message types.

Functions

static inline const char *usbd_msg_type_string(const enum usbd_msg_type type)

Returns the message type as a constant string.

Parameters:

type – [in] USBD message type

Returns:

Message type as a constant string

struct usbd_msg

#include <usbd_msg.h>

USB device message.

Public Members

enum usbd_msg_type type: Message type.

union usbd_msg: Message status, value or data.