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/** 73 * struct usb_ctrlrequest - SETUP data for a USB device control request 74 * @bRequestType: matches the USB bmRequestType field 75 * @bRequest: matches the USB bRequest field 76 * @wValue: matches the USB wValue field (le16 byte order) 77 * @wIndex: matches the USB wIndex field (le16 byte order) 78 * @wLength: matches the USB wLength field (le16 byte order) 79 * 80 * This structure is used to send control requests to a USB device. It matches 81 * the different fields of the USB 2.0 Spec section 9.3, table 9-2. See the 82 * USB spec for a fuller description of the different fields, and what they are 83 * used for. 84 * 85 * Note that the driver for any interface can issue control requests. 86 * For most devices, interfaces don't coordinate with each other, so 87 * such requests may be made at any time. 88 */ 89struct usb_ctrlrequest { 90 __u8 bRequestType; 91 __u8 bRequest; 92 __u16 wValue; 93 __u16 wIndex; 94 __u16 wLength; 95} __attribute__ ((packed)); 96 97/*-------------------------------------------------------------------------*/ 98 99/* 100 * STANDARD DESCRIPTORS ... as returned by GET_DESCRIPTOR, or 101 * (rarely) accepted by SET_DESCRIPTOR. 102 * 103 * Note that all multi-byte values here are encoded in little endian 104 * byte order "on the wire". But when exposed through Linux-USB APIs, 105 * they've been converted to cpu byte order. 106 */ 107 108/* 109 * Descriptor types ... USB 2.0 spec table 9.5 110 */ 111#define USB_DT_DEVICE 0x01 112#define USB_DT_CONFIG 0x02 113#define USB_DT_STRING 0x03 114#define USB_DT_INTERFACE 0x04 115#define USB_DT_ENDPOINT 0x05 116#define USB_DT_DEVICE_QUALIFIER 0x06 117#define USB_DT_OTHER_SPEED_CONFIG 0x07 118#define USB_DT_INTERFACE_POWER 0x08 119/* these are from a minor usb 2.0 revision (ECN) */ 120#define USB_DT_OTG 0x09 121#define USB_DT_DEBUG 0x0a 122#define USB_DT_INTERFACE_ASSOCIATION 0x0b 123 124/* conventional codes for class-specific descriptors */ 125#define USB_DT_CS_DEVICE 0x21 126#define USB_DT_CS_CONFIG 0x22 127#define USB_DT_CS_STRING 0x23 128#define USB_DT_CS_INTERFACE 0x24 129#define USB_DT_CS_ENDPOINT 0x25 130 131/* All standard descriptors have these 2 fields at the beginning */ 132struct usb_descriptor_header { 133 __u8 bLength; 134 __u8 bDescriptorType; 135} __attribute__ ((packed)); 136 137 138/*-------------------------------------------------------------------------*/ 139 140/* USB_DT_DEVICE: Device descriptor */ 141struct usb_device_descriptor { 142 __u8 bLength; 143 __u8 bDescriptorType; 144 145 __u16 bcdUSB; 146 __u8 bDeviceClass; 147 __u8 bDeviceSubClass; 148 __u8 bDeviceProtocol; 149 __u8 bMaxPacketSize0; 150 __u16 idVendor; 151 __u16 idProduct; 152 __u16 bcdDevice; 153 __u8 iManufacturer; 154 __u8 iProduct; 155 __u8 iSerialNumber; 156 __u8 bNumConfigurations; 157} __attribute__ ((packed)); 158 159#define USB_DT_DEVICE_SIZE 18 160 161 162/* 163 * Device and/or Interface Class codes 164 * as found in bDeviceClass or bInterfaceClass 165 * and defined by www.usb.org documents 166 */ 167#define USB_CLASS_PER_INTERFACE 0 /* for DeviceClass */ 168#define USB_CLASS_AUDIO 1 169#define USB_CLASS_COMM 2 170#define USB_CLASS_HID 3 171#define USB_CLASS_PHYSICAL 5 172#define USB_CLASS_STILL_IMAGE 6 173#define USB_CLASS_PRINTER 7 174#define USB_CLASS_MASS_STORAGE 8 175#define USB_CLASS_HUB 9 176#define USB_CLASS_CDC_DATA 0x0a 177#define USB_CLASS_CSCID 0x0b /* chip+ smart card */ 178#define USB_CLASS_CONTENT_SEC 0x0d /* content security */ 179#define USB_CLASS_VIDEO 0x0e 180#define USB_CLASS_APP_SPEC 0xfe 181#define USB_CLASS_VENDOR_SPEC 0xff 182 183/*-------------------------------------------------------------------------*/ 184 185/* USB_DT_CONFIG: Configuration descriptor information. 186 * 187 * USB_DT_OTHER_SPEED_CONFIG is the same descriptor, except that the 188 * descriptor type is different. Highspeed-capable devices can look 189 * different depending on what speed they're currently running. Only 190 * devices with a USB_DT_DEVICE_QUALIFIER have any OTHER_SPEED_CONFIG 191 * descriptors. 192 */ 193struct usb_config_descriptor { 194 __u8 bLength; 195 __u8 bDescriptorType; 196 197 __u16 wTotalLength; 198 __u8 bNumInterfaces; 199 __u8 bConfigurationValue; 200 __u8 iConfiguration; 201 __u8 bmAttributes; 202 __u8 bMaxPower; 203} __attribute__ ((packed)); 204 205#define USB_DT_CONFIG_SIZE 9 206 207/* from config descriptor bmAttributes */ 208#define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */ 209#define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */ 210#define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */ 211 212/*-------------------------------------------------------------------------*/ 213 214/* USB_DT_STRING: String descriptor */ 215struct usb_string_descriptor { 216 __u8 bLength; 217 __u8 bDescriptorType; 218 219 __u16 wData[1]; /* UTF-16LE encoded */ 220} __attribute__ ((packed)); 221 222/* note that "string" zero is special, it holds language codes that 223 * the device supports, not Unicode characters. 224 */ 225 226/*-------------------------------------------------------------------------*/ 227 228/* USB_DT_INTERFACE: Interface descriptor */ 229struct usb_interface_descriptor { 230 __u8 bLength; 231 __u8 bDescriptorType; 232 233 __u8 bInterfaceNumber; 234 __u8 bAlternateSetting; 235 __u8 bNumEndpoints; 236 __u8 bInterfaceClass; 237 __u8 bInterfaceSubClass; 238 __u8 bInterfaceProtocol; 239 __u8 iInterface; 240} __attribute__ ((packed)); 241 242#define USB_DT_INTERFACE_SIZE 9 243 244/*-------------------------------------------------------------------------*/ 245 246/* USB_DT_ENDPOINT: Endpoint descriptor */ 247struct usb_endpoint_descriptor { 248 __u8 bLength; 249 __u8 bDescriptorType; 250 251 __u8 bEndpointAddress; 252 __u8 bmAttributes; 253 __u16 wMaxPacketSize; 254 __u8 bInterval; 255 256 // NOTE: these two are _only_ in audio endpoints. 257 // use USB_DT_ENDPOINT*_SIZE in bLength, not sizeof. 258 __u8 bRefresh; 259 __u8 bSynchAddress; 260} __attribute__ ((packed)); 261 262#define USB_DT_ENDPOINT_SIZE 7 263#define USB_DT_ENDPOINT_AUDIO_SIZE 9 /* Audio extension */ 264 265 266/* 267 * Endpoints 268 */ 269#define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */ 270#define USB_ENDPOINT_DIR_MASK 0x80 271 272#define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */ 273#define USB_ENDPOINT_XFER_CONTROL 0 274#define USB_ENDPOINT_XFER_ISOC 1 275#define USB_ENDPOINT_XFER_BULK 2 276#define USB_ENDPOINT_XFER_INT 3 277 278 279/*-------------------------------------------------------------------------*/ 280 281/* USB_DT_DEVICE_QUALIFIER: Device Qualifier descriptor */ 282struct usb_qualifier_descriptor { 283 __u8 bLength; 284 __u8 bDescriptorType; 285 286 __u16 bcdUSB; 287 __u8 bDeviceClass; 288 __u8 bDeviceSubClass; 289 __u8 bDeviceProtocol; 290 __u8 bMaxPacketSize0; 291 __u8 bNumConfigurations; 292 __u8 bRESERVED; 293} __attribute__ ((packed)); 294 295 296/*-------------------------------------------------------------------------*/ 297 298/* USB_DT_OTG (from OTG 1.0a supplement) */ 299struct usb_otg_descriptor { 300 __u8 bLength; 301 __u8 bDescriptorType; 302 303 __u8 bmAttributes; /* support for HNP, SRP, etc */ 304} __attribute__ ((packed)); 305 306/* from usb_otg_descriptor.bmAttributes */ 307#define USB_OTG_SRP (1 << 0) 308#define USB_OTG_HNP (1 << 1) /* swap host/device roles */ 309 310/*-------------------------------------------------------------------------*/ 311 312/* USB_DT_INTERFACE_ASSOCIATION: groups interfaces */ 313struct usb_interface_assoc_descriptor { 314 __u8 bLength; 315 __u8 bDescriptorType; 316 317 __u8 bFirstInterface; 318 __u8 bInterfaceCount; 319 __u8 bFunctionClass; 320 __u8 bFunctionSubClass; 321 __u8 bFunctionProtocol; 322 __u8 iFunction; 323} __attribute__ ((packed)); 324 325 326/*-------------------------------------------------------------------------*/ 327 328/* USB 2.0 defines three speeds, here's how Linux identifies them */ 329 330enum usb_device_speed { 331 USB_SPEED_UNKNOWN = 0, /* enumerating */ 332 USB_SPEED_LOW, USB_SPEED_FULL, /* usb 1.1 */ 333 USB_SPEED_HIGH /* usb 2.0 */ 334}; 335 336enum usb_device_state { 337 /* NOTATTACHED isn't in the USB spec, and this state acts 338 * the same as ATTACHED ... but it's clearer this way. 339 */ 340 USB_STATE_NOTATTACHED = 0, 341 342 /* the chapter 9 device states */ 343 USB_STATE_ATTACHED, 344 USB_STATE_POWERED, 345 USB_STATE_DEFAULT, /* limited function */ 346 USB_STATE_ADDRESS, 347 USB_STATE_CONFIGURED, /* most functions */ 348 349 USB_STATE_SUSPENDED 350 351 /* NOTE: there are actually four different SUSPENDED 352 * states, returning to POWERED, DEFAULT, ADDRESS, or 353 * CONFIGURED respectively when SOF tokens flow again. 354 */ 355}; 356 357#endif /* __LINUX_USB_CH9_H */ 358