usb: device_next: usb3 support

Introduce definitions to enable USB3 device controllers to be written.
The USB3 support got added to the core implementaiton, and to the Loopback
and CDC-ACM class only.

Signed-off-by: Josuah Demangeon <me@josuah.net>

Author: josuah

drivers/usb/udc/udc_virtual.c

@@ -474,7 +474,8 @@ static enum udc_bus_speed udc_vrt_device_speed(const struct device *dev)
 	struct udc_data *data = dev->data;
 
 	/* FIXME: get actual device speed */
-	return data->caps.hs ? UDC_BUS_SPEED_HS : UDC_BUS_SPEED_FS;
+	return data->caps.ss ? UDC_BUS_SPEED_SS :
+	       data->caps.hs ? UDC_BUS_SPEED_HS : UDC_BUS_SPEED_FS;
 }
 
 static int udc_vrt_enable(const struct device *dev)
@@ -559,10 +560,13 @@ static int udc_vrt_driver_preinit(const struct device *dev)
 
 	data->caps.rwup = true;
 	data->caps.mps0 = UDC_MPS0_64;
-	if (config->speed_idx == 2) {
+	if (config->speed_idx >= 2) {
 		data->caps.hs = true;
 		mps = 1024;
 	}
+	if (config->speed_idx >= 3) {
+		data->caps.ss = true;
+	}
 
 	for (int i = 0; i < config->num_of_eps; i++) {
 		config->ep_cfg_out[i].caps.out = 1;

include/zephyr/drivers/usb/udc.h

@@ -26,6 +26,7 @@ enum udc_mps0 {
 	UDC_MPS0_16,
 	UDC_MPS0_32,
 	UDC_MPS0_64,
+	UDC_MPS0_512,
 };
 
 /**
@@ -36,6 +37,8 @@ enum udc_mps0 {
 struct udc_device_caps {
 	/** USB high speed capable controller */
 	uint32_t hs : 1;
+	/** USB super speed capable controller */
+	uint32_t ss : 1;
 	/** Controller supports USB remote wakeup */
 	uint32_t rwup : 1;
 	/** Controller performs status OUT stage automatically */
@@ -45,7 +48,7 @@ struct udc_device_caps {
 	/** Controller can detect the state change of USB supply VBUS.*/
 	uint32_t can_detect_vbus : 1;
 	/** Maximum packet size for control endpoint */
-	enum udc_mps0 mps0 : 2;
+	enum udc_mps0 mps0 : 3;
 };
 
 /**
@@ -221,7 +224,7 @@ typedef int (*udc_event_cb_t)(const struct device *dev,
  * @brief UDC driver API
  * This is the mandatory API any USB device controller driver needs to expose
  * with exception of:
- *   device_speed(), test_mode() are only required for HS controllers
+ *   device_speed(), test_mode() are only required for HS and SS controllers
  */
 struct udc_api {
 	enum udc_bus_speed (*device_speed)(const struct device *dev);
@@ -243,6 +246,8 @@ struct udc_api {
 	int (*host_wakeup)(const struct device *dev);
 	int (*set_address)(const struct device *dev,
 			   const uint8_t addr);
+	int (*set_system_exit_latency)(const struct device *dev,
+				       const struct usb_system_exit_latency *sel);
 	int (*test_mode)(const struct device *dev,
 			 const uint8_t mode, const bool dryrun);
 	int (*enable)(const struct device *dev);
@@ -407,7 +412,7 @@ int udc_shutdown(const struct device *dev);
  * @brief Get USB device controller capabilities
  *
  * Obtain the capabilities of the controller
- * such as full speed (FS), high speed (HS), and more.
+ * such as full speed (FS), high speed (HS), super speed (SS), and more.
  *
  * @param[in] dev    Pointer to device struct of the driver instance
  *
@@ -495,6 +500,40 @@ static inline int udc_test_mode(const struct device *dev,
 	return ret;
 }
 
+/**
+ * @brief Set USB3 U1/P1 U2/P2 link latency.
+ *
+ * USB3 defines link latencies values, and the host is expected to configure
+ * these parameters for the device through a SET_SEL command, defined in
+ * USB 3.2 standard (section 9.4.12).
+ *
+ * @param[in] dev Pointer to device struct of the driver instance
+ * @param[in] sel Pointer to struct with the latency values from the host
+ *
+ * @return 0 on success, all other values should be treated as error.
+ * @retval -EPERM controller is not enabled (or not initialized)
+ */
+static inline int udc_set_system_exit_latency(const struct device *dev,
+					      const struct usb_system_exit_latency *sel)
+{
+	const struct udc_api *api = dev->api;
+	int ret;
+
+	if (!udc_is_enabled(dev)) {
+		return -EPERM;
+	}
+
+	if (api->set_system_exit_latency != NULL) {
+		api->lock(dev);
+		ret = api->set_system_exit_latency(dev, sel);
+		api->unlock(dev);
+	} else {
+		ret = -ENOTSUP;
+	}
+
+	return ret;
+}
+
 /**
  * @brief Initiate host wakeup procedure.
  *

include/zephyr/usb/bos.h

@@ -30,7 +30,10 @@ struct usb_bos_descriptor {
 /** Device capability type codes */
 enum usb_bos_capability_types {
 	USB_BOS_CAPABILITY_EXTENSION = 0x02,
+	USB_BOS_CAPABILITY_SUPERSPEED_USB = 0x03,
 	USB_BOS_CAPABILITY_PLATFORM = 0x05,
+	USB_BOS_CAPABILITY_SUPERSPEED_PLUS = 0x0a,
+	USB_BOS_CAPABILITY_PRECISION_TIME_MEASUREMENT = 0x0b,
 };
 
 /** BOS USB 2.0 extension capability descriptor */
@@ -41,6 +44,12 @@ struct usb_bos_capability_lpm {
 	uint32_t bmAttributes;
 } __packed;
 
+/** Fields for @ref usb_bos_capability_lpm bmAttributes */
+enum usb_bos_attributes {
+	USB_BOS_ATTRIBUTES_LPM = BIT(1),
+	USB_BOS_ATTRIBUTES_BESL = BIT(2),
+};
+
 /** BOS platform capability descriptor */
 struct usb_bos_platform_descriptor {
 	uint8_t bLength;
@@ -50,6 +59,51 @@ struct usb_bos_platform_descriptor {
 	uint8_t PlatformCapabilityUUID[16];
 } __packed;
 
+/** BOS SuperSpeed device capability descriptor */
+struct usb_bos_capability_superspeed_usb {
+	uint8_t bLength;
+	uint8_t bDescriptorType;
+	uint8_t bDevCapabilityType;
+	uint8_t bmAttributes;
+	uint16_t wSpeedsSupported;
+	uint8_t bFunctionnalSupport;
+	uint8_t bU1DevExitLat;
+	uint16_t wU2DevExitLat;
+} __packed;
+
+/** Fields for @ref usb_bos_capability_superspeed_usb bmAttributes */
+enum usb_bos_attributes_superspeed_usb {
+	USB_BOS_ATTRIBUTES_SUPERSPEED_LTM = BIT(1),
+};
+
+/** BOS SuperSpeedPlus device capability descriptor */
+struct usb_bos_capability_superspeedplus {
+	uint8_t bLength;
+	uint8_t bDescriptorType;
+	uint8_t bDevCapabilityType;
+	uint8_t bReserved;
+	uint16_t bmAttributes;
+	uint16_t bFunctionnalSupport;
+	/* Variable size depending on the SSAC value in bmAttributes */
+	uint32_t bmSublinkSpeedAttr[1];
+} __packed;
+
+/** BOS Precision Time Measurement device capability descriptor */
+struct usb_bos_capability_precision_time_measurement {
+	uint8_t bLength;
+	uint8_t bDescriptorType;
+	uint8_t bDevCapabilityType;
+};
+
+/** BOS description of different speeds supported by the device */
+enum usb_bos_speed {
+	USB_BOS_SPEED_LOWSPEED = BIT(0),
+	USB_BOS_SPEED_FULLSPEED = BIT(1),
+	USB_BOS_SPEED_HIGHSPEED = BIT(2),
+	USB_BOS_SPEED_SUPERSPEED_GEN1 = BIT(3),
+	USB_BOS_SPEED_SUPERSPEED_GEN2 = BIT(4),
+};
+
 /** WebUSB specific part of platform capability descriptor */
 struct usb_bos_capability_webusb {
 	uint16_t bcdVersion;

include/zephyr/usb/usb_ch9.h

@@ -105,6 +105,22 @@ static inline bool usb_reqtype_is_to_device(const struct usb_setup_packet *setup
 #define USB_SREQ_GET_INTERFACE		0x0A
 #define USB_SREQ_SET_INTERFACE		0x0B
 #define USB_SREQ_SYNCH_FRAME		0x0C
+/** Additional Request Codes defined in USB 3.2 spec. Table 9-5 */
+#define USB_SREQ_SET_ENCRYPTION		0x0D
+#define USB_SREQ_GET_ENCRYPTION		0x0E
+#define USB_SREQ_SET_HANDSHAKE		0x0F
+#define USB_SREQ_GET_HANDSHAKE		0x10
+#define USB_SREQ_SET_CONNECTION		0x11
+#define USB_SREQ_SET_SECURITY_DATA	0x12
+#define USB_SREQ_GET_SECURITY_DATA	0x13
+#define USB_SREQ_SET_WUSB_DATA		0x14
+#define USB_SREQ_LOOPBACK_DATA_WRITE	0x15
+#define USB_SREQ_LOOPBACK_DATA_READ	0x16
+#define USB_SREQ_SET_INTERFACE_DS	0x17
+#define USB_SREQ_GET_FW_STATUS		0x1A
+#define USB_SREQ_SET_FW_STATUS		0x1B
+#define USB_SREQ_SET_SEL		0x30
+#define USB_SREQ_SET_ISOCH_DELAY	0x31
 
 /** Descriptor Types defined in spec. Table 9-5 */
 #define USB_DESC_DEVICE			1
@@ -121,6 +137,8 @@ static inline bool usb_reqtype_is_to_device(const struct usb_setup_packet *setup
 #define USB_DESC_INTERFACE_ASSOC	11
 #define USB_DESC_BOS			15
 #define USB_DESC_DEVICE_CAPABILITY	16
+#define USB_DESC_ENDPOINT_COMPANION	48
+#define USB_DESC_ISO_ENDPOINT_COMPANION	49
 
 /** Class-Specific Descriptor Types as defined by
  *  USB Common Class Specification
@@ -248,6 +266,23 @@ struct usb_association_descriptor {
 	uint8_t iFunction;
 } __packed;
 
+/** USB Endpoint Companion Descriptor defined in USB3 spec. Table 9-27. */
+struct usb_ss_endpoint_companion_descriptor {
+	uint8_t bLength;
+	uint8_t bDescriptorType;
+	uint8_t bMaxBurst;
+	uint8_t bmAttributes;
+	uint16_t wBytesPerInterval;
+} __packed;
+
+/** USB3 SET_SEL command payload from the host. Section 9.4.12. */
+struct usb_system_exit_latency {
+	uint8_t u1sel;
+	uint8_t u1pel;
+	uint16_t u2sel;
+	uint16_t u2pel;
+} __packed;
+
 /** USB Standard Configuration Descriptor Characteristics from Table 9-10 */
 #define USB_SCD_RESERVED	BIT(7)
 #define USB_SCD_SELF_POWERED	BIT(6)
@@ -270,7 +305,9 @@ struct usb_association_descriptor {
 #define USB_SRN_2_0			0x0200
 #define USB_SRN_2_0_1			0x0201
 #define USB_SRN_2_1			0x0210
-
+#define USB_SRN_3_0			0x0300
+#define USB_SRN_3_1			0x0310
+#define USB_SRN_3_2			0x0320
 #define USB_DEC_TO_BCD(dec)	((((dec) / 10) << 4) | ((dec) % 10))
 
 /** USB Device release number (bcdDevice Descriptor field) */
@@ -347,12 +384,18 @@ struct usb_association_descriptor {
 /** Calculate high speed interrupt endpoint bInterval from a value in microseconds */
 #define USB_HS_INT_EP_INTERVAL(us)	CLAMP((ilog2((us) / 125U) + 1U), 1U, 16U)
 
-/** Calculate high speed isochronous endpoint bInterval from a value in microseconds */
+/** Calculate super speed interrupt endpoint bInterval from a value in microseconds */
+#define USB_SS_INT_EP_INTERVAL(us)	CLAMP((ilog2((us) / 125U) + 1U), 1U, 16U)
+
+/** Calculate full speed isochronous endpoint bInterval from a value in microseconds */
 #define USB_FS_ISO_EP_INTERVAL(us)	CLAMP(((us) / 1000U), 1U, 16U)
 
 /** Calculate high speed isochronous endpoint bInterval from a value in microseconds */
 #define USB_HS_ISO_EP_INTERVAL(us)	CLAMP((ilog2((us) / 125U) + 1U), 1U, 16U)
 
+/** Calculate super speed isochronous endpoint bInterval from a value in microseconds */
+#define USB_SS_ISO_EP_INTERVAL(us)	CLAMP((ilog2((us) / 125U) + 1U), 1U, 16U)
+
 /** Get endpoint size field from Max Packet Size value */
 #define USB_MPS_EP_SIZE(mps)		((mps) & BIT_MASK(11))
 

include/zephyr/usb/usbd.h

@@ -295,6 +295,8 @@ struct usbd_context {
 	sys_slist_t fs_configs;
 	/** slist to manage High-Speed device configurations */
 	sys_slist_t hs_configs;
+	/** slist to manage Super-Speed device configurations */
+	sys_slist_t ss_configs;
 	/** dlist to manage vendor requests with recipient device */
 	sys_dlist_t vreqs;
 	/** Status of the USB device support */
@@ -303,6 +305,8 @@ struct usbd_context {
 	void *fs_desc;
 	/** Pointer to High-Speed device descriptor */
 	void *hs_desc;
+	/** Pointer to Super-Speed device descriptor */
+	void *ss_desc;
 };
 
 /**
@@ -502,11 +506,29 @@ static inline void *usbd_class_get_private(const struct usbd_class_data *const c
 		.iSerialNumber = 0,					\
 		.bNumConfigurations = 0,				\
 	};								\
+	static struct usb_device_descriptor				\
+	ss_desc_##device_name = {					\
+		.bLength = sizeof(struct usb_device_descriptor),	\
+		.bDescriptorType = USB_DESC_DEVICE,			\
+		.bcdUSB = sys_cpu_to_le16(USB_SRN_3_2),			\
+		.bDeviceClass = USB_BCC_MISCELLANEOUS,			\
+		.bDeviceSubClass = 2,					\
+		.bDeviceProtocol = 1,					\
+		.bMaxPacketSize0 = 9,					\
+		.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,			\
+		.ss_desc = &ss_desc_##device_name,			\
 	}
 
 /**
@@ -740,6 +762,10 @@ static inline void *usbd_class_get_private(const struct usbd_class_data *const c
 	static STRUCT_SECTION_ITERABLE_ALTERNATE(				\
 		usbd_class_hs, usbd_class_node, class_name##_hs) = {		\
 		.c_data = &class_name,						\
+	};									\
+	static STRUCT_SECTION_ITERABLE_ALTERNATE(				\
+		usbd_class_ss, usbd_class_node, class_name##_ss) = {		\
+		.c_data = &class_name,						\
 	}
 
 /** @brief Helper to declare request table of usbd_cctx_vendor_req