Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
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 */
18
19#ifndef __LINUX_USB_CH9_H
20#define __LINUX_USB_CH9_H
21
22#include <linux/types.h> /* __u8 etc */
23
24/*-------------------------------------------------------------------------*/
25
26/* CONTROL REQUEST SUPPORT */
27
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 */
36
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)
45
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
54
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
73
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
85
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) */
100
101#define USB_ENDPOINT_HALT 0 /* IN/OUT will STALL */
102
103
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 */
121struct usb_ctrlrequest {
122 __u8 bRequestType;
123 __u8 bRequest;
124 __le16 wValue;
125 __le16 wIndex;
126 __le16 wLength;
127} __attribute__ ((packed));
128
129/*-------------------------------------------------------------------------*/
130
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 */
139
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
162
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
169
170/* All standard descriptors have these 2 fields at the beginning */
171struct usb_descriptor_header {
172 __u8 bLength;
173 __u8 bDescriptorType;
174} __attribute__ ((packed));
175
176
177/*-------------------------------------------------------------------------*/
178
179/* USB_DT_DEVICE: Device descriptor */
180struct usb_device_descriptor {
181 __u8 bLength;
182 __u8 bDescriptorType;
183
184 __le16 bcdUSB;
185 __u8 bDeviceClass;
186 __u8 bDeviceSubClass;
187 __u8 bDeviceProtocol;
188 __u8 bMaxPacketSize0;
189 __le16 idVendor;
190 __le16 idProduct;
191 __le16 bcdDevice;
192 __u8 iManufacturer;
193 __u8 iProduct;
194 __u8 iSerialNumber;
195 __u8 bNumConfigurations;
196} __attribute__ ((packed));
197
198#define USB_DT_DEVICE_SIZE 18
199
200
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
222
223/*-------------------------------------------------------------------------*/
224
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 */
233struct usb_config_descriptor {
234 __u8 bLength;
235 __u8 bDescriptorType;
236
237 __le16 wTotalLength;
238 __u8 bNumInterfaces;
239 __u8 bConfigurationValue;
240 __u8 iConfiguration;
241 __u8 bmAttributes;
242 __u8 bMaxPower;
243} __attribute__ ((packed));
244
245#define USB_DT_CONFIG_SIZE 9
246
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 */
252
253/*-------------------------------------------------------------------------*/
254
255/* USB_DT_STRING: String descriptor */
256struct usb_string_descriptor {
257 __u8 bLength;
258 __u8 bDescriptorType;
259
260 __le16 wData[1]; /* UTF-16LE encoded */
261} __attribute__ ((packed));
262
263/* note that "string" zero is special, it holds language codes that
264 * the device supports, not Unicode characters.
265 */
266
267/*-------------------------------------------------------------------------*/
268
269/* USB_DT_INTERFACE: Interface descriptor */
270struct usb_interface_descriptor {
271 __u8 bLength;
272 __u8 bDescriptorType;
273
274 __u8 bInterfaceNumber;
275 __u8 bAlternateSetting;
276 __u8 bNumEndpoints;
277 __u8 bInterfaceClass;
278 __u8 bInterfaceSubClass;
279 __u8 bInterfaceProtocol;
280 __u8 iInterface;
281} __attribute__ ((packed));
282
283#define USB_DT_INTERFACE_SIZE 9
284
285/*-------------------------------------------------------------------------*/
286
287/* USB_DT_ENDPOINT: Endpoint descriptor */
288struct usb_endpoint_descriptor {
289 __u8 bLength;
290 __u8 bDescriptorType;
291
292 __u8 bEndpointAddress;
293 __u8 bmAttributes;
294 __le16 wMaxPacketSize;
295 __u8 bInterval;
296
297 /* NOTE: these two are _only_ in audio endpoints. */
298 /* use USB_DT_ENDPOINT*_SIZE in bLength, not sizeof. */
299 __u8 bRefresh;
300 __u8 bSynchAddress;
301} __attribute__ ((packed));
302
303#define USB_DT_ENDPOINT_SIZE 7
304#define USB_DT_ENDPOINT_AUDIO_SIZE 9 /* Audio extension */
305
306
307/*
308 * Endpoints
309 */
310#define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */
311#define USB_ENDPOINT_DIR_MASK 0x80
312
313#define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */
314#define USB_ENDPOINT_XFER_CONTROL 0
315#define USB_ENDPOINT_XFER_ISOC 1
316#define USB_ENDPOINT_XFER_BULK 2
317#define USB_ENDPOINT_XFER_INT 3
318#define USB_ENDPOINT_MAX_ADJUSTABLE 0x80
319
320
321/*-------------------------------------------------------------------------*/
322
323/* USB_DT_DEVICE_QUALIFIER: Device Qualifier descriptor */
324struct usb_qualifier_descriptor {
325 __u8 bLength;
326 __u8 bDescriptorType;
327
328 __le16 bcdUSB;
329 __u8 bDeviceClass;
330 __u8 bDeviceSubClass;
331 __u8 bDeviceProtocol;
332 __u8 bMaxPacketSize0;
333 __u8 bNumConfigurations;
334 __u8 bRESERVED;
335} __attribute__ ((packed));
336
337
338/*-------------------------------------------------------------------------*/
339
340/* USB_DT_OTG (from OTG 1.0a supplement) */
341struct usb_otg_descriptor {
342 __u8 bLength;
343 __u8 bDescriptorType;
344
345 __u8 bmAttributes; /* support for HNP, SRP, etc */
346} __attribute__ ((packed));
347
348/* from usb_otg_descriptor.bmAttributes */
349#define USB_OTG_SRP (1 << 0)
350#define USB_OTG_HNP (1 << 1) /* swap host/device roles */
351
352/*-------------------------------------------------------------------------*/
353
354/* USB_DT_DEBUG: for special highspeed devices, replacing serial console */
355struct usb_debug_descriptor {
356 __u8 bLength;
357 __u8 bDescriptorType;
358
359 /* bulk endpoints with 8 byte maxpacket */
360 __u8 bDebugInEndpoint;
361 __u8 bDebugOutEndpoint;
362};
363
364/*-------------------------------------------------------------------------*/
365
366/* USB_DT_INTERFACE_ASSOCIATION: groups interfaces */
367struct usb_interface_assoc_descriptor {
368 __u8 bLength;
369 __u8 bDescriptorType;
370
371 __u8 bFirstInterface;
372 __u8 bInterfaceCount;
373 __u8 bFunctionClass;
374 __u8 bFunctionSubClass;
375 __u8 bFunctionProtocol;
376 __u8 iFunction;
377} __attribute__ ((packed));
378
379
380/*-------------------------------------------------------------------------*/
381
382/* USB_DT_SECURITY: group of wireless security descriptors, including
383 * encryption types available for setting up a CC/association.
384 */
385struct usb_security_descriptor {
386 __u8 bLength;
387 __u8 bDescriptorType;
388
389 __le16 wTotalLength;
390 __u8 bNumEncryptionTypes;
391};
392
393/*-------------------------------------------------------------------------*/
394
395/* USB_DT_KEY: used with {GET,SET}_SECURITY_DATA; only public keys
396 * may be retrieved.
397 */
398struct usb_key_descriptor {
399 __u8 bLength;
400 __u8 bDescriptorType;
401
402 __u8 tTKID[3];
403 __u8 bReserved;
404 __u8 bKeyData[0];
405};
406
407/*-------------------------------------------------------------------------*/
408
409/* USB_DT_ENCRYPTION_TYPE: bundled in DT_SECURITY groups */
410struct usb_encryption_descriptor {
411 __u8 bLength;
412 __u8 bDescriptorType;
413
414 __u8 bEncryptionType;
415#define USB_ENC_TYPE_UNSECURE 0
416#define USB_ENC_TYPE_WIRED 1 /* non-wireless mode */
417#define USB_ENC_TYPE_CCM_1 2 /* aes128/cbc session */
418#define USB_ENC_TYPE_RSA_1 3 /* rsa3072/sha1 auth */
419 __u8 bEncryptionValue; /* use in SET_ENCRYPTION */
420 __u8 bAuthKeyIndex;
421};
422
423
424/*-------------------------------------------------------------------------*/
425
426/* USB_DT_BOS: group of wireless capabilities */
427struct usb_bos_descriptor {
428 __u8 bLength;
429 __u8 bDescriptorType;
430
431 __le16 wTotalLength;
432 __u8 bNumDeviceCaps;
433};
434
435/*-------------------------------------------------------------------------*/
436
437/* USB_DT_DEVICE_CAPABILITY: grouped with BOS */
438struct usb_dev_cap_header {
439 __u8 bLength;
440 __u8 bDescriptorType;
441 __u8 bDevCapabilityType;
442};
443
444#define USB_CAP_TYPE_WIRELESS_USB 1
445
446struct usb_wireless_cap_descriptor { /* Ultra Wide Band */
447 __u8 bLength;
448 __u8 bDescriptorType;
449 __u8 bDevCapabilityType;
450
451 __u8 bmAttributes;
452#define USB_WIRELESS_P2P_DRD (1 << 1)
453#define USB_WIRELESS_BEACON_MASK (3 << 2)
454#define USB_WIRELESS_BEACON_SELF (1 << 2)
455#define USB_WIRELESS_BEACON_DIRECTED (2 << 2)
456#define USB_WIRELESS_BEACON_NONE (3 << 2)
457 __le16 wPHYRates; /* bit rates, Mbps */
458#define USB_WIRELESS_PHY_53 (1 << 0) /* always set */
459#define USB_WIRELESS_PHY_80 (1 << 1)
460#define USB_WIRELESS_PHY_107 (1 << 2) /* always set */
461#define USB_WIRELESS_PHY_160 (1 << 3)
462#define USB_WIRELESS_PHY_200 (1 << 4) /* always set */
463#define USB_WIRELESS_PHY_320 (1 << 5)
464#define USB_WIRELESS_PHY_400 (1 << 6)
465#define USB_WIRELESS_PHY_480 (1 << 7)
466 __u8 bmTFITXPowerInfo; /* TFI power levels */
467 __u8 bmFFITXPowerInfo; /* FFI power levels */
468 __le16 bmBandGroup;
469 __u8 bReserved;
470};
471
472/*-------------------------------------------------------------------------*/
473
474/* USB_DT_WIRELESS_ENDPOINT_COMP: companion descriptor associated with
475 * each endpoint descriptor for a wireless device
476 */
477struct usb_wireless_ep_comp_descriptor {
478 __u8 bLength;
479 __u8 bDescriptorType;
480
481 __u8 bMaxBurst;
482 __u8 bMaxSequence;
483 __le16 wMaxStreamDelay;
484 __le16 wOverTheAirPacketSize;
485 __u8 bOverTheAirInterval;
486 __u8 bmCompAttributes;
487#define USB_ENDPOINT_SWITCH_MASK 0x03 /* in bmCompAttributes */
488#define USB_ENDPOINT_SWITCH_NO 0
489#define USB_ENDPOINT_SWITCH_SWITCH 1
490#define USB_ENDPOINT_SWITCH_SCALE 2
491};
492
493/*-------------------------------------------------------------------------*/
494
495/* USB_REQ_SET_HANDSHAKE is a four-way handshake used between a wireless
496 * host and a device for connection set up, mutual authentication, and
497 * exchanging short lived session keys. The handshake depends on a CC.
498 */
499struct usb_handshake {
500 __u8 bMessageNumber;
501 __u8 bStatus;
502 __u8 tTKID[3];
503 __u8 bReserved;
504 __u8 CDID[16];
505 __u8 nonce[16];
506 __u8 MIC[8];
507};
508
509/*-------------------------------------------------------------------------*/
510
511/* USB_REQ_SET_CONNECTION modifies or revokes a connection context (CC).
512 * A CC may also be set up using non-wireless secure channels (including
513 * wired USB!), and some devices may support CCs with multiple hosts.
514 */
515struct usb_connection_context {
516 __u8 CHID[16]; /* persistent host id */
517 __u8 CDID[16]; /* device id (unique w/in host context) */
518 __u8 CK[16]; /* connection key */
519};
520
521/*-------------------------------------------------------------------------*/
522
523/* USB 2.0 defines three speeds, here's how Linux identifies them */
524
525enum usb_device_speed {
526 USB_SPEED_UNKNOWN = 0, /* enumerating */
527 USB_SPEED_LOW, USB_SPEED_FULL, /* usb 1.1 */
528 USB_SPEED_HIGH, /* usb 2.0 */
529 USB_SPEED_VARIABLE, /* wireless (usb 2.5) */
530};
531
532enum usb_device_state {
533 /* NOTATTACHED isn't in the USB spec, and this state acts
534 * the same as ATTACHED ... but it's clearer this way.
535 */
536 USB_STATE_NOTATTACHED = 0,
537
538 /* the chapter 9 device states */
539 USB_STATE_ATTACHED,
540 USB_STATE_POWERED,
541 USB_STATE_DEFAULT, /* limited function */
542 USB_STATE_ADDRESS,
543 USB_STATE_CONFIGURED, /* most functions */
544
545 USB_STATE_SUSPENDED
546
547 /* NOTE: there are actually four different SUSPENDED
548 * states, returning to POWERED, DEFAULT, ADDRESS, or
549 * CONFIGURED respectively when SOF tokens flow again.
550 */
551};
552
553#endif /* __LINUX_USB_CH9_H */