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
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.
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.
16 #ifndef __LINUX_USB_CH9_H
17 #define __LINUX_USB_CH9_H
19 #include <asm/types.h> /* __u8 etc */
21 /*-------------------------------------------------------------------------*/
23 /* CONTROL REQUEST SUPPORT */
28 * This bit flag is used in endpoint descriptors' bEndpointAddress field.
29 * It's also one of three fields in control requests bRequestType.
31 #define USB_DIR_OUT 0 /* to device */
32 #define USB_DIR_IN 0x80 /* to host */
35 * USB types, the second of three bRequestType fields
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)
44 * USB recipients, the third of three bRequestType fields
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
53 * Standard requests, for the bRequest field of a SETUP packet.
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.
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
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.)
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 */
83 #define USB_ENDPOINT_HALT 0 /* IN/OUT will STALL */
87 * struct usb_ctrlrequest - SETUP data for a USB device control request
88 * @bRequestType: matches the USB bmRequestType field
89 * @bRequest: matches the USB bRequest field
90 * @wValue: matches the USB wValue field (le16 byte order)
91 * @wIndex: matches the USB wIndex field (le16 byte order)
92 * @wLength: matches the USB wLength field (le16 byte order)
94 * This structure is used to send control requests to a USB device. It matches
95 * the different fields of the USB 2.0 Spec section 9.3, table 9-2. See the
96 * USB spec for a fuller description of the different fields, and what they are
99 * Note that the driver for any interface can issue control requests.
100 * For most devices, interfaces don't coordinate with each other, so
101 * such requests may be made at any time.
103 struct usb_ctrlrequest
{
109 } __attribute__ ((packed
));
111 /*-------------------------------------------------------------------------*/
114 * STANDARD DESCRIPTORS ... as returned by GET_DESCRIPTOR, or
115 * (rarely) accepted by SET_DESCRIPTOR.
117 * Note that all multi-byte values here are encoded in little endian
118 * byte order "on the wire". But when exposed through Linux-USB APIs,
119 * they've been converted to cpu byte order.
123 * Descriptor types ... USB 2.0 spec table 9.5
125 #define USB_DT_DEVICE 0x01
126 #define USB_DT_CONFIG 0x02
127 #define USB_DT_STRING 0x03
128 #define USB_DT_INTERFACE 0x04
129 #define USB_DT_ENDPOINT 0x05
130 #define USB_DT_DEVICE_QUALIFIER 0x06
131 #define USB_DT_OTHER_SPEED_CONFIG 0x07
132 #define USB_DT_INTERFACE_POWER 0x08
133 /* these are from a minor usb 2.0 revision (ECN) */
134 #define USB_DT_OTG 0x09
135 #define USB_DT_DEBUG 0x0a
136 #define USB_DT_INTERFACE_ASSOCIATION 0x0b
138 /* conventional codes for class-specific descriptors */
139 #define USB_DT_CS_DEVICE 0x21
140 #define USB_DT_CS_CONFIG 0x22
141 #define USB_DT_CS_STRING 0x23
142 #define USB_DT_CS_INTERFACE 0x24
143 #define USB_DT_CS_ENDPOINT 0x25
145 /* All standard descriptors have these 2 fields at the beginning */
146 struct usb_descriptor_header
{
148 __u8 bDescriptorType
;
149 } __attribute__ ((packed
));
152 /*-------------------------------------------------------------------------*/
154 /* USB_DT_DEVICE: Device descriptor */
155 struct usb_device_descriptor
{
157 __u8 bDescriptorType
;
161 __u8 bDeviceSubClass
;
162 __u8 bDeviceProtocol
;
163 __u8 bMaxPacketSize0
;
170 __u8 bNumConfigurations
;
171 } __attribute__ ((packed
));
173 #define USB_DT_DEVICE_SIZE 18
177 * Device and/or Interface Class codes
178 * as found in bDeviceClass or bInterfaceClass
179 * and defined by www.usb.org documents
181 #define USB_CLASS_PER_INTERFACE 0 /* for DeviceClass */
182 #define USB_CLASS_AUDIO 1
183 #define USB_CLASS_COMM 2
184 #define USB_CLASS_HID 3
185 #define USB_CLASS_PHYSICAL 5
186 #define USB_CLASS_STILL_IMAGE 6
187 #define USB_CLASS_PRINTER 7
188 #define USB_CLASS_MASS_STORAGE 8
189 #define USB_CLASS_HUB 9
190 #define USB_CLASS_CDC_DATA 0x0a
191 #define USB_CLASS_CSCID 0x0b /* chip+ smart card */
192 #define USB_CLASS_CONTENT_SEC 0x0d /* content security */
193 #define USB_CLASS_VIDEO 0x0e
194 #define USB_CLASS_APP_SPEC 0xfe
195 #define USB_CLASS_VENDOR_SPEC 0xff
197 /*-------------------------------------------------------------------------*/
199 /* USB_DT_CONFIG: Configuration descriptor information.
201 * USB_DT_OTHER_SPEED_CONFIG is the same descriptor, except that the
202 * descriptor type is different. Highspeed-capable devices can look
203 * different depending on what speed they're currently running. Only
204 * devices with a USB_DT_DEVICE_QUALIFIER have any OTHER_SPEED_CONFIG
207 struct usb_config_descriptor
{
209 __u8 bDescriptorType
;
213 __u8 bConfigurationValue
;
217 } __attribute__ ((packed
));
219 #define USB_DT_CONFIG_SIZE 9
221 /* from config descriptor bmAttributes */
222 #define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */
223 #define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */
224 #define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */
226 /*-------------------------------------------------------------------------*/
228 /* USB_DT_STRING: String descriptor */
229 struct usb_string_descriptor
{
231 __u8 bDescriptorType
;
233 __u16 wData
[1]; /* UTF-16LE encoded */
234 } __attribute__ ((packed
));
236 /* note that "string" zero is special, it holds language codes that
237 * the device supports, not Unicode characters.
240 /*-------------------------------------------------------------------------*/
242 /* USB_DT_INTERFACE: Interface descriptor */
243 struct usb_interface_descriptor
{
245 __u8 bDescriptorType
;
247 __u8 bInterfaceNumber
;
248 __u8 bAlternateSetting
;
250 __u8 bInterfaceClass
;
251 __u8 bInterfaceSubClass
;
252 __u8 bInterfaceProtocol
;
254 } __attribute__ ((packed
));
256 #define USB_DT_INTERFACE_SIZE 9
258 /*-------------------------------------------------------------------------*/
260 /* USB_DT_ENDPOINT: Endpoint descriptor */
261 struct usb_endpoint_descriptor
{
263 __u8 bDescriptorType
;
265 __u8 bEndpointAddress
;
267 __u16 wMaxPacketSize
;
270 // NOTE: these two are _only_ in audio endpoints.
271 // use USB_DT_ENDPOINT*_SIZE in bLength, not sizeof.
274 } __attribute__ ((packed
));
276 #define USB_DT_ENDPOINT_SIZE 7
277 #define USB_DT_ENDPOINT_AUDIO_SIZE 9 /* Audio extension */
283 #define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */
284 #define USB_ENDPOINT_DIR_MASK 0x80
286 #define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */
287 #define USB_ENDPOINT_XFER_CONTROL 0
288 #define USB_ENDPOINT_XFER_ISOC 1
289 #define USB_ENDPOINT_XFER_BULK 2
290 #define USB_ENDPOINT_XFER_INT 3
293 /*-------------------------------------------------------------------------*/
295 /* USB_DT_DEVICE_QUALIFIER: Device Qualifier descriptor */
296 struct usb_qualifier_descriptor
{
298 __u8 bDescriptorType
;
302 __u8 bDeviceSubClass
;
303 __u8 bDeviceProtocol
;
304 __u8 bMaxPacketSize0
;
305 __u8 bNumConfigurations
;
307 } __attribute__ ((packed
));
310 /*-------------------------------------------------------------------------*/
312 /* USB_DT_OTG (from OTG 1.0a supplement) */
313 struct usb_otg_descriptor
{
315 __u8 bDescriptorType
;
317 __u8 bmAttributes
; /* support for HNP, SRP, etc */
318 } __attribute__ ((packed
));
320 /* from usb_otg_descriptor.bmAttributes */
321 #define USB_OTG_SRP (1 << 0)
322 #define USB_OTG_HNP (1 << 1) /* swap host/device roles */
324 /*-------------------------------------------------------------------------*/
326 /* USB_DT_INTERFACE_ASSOCIATION: groups interfaces */
327 struct usb_interface_assoc_descriptor
{
329 __u8 bDescriptorType
;
331 __u8 bFirstInterface
;
332 __u8 bInterfaceCount
;
334 __u8 bFunctionSubClass
;
335 __u8 bFunctionProtocol
;
337 } __attribute__ ((packed
));
340 /*-------------------------------------------------------------------------*/
342 /* USB 2.0 defines three speeds, here's how Linux identifies them */
344 enum usb_device_speed
{
345 USB_SPEED_UNKNOWN
= 0, /* enumerating */
346 USB_SPEED_LOW
, USB_SPEED_FULL
, /* usb 1.1 */
347 USB_SPEED_HIGH
/* usb 2.0 */
350 enum usb_device_state
{
351 /* NOTATTACHED isn't in the USB spec, and this state acts
352 * the same as ATTACHED ... but it's clearer this way.
354 USB_STATE_NOTATTACHED
= 0,
356 /* the chapter 9 device states */
359 USB_STATE_DEFAULT
, /* limited function */
361 USB_STATE_CONFIGURED
, /* most functions */
365 /* NOTE: there are actually four different SUSPENDED
366 * states, returning to POWERED, DEFAULT, ADDRESS, or
367 * CONFIGURED respectively when SOF tokens flow again.
371 #endif /* __LINUX_USB_CH9_H */