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