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 CDC-ACM: Use USB CDC-ACM driver to implement a serial port echo.
USB CDC-ACM composite: Implement a composite USB device exposing two serial ports using USB CDC-ACM driver.
USB DFU (Device Firmware Upgrade): Implement device firmware upgrade using the USB DFU class driver.
USB HID (Human Interface Device): Use USB HID driver to enumerate as a raw HID 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.
WebUSB: Receive and echo data from a web page using WebUSB API.

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, uhc_dev, vid, pid)

USBD_CONFIGURATION_DEFINE(name, attrib, power)

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)

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, d_string)

Create a string descriptor node and serial number string descriptor.

This macro defines a descriptor node and a string descriptor that, when added to the device context, is automatically used as the serial number string descriptor. The string literal parameter is used as a placeholder, the unique number is obtained from hwinfo. Both descriptor node and descriptor are defined with static-storage-class specifier.

Parameters:

d_name – String descriptor node identifier.
d_string – ASCII7 encoded serial number string literal placeholder

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

Enums

enum usbd_desc_usage_type

Values:

enumerator USBD_DUT_STRING_LANG

enumerator USBD_DUT_STRING_MANUFACTURER

enumerator USBD_DUT_STRING_PRODUCT

enumerator USBD_DUT_STRING_SERIAL_NUMBER

enumerator USBD_DUT_STRING_INTERFACE

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

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_msg_register_cb(struct usbd_contex *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_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_code_triple(struct usbd_contex *const uds_ctx, 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
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_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.

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

Public Members

sys_dnode_t node: slist node struct

unsigned int idx: Descriptor index, required for string descriptors.

unsigned int utype: Descriptor usage type (not bDescriptorType)

unsigned int utf16le: If not set, string descriptor must be converted to UTF16LE.

unsigned int custom_sn: If not set, device stack obtains SN using the hwinfo API.

void *desc: Pointer to a descriptor.

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.

struct usbd_contex

#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 configs: slist to manage device configurations

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

void *desc: Pointer to 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_node *const node, uint8_t ep, bool halted): Feature halt state update handler.

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

int (*control_to_dev)(struct usbd_class_node *const node, 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_node *const node, const struct usb_setup_packet *const setup, struct net_buf *const buf): USB control request handler to host.

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

void (*suspended)(struct usbd_class_node *const node): USB power management handler suspended.

void (*resumed)(struct usbd_class_node *const node): USB power management handler resumed.

void (*sof)(struct usbd_class_node *const node): Start of Frame.

void (*enable)(struct usbd_class_node *const node): Class associated configuration is selected.

void (*disable)(struct usbd_class_node *const node): Class associated configuration is disabled.

int (*init)(struct usbd_class_node *const node): Initialization of the class implementation.

void (*shutdown)(struct usbd_class_node *const node): Shutdown of the class implementation.

struct usbd_class_data

#include <usbd.h>

USB device support class data.

Public Members

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

void *desc: Pointer to a class implementation descriptor that should end with a nil descriptor (bLength = 0 and bDescriptorType = 0).

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

uint32_t ep_assigned

Bitmap of all endpoints assigned to the instance.

The IN endpoints are mapped in the upper halfword.

uint32_t ep_active

Bitmap of the enabled endpoints of the instance.

The IN endpoints are mapped in the upper halfword.

uint32_t iface_bm: Bitmap of the bInterfaceNumbers of the class instance.

atomic_t state: Variable to store the state of the class instance.

void *priv: Pointer to private data.

struct usbd_class_node

#include <usbd.h>

Public Members

sys_snode_t node: Node information for the slist.

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

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

struct usbd_class_data *data: Pointer to USB device support class data.