blob: f5fe94e09a033fbf5ebba0ac167c9bc2fc22f65a [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001/*
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 * - (eventually) a Linux "gadget" slave/device 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 will benefit from working well together.
14 */
15
16#ifndef __LINUX_USB_CH9_H
17#define __LINUX_USB_CH9_H
18
19#include <asm/types.h> /* __u8 etc */
20
21/*-------------------------------------------------------------------------*/
22
23/* CONTROL REQUEST SUPPORT */
24
25/*
26 * USB directions
27 *
28 * This bit flag is used in endpoint descriptors' bEndpointAddress field.
29 * It's also one of three fields in control requests bRequestType.
30 */
31#define USB_DIR_OUT 0 /* to device */
32#define USB_DIR_IN 0x80 /* to host */
33
34/*
35 * USB types, the second of three bRequestType fields
36 */
37#define USB_TYPE_MASK (0x03 << 5)
38#define USB_TYPE_STANDARD (0x00 << 5)
39#define USB_TYPE_CLASS (0x01 << 5)
40#define USB_TYPE_VENDOR (0x02 << 5)
41#define USB_TYPE_RESERVED (0x03 << 5)
42
43/*
44 * USB recipients, the third of three bRequestType fields
45 */
46#define USB_RECIP_MASK 0x1f
47#define USB_RECIP_DEVICE 0x00
48#define USB_RECIP_INTERFACE 0x01
49#define USB_RECIP_ENDPOINT 0x02
50#define USB_RECIP_OTHER 0x03
51
52/*
53 * Standard requests, for the bRequest field of a SETUP packet.
54 *
55 * These are qualified by the bRequestType field, so that for example
56 * TYPE_CLASS or TYPE_VENDOR specific feature flags could be retrieved
57 * by a GET_STATUS request.
58 */
59#define USB_REQ_GET_STATUS 0x00
60#define USB_REQ_CLEAR_FEATURE 0x01
61#define USB_REQ_SET_FEATURE 0x03
62#define USB_REQ_SET_ADDRESS 0x05
63#define USB_REQ_GET_DESCRIPTOR 0x06
64#define USB_REQ_SET_DESCRIPTOR 0x07
65#define USB_REQ_GET_CONFIGURATION 0x08
66#define USB_REQ_SET_CONFIGURATION 0x09
67#define USB_REQ_GET_INTERFACE 0x0A
68#define USB_REQ_SET_INTERFACE 0x0B
69#define USB_REQ_SYNCH_FRAME 0x0C
70
71/*
72 * USB feature flags are written using USB_REQ_{CLEAR,SET}_FEATURE, and
73 * are read as a bit array returned by USB_REQ_GET_STATUS. (So there
74 * are at most sixteen features of each type.)
75 */
76#define USB_DEVICE_SELF_POWERED 0 /* (read only) */
77#define USB_DEVICE_REMOTE_WAKEUP 1 /* dev may initiate wakeup */
78#define USB_DEVICE_TEST_MODE 2 /* (high speed only) */
79#define USB_DEVICE_B_HNP_ENABLE 3 /* dev may initiate HNP */
80#define USB_DEVICE_A_HNP_SUPPORT 4 /* RH port supports HNP */
81#define USB_DEVICE_A_ALT_HNP_SUPPORT 5 /* other RH port does */
82#define USB_DEVICE_DEBUG_MODE 6 /* (special devices only) */
83
84#define USB_ENDPOINT_HALT 0 /* IN/OUT will STALL */
85
86
87/**
88 * struct usb_ctrlrequest - SETUP data for a USB device control request
89 * @bRequestType: matches the USB bmRequestType field
90 * @bRequest: matches the USB bRequest field
91 * @wValue: matches the USB wValue field (le16 byte order)
92 * @wIndex: matches the USB wIndex field (le16 byte order)
93 * @wLength: matches the USB wLength field (le16 byte order)
94 *
95 * This structure is used to send control requests to a USB device. It matches
96 * the different fields of the USB 2.0 Spec section 9.3, table 9-2. See the
97 * USB spec for a fuller description of the different fields, and what they are
98 * used for.
99 *
100 * Note that the driver for any interface can issue control requests.
101 * For most devices, interfaces don't coordinate with each other, so
102 * such requests may be made at any time.
103 */
104struct usb_ctrlrequest {
105 __u8 bRequestType;
106 __u8 bRequest;
107 __le16 wValue;
108 __le16 wIndex;
109 __le16 wLength;
110} __attribute__ ((packed));
111
112/*-------------------------------------------------------------------------*/
113
114/*
115 * STANDARD DESCRIPTORS ... as returned by GET_DESCRIPTOR, or
116 * (rarely) accepted by SET_DESCRIPTOR.
117 *
118 * Note that all multi-byte values here are encoded in little endian
119 * byte order "on the wire". But when exposed through Linux-USB APIs,
120 * they've been converted to cpu byte order.
121 */
122
123/*
124 * Descriptor types ... USB 2.0 spec table 9.5
125 */
126#define USB_DT_DEVICE 0x01
127#define USB_DT_CONFIG 0x02
128#define USB_DT_STRING 0x03
129#define USB_DT_INTERFACE 0x04
130#define USB_DT_ENDPOINT 0x05
131#define USB_DT_DEVICE_QUALIFIER 0x06
132#define USB_DT_OTHER_SPEED_CONFIG 0x07
133#define USB_DT_INTERFACE_POWER 0x08
134/* these are from a minor usb 2.0 revision (ECN) */
135#define USB_DT_OTG 0x09
136#define USB_DT_DEBUG 0x0a
137#define USB_DT_INTERFACE_ASSOCIATION 0x0b
138
139/* conventional codes for class-specific descriptors */
140#define USB_DT_CS_DEVICE 0x21
141#define USB_DT_CS_CONFIG 0x22
142#define USB_DT_CS_STRING 0x23
143#define USB_DT_CS_INTERFACE 0x24
144#define USB_DT_CS_ENDPOINT 0x25
145
146/* All standard descriptors have these 2 fields at the beginning */
147struct usb_descriptor_header {
148 __u8 bLength;
149 __u8 bDescriptorType;
150} __attribute__ ((packed));
151
152
153/*-------------------------------------------------------------------------*/
154
155/* USB_DT_DEVICE: Device descriptor */
156struct usb_device_descriptor {
157 __u8 bLength;
158 __u8 bDescriptorType;
159
160 __le16 bcdUSB;
161 __u8 bDeviceClass;
162 __u8 bDeviceSubClass;
163 __u8 bDeviceProtocol;
164 __u8 bMaxPacketSize0;
165 __le16 idVendor;
166 __le16 idProduct;
167 __le16 bcdDevice;
168 __u8 iManufacturer;
169 __u8 iProduct;
170 __u8 iSerialNumber;
171 __u8 bNumConfigurations;
172} __attribute__ ((packed));
173
174#define USB_DT_DEVICE_SIZE 18
175
176
177/*
178 * Device and/or Interface Class codes
179 * as found in bDeviceClass or bInterfaceClass
180 * and defined by www.usb.org documents
181 */
182#define USB_CLASS_PER_INTERFACE 0 /* for DeviceClass */
183#define USB_CLASS_AUDIO 1
184#define USB_CLASS_COMM 2
185#define USB_CLASS_HID 3
186#define USB_CLASS_PHYSICAL 5
187#define USB_CLASS_STILL_IMAGE 6
188#define USB_CLASS_PRINTER 7
189#define USB_CLASS_MASS_STORAGE 8
190#define USB_CLASS_HUB 9
191#define USB_CLASS_CDC_DATA 0x0a
192#define USB_CLASS_CSCID 0x0b /* chip+ smart card */
193#define USB_CLASS_CONTENT_SEC 0x0d /* content security */
194#define USB_CLASS_VIDEO 0x0e
195#define USB_CLASS_APP_SPEC 0xfe
196#define USB_CLASS_VENDOR_SPEC 0xff
197
198/*-------------------------------------------------------------------------*/
199
200/* USB_DT_CONFIG: Configuration descriptor information.
201 *
202 * USB_DT_OTHER_SPEED_CONFIG is the same descriptor, except that the
203 * descriptor type is different. Highspeed-capable devices can look
204 * different depending on what speed they're currently running. Only
205 * devices with a USB_DT_DEVICE_QUALIFIER have any OTHER_SPEED_CONFIG
206 * descriptors.
207 */
208struct usb_config_descriptor {
209 __u8 bLength;
210 __u8 bDescriptorType;
211
212 __le16 wTotalLength;
213 __u8 bNumInterfaces;
214 __u8 bConfigurationValue;
215 __u8 iConfiguration;
216 __u8 bmAttributes;
217 __u8 bMaxPower;
218} __attribute__ ((packed));
219
220#define USB_DT_CONFIG_SIZE 9
221
222/* from config descriptor bmAttributes */
223#define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */
224#define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */
225#define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */
226
227/*-------------------------------------------------------------------------*/
228
229/* USB_DT_STRING: String descriptor */
230struct usb_string_descriptor {
231 __u8 bLength;
232 __u8 bDescriptorType;
233
234 __le16 wData[1]; /* UTF-16LE encoded */
235} __attribute__ ((packed));
236
237/* note that "string" zero is special, it holds language codes that
238 * the device supports, not Unicode characters.
239 */
240
241/*-------------------------------------------------------------------------*/
242
243/* USB_DT_INTERFACE: Interface descriptor */
244struct usb_interface_descriptor {
245 __u8 bLength;
246 __u8 bDescriptorType;
247
248 __u8 bInterfaceNumber;
249 __u8 bAlternateSetting;
250 __u8 bNumEndpoints;
251 __u8 bInterfaceClass;
252 __u8 bInterfaceSubClass;
253 __u8 bInterfaceProtocol;
254 __u8 iInterface;
255} __attribute__ ((packed));
256
257#define USB_DT_INTERFACE_SIZE 9
258
259/*-------------------------------------------------------------------------*/
260
261/* USB_DT_ENDPOINT: Endpoint descriptor */
262struct usb_endpoint_descriptor {
263 __u8 bLength;
264 __u8 bDescriptorType;
265
266 __u8 bEndpointAddress;
267 __u8 bmAttributes;
268 __le16 wMaxPacketSize;
269 __u8 bInterval;
270
271 // NOTE: these two are _only_ in audio endpoints.
272 // use USB_DT_ENDPOINT*_SIZE in bLength, not sizeof.
273 __u8 bRefresh;
274 __u8 bSynchAddress;
275} __attribute__ ((packed));
276
277#define USB_DT_ENDPOINT_SIZE 7
278#define USB_DT_ENDPOINT_AUDIO_SIZE 9 /* Audio extension */
279
280
281/*
282 * Endpoints
283 */
284#define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */
285#define USB_ENDPOINT_DIR_MASK 0x80
286
287#define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */
288#define USB_ENDPOINT_XFER_CONTROL 0
289#define USB_ENDPOINT_XFER_ISOC 1
290#define USB_ENDPOINT_XFER_BULK 2
291#define USB_ENDPOINT_XFER_INT 3
292
293
294/*-------------------------------------------------------------------------*/
295
296/* USB_DT_DEVICE_QUALIFIER: Device Qualifier descriptor */
297struct usb_qualifier_descriptor {
298 __u8 bLength;
299 __u8 bDescriptorType;
300
301 __le16 bcdUSB;
302 __u8 bDeviceClass;
303 __u8 bDeviceSubClass;
304 __u8 bDeviceProtocol;
305 __u8 bMaxPacketSize0;
306 __u8 bNumConfigurations;
307 __u8 bRESERVED;
308} __attribute__ ((packed));
309
310
311/*-------------------------------------------------------------------------*/
312
313/* USB_DT_OTG (from OTG 1.0a supplement) */
314struct usb_otg_descriptor {
315 __u8 bLength;
316 __u8 bDescriptorType;
317
318 __u8 bmAttributes; /* support for HNP, SRP, etc */
319} __attribute__ ((packed));
320
321/* from usb_otg_descriptor.bmAttributes */
322#define USB_OTG_SRP (1 << 0)
323#define USB_OTG_HNP (1 << 1) /* swap host/device roles */
324
325/*-------------------------------------------------------------------------*/
326
327/* USB_DT_DEBUG: for special highspeed devices, replacing serial console */
328struct usb_debug_descriptor {
329 __u8 bLength;
330 __u8 bDescriptorType;
331
332 /* bulk endpoints with 8 byte maxpacket */
333 __u8 bDebugInEndpoint;
334 __u8 bDebugOutEndpoint;
335};
336
337/*-------------------------------------------------------------------------*/
338
339/* USB_DT_INTERFACE_ASSOCIATION: groups interfaces */
340struct usb_interface_assoc_descriptor {
341 __u8 bLength;
342 __u8 bDescriptorType;
343
344 __u8 bFirstInterface;
345 __u8 bInterfaceCount;
346 __u8 bFunctionClass;
347 __u8 bFunctionSubClass;
348 __u8 bFunctionProtocol;
349 __u8 iFunction;
350} __attribute__ ((packed));
351
352
353/*-------------------------------------------------------------------------*/
354
355/* USB 2.0 defines three speeds, here's how Linux identifies them */
356
357enum usb_device_speed {
358 USB_SPEED_UNKNOWN = 0, /* enumerating */
359 USB_SPEED_LOW, USB_SPEED_FULL, /* usb 1.1 */
360 USB_SPEED_HIGH /* usb 2.0 */
361};
362
363enum usb_device_state {
364 /* NOTATTACHED isn't in the USB spec, and this state acts
365 * the same as ATTACHED ... but it's clearer this way.
366 */
367 USB_STATE_NOTATTACHED = 0,
368
369 /* the chapter 9 device states */
370 USB_STATE_ATTACHED,
371 USB_STATE_POWERED,
372 USB_STATE_DEFAULT, /* limited function */
373 USB_STATE_ADDRESS,
374 USB_STATE_CONFIGURED, /* most functions */
375
376 USB_STATE_SUSPENDED
377
378 /* NOTE: there are actually four different SUSPENDED
379 * states, returning to POWERED, DEFAULT, ADDRESS, or
380 * CONFIGURED respectively when SOF tokens flow again.
381 */
382};
383
384#endif /* __LINUX_USB_CH9_H */