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 * - (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 */ 104 struct usb_ctrlrequest { 105 __u8 bRequestType; 106 __u8 bRequest; 107 __u16 wValue; 108 __u16 wIndex; 109 __u16 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 */ 147 struct usb_descriptor_header { 148 __u8 bLength; 149 __u8 bDescriptorType; 150 } __attribute__ ((packed)); 151 152 153 /*-------------------------------------------------------------------------*/ 154 155 /* USB_DT_DEVICE: Device descriptor */ 156 struct usb_device_descriptor { 157 __u8 bLength; 158 __u8 bDescriptorType; 159 160 __u16 bcdUSB; 161 __u8 bDeviceClass; 162 __u8 bDeviceSubClass; 163 __u8 bDeviceProtocol; 164 __u8 bMaxPacketSize0; 165 __u16 idVendor; 166 __u16 idProduct; 167 __u16 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 */ 208 struct usb_config_descriptor { 209 __u8 bLength; 210 __u8 bDescriptorType; 211 212 __u16 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 */ 230 struct usb_string_descriptor { 231 __u8 bLength; 232 __u8 bDescriptorType; 233 234 __u16 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 */ 244 struct 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 */ 262 struct usb_endpoint_descriptor { 263 __u8 bLength; 264 __u8 bDescriptorType; 265 266 __u8 bEndpointAddress; 267 __u8 bmAttributes; 268 __u16 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 */ 297 struct usb_qualifier_descriptor { 298 __u8 bLength; 299 __u8 bDescriptorType; 300 301 __u16 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) */ 314 struct 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 */ 328 struct 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 */ 340 struct 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 357 enum 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 363 enum 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 */ 385