1 /*
2 * Copyright (c) 2020 PHYTEC Messtechnik GmbH
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /**
8 * @file
9 * @brief USB Chapter 9 structures and definitions
10 *
11 * This file contains the USB Chapter 9 structures definitions
12 * and follows, with few exceptions, the USB Specification 2.0.
13 */
14
15 #include <zephyr/version.h>
16 #include <zephyr/sys/util.h>
17 #include <zephyr/math/ilog2.h>
18 #include <zephyr/usb/class/usb_hub.h>
19
20 #ifndef ZEPHYR_INCLUDE_USB_CH9_H_
21 #define ZEPHYR_INCLUDE_USB_CH9_H_
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26
27 struct usb_req_type_field {
28 #ifdef CONFIG_LITTLE_ENDIAN
29 uint8_t recipient : 5;
30 uint8_t type : 2;
31 uint8_t direction : 1;
32 #else
33 uint8_t direction : 1;
34 uint8_t type : 2;
35 uint8_t recipient : 5;
36 #endif
37 } __packed;
38
39 /** USB Setup Data packet defined in spec. Table 9-2 */
40 struct usb_setup_packet {
41 union {
42 uint8_t bmRequestType;
43 struct usb_req_type_field RequestType;
44 };
45 uint8_t bRequest;
46 uint16_t wValue;
47 uint16_t wIndex;
48 uint16_t wLength;
49 };
50
51 /** USB Setup packet RequestType Direction values (from Table 9-2) */
52 #define USB_REQTYPE_DIR_TO_DEVICE 0
53 #define USB_REQTYPE_DIR_TO_HOST 1
54
55 /** USB Setup packet RequestType Type values (from Table 9-2) */
56 #define USB_REQTYPE_TYPE_STANDARD 0
57 #define USB_REQTYPE_TYPE_CLASS 1
58 #define USB_REQTYPE_TYPE_VENDOR 2
59 #define USB_REQTYPE_TYPE_RESERVED 3
60
61 /** USB Setup packet RequestType Recipient values (from Table 9-2) */
62 #define USB_REQTYPE_RECIPIENT_DEVICE 0
63 #define USB_REQTYPE_RECIPIENT_INTERFACE 1
64 #define USB_REQTYPE_RECIPIENT_ENDPOINT 2
65 #define USB_REQTYPE_RECIPIENT_OTHER 3
66
67 /** Get data transfer direction from bmRequestType */
68 #define USB_REQTYPE_GET_DIR(bmRequestType) (((bmRequestType) >> 7) & 0x01U)
69 /** Get request type from bmRequestType */
70 #define USB_REQTYPE_GET_TYPE(bmRequestType) (((bmRequestType) >> 5) & 0x03U)
71 /** Get request recipient from bmRequestType */
72 #define USB_REQTYPE_GET_RECIPIENT(bmRequestType) ((bmRequestType) & 0x1FU)
73
74 /**
75 * @brief Check if request transfer direction is to host.
76 *
77 * @param setup Pointer to USB Setup packet
78 * @return true If transfer direction is to host
79 */
usb_reqtype_is_to_host(const struct usb_setup_packet * setup)80 static inline bool usb_reqtype_is_to_host(const struct usb_setup_packet *setup)
81 {
82 return setup->RequestType.direction == USB_REQTYPE_DIR_TO_HOST;
83 }
84
85 /**
86 * @brief Check if request transfer direction is to device.
87 *
88 * @param setup Pointer to USB Setup packet
89 * @return true If transfer direction is to device
90 */
usb_reqtype_is_to_device(const struct usb_setup_packet * setup)91 static inline bool usb_reqtype_is_to_device(const struct usb_setup_packet *setup)
92 {
93 return setup->RequestType.direction == USB_REQTYPE_DIR_TO_DEVICE;
94 }
95
96 /** USB Standard Request Codes defined in spec. Table 9-4 */
97 #define USB_SREQ_GET_STATUS 0x00
98 #define USB_SREQ_CLEAR_FEATURE 0x01
99 #define USB_SREQ_SET_FEATURE 0x03
100 #define USB_SREQ_SET_ADDRESS 0x05
101 #define USB_SREQ_GET_DESCRIPTOR 0x06
102 #define USB_SREQ_SET_DESCRIPTOR 0x07
103 #define USB_SREQ_GET_CONFIGURATION 0x08
104 #define USB_SREQ_SET_CONFIGURATION 0x09
105 #define USB_SREQ_GET_INTERFACE 0x0A
106 #define USB_SREQ_SET_INTERFACE 0x0B
107 #define USB_SREQ_SYNCH_FRAME 0x0C
108
109 /** Descriptor Types defined in spec. Table 9-5 */
110 #define USB_DESC_DEVICE 1
111 #define USB_DESC_CONFIGURATION 2
112 #define USB_DESC_STRING 3
113 #define USB_DESC_INTERFACE 4
114 #define USB_DESC_ENDPOINT 5
115 #define USB_DESC_DEVICE_QUALIFIER 6
116 #define USB_DESC_OTHER_SPEED 7
117 #define USB_DESC_INTERFACE_POWER 8
118 /** Additional Descriptor Types defined in USB 3 spec. Table 9-5 */
119 #define USB_DESC_OTG 9
120 #define USB_DESC_DEBUG 10
121 #define USB_DESC_INTERFACE_ASSOC 11
122 #define USB_DESC_BOS 15
123 #define USB_DESC_DEVICE_CAPABILITY 16
124
125 /** Class-Specific Descriptor Types as defined by
126 * USB Common Class Specification
127 */
128 #define USB_DESC_CS_DEVICE 0x21
129 #define USB_DESC_CS_CONFIGURATION 0x22
130 #define USB_DESC_CS_STRING 0x23
131 #define USB_DESC_CS_INTERFACE 0x24
132 #define USB_DESC_CS_ENDPOINT 0x25
133
134 /** USB Standard Feature Selectors defined in spec. Table 9-6 */
135 #define USB_SFS_ENDPOINT_HALT 0x00
136 #define USB_SFS_REMOTE_WAKEUP 0x01
137 #define USB_SFS_TEST_MODE 0x02
138
139 /** Bits used for GetStatus response defined in spec. Figure 9-4 */
140 #define USB_GET_STATUS_SELF_POWERED BIT(0)
141 #define USB_GET_STATUS_REMOTE_WAKEUP BIT(1)
142
143 /** Header of an USB descriptor */
144 struct usb_desc_header {
145 uint8_t bLength;
146 uint8_t bDescriptorType;
147 } __packed;
148
149 /** USB Standard Device Descriptor defined in spec. Table 9-8 */
150 struct usb_device_descriptor {
151 uint8_t bLength;
152 uint8_t bDescriptorType;
153 uint16_t bcdUSB;
154 uint8_t bDeviceClass;
155 uint8_t bDeviceSubClass;
156 uint8_t bDeviceProtocol;
157 uint8_t bMaxPacketSize0;
158 uint16_t idVendor;
159 uint16_t idProduct;
160 uint16_t bcdDevice;
161 uint8_t iManufacturer;
162 uint8_t iProduct;
163 uint8_t iSerialNumber;
164 uint8_t bNumConfigurations;
165 } __packed;
166
167 /** USB Device Qualifier Descriptor defined in spec. Table 9-9 */
168 struct usb_device_qualifier_descriptor {
169 uint8_t bLength;
170 uint8_t bDescriptorType;
171 uint16_t bcdUSB;
172 uint8_t bDeviceClass;
173 uint8_t bDeviceSubClass;
174 uint8_t bDeviceProtocol;
175 uint8_t bMaxPacketSize0;
176 uint8_t bNumConfigurations;
177 uint8_t bReserved;
178 } __packed;
179
180 /** USB Standard Configuration Descriptor defined in spec. Table 9-10 */
181 struct usb_cfg_descriptor {
182 uint8_t bLength;
183 uint8_t bDescriptorType;
184 uint16_t wTotalLength;
185 uint8_t bNumInterfaces;
186 uint8_t bConfigurationValue;
187 uint8_t iConfiguration;
188 uint8_t bmAttributes;
189 uint8_t bMaxPower;
190 } __packed;
191
192 /** USB Standard Interface Descriptor defined in spec. Table 9-12 */
193 struct usb_if_descriptor {
194 uint8_t bLength;
195 uint8_t bDescriptorType;
196 uint8_t bInterfaceNumber;
197 uint8_t bAlternateSetting;
198 uint8_t bNumEndpoints;
199 uint8_t bInterfaceClass;
200 uint8_t bInterfaceSubClass;
201 uint8_t bInterfaceProtocol;
202 uint8_t iInterface;
203 } __packed;
204
205 struct usb_ep_desc_bmattr {
206 #ifdef CONFIG_LITTLE_ENDIAN
207 uint8_t transfer : 2;
208 uint8_t synch: 2;
209 uint8_t usage: 2;
210 uint8_t reserved: 2;
211 #else
212 uint8_t reserved: 2;
213 uint8_t usage : 2;
214 uint8_t synch : 2;
215 uint8_t transfer : 2;
216 #endif
217 } __packed;
218
219 /** USB Standard Endpoint Descriptor defined in spec. Table 9-13 */
220 struct usb_ep_descriptor {
221 uint8_t bLength;
222 uint8_t bDescriptorType;
223 uint8_t bEndpointAddress;
224 union {
225 uint8_t bmAttributes;
226 struct usb_ep_desc_bmattr Attributes;
227 };
228 uint16_t wMaxPacketSize;
229 uint8_t bInterval;
230 } __packed;
231
232 /** USB Unicode (UTF16LE) String Descriptor defined in spec. Table 9-15 */
233 struct usb_string_descriptor {
234 uint8_t bLength;
235 uint8_t bDescriptorType;
236 uint16_t bString;
237 } __packed;
238
239 /** USB Association Descriptor defined in USB 3 spec. Table 9-16 */
240 struct usb_association_descriptor {
241 uint8_t bLength;
242 uint8_t bDescriptorType;
243 uint8_t bFirstInterface;
244 uint8_t bInterfaceCount;
245 uint8_t bFunctionClass;
246 uint8_t bFunctionSubClass;
247 uint8_t bFunctionProtocol;
248 uint8_t iFunction;
249 } __packed;
250
251 /** USB Standard Configuration Descriptor Characteristics from Table 9-10 */
252 #define USB_SCD_RESERVED BIT(7)
253 #define USB_SCD_SELF_POWERED BIT(6)
254 #define USB_SCD_REMOTE_WAKEUP BIT(5)
255
256 /** USB Defined Base Class Codes from https://www.usb.org/defined-class-codes */
257 #define USB_BCC_AUDIO 0x01
258 #define USB_BCC_CDC_CONTROL 0x02
259 #define USB_BCC_HID 0x03
260 #define USB_BCC_MASS_STORAGE 0x08
261 #define USB_BCC_CDC_DATA 0x0A
262 #define USB_BCC_VIDEO 0x0E
263 #define USB_BCC_WIRELESS_CONTROLLER 0xE0
264 #define USB_BCC_MISCELLANEOUS 0xEF
265 #define USB_BCC_APPLICATION 0xFE
266 #define USB_BCC_VENDOR 0xFF
267
268 /** USB Specification Release Numbers (bcdUSB Descriptor field) */
269 #define USB_SRN_1_1 0x0110
270 #define USB_SRN_2_0 0x0200
271 #define USB_SRN_2_0_1 0x0201
272 #define USB_SRN_2_1 0x0210
273
274 #define USB_DEC_TO_BCD(dec) ((((dec) / 10) << 4) | ((dec) % 10))
275
276 /** USB Device release number (bcdDevice Descriptor field) */
277 #define USB_BCD_DRN (USB_DEC_TO_BCD(KERNEL_VERSION_MAJOR) << 8 | \
278 USB_DEC_TO_BCD(KERNEL_VERSION_MINOR))
279
280 /** Macro to obtain descriptor type from USB_SREQ_GET_DESCRIPTOR request */
281 #define USB_GET_DESCRIPTOR_TYPE(wValue) ((uint8_t)((wValue) >> 8))
282
283 /** Macro to obtain descriptor index from USB_SREQ_GET_DESCRIPTOR request */
284 #define USB_GET_DESCRIPTOR_INDEX(wValue) ((uint8_t)(wValue))
285
286 /**
287 * USB Control Endpoints maximum packet size (MPS)
288 *
289 * This value may not be correct for devices operating at speeds other than
290 * high speed.
291 */
292 #define USB_CONTROL_EP_MPS 64U
293
294 /** USB endpoint direction mask */
295 #define USB_EP_DIR_MASK (uint8_t)BIT(7)
296
297 /** USB IN endpoint direction */
298 #define USB_EP_DIR_IN (uint8_t)BIT(7)
299
300 /** USB OUT endpoint direction */
301 #define USB_EP_DIR_OUT 0U
302
303 /*
304 * REVISE: this should actually be (ep) & 0x0F, but is causes
305 * many regressions in the current device support that are difficult
306 * to handle.
307 */
308 /** Get endpoint index (number) from endpoint address */
309 #define USB_EP_GET_IDX(ep) ((ep) & ~USB_EP_DIR_MASK)
310
311 /** Get direction based on endpoint address */
312 #define USB_EP_GET_DIR(ep) ((ep) & USB_EP_DIR_MASK)
313
314 /** Get endpoint address from endpoint index and direction */
315 #define USB_EP_GET_ADDR(idx, dir) ((idx) | ((dir) & USB_EP_DIR_MASK))
316
317 /** True if the endpoint is an IN endpoint */
318 #define USB_EP_DIR_IS_IN(ep) (USB_EP_GET_DIR(ep) == USB_EP_DIR_IN)
319
320 /** True if the endpoint is an OUT endpoint */
321 #define USB_EP_DIR_IS_OUT(ep) (USB_EP_GET_DIR(ep) == USB_EP_DIR_OUT)
322
323 /** USB Control Endpoints OUT address */
324 #define USB_CONTROL_EP_OUT (USB_EP_DIR_OUT | 0U)
325
326 /** USB Control Endpoints IN address */
327 #define USB_CONTROL_EP_IN (USB_EP_DIR_IN | 0U)
328
329 /** USB endpoint transfer type mask */
330 #define USB_EP_TRANSFER_TYPE_MASK 0x3U
331
332 /** USB endpoint transfer type control */
333 #define USB_EP_TYPE_CONTROL 0U
334
335 /** USB endpoint transfer type isochronous */
336 #define USB_EP_TYPE_ISO 1U
337
338 /** USB endpoint transfer type bulk */
339 #define USB_EP_TYPE_BULK 2U
340
341 /** USB endpoint transfer type interrupt */
342 #define USB_EP_TYPE_INTERRUPT 3U
343
344 /** Calculate full speed interrupt endpoint bInterval from a value in microseconds */
345 #define USB_FS_INT_EP_INTERVAL(us) CLAMP(((us) / 1000U), 1U, 255U)
346
347 /** Calculate high speed interrupt endpoint bInterval from a value in microseconds */
348 #define USB_HS_INT_EP_INTERVAL(us) CLAMP((ilog2((us) / 125U) + 1U), 1U, 16U)
349
350 /** Calculate high speed isochronous endpoint bInterval from a value in microseconds */
351 #define USB_FS_ISO_EP_INTERVAL(us) CLAMP(((us) / 1000U), 1U, 16U)
352
353 /** Calculate high speed isochronous endpoint bInterval from a value in microseconds */
354 #define USB_HS_ISO_EP_INTERVAL(us) CLAMP((ilog2((us) / 125U) + 1U), 1U, 16U)
355
356 /** Get endpoint size field from Max Packet Size value */
357 #define USB_MPS_EP_SIZE(mps) ((mps) & BIT_MASK(11))
358
359 /** Get number of additional transactions per microframe from Max Packet Size value */
360 #define USB_MPS_ADDITIONAL_TRANSACTIONS(mps) (((mps) & 0x1800) >> 11)
361
362 /** Calculate total payload length from Max Packet Size value */
363 #define USB_MPS_TO_TPL(mps) \
364 ((1 + USB_MPS_ADDITIONAL_TRANSACTIONS(mps)) * USB_MPS_EP_SIZE(mps))
365
366 /** Calculate Max Packet Size value from total payload length */
367 #define USB_TPL_TO_MPS(tpl) \
368 (((tpl) > 2048) ? ((2 << 11) | ((tpl) / 3)) : \
369 ((tpl) > 1024) ? ((1 << 11) | ((tpl) / 2)) : \
370 (tpl))
371
372 /** Round up total payload length to next valid value */
373 #define USB_TPL_ROUND_UP(tpl) \
374 (((tpl) > 2048) ? ROUND_UP(tpl, 3) : \
375 ((tpl) > 1024) ? ROUND_UP(tpl, 2) : \
376 (tpl))
377
378 /** Determine whether total payload length value is valid according to USB 2.0 */
379 #define USB_TPL_IS_VALID(tpl) \
380 (((tpl) > 3072) ? false : \
381 ((tpl) > 2048) ? ((tpl) % 3 == 0) : \
382 ((tpl) > 1024) ? ((tpl) % 2 == 0) : \
383 ((tpl) >= 0))
384
385 #ifdef __cplusplus
386 }
387 #endif
388
389 #endif /* ZEPHYR_INCLUDE_USB_CH9_H_ */
390
