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/usb_ch9.h>
#include <zephyr/net/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
 
/*
 * 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)
 
/* Used internally to keep descriptors in order */
enum usbd_desc_usage_type {
        USBD_DUT_STRING_LANG,
        USBD_DUT_STRING_MANUFACTURER,
        USBD_DUT_STRING_PRODUCT,
        USBD_DUT_STRING_SERIAL_NUMBER,
        USBD_DUT_STRING_INTERFACE,
};
 
struct usbd_desc_node {
        sys_dnode_t node;
        unsigned int idx : 8;
        unsigned int utype : 8;
        unsigned int utf16le : 1;
        unsigned int custom_sn : 1;
        void *desc;
};
 
struct usbd_config_node {
        sys_snode_t node;
        void *desc;
        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];
};
 
struct usbd_status {
        unsigned int initialized : 1;
        unsigned int enabled : 1;
        unsigned int suspended : 1;
        unsigned int rwup : 1;
};
 
struct usbd_contex {
        const char *name;
        struct k_mutex mutex;
        const struct device *dev;
        struct usbd_ch9_data ch9_data;
        sys_dlist_t descriptors;
        sys_slist_t configs;
        struct usbd_status status;
        void *desc;
};
 
struct usbd_cctx_vendor_req {
        const uint8_t *reqs;
        uint8_t len;
};
 
#define USBD_CCTX_REGISTERED            0
 
struct usbd_class_node;
 
struct usbd_class_api {
        void (*feature_halt)(struct usbd_class_node *const node,
                             uint8_t ep, bool halted);
 
        void (*update)(struct usbd_class_node *const node,
                       uint8_t iface, uint8_t alternate);
 
        int (*control_to_dev)(struct usbd_class_node *const node,
                              const struct usb_setup_packet *const setup,
                              const struct net_buf *const buf);
 
        int (*control_to_host)(struct usbd_class_node *const node,
                               const struct usb_setup_packet *const setup,
                               struct net_buf *const buf);
 
        int (*request)(struct usbd_class_node *const node,
                       struct net_buf *buf, int err);
 
        void (*suspended)(struct usbd_class_node *const node);
 
        void (*resumed)(struct usbd_class_node *const node);
 
        void (*sof)(struct usbd_class_node *const node);
 
        void (*enable)(struct usbd_class_node *const node);
 
        void (*disable)(struct usbd_class_node *const node);
 
        int (*init)(struct usbd_class_node *const node);
 
        void (*shutdown)(struct usbd_class_node *const node);
};
 
struct usbd_class_data {
        struct usbd_contex *uds_ctx;
        void *desc;
        const struct usbd_cctx_vendor_req *v_reqs;
        uint32_t ep_assigned;
        uint32_t ep_active;
        uint32_t iface_bm;
        atomic_t state;
        void *priv;
};
 
struct usbd_class_node {
        sys_snode_t node;
        const char *name;
        const struct usbd_class_api *api;
        struct usbd_class_data *data;
};
 
#define USBD_DEVICE_DEFINE(device_name, uhc_dev, vid, pid)              \
        static struct usb_device_descriptor                             \
        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_SECTION_ITERABLE(usbd_contex, device_name) = {    \
                .name = STRINGIFY(device_name),                         \
                .dev = uhc_dev,                                         \
                .desc = &desc_##device_name,                            \
        }
 
#define USBD_CONFIGURATION_DEFINE(name, attrib, power)                  \
        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,                               \
        }
 
#define USBD_DESC_LANG_DEFINE(name)                                     \
        static struct usb_string_descriptor                             \
        string_desc_##name = {                                          \
                .bLength = sizeof(struct usb_string_descriptor),        \
                .bDescriptorType = USB_DESC_STRING,                     \
                .bString = sys_cpu_to_le16(0x0409),                     \
        };                                                              \
        static struct usbd_desc_node name = {                           \
                .idx = 0,                                               \
                .utype = USBD_DUT_STRING_LANG,                          \
                .desc = &string_desc_##name,                            \
        }
 
#define USBD_DESC_STRING_DEFINE(d_name, d_string, d_utype)              \
        struct usb_string_descriptor_##d_name {                         \
                uint8_t bLength;                                        \
                uint8_t bDescriptorType;                                \
                uint8_t bString[USB_BSTRING_LENGTH(d_string)];          \
        } __packed;                                                     \
        static struct usb_string_descriptor_##d_name                    \
        string_desc_##d_name = {                                        \
                .bLength = USB_STRING_DESCRIPTOR_LENGTH(d_string),      \
                .bDescriptorType = USB_DESC_STRING,                     \
                .bString = d_string,                                    \
        };                                                              \
        static struct usbd_desc_node d_name = {                         \
                .utype = d_utype,                                       \
                .desc = &string_desc_##d_name,                          \
        }
 
#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, d_string)                \
        USBD_DESC_STRING_DEFINE(d_name, d_string, USBD_DUT_STRING_SERIAL_NUMBER)
 
#define USBD_DEFINE_CLASS(class_name, class_api, class_data)            \
        static STRUCT_SECTION_ITERABLE(usbd_class_node, class_name) = { \
                .name = STRINGIFY(class_name),                          \
                .api = class_api,                                       \
                .data = class_data,                                     \
        }
 
#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_contex *uds_ctx,
                        struct usbd_desc_node *dn);
 
int usbd_add_configuration(struct usbd_contex *uds_ctx,
                           struct usbd_config_node *cd);
 
int usbd_register_class(struct usbd_contex *uds_ctx,
                        const char *name,
                        uint8_t cfg);
 
int usbd_unregister_class(struct usbd_contex *uds_ctx,
                          const char *name,
                          uint8_t cfg);
 
int usbd_init(struct usbd_contex *uds_ctx);
 
int usbd_enable(struct usbd_contex *uds_ctx);
 
int usbd_disable(struct usbd_contex *uds_ctx);
 
int usbd_shutdown(struct usbd_contex *const uds_ctx);
 
int usbd_ep_set_halt(struct usbd_contex *uds_ctx, uint8_t ep);
 
int usbd_ep_clear_halt(struct usbd_contex *uds_ctx, uint8_t ep);
 
bool usbd_ep_is_halted(struct usbd_contex *uds_ctx, uint8_t ep);
 
struct net_buf *usbd_ep_ctrl_buf_alloc(struct usbd_contex *const uds_ctx,
                                       const uint8_t ep, const size_t size);
 
struct net_buf *usbd_ep_buf_alloc(const struct usbd_class_node *const c_nd,
                                  const uint8_t ep, const size_t size);
 
int usbd_ep_ctrl_enqueue(struct usbd_contex *const uds_ctx,
                         struct net_buf *const buf);
 
int usbd_ep_enqueue(const struct usbd_class_node *const c_nd,
                    struct net_buf *const buf);
 
int usbd_ep_dequeue(struct usbd_contex *uds_ctx, const uint8_t ep);
 
int usbd_ep_buf_free(struct usbd_contex *uds_ctx, struct net_buf *buf);
 
bool usbd_is_suspended(struct usbd_contex *uds_ctx);
 
int usbd_wakeup_request(struct usbd_contex *uds_ctx);
 
int usbd_device_set_bcd(struct usbd_contex *const uds_ctx,
                         const uint16_t bcd);
 
int usbd_device_set_vid(struct usbd_contex *const uds_ctx,
                         const uint16_t vid);
 
int usbd_device_set_pid(struct usbd_contex *const uds_ctx,
                        const uint16_t pid);
 
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);
 
int usbd_config_attrib_rwup(struct usbd_contex *const uds_ctx,
                            const uint8_t cfg, const bool enable);
 
int usbd_config_attrib_self(struct usbd_contex *const uds_ctx,
                            const uint8_t cfg, const bool enable);
 
int usbd_config_maxpower(struct usbd_contex *const uds_ctx,
                         const uint8_t cfg, const uint8_t power);
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_USBD_H_ */