New USB device stack core API. More...

Data Structures
struct	usbd_str_desc_data
	Used internally to keep descriptors in order. More...

struct	usbd_bos_desc_data
	USBD BOS Device Capability descriptor data. More...

struct	usbd_desc_node
	Descriptor node. More...

struct	usbd_config_node
	Device configuration node. More...

struct	usbd_ch9_data
	USB device support middle layer runtime data. More...

struct	usbd_status
	USB device support status. More...

struct	usbd_context
	USB device support runtime context. More...

struct	usbd_cctx_vendor_req
	Vendor Requests Table. More...

struct	usbd_class_api
	USB device support class instance API. More...

struct	usbd_class_data
	USB device support class data. More...

Macros
#define	USB_BSTRING_LENGTH(s) (sizeof(s) * 2 - 2)

#define	USB_STRING_DESCRIPTOR_LENGTH(s) (sizeof(s) * 2)

#define	USBD_NUMOF_INTERFACES_MAX 16U

#define	USBD_CCTX_REGISTERED 0
	USB Class instance registered flag.

#define	USBD_DEVICE_DEFINE(device_name, udc_dev, vid, pid)
	Define USB device context structure.

#define	USBD_CONFIGURATION_DEFINE(name, attrib, power, desc_nd)
	Define USB device configuration.

#define	USBD_DESC_LANG_DEFINE(name)
	Create a string descriptor node and language string descriptor.

#define	USBD_DESC_STRING_DEFINE(d_name, d_string, d_utype)
	Create a string descriptor.

#define	USBD_DESC_MANUFACTURER_DEFINE(d_name, d_string) USBD_DESC_STRING_DEFINE(d_name, d_string, USBD_DUT_STRING_MANUFACTURER)
	Create a string descriptor node and manufacturer string descriptor.

#define	USBD_DESC_PRODUCT_DEFINE(d_name, d_string) USBD_DESC_STRING_DEFINE(d_name, d_string, USBD_DUT_STRING_PRODUCT)
	Create a string descriptor node and product string descriptor.

#define	USBD_DESC_SERIAL_NUMBER_DEFINE(d_name)
	Create a string descriptor node and serial number string descriptor.

#define	USBD_DESC_CONFIG_DEFINE(d_name, d_string) USBD_DESC_STRING_DEFINE(d_name, d_string, USBD_DUT_STRING_CONFIG)
	Create a string descriptor node for configuration descriptor.

#define	USBD_DESC_BOS_DEFINE(name, len, subset)
	Define BOS Device Capability descriptor node.

#define	USBD_DEFINE_CLASS(class_name, class_api, class_priv, class_v_reqs)
	Define USB device support class data.

#define	VENDOR_REQ_DEFINE(_reqs, _len)
	Helper to declare request table of usbd_cctx_vendor_req.

#define	USBD_VENDOR_REQ(_reqs...)
	Helper to declare supported 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.

Enumerations
enum	usbd_ch9_state { USBD_STATE_DEFAULT = 0 , USBD_STATE_ADDRESS , USBD_STATE_CONFIGURED }
	USB device support middle layer runtime state. More...

enum	usbd_speed { USBD_SPEED_FS , USBD_SPEED_HS , USBD_SPEED_SS }
	USB device speed. More...

Functions
static 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.

static void *	usbd_class_get_private (const struct usbd_class_data *const c_data)
	Get class implementation private data.

int	usbd_add_descriptor (struct usbd_context uds_ctx, struct usbd_desc_node dn)
	Add common USB descriptor.

uint8_t	usbd_str_desc_get_idx (const struct usbd_desc_node *const desc_nd)
	Get USB string descriptor index from descriptor node.

void	usbd_remove_descriptor (struct usbd_desc_node *const desc_nd)
	Remove USB string descriptor.

int	usbd_add_configuration (struct usbd_context uds_ctx, const enum usbd_speed speed, struct usbd_config_node cd)
	Add a USB device configuration.

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.

int	usbd_register_all_classes (struct usbd_context *uds_ctx, const enum usbd_speed speed, uint8_t cfg)
	Register all available USB class instances.

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.

int	usbd_unregister_all_classes (struct usbd_context *uds_ctx, const enum usbd_speed speed, uint8_t cfg)
	Unregister all available USB class instances.

int	usbd_msg_register_cb (struct usbd_context *const uds_ctx, const usbd_msg_cb_t cb)
	Register USB notification message callback.

int	usbd_init (struct usbd_context *uds_ctx)
	Initialize USB device.

int	usbd_enable (struct usbd_context *uds_ctx)
	Enable the USB device support and registered class instances.

int	usbd_disable (struct usbd_context *uds_ctx)
	Disable the USB device support.

int	usbd_shutdown (struct usbd_context *const uds_ctx)
	Shutdown the USB device support.

int	usbd_ep_set_halt (struct usbd_context *uds_ctx, uint8_t ep)
	Halt endpoint.

int	usbd_ep_clear_halt (struct usbd_context *uds_ctx, uint8_t ep)
	Clear endpoint halt.

bool	usbd_ep_is_halted (struct usbd_context *uds_ctx, uint8_t ep)
	Checks whether the endpoint is halted.

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.

int	usbd_ep_ctrl_enqueue (struct usbd_context const uds_ctx, struct net_buf const buf)
	Queue USB device control request.

int	usbd_ep_enqueue (const struct usbd_class_data const c_data, struct net_buf const buf)
	Queue USB device request.

int	usbd_ep_dequeue (struct usbd_context *uds_ctx, const uint8_t ep)
	Remove all USB device controller requests from endpoint queue.

int	usbd_ep_buf_free (struct usbd_context uds_ctx, struct net_buf buf)
	Free USB device request buffer.

bool	usbd_is_suspended (struct usbd_context *uds_ctx)
	Checks whether the USB device controller is suspended.

int	usbd_wakeup_request (struct usbd_context *uds_ctx)
	Initiate the USB remote wakeup (TBD)

enum usbd_speed	usbd_bus_speed (const struct usbd_context *const uds_ctx)
	Get actual device speed.

enum usbd_speed	usbd_caps_speed (const struct usbd_context *const uds_ctx)
	Get highest speed supported by the controller.

int	usbd_device_set_bcd_usb (struct usbd_context *const uds_ctx, const enum usbd_speed speed, const uint16_t bcd)
	Set USB device descriptor value bcdUSB.

int	usbd_device_set_vid (struct usbd_context *const uds_ctx, const uint16_t vid)
	Set USB device descriptor value idVendor.

int	usbd_device_set_pid (struct usbd_context *const uds_ctx, const uint16_t pid)
	Set USB device descriptor value idProduct.

int	usbd_device_set_bcd_device (struct usbd_context *const uds_ctx, const uint16_t bcd)
	Set USB device descriptor value bcdDevice.

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.

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.

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.

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.

bool	usbd_can_detect_vbus (struct usbd_context *const uds_ctx)
	Check that the controller can detect the VBUS state change.

Detailed Description

New USB device stack core API.

Since: 3.3

Version: 0.1.0

Macro Definition Documentation

◆ USB_BSTRING_LENGTH

#define USB_BSTRING_LENGTH ( s ) (sizeof(s) * 2 - 2)

#include <include/zephyr/usb/usbd.h>

◆ USB_STRING_DESCRIPTOR_LENGTH

#define USB_STRING_DESCRIPTOR_LENGTH ( s ) (sizeof(s) * 2)

#include <include/zephyr/usb/usbd.h>

◆ USBD_CCTX_REGISTERED

#define USBD_CCTX_REGISTERED 0

#include <include/zephyr/usb/usbd.h>

USB Class instance registered flag.

◆ USBD_CONFIGURATION_DEFINE

#define USBD_CONFIGURATION_DEFINE	(	name,
		attrib,
		power,
		desc_nd
	)

#include <include/zephyr/usb/usbd.h>

Value:

        static struct usb_cfg_descriptor                                \
        cfg_desc_##name = {                                             \
                .bLength = sizeof(struct usb_cfg_descriptor),           \
                .bDescriptorType = USB_DESC_CONFIGURATION,              \
                .wTotalLength = 0,                                      \
                .bNumInterfaces = 0,                                    \
                .bConfigurationValue = 1,                               \
                .iConfiguration = 0,                                    \
                .bmAttributes = USB_SCD_RESERVED | (attrib),            \
                .bMaxPower = (power),                                   \
        };                                                              \
        BUILD_ASSERT((power) < 256, "Too much power");                  \
        static struct usbd_config_node name = {                         \
                .desc = &cfg_desc_##name,                               \
                .str_desc_nd = desc_nd,                                 \
        }

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()
desc_nd	Address of the string descriptor node used to describe the configuration, see USBD_DESC_CONFIG_DEFINE(). String descriptors are optional and the parameter can be NULL.

◆ USBD_DEFINE_CLASS

#define USBD_DEFINE_CLASS	(	class_name,
		class_api,
		class_priv,
		class_v_reqs
	)

#include <include/zephyr/usb/usbd.h>

Value:

        static struct usbd_class_data class_name = {                            \
                .name = STRINGIFY(class_name),                                  \
                .api = class_api,                                               \
                .v_reqs = class_v_reqs,                                         \
                .priv = class_priv,                                             \
        };                                                                      \
        static STRUCT_SECTION_ITERABLE_ALTERNATE(                               \
                usbd_class_fs, usbd_class_node, class_name##_fs) = {            \
                .c_data = &class_name,                                          \
        };                                                                      \
        static STRUCT_SECTION_ITERABLE_ALTERNATE(                               \
                usbd_class_hs, usbd_class_node, class_name##_hs) = {            \
                .c_data = &class_name,                                          \
        }

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

◆ USBD_DESC_BOS_DEFINE

#define USBD_DESC_BOS_DEFINE	(	name,
		len,
		subset
	)

#include <include/zephyr/usb/usbd.h>

Value:

        static struct usbd_desc_node name = {                                   \
                .bos = {                                                        \
                        .utype = USBD_DUT_BOS_NONE,                             \
                },                                                              \
                .ptr = subset,                                                  \
                .bLength = len,                                                 \
                .bDescriptorType = USB_DESC_BOS,                                \
        }

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_DESC_CONFIG_DEFINE

#define USBD_DESC_CONFIG_DEFINE	(	d_name,
		d_string
	)	USBD_DESC_STRING_DEFINE(d_name, d_string, USBD_DUT_STRING_CONFIG)

#include <include/zephyr/usb/usbd.h>

Create a string descriptor node for configuration descriptor.

This macro defines a descriptor node whose address can be used as an argument for the USBD_CONFIGURATION_DEFINE() macro.

Parameters

d_name	String descriptor node identifier.
d_string	ASCII7 encoded configuration description string literal

◆ USBD_DESC_LANG_DEFINE

#define USBD_DESC_LANG_DEFINE ( name )

#include <include/zephyr/usb/usbd.h>

Value:

        static uint16_t langid_##name = sys_cpu_to_le16(0x0409);        \
        static struct usbd_desc_node name = {                           \
                .str = {                                                \
                        .idx = 0,                                       \
                        .utype = USBD_DUT_STRING_LANG,                  \
                },                                                      \
                .ptr = &langid_##name,                                  \
                .bLength = sizeof(struct usb_string_descriptor),        \
                .bDescriptorType = USB_DESC_STRING,                     \
        }

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_MANUFACTURER_DEFINE

#define USBD_DESC_MANUFACTURER_DEFINE	(	d_name,
		d_string
	)	USBD_DESC_STRING_DEFINE(d_name, d_string, USBD_DUT_STRING_MANUFACTURER)

#include <include/zephyr/usb/usbd.h>

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

#define USBD_DESC_PRODUCT_DEFINE	(	d_name,
		d_string
	)	USBD_DESC_STRING_DEFINE(d_name, d_string, USBD_DUT_STRING_PRODUCT)

#include <include/zephyr/usb/usbd.h>

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

#define USBD_DESC_SERIAL_NUMBER_DEFINE ( d_name )

#include <include/zephyr/usb/usbd.h>

Value:

        static struct usbd_desc_node d_name = {                                 \
                .str = {                                                        \
                        .utype = USBD_DUT_STRING_SERIAL_NUMBER,                 \
                        .ascii7 = true,                                         \
                        .use_hwinfo = true,                                     \
                },                                                              \
                .bDescriptorType = USB_DESC_STRING,                             \
        }

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_STRING_DEFINE

#define USBD_DESC_STRING_DEFINE	(	d_name,
		d_string,
		d_utype
	)

#include <include/zephyr/usb/usbd.h>

Value:

        static uint8_t ascii_##d_name[USB_BSTRING_LENGTH(d_string)] = d_string; \
        static struct usbd_desc_node d_name = {                                 \
                .str = {                                                        \
                        .utype = d_utype,                                       \
                        .ascii7 = true,                                         \
                },                                                              \
                .ptr = &ascii_##d_name,                                         \
                .bLength = USB_STRING_DESCRIPTOR_LENGTH(d_string),              \
                .bDescriptorType = USB_DESC_STRING,                             \
        }

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_DEVICE_DEFINE

#define USBD_DEVICE_DEFINE	(	device_name,
		udc_dev,
		vid,
		pid
	)

#include <include/zephyr/usb/usbd.h>

Value:

        static struct usb_device_descriptor                             \
        fs_desc_##device_name = {                                       \
                .bLength = sizeof(struct usb_device_descriptor),        \
                .bDescriptorType = USB_DESC_DEVICE,                     \
                .bcdUSB = sys_cpu_to_le16(USB_SRN_2_0),                 \
                .bDeviceClass = USB_BCC_MISCELLANEOUS,                  \
                .bDeviceSubClass = 2,                                   \
                .bDeviceProtocol = 1,                                   \
                .bMaxPacketSize0 = USB_CONTROL_EP_MPS,                  \
                .idVendor = vid,                                        \
                .idProduct = pid,                                       \
                .bcdDevice = sys_cpu_to_le16(USB_BCD_DRN),              \
                .iManufacturer = 0,                                     \
                .iProduct = 0,                                          \
                .iSerialNumber = 0,                                     \
                .bNumConfigurations = 0,                                \
        };                                                              \
        static struct usb_device_descriptor                             \
        hs_desc_##device_name = {                                       \
                .bLength = sizeof(struct usb_device_descriptor),        \
                .bDescriptorType = USB_DESC_DEVICE,                     \
                .bcdUSB = sys_cpu_to_le16(USB_SRN_2_0),                 \
                .bDeviceClass = USB_BCC_MISCELLANEOUS,                  \
                .bDeviceSubClass = 2,                                   \
                .bDeviceProtocol = 1,                                   \
                .bMaxPacketSize0 = 64,                                  \
                .idVendor = vid,                                        \
                .idProduct = pid,                                       \
                .bcdDevice = sys_cpu_to_le16(USB_BCD_DRN),              \
                .iManufacturer = 0,                                     \
                .iProduct = 0,                                          \
                .iSerialNumber = 0,                                     \
                .bNumConfigurations = 0,                                \
        };                                                              \
        static STRUCT_SECTION_ITERABLE(usbd_context, device_name) = {   \
                .name = STRINGIFY(device_name),                         \
                .dev = udc_dev,                                         \
                .fs_desc = &fs_desc_##device_name,                      \
                .hs_desc = &hs_desc_##device_name,                      \
        }

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_NUMOF_INTERFACES_MAX

#define USBD_NUMOF_INTERFACES_MAX 16U

#include <include/zephyr/usb/usbd.h>

◆ USBD_VENDOR_REQ

#define USBD_VENDOR_REQ ( _reqs... )

#include <include/zephyr/usb/usbd.h>

Value:

VENDOR_REQ_DEFINE(((uint8_t []) { _reqs }), \

sizeof((uint8_t []) { _reqs }))

VENDOR_REQ_DEFINE

#define VENDOR_REQ_DEFINE(_reqs, _len)

Helper to declare request table of usbd_cctx_vendor_req.

Definition usbd.h:653

Helper to declare supported vendor requests.

Parameters

_reqs Variable number of vendor requests

◆ VENDOR_REQ_DEFINE

#define VENDOR_REQ_DEFINE	(	_reqs,
		_len
	)

#include <include/zephyr/usb/usbd.h>

Value:

        { \
                .reqs = (const uint8_t *)(_reqs), \
                .len = (_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

Typedef Documentation

◆ usbd_msg_cb_t

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

#include <include/zephyr/usb/usbd.h>

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.

Parameters

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

Enumeration Type Documentation

◆ usbd_ch9_state

enum usbd_ch9_state

#include <include/zephyr/usb/usbd.h>

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.

Enumerator
USBD_STATE_DEFAULT
USBD_STATE_ADDRESS
USBD_STATE_CONFIGURED

◆ usbd_speed

enum usbd_speed

#include <include/zephyr/usb/usbd.h>

USB device speed.

Enumerator
USBD_SPEED_FS	Device supports or is connected to a full speed bus.
USBD_SPEED_HS	Device supports or is connected to a high speed bus
USBD_SPEED_SS	Device supports or is connected to a super speed bus.

Function Documentation

◆ usbd_add_configuration()

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

#include <include/zephyr/usb/usbd.h>

Add a USB device configuration.

Parameters

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

Returns: 0 on success, other values on fail.

◆ usbd_add_descriptor()

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

#include <include/zephyr/usb/usbd.h>

Add common USB descriptor.

Add common descriptor like string or BOS Device Capability.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	dn	Pointer to USB descriptor node

Returns: 0 on success, other values on fail.

◆ usbd_bus_speed()

enum usbd_speed usbd_bus_speed ( const struct usbd_context *const uds_ctx )

#include <include/zephyr/usb/usbd.h>

Get actual device speed.

Parameters

[in] uds_ctx Pointer to a device context

Returns: Actual device speed

◆ usbd_can_detect_vbus()

bool usbd_can_detect_vbus ( struct usbd_context *const uds_ctx )

#include <include/zephyr/usb/usbd.h>

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

[in] uds_ctx Pointer to USB device support context

Returns: true if controller can detect VBUS state change, false otherwise

◆ usbd_caps_speed()

enum usbd_speed usbd_caps_speed ( const struct usbd_context *const uds_ctx )

#include <include/zephyr/usb/usbd.h>

Get highest speed supported by the controller.

Parameters

[in] uds_ctx Pointer to a device context

Returns: Highest supported speed

◆ usbd_class_get_ctx()

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

inlinestatic

#include <include/zephyr/usb/usbd.h>

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

[in] c_data Pointer to USB device class data

Returns: Pointer to USB device runtime context

◆ usbd_class_get_private()

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

inlinestatic

#include <include/zephyr/usb/usbd.h>

Get class implementation private data.

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

Parameters

[in] c_data Pointer to USB device class data

Returns: Pointer to class implementation private data

◆ usbd_config_attrib_rwup()

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

#include <include/zephyr/usb/usbd.h>

Setup USB device configuration attribute Remote Wakeup.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	speed	Configuration speed
[in]	cfg	Configuration number
[in]	enable	Sets attribute if true, clears it otherwise

Returns: 0 on success, other values on fail.

◆ usbd_config_attrib_self()

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

#include <include/zephyr/usb/usbd.h>

Setup USB device configuration attribute Self-powered.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	speed	Configuration speed
[in]	cfg	Configuration number
[in]	enable	Sets attribute if true, clears it otherwise

Returns: 0 on success, other values on fail.

◆ usbd_config_maxpower()

int usbd_config_maxpower	(	struct usbd_context *const	uds_ctx,
		const enum usbd_speed	speed,
		const uint8_t	cfg,
		const uint8_t	power
	)

#include <include/zephyr/usb/usbd.h>

Setup USB device configuration power consumption.

Parameters

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

Returns: 0 on success, other values on fail.

◆ usbd_device_set_bcd_device()

int usbd_device_set_bcd_device	(	struct usbd_context *const	uds_ctx,
		const uint16_t	bcd
	)

#include <include/zephyr/usb/usbd.h>

Set USB device descriptor value bcdDevice.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	bcd	bcdDevice value

Returns: 0 on success, other values on fail.

◆ usbd_device_set_bcd_usb()

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

#include <include/zephyr/usb/usbd.h>

Set USB device descriptor value bcdUSB.

Parameters

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

Returns: 0 on success, other values on fail.

◆ usbd_device_set_code_triple()

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
	)

#include <include/zephyr/usb/usbd.h>

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

Parameters

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

Returns: 0 on success, other values on fail.

◆ usbd_device_set_pid()

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

#include <include/zephyr/usb/usbd.h>

Set USB device descriptor value idProduct.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	pid	idProduct value

Returns: 0 on success, other values on fail.

◆ usbd_device_set_vid()

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

#include <include/zephyr/usb/usbd.h>

Set USB device descriptor value idVendor.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	vid	idVendor value

Returns: 0 on success, other values on fail.

◆ usbd_disable()

int usbd_disable ( struct usbd_context * uds_ctx )

#include <include/zephyr/usb/usbd.h>

Disable the USB device support.

This function disables the USB device support.

Parameters

[in] uds_ctx Pointer to USB device support context

Returns: 0 on success, other values on fail.

◆ usbd_enable()

int usbd_enable ( struct usbd_context * uds_ctx )

#include <include/zephyr/usb/usbd.h>

Enable the USB device support and registered class instances.

This function enables the USB device support.

Parameters

[in] uds_ctx Pointer to USB device support context

Returns: 0 on success, other values on fail.

◆ usbd_ep_buf_alloc()

struct net_buf * usbd_ep_buf_alloc	(	const struct usbd_class_data *const	c_data,
		const uint8_t	ep,
		const size_t	size
	)

#include <include/zephyr/usb/usbd.h>

Allocate buffer for USB device request.

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

Parameters

[in]	c_data	Pointer to USB device class data
[in]	ep	Endpoint address
[in]	size	Size of the request buffer

Returns: pointer to allocated request or NULL on error.

◆ usbd_ep_buf_free()

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

#include <include/zephyr/usb/usbd.h>

Free USB device request buffer.

Put the buffer back into the request buffer pool.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	buf	Pointer to UDC request buffer

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

◆ usbd_ep_clear_halt()

int usbd_ep_clear_halt	(	struct usbd_context *	uds_ctx,
		uint8_t	ep
	)

#include <include/zephyr/usb/usbd.h>

Clear endpoint halt.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	ep	Endpoint address

Returns: 0 on success, or error from udc_ep_clear_halt()

◆ usbd_ep_ctrl_enqueue()

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

#include <include/zephyr/usb/usbd.h>

Queue USB device control request.

Add control request to the queue.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	buf	Pointer to UDC request buffer

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

◆ usbd_ep_dequeue()

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

#include <include/zephyr/usb/usbd.h>

Remove all USB device controller requests from endpoint queue.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	ep	Endpoint address

Returns: 0 on success, or error from udc_ep_dequeue()

◆ usbd_ep_enqueue()

int usbd_ep_enqueue	(	const struct usbd_class_data *const	c_data,
		struct net_buf *const	buf
	)

#include <include/zephyr/usb/usbd.h>

Queue USB device request.

Add request to the queue.

Parameters

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

Returns: 0 on success, or error from udc_ep_enqueue()

◆ usbd_ep_is_halted()

bool usbd_ep_is_halted	(	struct usbd_context *	uds_ctx,
		uint8_t	ep
	)

#include <include/zephyr/usb/usbd.h>

Checks whether the endpoint is halted.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	ep	Endpoint address

Returns: true if endpoint is halted, false otherwise

◆ usbd_ep_set_halt()

int usbd_ep_set_halt	(	struct usbd_context *	uds_ctx,
		uint8_t	ep
	)

#include <include/zephyr/usb/usbd.h>

Halt endpoint.

Parameters

[in]	uds_ctx	Pointer to USB device support context
[in]	ep	Endpoint address

Returns: 0 on success, or error from udc_ep_set_halt()

◆ usbd_init()

int usbd_init ( struct usbd_context * uds_ctx )

#include <include/zephyr/usb/usbd.h>

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

[in] uds_ctx Pointer to USB device support context

Returns: 0 on success, other values on fail.

◆ usbd_is_suspended()

bool usbd_is_suspended ( struct usbd_context * uds_ctx )

#include <include/zephyr/usb/usbd.h>

Checks whether the USB device controller is suspended.

Parameters

[in] uds_ctx Pointer to USB device support context

Returns: true if endpoint is halted, false otherwise

◆ usbd_msg_register_cb()

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

#include <include/zephyr/usb/usbd.h>

Register USB notification message callback.

Parameters

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

Returns: 0 on success, other values on fail.

◆ usbd_register_all_classes()

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

#include <include/zephyr/usb/usbd.h>

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

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

Returns: 0 on success, other values on fail.

◆ usbd_register_class()

int usbd_register_class	(	struct usbd_context *	uds_ctx,
		const char *	name,
		const enum usbd_speed	speed,
		uint8_t	cfg
	)

#include <include/zephyr/usb/usbd.h>

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

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

Returns: 0 on success, other values on fail.

◆ usbd_remove_descriptor()

void usbd_remove_descriptor ( struct usbd_desc_node *const desc_nd )

#include <include/zephyr/usb/usbd.h>

Remove USB string descriptor.

Remove linked USB string descriptor from any list.

Parameters

[in] desc_nd Pointer to USB descriptor node

◆ usbd_shutdown()

int usbd_shutdown ( struct usbd_context *const uds_ctx )

#include <include/zephyr/usb/usbd.h>

Shutdown the USB device support.

This function completely disables the USB device support.

Parameters

[in] uds_ctx Pointer to USB device support context

Returns: 0 on success, other values on fail.

◆ usbd_str_desc_get_idx()

uint8_t usbd_str_desc_get_idx ( const struct usbd_desc_node *const desc_nd )

#include <include/zephyr/usb/usbd.h>

Get USB string descriptor index from descriptor node.

Parameters

[in] desc_nd Pointer to USB descriptor node

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

◆ usbd_unregister_all_classes()

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

#include <include/zephyr/usb/usbd.h>

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

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

Returns: 0 on success, other values on fail.

◆ usbd_unregister_class()

int usbd_unregister_class	(	struct usbd_context *	uds_ctx,
		const char *	name,
		const enum usbd_speed	speed,
		uint8_t	cfg
	)

#include <include/zephyr/usb/usbd.h>

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

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

Returns: 0 on success, other values on fail.

◆ usbd_wakeup_request()

int usbd_wakeup_request ( struct usbd_context * uds_ctx )

#include <include/zephyr/usb/usbd.h>

Initiate the USB remote wakeup (TBD)

Returns: 0 on success, other values on fail.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ USB_BSTRING_LENGTH

◆ USB_STRING_DESCRIPTOR_LENGTH

◆ USBD_CCTX_REGISTERED

◆ USBD_CONFIGURATION_DEFINE

◆ USBD_DEFINE_CLASS

◆ USBD_DESC_BOS_DEFINE

◆ USBD_DESC_CONFIG_DEFINE

◆ USBD_DESC_LANG_DEFINE

◆ USBD_DESC_MANUFACTURER_DEFINE

◆ USBD_DESC_PRODUCT_DEFINE

◆ USBD_DESC_SERIAL_NUMBER_DEFINE

◆ USBD_DESC_STRING_DEFINE

◆ USBD_DEVICE_DEFINE

◆ USBD_NUMOF_INTERFACES_MAX

◆ USBD_VENDOR_REQ

◆ VENDOR_REQ_DEFINE

Typedef Documentation

◆ usbd_msg_cb_t

Enumeration Type Documentation

◆ usbd_ch9_state

◆ usbd_speed

Function Documentation

◆ usbd_add_configuration()

◆ usbd_add_descriptor()

◆ usbd_bus_speed()

◆ usbd_can_detect_vbus()

◆ usbd_caps_speed()

◆ usbd_class_get_ctx()

◆ usbd_class_get_private()

◆ usbd_config_attrib_rwup()

◆ usbd_config_attrib_self()

◆ usbd_config_maxpower()

◆ usbd_device_set_bcd_device()

◆ usbd_device_set_bcd_usb()

◆ usbd_device_set_code_triple()

◆ usbd_device_set_pid()

◆ usbd_device_set_vid()

◆ usbd_disable()

◆ usbd_enable()

◆ usbd_ep_buf_alloc()

◆ usbd_ep_buf_free()

◆ usbd_ep_clear_halt()

◆ usbd_ep_ctrl_enqueue()

◆ usbd_ep_dequeue()

◆ usbd_ep_enqueue()

◆ usbd_ep_is_halted()

◆ usbd_ep_set_halt()

◆ usbd_init()

◆ usbd_is_suspended()

◆ usbd_msg_register_cb()

◆ usbd_register_all_classes()

◆ usbd_register_class()

◆ usbd_remove_descriptor()

◆ usbd_shutdown()

◆ usbd_str_desc_get_idx()

◆ usbd_unregister_all_classes()

◆ usbd_unregister_class()

◆ usbd_wakeup_request()