| blob | 46066f24cfb307402d7cb2b9cb9db70133e075ce |
1 /*
2 * This file holds USB constants and structures that are needed for USB
3 * device APIs. These are used by the USB device model, which is defined
4 * in chapter 9 of the USB 2.0 specification. Linux has several APIs in C
5 * that need these:
6 *
7 * - the master/host side Linux-USB kernel driver API;
8 * - the "usbfs" user space API; and
9 * - the Linux "gadget" slave/device/peripheral side driver API.
10 *
11 * USB 2.0 adds an additional "On The Go" (OTG) mode, which lets systems
12 * act either as a USB master/host or as a USB slave/device. That means
13 * the master and slave side APIs benefit from working well together.
14 *
15 * There's also "Wireless USB", using low power short range radios for
16 * peripheral interconnection but otherwise building on the USB framework.
17 */
19 #ifndef __LINUX_USB_CH9_H
20 #define __LINUX_USB_CH9_H
22 #include <sys/types.h>
24 /*-------------------------------------------------------------------------*/
26 /* CONTROL REQUEST SUPPORT */
28 /*
29 * USB directions
30 *
31 * This bit flag is used in endpoint descriptors' bEndpointAddress field.
32 * It's also one of three fields in control requests bRequestType.
33 */
34 #define USB_DIR_OUT 0 /* to device */
35 #define USB_DIR_IN 0x80 /* to host */
37 /*
38 * USB types, the second of three bRequestType fields
39 */
40 #define USB_TYPE_MASK (0x03 << 5)
41 #define USB_TYPE_STANDARD (0x00 << 5)
42 #define USB_TYPE_CLASS (0x01 << 5)
43 #define USB_TYPE_VENDOR (0x02 << 5)
44 #define USB_TYPE_RESERVED (0x03 << 5)
46 /*
47 * USB recipients, the third of three bRequestType fields
48 */
49 #define USB_RECIP_MASK 0x1f
50 #define USB_RECIP_DEVICE 0x00
51 #define USB_RECIP_INTERFACE 0x01
52 #define USB_RECIP_ENDPOINT 0x02
53 #define USB_RECIP_OTHER 0x03
55 /*
56 * Standard requests, for the bRequest field of a SETUP packet.
57 *
58 * These are qualified by the bRequestType field, so that for example
59 * TYPE_CLASS or TYPE_VENDOR specific feature flags could be retrieved
60 * by a GET_STATUS request.
61 */
62 #define USB_REQ_GET_STATUS 0x00
63 #define USB_REQ_CLEAR_FEATURE 0x01
64 #define USB_REQ_SET_FEATURE 0x03
65 #define USB_REQ_SET_ADDRESS 0x05
66 #define USB_REQ_GET_DESCRIPTOR 0x06
67 #define USB_REQ_SET_DESCRIPTOR 0x07
68 #define USB_REQ_GET_CONFIGURATION 0x08
69 #define USB_REQ_SET_CONFIGURATION 0x09
70 #define USB_REQ_GET_INTERFACE 0x0A
71 #define USB_REQ_SET_INTERFACE 0x0B
72 #define USB_REQ_SYNCH_FRAME 0x0C
74 #define USB_REQ_SET_ENCRYPTION 0x0D /* Wireless USB */
75 #define USB_REQ_GET_ENCRYPTION 0x0E
76 #define USB_REQ_SET_HANDSHAKE 0x0F
77 #define USB_REQ_GET_HANDSHAKE 0x10
78 #define USB_REQ_SET_CONNECTION 0x11
79 #define USB_REQ_SET_SECURITY_DATA 0x12
80 #define USB_REQ_GET_SECURITY_DATA 0x13
81 #define USB_REQ_SET_WUSB_DATA 0x14
82 #define USB_REQ_LOOPBACK_DATA_WRITE 0x15
83 #define USB_REQ_LOOPBACK_DATA_READ 0x16
84 #define USB_REQ_SET_INTERFACE_DS 0x17
86 /*
87 * USB feature flags are written using USB_REQ_{CLEAR,SET}_FEATURE, and
88 * are read as a bit array returned by USB_REQ_GET_STATUS. (So there
89 * are at most sixteen features of each type.)
90 */
91 #define USB_DEVICE_SELF_POWERED 0 /* (read only) */
92 #define USB_DEVICE_REMOTE_WAKEUP 1 /* dev may initiate wakeup */
93 #define USB_DEVICE_TEST_MODE 2 /* (wired high speed only) */
94 #define USB_DEVICE_BATTERY 2 /* (wireless) */
95 #define USB_DEVICE_B_HNP_ENABLE 3 /* (otg) dev may initiate HNP */
96 #define USB_DEVICE_WUSB_DEVICE 3 /* (wireless)*/
97 #define USB_DEVICE_A_HNP_SUPPORT 4 /* (otg) RH port supports HNP */
98 #define USB_DEVICE_A_ALT_HNP_SUPPORT 5 /* (otg) other RH port does */
99 #define USB_DEVICE_DEBUG_MODE 6 /* (special devices only) */
101 #define USB_ENDPOINT_HALT 0 /* IN/OUT will STALL */
104 /**
105 * struct usb_ctrlrequest - SETUP data for a USB device control request
106 * @bRequestType: matches the USB bmRequestType field
107 * @bRequest: matches the USB bRequest field
108 * @wValue: matches the USB wValue field (le16 byte order)
109 * @wIndex: matches the USB wIndex field (le16 byte order)
110 * @wLength: matches the USB wLength field (le16 byte order)
111 *
112 * This structure is used to send control requests to a USB device. It matches
113 * the different fields of the USB 2.0 Spec section 9.3, table 9-2. See the
114 * USB spec for a fuller description of the different fields, and what they are
115 * used for.
116 *
117 * Note that the driver for any interface can issue control requests.
118 * For most devices, interfaces don't coordinate with each other, so
119 * such requests may be made at any time.
120 */
121 struct usb_ctrlrequest {
122 u_int8_t bRequestType;
123 u_int8_t bRequest;
124 u_int16_t wValue;
125 u_int16_t wIndex;
126 u_int16_t wLength;
127 } __attribute__ ((packed));
129 /*-------------------------------------------------------------------------*/
131 /*
132 * STANDARD DESCRIPTORS ... as returned by GET_DESCRIPTOR, or
133 * (rarely) accepted by SET_DESCRIPTOR.
134 *
135 * Note that all multi-byte values here are encoded in little endian
136 * byte order "on the wire". But when exposed through Linux-USB APIs,
137 * they've been converted to cpu byte order.
138 */
140 /*
141 * Descriptor types ... USB 2.0 spec table 9.5
142 */
143 #define USB_DT_DEVICE 0x01
144 #define USB_DT_CONFIG 0x02
145 #define USB_DT_STRING 0x03
146 #define USB_DT_INTERFACE 0x04
147 #define USB_DT_ENDPOINT 0x05
148 #define USB_DT_DEVICE_QUALIFIER 0x06
149 #define USB_DT_OTHER_SPEED_CONFIG 0x07
150 #define USB_DT_INTERFACE_POWER 0x08
151 /* these are from a minor usb 2.0 revision (ECN) */
152 #define USB_DT_OTG 0x09
153 #define USB_DT_DEBUG 0x0a
154 #define USB_DT_INTERFACE_ASSOCIATION 0x0b
155 /* these are from the Wireless USB spec */
156 #define USB_DT_SECURITY 0x0c
157 #define USB_DT_KEY 0x0d
158 #define USB_DT_ENCRYPTION_TYPE 0x0e
159 #define USB_DT_BOS 0x0f
160 #define USB_DT_DEVICE_CAPABILITY 0x10
161 #define USB_DT_WIRELESS_ENDPOINT_COMP 0x11
163 /* conventional codes for class-specific descriptors */
164 #define USB_DT_CS_DEVICE 0x21
165 #define USB_DT_CS_CONFIG 0x22
166 #define USB_DT_CS_STRING 0x23
167 #define USB_DT_CS_INTERFACE 0x24
168 #define USB_DT_CS_ENDPOINT 0x25
170 /* All standard descriptors have these 2 fields at the beginning */
171 struct usb_descriptor_header {
172 u_int8_t bLength;
173 u_int8_t bDescriptorType;
174 } __attribute__ ((packed));
177 /*-------------------------------------------------------------------------*/
179 /* USB_DT_DEVICE: Device descriptor */
180 struct usb_device_descriptor {
181 u_int8_t bLength;
182 u_int8_t bDescriptorType;
184 u_int16_t bcdUSB;
185 u_int8_t bDeviceClass;
186 u_int8_t bDeviceSubClass;
187 u_int8_t bDeviceProtocol;
188 u_int8_t bMaxPacketSize0;
189 u_int16_t idVendor;
190 u_int16_t idProduct;
191 u_int16_t bcdDevice;
192 u_int8_t iManufacturer;
193 u_int8_t iProduct;
194 u_int8_t iSerialNumber;
195 u_int8_t bNumConfigurations;
196 } __attribute__ ((packed));
198 #define USB_DT_DEVICE_SIZE 18
201 /*
202 * Device and/or Interface Class codes
203 * as found in bDeviceClass or bInterfaceClass
204 * and defined by www.usb.org documents
205 */
206 #define USB_CLASS_PER_INTERFACE 0 /* for DeviceClass */
207 #define USB_CLASS_AUDIO 1
208 #define USB_CLASS_COMM 2
209 #define USB_CLASS_HID 3
210 #define USB_CLASS_PHYSICAL 5
211 #define USB_CLASS_STILL_IMAGE 6
212 #define USB_CLASS_PRINTER 7
213 #define USB_CLASS_MASS_STORAGE 8
214 #define USB_CLASS_HUB 9
215 #define USB_CLASS_CDC_DATA 0x0a
216 #define USB_CLASS_CSCID 0x0b /* chip+ smart card */
217 #define USB_CLASS_CONTENT_SEC 0x0d /* content security */
218 #define USB_CLASS_VIDEO 0x0e
219 #define USB_CLASS_WIRELESS_CONTROLLER 0xe0
220 #define USB_CLASS_APP_SPEC 0xfe
221 #define USB_CLASS_VENDOR_SPEC 0xff
223 /*-------------------------------------------------------------------------*/
225 /* USB_DT_CONFIG: Configuration descriptor information.
226 *
227 * USB_DT_OTHER_SPEED_CONFIG is the same descriptor, except that the
228 * descriptor type is different. Highspeed-capable devices can look
229 * different depending on what speed they're currently running. Only
230 * devices with a USB_DT_DEVICE_QUALIFIER have any OTHER_SPEED_CONFIG
231 * descriptors.
232 */
233 struct usb_config_descriptor {
234 u_int8_t bLength;
235 u_int8_t bDescriptorType;
237 u_int16_t wTotalLength;
238 u_int8_t bNumInterfaces;
239 u_int8_t bConfigurationValue;
240 u_int8_t iConfiguration;
241 u_int8_t bmAttributes;
242 u_int8_t bMaxPower;
243 } __attribute__ ((packed));
245 #define USB_DT_CONFIG_SIZE 9
247 /* from config descriptor bmAttributes */
248 #define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */
249 #define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */
250 #define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */
251 #define USB_CONFIG_ATT_BATTERY (1 << 4) /* battery powered */
253 /*-------------------------------------------------------------------------*/
255 /* USB_DT_STRING: String descriptor */
256 struct usb_string_descriptor {
257 u_int8_t bLength;
258 u_int8_t bDescriptorType;
260 u_int16_t wData[0]; /* UTF-16LE encoded */
261 } __attribute__ ((packed));
263 /* note that "string" zero is special, it holds language codes that
264 * the device supports, not Unicode characters.
265 */
267 /*-------------------------------------------------------------------------*/
269 /* USB_DT_INTERFACE: Interface descriptor */
270 struct usb_interface_descriptor {
271 u_int8_t bLength;
272 u_int8_t bDescriptorType;
274 u_int8_t bInterfaceNumber;
275 u_int8_t bAlternateSetting;
276 u_int8_t bNumEndpoints;
277 u_int8_t bInterfaceClass;
278 u_int8_t bInterfaceSubClass;
279 u_int8_t bInterfaceProtocol;
280 u_int8_t iInterface;
281 } __attribute__ ((packed));
283 #define USB_DT_INTERFACE_SIZE 9
285 /*-------------------------------------------------------------------------*/
287 /* USB_DT_ENDPOINT: Endpoint descriptor */
288 struct usb_endpoint_descriptor {
289 u_int8_t bLength;
290 u_int8_t bDescriptorType;
292 u_int8_t bEndpointAddress;
293 u_int8_t bmAttributes;
294 u_int16_t wMaxPacketSize;
295 u_int8_t bInterval;
296 } __attribute__ ((packed));
298 #define USB_DT_ENDPOINT_SIZE 7
299 #define USB_DT_ENDPOINT_AUDIO_SIZE 9 /* Audio extension */
302 /*
303 * Endpoints
304 */
305 #define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */
306 #define USB_ENDPOINT_DIR_MASK 0x80
308 #define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */
309 #define USB_ENDPOINT_XFER_CONTROL 0
310 #define USB_ENDPOINT_XFER_ISOC 1
311 #define USB_ENDPOINT_XFER_BULK 2
312 #define USB_ENDPOINT_XFER_INT 3
313 #define USB_ENDPOINT_MAX_ADJUSTABLE 0x80
316 /*-------------------------------------------------------------------------*/
318 /* USB_DT_DEVICE_QUALIFIER: Device Qualifier descriptor */
319 struct usb_qualifier_descriptor {
320 u_int8_t bLength;
321 u_int8_t bDescriptorType;
323 u_int16_t bcdUSB;
324 u_int8_t bDeviceClass;
325 u_int8_t bDeviceSubClass;
326 u_int8_t bDeviceProtocol;
327 u_int8_t bMaxPacketSize0;
328 u_int8_t bNumConfigurations;
329 u_int8_t bRESERVED;
330 } __attribute__ ((packed));
333 /*-------------------------------------------------------------------------*/
335 /* USB_DT_OTG (from OTG 1.0a supplement) */
336 struct usb_otg_descriptor {
337 u_int8_t bLength;
338 u_int8_t bDescriptorType;
340 u_int8_t bmAttributes; /* support for HNP, SRP, etc */
341 } __attribute__ ((packed));
343 /* from usb_otg_descriptor.bmAttributes */
344 #define USB_OTG_SRP (1 << 0)
345 #define USB_OTG_HNP (1 << 1) /* swap host/device roles */
347 /*-------------------------------------------------------------------------*/
349 /* USB_DT_DEBUG: for special highspeed devices, replacing serial console */
350 struct usb_debug_descriptor {
351 u_int8_t bLength;
352 u_int8_t bDescriptorType;
354 /* bulk endpoints with 8 byte maxpacket */
355 u_int8_t bDebugInEndpoint;
356 u_int8_t bDebugOutEndpoint;
357 };
359 /*-------------------------------------------------------------------------*/
361 /* USB_DT_INTERFACE_ASSOCIATION: groups interfaces */
362 struct usb_interface_assoc_descriptor {
363 u_int8_t bLength;
364 u_int8_t bDescriptorType;
366 u_int8_t bFirstInterface;
367 u_int8_t bInterfaceCount;
368 u_int8_t bFunctionClass;
369 u_int8_t bFunctionSubClass;
370 u_int8_t bFunctionProtocol;
371 u_int8_t iFunction;
372 } __attribute__ ((packed));
375 /*-------------------------------------------------------------------------*/
377 /* USB_DT_SECURITY: group of wireless security descriptors, including
378 * encryption types available for setting up a CC/association.
379 */
380 struct usb_security_descriptor {
381 u_int8_t bLength;
382 u_int8_t bDescriptorType;
384 u_int16_t wTotalLength;
385 u_int8_t bNumEncryptionTypes;
386 };
388 /*-------------------------------------------------------------------------*/
390 /* USB_DT_KEY: used with {GET,SET}_SECURITY_DATA; only public keys
391 * may be retrieved.
392 */
393 struct usb_key_descriptor {
394 u_int8_t bLength;
395 u_int8_t bDescriptorType;
397 u_int8_t tTKID[3];
398 u_int8_t bReserved;
399 u_int8_t bKeyData[0];
400 };
402 /*-------------------------------------------------------------------------*/
404 /* USB_DT_ENCRYPTION_TYPE: bundled in DT_SECURITY groups */
405 struct usb_encryption_descriptor {
406 u_int8_t bLength;
407 u_int8_t bDescriptorType;
409 u_int8_t bEncryptionType;
410 #define USB_ENC_TYPE_UNSECURE 0
411 #define USB_ENC_TYPE_WIRED 1 /* non-wireless mode */
412 #define USB_ENC_TYPE_CCM_1 2 /* aes128/cbc session */
413 #define USB_ENC_TYPE_RSA_1 3 /* rsa3072/sha1 auth */
414 u_int8_t bEncryptionValue; /* use in SET_ENCRYPTION */
415 u_int8_t bAuthKeyIndex;
416 };
419 /*-------------------------------------------------------------------------*/
421 /* USB_DT_BOS: group of wireless capabilities */
422 struct usb_bos_descriptor {
423 u_int8_t bLength;
424 u_int8_t bDescriptorType;
426 u_int16_t wTotalLength;
427 u_int8_t bNumDeviceCaps;
428 };
430 /*-------------------------------------------------------------------------*/
432 /* USB_DT_DEVICE_CAPABILITY: grouped with BOS */
433 struct usb_dev_cap_header {
434 u_int8_t bLength;
435 u_int8_t bDescriptorType;
436 u_int8_t bDevCapabilityType;
437 };
439 #define USB_CAP_TYPE_WIRELESS_USB 1
441 struct usb_wireless_cap_descriptor { /* Ultra Wide Band */
442 u_int8_t bLength;
443 u_int8_t bDescriptorType;
444 u_int8_t bDevCapabilityType;
446 u_int8_t bmAttributes;
447 #define USB_WIRELESS_P2P_DRD (1 << 1)
448 #define USB_WIRELESS_BEACON_MASK (3 << 2)
449 #define USB_WIRELESS_BEACON_SELF (1 << 2)
450 #define USB_WIRELESS_BEACON_DIRECTED (2 << 2)
451 #define USB_WIRELESS_BEACON_NONE (3 << 2)
452 u_int16_t wPHYRates; /* bit rates, Mbps */
453 #define USB_WIRELESS_PHY_53 (1 << 0) /* always set */
454 #define USB_WIRELESS_PHY_80 (1 << 1)
455 #define USB_WIRELESS_PHY_107 (1 << 2) /* always set */
456 #define USB_WIRELESS_PHY_160 (1 << 3)
457 #define USB_WIRELESS_PHY_200 (1 << 4) /* always set */
458 #define USB_WIRELESS_PHY_320 (1 << 5)
459 #define USB_WIRELESS_PHY_400 (1 << 6)
460 #define USB_WIRELESS_PHY_480 (1 << 7)
461 u_int8_t bmTFITXPowerInfo; /* TFI power levels */
462 u_int8_t bmFFITXPowerInfo; /* FFI power levels */
463 u_int16_t bmBandGroup;
464 u_int8_t bReserved;
465 };
467 /*-------------------------------------------------------------------------*/
469 /* USB_DT_WIRELESS_ENDPOINT_COMP: companion descriptor associated with
470 * each endpoint descriptor for a wireless device
471 */
472 struct usb_wireless_ep_comp_descriptor {
473 u_int8_t bLength;
474 u_int8_t bDescriptorType;
476 u_int8_t bMaxBurst;
477 u_int8_t bMaxSequence;
478 u_int16_t wMaxStreamDelay;
479 u_int16_t wOverTheAirPacketSize;
480 u_int8_t bOverTheAirInterval;
481 u_int8_t bmCompAttributes;
482 #define USB_ENDPOINT_SWITCH_MASK 0x03 /* in bmCompAttributes */
483 #define USB_ENDPOINT_SWITCH_NO 0
484 #define USB_ENDPOINT_SWITCH_SWITCH 1
485 #define USB_ENDPOINT_SWITCH_SCALE 2
486 };
488 /*-------------------------------------------------------------------------*/
490 /* USB_REQ_SET_HANDSHAKE is a four-way handshake used between a wireless
491 * host and a device for connection set up, mutual authentication, and
492 * exchanging short lived session keys. The handshake depends on a CC.
493 */
494 struct usb_handshake {
495 u_int8_t bMessageNumber;
496 u_int8_t bStatus;
497 u_int8_t tTKID[3];
498 u_int8_t bReserved;
499 u_int8_t CDID[16];
500 u_int8_t nonce[16];
501 u_int8_t MIC[8];
502 };
504 /*-------------------------------------------------------------------------*/
506 /* USB_REQ_SET_CONNECTION modifies or revokes a connection context (CC).
507 * A CC may also be set up using non-wireless secure channels (including
508 * wired USB!), and some devices may support CCs with multiple hosts.
509 */
510 struct usb_connection_context {
511 u_int8_t CHID[16]; /* persistent host id */
512 u_int8_t CDID[16]; /* device id (unique w/in host context) */
513 u_int8_t CK[16]; /* connection key */
514 };
516 /*-------------------------------------------------------------------------*/
518 /* USB 2.0 defines three speeds, here's how Linux identifies them */
520 enum usb_device_speed {
521 USB_SPEED_UNKNOWN = 0, /* enumerating */
522 USB_SPEED_LOW, USB_SPEED_FULL, /* usb 1.1 */
523 USB_SPEED_HIGH, /* usb 2.0 */
524 USB_SPEED_VARIABLE, /* wireless (usb 2.5) */
525 };
527 enum usb_device_state {
528 /* NOTATTACHED isn't in the USB spec, and this state acts
529 * the same as ATTACHED ... but it's clearer this way.
530 */
531 USB_STATE_NOTATTACHED = 0,
533 /* chapter 9 and authentication (wireless) device states */
534 USB_STATE_ATTACHED,
535 USB_STATE_POWERED, /* wired */
536 USB_STATE_UNAUTHENTICATED, /* auth */
537 USB_STATE_RECONNECTING, /* auth */
538 USB_STATE_DEFAULT, /* limited function */
539 USB_STATE_ADDRESS,
540 USB_STATE_CONFIGURED, /* most functions */
542 USB_STATE_SUSPENDED
544 /* NOTE: there are actually four different SUSPENDED
545 * states, returning to POWERED, DEFAULT, ADDRESS, or
546 * CONFIGURED respectively when SOF tokens flow again.
547 */
548 };
550 #endif /* __LINUX_USB_CH9_H */