usbd.h

Go to the documentation of this file.

/*
 * Copyright (c) 2022 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_USBD_H_
#define ZEPHYR_INCLUDE_USBD_H_
 
#include <zephyr/device.h>
#include <zephyr/usb/bos.h>
#include <zephyr/usb/usb_ch9.h>
#include <zephyr/usb/usbd_msg.h>
#include <zephyr/drivers/usb/udc_buf.h>
#include <zephyr/sys/byteorder.h>
#include <zephyr/sys/slist.h>
#include <zephyr/logging/log.h>
#include <zephyr/sys/iterable_sections.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* 1 if USB device stack is compiled with High-Speed support */
#define USBD_SUPPORTS_HIGH_SPEED IS_EQ(CONFIG_USBD_MAX_SPEED, 1)
 
/* Maximum bulk max packet size the stack supports */
#define USBD_MAX_BULK_MPS COND_CODE_1(USBD_SUPPORTS_HIGH_SPEED, (512), (64))
 
/*
 * The USB Unicode bString is encoded in UTF16LE, which means it takes up
 * twice the amount of bytes than the same string encoded in ASCII7.
 * Use this macro to determine the length of the bString array.
 *
 * bString length without null character:
 *   bString_length = (sizeof(initializer_string) - 1) * 2
 * or:
 *   bString_length = sizeof(initializer_string) * 2 - 2
 */
#define USB_BSTRING_LENGTH(s)           (sizeof(s) * 2 - 2)
 
/*
 * The length of the string descriptor (bLength) is calculated from the
 * size of the two octets bLength and bDescriptorType plus the
 * length of the UTF16LE string:
 *
 *   bLength = 2 + bString_length
 *   bLength = 2 + sizeof(initializer_string) * 2 - 2
 *   bLength = sizeof(initializer_string) * 2
 * Use this macro to determine the bLength of the string descriptor.
 */
#define USB_STRING_DESCRIPTOR_LENGTH(s) (sizeof(s) * 2)
 
struct usbd_context;
 
enum usbd_str_desc_utype {
        USBD_DUT_STRING_LANG,
        USBD_DUT_STRING_MANUFACTURER,
        USBD_DUT_STRING_PRODUCT,
        USBD_DUT_STRING_SERIAL_NUMBER,
        USBD_DUT_STRING_CONFIG,
        USBD_DUT_STRING_INTERFACE,
};
 
enum usbd_bos_desc_utype {
        USBD_DUT_BOS_NONE,
        USBD_DUT_BOS_VREQ,
};
struct usbd_str_desc_data {
        uint8_t idx;
        enum usbd_str_desc_utype utype : 8;
        unsigned int ascii7 : 1;
        unsigned int use_hwinfo : 1;
};
 
struct usbd_vreq_node {
        sys_dnode_t node;
        const uint8_t code;
        int (*to_host)(const struct usbd_context *const ctx,
                       const struct usb_setup_packet *const setup,
                       struct net_buf *const buf);
        int (*to_dev)(const struct usbd_context *const ctx,
                      const struct usb_setup_packet *const setup,
                      const struct net_buf *const buf);
};
 
struct usbd_bos_desc_data {
        enum usbd_bos_desc_utype utype : 8;
        union {
                struct usbd_vreq_node *const vreq_nd;
        };
};
 
struct usbd_desc_node {
        sys_dnode_t node;
        union {
                struct usbd_str_desc_data str;
                struct usbd_bos_desc_data bos;
        };
        const void *const ptr;
        uint8_t bLength;
        uint8_t bDescriptorType;
};
 
struct usbd_config_node {
        sys_snode_t node;
        void *desc;
        struct usbd_desc_node *str_desc_nd;
        sys_slist_t class_list;
};
 
/* TODO: Kconfig option USBD_NUMOF_INTERFACES_MAX? */
#define USBD_NUMOF_INTERFACES_MAX       16U
 
enum usbd_ch9_state {
        USBD_STATE_DEFAULT = 0,
        USBD_STATE_ADDRESS,
        USBD_STATE_CONFIGURED,
};
 
 
struct usbd_ch9_data {
        struct usb_setup_packet setup;
        int ctrl_type;
        enum usbd_ch9_state state;
        uint32_t ep_halt;
        uint8_t configuration;
        bool post_status;
        uint8_t alternate[USBD_NUMOF_INTERFACES_MAX];
};
 
enum usbd_speed {
        USBD_SPEED_FS,
        USBD_SPEED_HS,
        USBD_SPEED_SS,
};
 
struct usbd_status {
        unsigned int initialized : 1;
        unsigned int enabled : 1;
        unsigned int suspended : 1;
        unsigned int rwup : 1;
        unsigned int self_powered : 1;
        enum usbd_speed speed : 2;
};
 
typedef void (*usbd_msg_cb_t)(struct usbd_context *const ctx,
                              const struct usbd_msg *const msg);
 
struct usbd_context {
        const char *name;
        struct k_mutex mutex;
        const struct device *dev;
        usbd_msg_cb_t msg_cb;
        struct usbd_ch9_data ch9_data;
        sys_dlist_t descriptors;
        sys_slist_t fs_configs;
        sys_slist_t hs_configs;
        sys_dlist_t vreqs;
        struct usbd_status status;
        void *fs_desc;
        void *hs_desc;
};
 
struct usbd_cctx_vendor_req {
        const uint8_t *reqs;
        uint8_t len;
};
 
#define USBD_CCTX_REGISTERED            0
 
struct usbd_class_data;
 
struct usbd_class_api {
        void (*feature_halt)(struct usbd_class_data *const c_data,
                             uint8_t ep, bool halted);
 
        void (*update)(struct usbd_class_data *const c_data,
                       uint8_t iface, uint8_t alternate);
 
        int (*control_to_dev)(struct usbd_class_data *const c_data,
                              const struct usb_setup_packet *const setup,
                              const struct net_buf *const buf);
 
        int (*control_to_host)(struct usbd_class_data *const c_data,
                               const struct usb_setup_packet *const setup,
                               struct net_buf *const buf);
 
        int (*request)(struct usbd_class_data *const c_data,
                       struct net_buf *buf, int err);
 
        void (*suspended)(struct usbd_class_data *const c_data);
 
        void (*resumed)(struct usbd_class_data *const c_data);
 
        void (*sof)(struct usbd_class_data *const c_data);
 
        void (*enable)(struct usbd_class_data *const c_data);
 
        void (*disable)(struct usbd_class_data *const c_data);
 
        int (*init)(struct usbd_class_data *const c_data);
 
        void (*shutdown)(struct usbd_class_data *const c_data);
 
        void *(*get_desc)(struct usbd_class_data *const c_data,
                          const enum usbd_speed speed);
};
 
struct usbd_class_data {
        const char *name;
        struct usbd_context *uds_ctx;
        const struct usbd_class_api *api;
        const struct usbd_cctx_vendor_req *v_reqs;
        void *priv;
};
 
struct usbd_class_node {
        sys_snode_t node;
        struct usbd_class_data *const c_data;
        uint32_t ep_assigned;
        uint32_t ep_active;
        uint32_t iface_bm;
        atomic_t state;
};
 
static inline struct usbd_context *usbd_class_get_ctx(const struct usbd_class_data *const c_data)
{
        return c_data->uds_ctx;
}
 
static inline void *usbd_class_get_private(const struct usbd_class_data *const c_data)
{
        return c_data->priv;
}
 
#define USBD_DEVICE_DEFINE(device_name, udc_dev, vid, pid)              \
        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,                                \
        };                                                              \
        IF_ENABLED(USBD_SUPPORTS_HIGH_SPEED, (                          \
        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,                      \
                IF_ENABLED(USBD_SUPPORTS_HIGH_SPEED, (                  \
                .hs_desc = &hs_desc_##device_name,                      \
                ))                                                      \
        }
 
#define USBD_CONFIGURATION_DEFINE(name, attrib, power, desc_nd)         \
        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 USBD_DESC_LANG_DEFINE(name)                                     \
        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,                     \
        }
 
#define USBD_DESC_STRING_DEFINE(d_name, d_string, d_utype)                      \
        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,                             \
        }
 
#define USBD_DESC_MANUFACTURER_DEFINE(d_name, d_string)                 \
        USBD_DESC_STRING_DEFINE(d_name, d_string, USBD_DUT_STRING_MANUFACTURER)
 
#define USBD_DESC_PRODUCT_DEFINE(d_name, d_string)                      \
        USBD_DESC_STRING_DEFINE(d_name, d_string, USBD_DUT_STRING_PRODUCT)
 
#define USBD_DESC_SERIAL_NUMBER_DEFINE(d_name)                                  \
        BUILD_ASSERT(IS_ENABLED(CONFIG_HWINFO), "HWINFO not enabled");          \
        static struct usbd_desc_node d_name = {                                 \
                .str = {                                                        \
                        .utype = USBD_DUT_STRING_SERIAL_NUMBER,                 \
                        .ascii7 = true,                                         \
                        .use_hwinfo = true,                                     \
                },                                                              \
                .bDescriptorType = USB_DESC_STRING,                             \
        }
 
#define USBD_DESC_CONFIG_DEFINE(d_name, d_string)                       \
        USBD_DESC_STRING_DEFINE(d_name, d_string, USBD_DUT_STRING_CONFIG)
 
#define USBD_DESC_BOS_DEFINE(name, len, subset)                                 \
        BUILD_ASSERT(IS_ENABLED(CONFIG_USBD_BOS_SUPPORT),                       \
                     "USB device BOS support is disabled");                     \
        static struct usbd_desc_node name = {                                   \
                .bos = {                                                        \
                        .utype = USBD_DUT_BOS_NONE,                             \
                },                                                              \
                .ptr = subset,                                                  \
                .bLength = len,                                                 \
                .bDescriptorType = USB_DESC_BOS,                                \
        }
 
#define USBD_VREQUEST_DEFINE(name, vcode, vto_host, vto_dev)                    \
        BUILD_ASSERT(IS_ENABLED(CONFIG_USBD_VREQ_SUPPORT),                      \
                     "USB device vendor request support is disabled");          \
        static struct usbd_vreq_node name = {                                   \
                .code = vcode,                                                  \
                .to_host = vto_host,                                            \
                .to_dev = vto_dev,                                              \
        }
 
#define USBD_DESC_BOS_VREQ_DEFINE(name, len, subset, vcode, vto_host, vto_dev)  \
        BUILD_ASSERT(IS_ENABLED(CONFIG_USBD_BOS_SUPPORT),                       \
                     "USB device BOS support is disabled");                     \
        USBD_VREQUEST_DEFINE(vreq_nd_##name, vcode, vto_host, vto_dev);         \
        static struct usbd_desc_node name = {                                   \
                .bos = {                                                        \
                        .utype = USBD_DUT_BOS_VREQ,                             \
                        .vreq_nd = &vreq_nd_##name,                             \
                },                                                              \
                .ptr = subset,                                                  \
                .bLength = len,                                                 \
                .bDescriptorType = USB_DESC_BOS,                                \
        }
 
#define USBD_DEFINE_CLASS(class_name, class_api, class_priv, class_v_reqs)      \
        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,                                          \
        };                                                                      \
        IF_ENABLED(USBD_SUPPORTS_HIGH_SPEED, (                                  \
        static STRUCT_SECTION_ITERABLE_ALTERNATE(                               \
                usbd_class_hs, usbd_class_node, class_name##_hs) = {            \
                .c_data = &class_name,                                          \
        }                                                                       \
        ))
 
#define VENDOR_REQ_DEFINE(_reqs, _len) \
        { \
                .reqs = (const uint8_t *)(_reqs), \
                .len = (_len), \
        }
 
#define USBD_VENDOR_REQ(_reqs...) \
        VENDOR_REQ_DEFINE(((uint8_t []) { _reqs }), \
                          sizeof((uint8_t []) { _reqs }))
 
 
int usbd_add_descriptor(struct usbd_context *uds_ctx,
                        struct usbd_desc_node *dn);
 
uint8_t usbd_str_desc_get_idx(const struct usbd_desc_node *const desc_nd);
 
void usbd_remove_descriptor(struct usbd_desc_node *const desc_nd);
 
int usbd_add_configuration(struct usbd_context *uds_ctx,
                           const enum usbd_speed speed,
                           struct usbd_config_node *cd);
 
int usbd_register_class(struct usbd_context *uds_ctx,
                        const char *name,
                        const enum usbd_speed speed, uint8_t cfg);
 
int usbd_register_all_classes(struct usbd_context *uds_ctx,
                              const enum usbd_speed speed, uint8_t cfg,
                              const char *const blocklist[]);
 
int usbd_unregister_class(struct usbd_context *uds_ctx,
                          const char *name,
                          const enum usbd_speed speed, uint8_t cfg);
 
int usbd_unregister_all_classes(struct usbd_context *uds_ctx,
                                const enum usbd_speed speed, uint8_t cfg);
 
int usbd_msg_register_cb(struct usbd_context *const uds_ctx,
                         const usbd_msg_cb_t cb);
 
int usbd_init(struct usbd_context *uds_ctx);
 
int usbd_enable(struct usbd_context *uds_ctx);
 
int usbd_disable(struct usbd_context *uds_ctx);
 
int usbd_shutdown(struct usbd_context *const uds_ctx);
 
int usbd_ep_set_halt(struct usbd_context *uds_ctx, uint8_t ep);
 
int usbd_ep_clear_halt(struct usbd_context *uds_ctx, uint8_t ep);
 
bool usbd_ep_is_halted(struct usbd_context *uds_ctx, uint8_t ep);
 
struct net_buf *usbd_ep_buf_alloc(const struct usbd_class_data *const c_data,
                                  const uint8_t ep, const size_t size);
 
int usbd_ep_ctrl_enqueue(struct usbd_context *const uds_ctx,
                         struct net_buf *const buf);
 
int usbd_ep_enqueue(const struct usbd_class_data *const c_data,
                    struct net_buf *const buf);
 
int usbd_ep_dequeue(struct usbd_context *uds_ctx, const uint8_t ep);
 
int usbd_ep_buf_free(struct usbd_context *uds_ctx, struct net_buf *buf);
 
bool usbd_is_suspended(struct usbd_context *uds_ctx);
 
int usbd_wakeup_request(struct usbd_context *uds_ctx);
 
void usbd_self_powered(struct usbd_context *uds_ctx, const bool status);
 
enum usbd_speed usbd_bus_speed(const struct usbd_context *const uds_ctx);
 
enum usbd_speed usbd_caps_speed(const struct usbd_context *const uds_ctx);
 
int usbd_device_set_bcd_usb(struct usbd_context *const uds_ctx,
                            const enum usbd_speed speed, const uint16_t bcd);
 
int usbd_device_set_vid(struct usbd_context *const uds_ctx,
                         const uint16_t vid);
 
int usbd_device_set_pid(struct usbd_context *const uds_ctx,
                        const uint16_t pid);
 
int usbd_device_set_bcd_device(struct usbd_context *const uds_ctx,
                               const uint16_t bcd);
 
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);
 
int usbd_config_attrib_rwup(struct usbd_context *const uds_ctx,
                            const enum usbd_speed speed,
                            const uint8_t cfg, const bool enable);
 
int usbd_config_attrib_self(struct usbd_context *const uds_ctx,
                            const enum usbd_speed speed,
                            const uint8_t cfg, const bool enable);
 
int usbd_config_maxpower(struct usbd_context *const uds_ctx,
                         const enum usbd_speed speed,
                         const uint8_t cfg, const uint8_t power);
 
bool usbd_can_detect_vbus(struct usbd_context *const uds_ctx);
 
int usbd_device_register_vreq(struct usbd_context *const uds_ctx,
                              struct usbd_vreq_node *const vreq_nd);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_USBD_H_ */