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 } __packed;
45 uint8_t bRequest;
46 uint16_t wValue;
47 uint16_t wIndex;
48 uint16_t wLength;
49 } __packed;
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 /** USB Test Mode Selectors defined in spec. Table 9-7 */
140 #define USB_SFS_TEST_MODE_J 0x01
141 #define USB_SFS_TEST_MODE_K 0x02
142 #define USB_SFS_TEST_MODE_SE0_NAK 0x03
143 #define USB_SFS_TEST_MODE_PACKET 0x04
144 #define USB_SFS_TEST_MODE_FORCE_ENABLE 0x05
145
146 /** Bits used for GetStatus response defined in spec. Figure 9-4 */
147 #define USB_GET_STATUS_SELF_POWERED BIT(0)
148 #define USB_GET_STATUS_REMOTE_WAKEUP BIT(1)
149
150 /** Header of an USB descriptor */
151 struct usb_desc_header {
152 uint8_t bLength;
153 uint8_t bDescriptorType;
154 } __packed;
155
156 /** USB Standard Device Descriptor defined in spec. Table 9-8 */
157 struct usb_device_descriptor {
158 uint8_t bLength;
159 uint8_t bDescriptorType;
160 uint16_t bcdUSB;
161 uint8_t bDeviceClass;
162 uint8_t bDeviceSubClass;
163 uint8_t bDeviceProtocol;
164 uint8_t bMaxPacketSize0;
165 uint16_t idVendor;
166 uint16_t idProduct;
167 uint16_t bcdDevice;
168 uint8_t iManufacturer;
169 uint8_t iProduct;
170 uint8_t iSerialNumber;
171 uint8_t bNumConfigurations;
172 } __packed;
173
174 /** USB Device Qualifier Descriptor defined in spec. Table 9-9 */
175 struct usb_device_qualifier_descriptor {
176 uint8_t bLength;
177 uint8_t bDescriptorType;
178 uint16_t bcdUSB;
179 uint8_t bDeviceClass;
180 uint8_t bDeviceSubClass;
181 uint8_t bDeviceProtocol;
182 uint8_t bMaxPacketSize0;
183 uint8_t bNumConfigurations;
184 uint8_t bReserved;
185 } __packed;
186
187 /** USB Standard Configuration Descriptor defined in spec. Table 9-10 */
188 struct usb_cfg_descriptor {
189 uint8_t bLength;
190 uint8_t bDescriptorType;
191 uint16_t wTotalLength;
192 uint8_t bNumInterfaces;
193 uint8_t bConfigurationValue;
194 uint8_t iConfiguration;
195 uint8_t bmAttributes;
196 uint8_t bMaxPower;
197 } __packed;
198
199 /** USB Standard Interface Descriptor defined in spec. Table 9-12 */
200 struct usb_if_descriptor {
201 uint8_t bLength;
202 uint8_t bDescriptorType;
203 uint8_t bInterfaceNumber;
204 uint8_t bAlternateSetting;
205 uint8_t bNumEndpoints;
206 uint8_t bInterfaceClass;
207 uint8_t bInterfaceSubClass;
208 uint8_t bInterfaceProtocol;
209 uint8_t iInterface;
210 } __packed;
211
212 struct usb_ep_desc_bmattr {
213 #ifdef CONFIG_LITTLE_ENDIAN
214 uint8_t transfer : 2;
215 uint8_t synch: 2;
216 uint8_t usage: 2;
217 uint8_t reserved: 2;
218 #else
219 uint8_t reserved: 2;
220 uint8_t usage : 2;
221 uint8_t synch : 2;
222 uint8_t transfer : 2;
223 #endif
224 } __packed;
225
226 /** USB Standard Endpoint Descriptor defined in spec. Table 9-13 */
227 struct usb_ep_descriptor {
228 uint8_t bLength;
229 uint8_t bDescriptorType;
230 uint8_t bEndpointAddress;
231 union {
232 uint8_t bmAttributes;
233 struct usb_ep_desc_bmattr Attributes;
234 };
235 uint16_t wMaxPacketSize;
236 uint8_t bInterval;
237 } __packed;
238
239 /** USB Unicode (UTF16LE) String Descriptor defined in spec. Table 9-15 */
240 struct usb_string_descriptor {
241 uint8_t bLength;
242 uint8_t bDescriptorType;
243 uint16_t bString;
244 } __packed;
245
246 /** USB Association Descriptor defined in USB 3 spec. Table 9-16 */
247 struct usb_association_descriptor {
248 uint8_t bLength;
249 uint8_t bDescriptorType;
250 uint8_t bFirstInterface;
251 uint8_t bInterfaceCount;
252 uint8_t bFunctionClass;
253 uint8_t bFunctionSubClass;
254 uint8_t bFunctionProtocol;
255 uint8_t iFunction;
256 } __packed;
257
258 /** USB Standard Configuration Descriptor Characteristics from Table 9-10 */
259 #define USB_SCD_RESERVED BIT(7)
260 #define USB_SCD_SELF_POWERED BIT(6)
261 #define USB_SCD_REMOTE_WAKEUP BIT(5)
262
263 /** USB Defined Base Class Codes from https://www.usb.org/defined-class-codes */
264 #define USB_BCC_AUDIO 0x01
265 #define USB_BCC_CDC_CONTROL 0x02
266 #define USB_BCC_HID 0x03
267 #define USB_BCC_MASS_STORAGE 0x08
268 #define USB_BCC_CDC_DATA 0x0A
269 #define USB_BCC_VIDEO 0x0E
270 #define USB_BCC_MCTP 0x14
271 #define USB_BCC_WIRELESS_CONTROLLER 0xE0
272 #define USB_BCC_MISCELLANEOUS 0xEF
273 #define USB_BCC_APPLICATION 0xFE
274 #define USB_BCC_VENDOR 0xFF
275
276 /** USB Specification Release Numbers (bcdUSB Descriptor field) */
277 #define USB_SRN_1_1 0x0110
278 #define USB_SRN_2_0 0x0200
279 #define USB_SRN_2_0_1 0x0201
280 #define USB_SRN_2_1 0x0210
281
282 #define USB_DEC_TO_BCD(dec) ((((dec) / 10) << 4) | ((dec) % 10))
283
284 /** USB Device release number (bcdDevice Descriptor field) */
285 #define USB_BCD_DRN (USB_DEC_TO_BCD(KERNEL_VERSION_MAJOR) << 8 | \
286 USB_DEC_TO_BCD(KERNEL_VERSION_MINOR))
287
288 /** Macro to obtain descriptor type from USB_SREQ_GET_DESCRIPTOR request */
289 #define USB_GET_DESCRIPTOR_TYPE(wValue) ((uint8_t)((wValue) >> 8))
290
291 /** Macro to obtain descriptor index from USB_SREQ_GET_DESCRIPTOR request */
292 #define USB_GET_DESCRIPTOR_INDEX(wValue) ((uint8_t)(wValue))
293
294 /**
295 * USB Control Endpoints maximum packet size (MPS)
296 *
297 * This value may not be correct for devices operating at speeds other than
298 * high speed.
299 */
300 #define USB_CONTROL_EP_MPS 64U
301
302 /** USB endpoint direction mask */
303 #define USB_EP_DIR_MASK (uint8_t)BIT(7)
304
305 /** USB IN endpoint direction */
306 #define USB_EP_DIR_IN (uint8_t)BIT(7)
307
308 /** USB OUT endpoint direction */
309 #define USB_EP_DIR_OUT 0U
310
311 /*
312 * REVISE: this should actually be (ep) & 0x0F, but is causes
313 * many regressions in the current device support that are difficult
314 * to handle.
315 */
316 /** Get endpoint index (number) from endpoint address */
317 #define USB_EP_GET_IDX(ep) ((ep) & ~USB_EP_DIR_MASK)
318
319 /** Get direction based on endpoint address */
320 #define USB_EP_GET_DIR(ep) ((ep) & USB_EP_DIR_MASK)
321
322 /** Get endpoint address from endpoint index and direction */
323 #define USB_EP_GET_ADDR(idx, dir) ((idx) | ((dir) & USB_EP_DIR_MASK))
324
325 /** True if the endpoint is an IN endpoint */
326 #define USB_EP_DIR_IS_IN(ep) (USB_EP_GET_DIR(ep) == USB_EP_DIR_IN)
327
328 /** True if the endpoint is an OUT endpoint */
329 #define USB_EP_DIR_IS_OUT(ep) (USB_EP_GET_DIR(ep) == USB_EP_DIR_OUT)
330
331 /** USB Control Endpoints OUT address */
332 #define USB_CONTROL_EP_OUT (USB_EP_DIR_OUT | 0U)
333
334 /** USB Control Endpoints IN address */
335 #define USB_CONTROL_EP_IN (USB_EP_DIR_IN | 0U)
336
337 /** USB endpoint transfer type mask */
338 #define USB_EP_TRANSFER_TYPE_MASK 0x3U
339
340 /** USB endpoint transfer type control */
341 #define USB_EP_TYPE_CONTROL 0U
342
343 /** USB endpoint transfer type isochronous */
344 #define USB_EP_TYPE_ISO 1U
345
346 /** USB endpoint transfer type bulk */
347 #define USB_EP_TYPE_BULK 2U
348
349 /** USB endpoint transfer type interrupt */
350 #define USB_EP_TYPE_INTERRUPT 3U
351
352 /** Calculate full speed interrupt endpoint bInterval from a value in microseconds */
353 #define USB_FS_INT_EP_INTERVAL(us) CLAMP(((us) / 1000U), 1U, 255U)
354
355 /** Calculate high speed interrupt endpoint bInterval from a value in microseconds */
356 #define USB_HS_INT_EP_INTERVAL(us) CLAMP((ilog2((us) / 125U) + 1U), 1U, 16U)
357
358 /** Calculate full speed isochronous endpoint bInterval from a value in microseconds */
359 #define USB_FS_ISO_EP_INTERVAL(us) CLAMP((ilog2((us) / 1000U) + 1U), 1U, 16U)
360
361 /** Calculate high speed isochronous endpoint bInterval from a value in microseconds */
362 #define USB_HS_ISO_EP_INTERVAL(us) CLAMP((ilog2((us) / 125U) + 1U), 1U, 16U)
363
364 /** Get endpoint size field from Max Packet Size value */
365 #define USB_MPS_EP_SIZE(mps) ((mps) & BIT_MASK(11))
366
367 /** Get number of additional transactions per microframe from Max Packet Size value */
368 #define USB_MPS_ADDITIONAL_TRANSACTIONS(mps) (((mps) & 0x1800) >> 11)
369
370 /** Calculate total payload length from Max Packet Size value */
371 #define USB_MPS_TO_TPL(mps) \
372 ((1 + USB_MPS_ADDITIONAL_TRANSACTIONS(mps)) * USB_MPS_EP_SIZE(mps))
373
374 /** Calculate Max Packet Size value from total payload length */
375 #define USB_TPL_TO_MPS(tpl) \
376 (((tpl) > 2048) ? ((2 << 11) | ((tpl) / 3)) : \
377 ((tpl) > 1024) ? ((1 << 11) | ((tpl) / 2)) : \
378 (tpl))
379
380 /** Round up total payload length to next valid value */
381 #define USB_TPL_ROUND_UP(tpl) \
382 (((tpl) > 2048) ? ROUND_UP(tpl, 3) : \
383 ((tpl) > 1024) ? ROUND_UP(tpl, 2) : \
384 (tpl))
385
386 /** Determine whether total payload length value is valid according to USB 2.0 */
387 #define USB_TPL_IS_VALID(tpl) \
388 (((tpl) > 3072) ? false : \
389 ((tpl) > 2048) ? ((tpl) % 3 == 0) : \
390 ((tpl) > 1024) ? ((tpl) % 2 == 0) : \
391 ((tpl) >= 0))
392
393 #ifdef __cplusplus
394 }
395 #endif
396
397 #endif /* ZEPHYR_INCLUDE_USB_CH9_H_ */
398
