reactos/drivers/usb/miniport/linux/usb_ch9.h

   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 #if 0
  19 #include <asm/types.h>          /* __u8 etc */
  20 #endif
  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  */
  89 struct 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
 120 /* All standard descriptors have these 2 fields at the beginning */
 121 struct usb_descriptor_header {
 122         __u8  bLength;
 123         __u8  bDescriptorType;
 124 } __attribute__ ((packed));
 125
 126
 127 /*-------------------------------------------------------------------------*/
 128
 129 /* USB_DT_DEVICE: Device descriptor */
 130 struct usb_device_descriptor {
 131         __u8  bLength;
 132         __u8  bDescriptorType;
 133
 134         __u16 bcdUSB;
 135         __u8  bDeviceClass;
 136         __u8  bDeviceSubClass;
 137         __u8  bDeviceProtocol;
 138         __u8  bMaxPacketSize0;
 139         __u16 idVendor;
 140         __u16 idProduct;
 141         __u16 bcdDevice;
 142         __u8  iManufacturer;
 143         __u8  iProduct;
 144         __u8  iSerialNumber;
 145         __u8  bNumConfigurations;
 146 } __attribute__ ((packed));
 147
 148 #define USB_DT_DEVICE_SIZE              18
 149
 150
 151 /*
 152  * Device and/or Interface Class codes
 153  * as found in bDeviceClass or bInterfaceClass
 154  * and defined by www.usb.org documents
 155  */
 156 #define USB_CLASS_PER_INTERFACE         0       /* for DeviceClass */
 157 #define USB_CLASS_AUDIO                 1
 158 #define USB_CLASS_COMM                  2
 159 #define USB_CLASS_HID                   3
 160 #define USB_CLASS_PHYSICAL              5
 161 #define USB_CLASS_STILL_IMAGE           6
 162 #define USB_CLASS_PRINTER               7
 163 #define USB_CLASS_MASS_STORAGE          8
 164 #define USB_CLASS_HUB                   9
 165 #define USB_CLASS_CDC_DATA              0x0a
 166 #define USB_CLASS_CSCID                 0x0b    /* chip+ smart card */
 167 #define USB_CLASS_CONTENT_SEC           0x0d    /* content security */
 168 #define USB_CLASS_APP_SPEC              0xfe
 169 #define USB_CLASS_VENDOR_SPEC           0xff
 170
 171 /*-------------------------------------------------------------------------*/
 172
 173 /* USB_DT_CONFIG: Configuration descriptor information.
 174  *
 175  * USB_DT_OTHER_SPEED_CONFIG is the same descriptor, except that the
 176  * descriptor type is different.  Highspeed-capable devices can look
 177  * different depending on what speed they're currently running.  Only
 178  * devices with a USB_DT_DEVICE_QUALIFIER have any OTHER_SPEED_CONFIG
 179  * descriptors.
 180  */
 181 struct usb_config_descriptor {
 182         __u8  bLength;
 183         __u8  bDescriptorType;
 184
 185         __u16 wTotalLength;
 186         __u8  bNumInterfaces;
 187         __u8  bConfigurationValue;
 188         __u8  iConfiguration;
 189         __u8  bmAttributes;
 190         __u8  bMaxPower;
 191 } __attribute__ ((packed));
 192
 193 #define USB_DT_CONFIG_SIZE              9
 194
 195 /* from config descriptor bmAttributes */
 196 #define USB_CONFIG_ATT_ONE              (1 << 7)        /* must be set */
 197 #define USB_CONFIG_ATT_SELFPOWER        (1 << 6)        /* self powered */
 198 #define USB_CONFIG_ATT_WAKEUP           (1 << 5)        /* can wakeup */
 199
 200 /*-------------------------------------------------------------------------*/
 201
 202 /* USB_DT_STRING: String descriptor */
 203 struct usb_string_descriptor {
 204         __u8  bLength;
 205         __u8  bDescriptorType;
 206
 207         __u16 wData[1];         /* UTF-16LE encoded */
 208 } __attribute__ ((packed));
 209
 210 /* note that "string" zero is special, it holds language codes that
 211  * the device supports, not Unicode characters.
 212  */
 213
 214 /*-------------------------------------------------------------------------*/
 215
 216 /* USB_DT_INTERFACE: Interface descriptor */
 217 struct usb_interface_descriptor {
 218         __u8  bLength;
 219         __u8  bDescriptorType;
 220
 221         __u8  bInterfaceNumber;
 222         __u8  bAlternateSetting;
 223         __u8  bNumEndpoints;
 224         __u8  bInterfaceClass;
 225         __u8  bInterfaceSubClass;
 226         __u8  bInterfaceProtocol;
 227         __u8  iInterface;
 228 } __attribute__ ((packed));
 229
 230 #define USB_DT_INTERFACE_SIZE           9
 231
 232 /*-------------------------------------------------------------------------*/
 233
 234 /* USB_DT_ENDPOINT: Endpoint descriptor */
 235 struct usb_endpoint_descriptor {
 236         __u8  bLength;
 237         __u8  bDescriptorType;
 238
 239         __u8  bEndpointAddress;
 240         __u8  bmAttributes;
 241         __u16 wMaxPacketSize;
 242         __u8  bInterval;
 243
 244         // NOTE:  these two are _only_ in audio endpoints.
 245         // use USB_DT_ENDPOINT*_SIZE in bLength, not sizeof.
 246         __u8  bRefresh;
 247         __u8  bSynchAddress;
 248 } __attribute__ ((packed));
 249
 250 #define USB_DT_ENDPOINT_SIZE            7
 251 #define USB_DT_ENDPOINT_AUDIO_SIZE      9       /* Audio extension */
 252
 253
 254 /*
 255  * Endpoints
 256  */
 257 #define USB_ENDPOINT_NUMBER_MASK        0x0f    /* in bEndpointAddress */
 258 #define USB_ENDPOINT_DIR_MASK           0x80
 259
 260 #define USB_ENDPOINT_XFERTYPE_MASK      0x03    /* in bmAttributes */
 261 #define USB_ENDPOINT_XFER_CONTROL       0
 262 #define USB_ENDPOINT_XFER_ISOC          1
 263 #define USB_ENDPOINT_XFER_BULK          2
 264 #define USB_ENDPOINT_XFER_INT           3
 265
 266
 267 /*-------------------------------------------------------------------------*/
 268
 269 /* USB_DT_DEVICE_QUALIFIER: Device Qualifier descriptor */
 270 struct usb_qualifier_descriptor {
 271         __u8  bLength;
 272         __u8  bDescriptorType;
 273
 274         __u16 bcdUSB;
 275         __u8  bDeviceClass;
 276         __u8  bDeviceSubClass;
 277         __u8  bDeviceProtocol;
 278         __u8  bMaxPacketSize0;
 279         __u8  bNumConfigurations;
 280         __u8  bRESERVED;
 281 } __attribute__ ((packed));
 282
 283
 284 /*-------------------------------------------------------------------------*/
 285
 286 /* USB 2.0 defines three speeds, here's how Linux identifies them */
 287
 288 enum usb_device_speed {
 289         USB_SPEED_UNKNOWN = 0,                  /* enumerating */
 290         USB_SPEED_LOW, USB_SPEED_FULL,          /* usb 1.1 */
 291         USB_SPEED_HIGH                          /* usb 2.0 */
 292 };
 293
 294 enum usb_device_state {
 295         /* NOTATTACHED isn't in the USB spec, and this state acts
 296          * the same as ATTACHED ... but it's clearer this way.
 297          */
 298         USB_STATE_NOTATTACHED = 0,
 299
 300         /* the chapter 9 device states */
 301         USB_STATE_ATTACHED,
 302         USB_STATE_POWERED,
 303         USB_STATE_DEFAULT,                      /* limited function */
 304         USB_STATE_ADDRESS,
 305         USB_STATE_CONFIGURED,                   /* most functions */
 306
 307         USB_STATE_SUSPENDED
 308
 309         /* NOTE:  there are actually four different SUSPENDED
 310          * states, returning to POWERED, DEFAULT, ADDRESS, or
 311          * CONFIGURED respectively when SOF tokens flow again.
 312          */
 313 };
 314
 315 #endif  /* __LINUX_USB_CH9_H */