usb: device_next: support vendor request with recipient device

Allow the user to register a vendor request node identified by the
vendor code (bRequest) and containing two callbacks to handle the vendor
request. The device stack uses the vendor request node to call the
vendor request callbacks when it receives a request of type Vendor,
recipient Device, and bRequest value equal to the vendor code.

Signed-off-by: Johann Fischer <[email protected]>

Author: jfischer-no

include/zephyr/usb/usbd.h

@@ -59,6 +59,8 @@ extern "C" {
  */
 #define USB_STRING_DESCRIPTOR_LENGTH(s)	(sizeof(s) * 2)
 
+struct usbd_context;
+
 /** Used internally to keep descriptors in order
  * @cond INTERNAL_HIDDEN
  */
@@ -89,6 +91,54 @@ struct usbd_str_desc_data {
 	unsigned int use_hwinfo : 1;
 };
 
+/**
+ * USBD vendor request node
+ *
+ * Vendor request node is identified by the vendor code and is used to register
+ * callbacks to handle the vendor request with the receiving device.
+ * When the device stack receives a request with type Vendor and recipient
+ * Device, and bRequest value equal to the vendor request code, it will call
+ * the vendor callbacks depending on the direction of the request.
+ *
+ * Example callback code fragment:
+ *
+ * @code{.c}
+ * static int foo_to_host_cb(const struct usbd_context *const ctx,
+ *                           const struct usb_setup_packet *const setup,
+ *                           struct net_buf *const buf)
+ * {
+ *     if (setup->wIndex == WEBUSB_REQ_GET_URL) {
+ *         uint8_t index = USB_GET_DESCRIPTOR_INDEX(setup->wValue);
+ *
+ *         if (index != SAMPLE_WEBUSB_LANDING_PAGE) {
+ *             return -ENOTSUP;
+ *         }
+ *
+ *         net_buf_add_mem(buf, &webusb_origin_url,
+ *                         MIN(net_buf_tailroom(buf), sizeof(webusb_origin_url)));
+ *
+ *         return 0;
+ *     }
+ *
+ *     return -ENOTSUP;
+ * }
+ * @endcode
+ */
+struct usbd_vreq_node {
+	/** Node information for the dlist */
+	sys_dnode_t node;
+	/** Vendor code (bRequest value) */
+	const uint8_t code;
+	/** Vendor request callback for device-to-host direction */
+	int (*to_host)(const struct usbd_context *const ctx,
+		       const struct usb_setup_packet *const setup,
+		       struct net_buf *const buf);
+	/** Vendor request callback for host-to-device direction */
+	int (*to_dev)(const struct usbd_context *const ctx,
+		      const struct usb_setup_packet *const setup,
+		      const struct net_buf *const buf);
+};
+
 /**
  * USBD BOS Device Capability descriptor data
  */
@@ -199,8 +249,6 @@ struct usbd_status {
 	enum usbd_speed speed : 2;
 };
 
-struct usbd_context;
-
 /**
  * @brief Callback type definition for USB device message delivery
  *
@@ -238,6 +286,8 @@ struct usbd_context {
 	sys_slist_t fs_configs;
 	/** slist to manage High-Speed device configurations */
 	sys_slist_t hs_configs;
+	/** dlist to manage vendor requests with recipient device */
+	sys_dlist_t vreqs;
 	/** Status of the USB device support */
 	struct usbd_status status;
 	/** Pointer to Full-Speed device descriptor */
@@ -597,6 +647,21 @@ static inline void *usbd_class_get_private(const struct usbd_class_data *const c
 		.bDescriptorType = USB_DESC_BOS,				\
 	}
 
+/**
+ * @brief Define a vendor request with recipient device
+ *
+ * @param name      Vendor request identifier
+ * @param vcode     Vendor request code
+ * @param vto_host  Vendor callback for to-host direction request
+ * @param vto_dev   Vendor callback for to-device direction request
+ */
+#define USBD_VREQUEST_DEFINE(name, vcode, vto_host, vto_dev)			\
+	static struct usbd_vreq_node name = {					\
+		.code = vcode,							\
+		.to_host = vto_host,						\
+		.to_dev = vto_dev,						\
+	}
+
 /**
  * @brief Define USB device support class data
  *
@@ -1056,6 +1121,20 @@ int usbd_config_maxpower(struct usbd_context *const uds_ctx,
  */
 bool usbd_can_detect_vbus(struct usbd_context *const uds_ctx);
 
+/**
+ * @brief Register an USB vendor request with recipient device
+ *
+ * The vendor request with the recipient device applies to all configurations
+ * within the device.
+ *
+ * @param[in] uds_ctx Pointer to USB device support context
+ * @param[in] vreq_nd Pointer to vendor request node
+ *
+ * @return 0 on success, other values on fail.
+ */
+int usbd_device_register_vreq(struct usbd_context *const uds_ctx,
+			      struct usbd_vreq_node *const vreq_nd);
+
 /**
  * @}
  */

subsys/usb/device_next/usbd_ch9.c

@@ -913,6 +913,34 @@ static int std_request_to_host(struct usbd_context *const uds_ctx,
 	return ret;
 }
 
+static int vendor_device_request(struct usbd_context *const uds_ctx,
+				 struct net_buf *const buf)
+{
+	struct usb_setup_packet *setup = usbd_get_setup_pkt(uds_ctx);
+	struct usbd_vreq_node *vreq_nd;
+
+	vreq_nd = usbd_device_get_vreq(uds_ctx, setup->bRequest);
+	if (vreq_nd == NULL) {
+		errno = -ENOTSUP;
+		return 0;
+	}
+
+	if (reqtype_is_to_device(setup) && vreq_nd->to_dev != NULL) {
+		LOG_ERR("Vendor request 0x%02x to device", setup->bRequest);
+		errno = vreq_nd->to_dev(uds_ctx, setup, buf);
+		return 0;
+	}
+
+	if (reqtype_is_to_host(setup) && vreq_nd->to_host != NULL) {
+		LOG_ERR("Vendor request 0x%02x to host", setup->bRequest);
+		errno = vreq_nd->to_host(uds_ctx, setup, buf);
+		return 0;
+	}
+
+	errno = -ENOTSUP;
+	return 0;
+}
+
 static int nonstd_request(struct usbd_context *const uds_ctx,
 			  struct net_buf *const dbuf)
 {
@@ -941,7 +969,7 @@ static int nonstd_request(struct usbd_context *const uds_ctx,
 			ret = usbd_class_control_to_host(c_nd->c_data, setup, dbuf);
 		}
 	} else {
-		errno = -ENOTSUP;
+		return vendor_device_request(uds_ctx, dbuf);
 	}
 
 	return ret;

subsys/usb/device_next/usbd_core.c

@@ -249,6 +249,8 @@ int usbd_device_shutdown_core(struct usbd_context *const uds_ctx)
 		LOG_ERR("Failed to cleanup descriptors, %d", ret);
 	}
 
+	usbd_device_unregister_all_vreq(uds_ctx);
+
 	return udc_shutdown(uds_ctx->dev);
 }
 

subsys/usb/device_next/usbd_device.c

@@ -310,3 +310,67 @@ bool usbd_can_detect_vbus(struct usbd_context *const uds_ctx)
 
 	return caps.can_detect_vbus;
 }
+
+struct usbd_vreq_node *usbd_device_get_vreq(struct usbd_context *const uds_ctx,
+					    const uint8_t code)
+{
+	struct usbd_vreq_node *vreq_nd;
+
+	SYS_DLIST_FOR_EACH_CONTAINER(&uds_ctx->vreqs, vreq_nd, node) {
+		if (vreq_nd->code == code) {
+			return vreq_nd;
+		}
+	}
+
+	return NULL;
+}
+
+int usbd_device_register_vreq(struct usbd_context *const uds_ctx,
+			      struct usbd_vreq_node *const vreq_nd)
+{
+	int ret = 0;
+
+	usbd_device_lock(uds_ctx);
+
+	if (usbd_is_initialized(uds_ctx)) {
+		ret = -EPERM;
+		goto error;
+	}
+
+	if (vreq_nd->to_dev == NULL && vreq_nd->to_host == NULL) {
+		ret = -EINVAL;
+		goto error;
+	}
+
+	if (!sys_dnode_is_linked(&uds_ctx->vreqs)) {
+		LOG_DBG("Initialize vendor request list");
+		sys_dlist_init(&uds_ctx->vreqs);
+	}
+
+	if (sys_dnode_is_linked(&vreq_nd->node)) {
+		ret = -EALREADY;
+		goto error;
+	}
+
+	sys_dlist_append(&uds_ctx->vreqs, &vreq_nd->node);
+	LOG_DBG("Registered vendor request 0x%02x", vreq_nd->code);
+
+error:
+	usbd_device_unlock(uds_ctx);
+	return ret;
+}
+
+void usbd_device_unregister_all_vreq(struct usbd_context *const uds_ctx)
+{
+	struct usbd_vreq_node *tmp;
+	sys_dnode_t *node;
+
+	if (!sys_dnode_is_linked(&uds_ctx->vreqs)) {
+		return;
+	}
+
+	while ((node = sys_dlist_get(&uds_ctx->vreqs))) {
+		tmp = CONTAINER_OF(node, struct usbd_vreq_node, node);
+		LOG_DBG("Remove vendor request 0x%02x", tmp->code);
+	}
+}

subsys/usb/device_next/usbd_device.h

@@ -10,6 +10,26 @@
 #include <zephyr/drivers/usb/udc.h>
 #include <zephyr/usb/usbd.h>
 
+/**
+ * @brief Get vendor request node
+ *
+ * Get vendor request node from internal vendor request list.
+ *
+ * @param[in] ctx    Pointer to USB device support context
+ * @param[in] code   Vendor request code
+ *
+ * @return pointer to vendor request node or NULL if not found.
+ */
+struct usbd_vreq_node *usbd_device_get_vreq(struct usbd_context *const uds_ctx,
+					    const uint8_t code);
+
+/**
+ * @brief Unregister all registered vendor request
+ *
+ * @param[in] uds_ctx Pointer to a device context
+ */
+void usbd_device_unregister_all_vreq(struct usbd_context *const uds_ctx);
+
 /**
  * @brief Get device descriptor bNumConfigurations value
  *