firmware/export/usb_ch9.h

   1 /***************************************************************************
   2  *             __________               __   ___.
   3  *   Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
   4  *   Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
   5  *   Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
   6  *   Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
   7  *                     \/            \/     \/    \/            \/
   8  * $Id$
   9  *
  10  * Copyright (C) by Linux Kernel Developers
  11  *
  12  * Based on code from the Linux Kernel
  13  * available at http://www.kernel.org
  14  * Original file: <kernel>/include/linux/usb/ch9.h
  15  *
  16  * This program is free software; you can redistribute it and/or
  17  * modify it under the terms of the GNU General Public License
  18  * as published by the Free Software Foundation; either version 2
  19  * of the License, or (at your option) any later version.
  20  *
  21  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  22  * KIND, either express or implied.
  23  *
  24  ****************************************************************************/
  25
  26 /*
  27  * This file holds USB constants and structures that are needed for
  28  * USB device APIs.  These are used by the USB device model, which is
  29  * defined in chapter 9 of the USB 2.0 specification and in the
  30  * Wireless USB 1.0 (spread around).  Linux has several APIs in C that
  31  * need these:
  32  *
  33  * - the master/host side Linux-USB kernel driver API;
  34  * - the "usbfs" user space API; and
  35  * - the Linux "gadget" slave/device/peripheral side driver API.
  36  *
  37  * USB 2.0 adds an additional "On The Go" (OTG) mode, which lets systems
  38  * act either as a USB master/host or as a USB slave/device.  That means
  39  * the master and slave side APIs benefit from working well together.
  40  *
  41  * There's also "Wireless USB", using low power short range radios for
  42  * peripheral interconnection but otherwise building on the USB framework.
  43  *
  44  * Note all descriptors are declared '__attribute__((packed))' so that:
  45  *
  46  * [a] they never get padded, either internally (USB spec writers
  47  *     probably handled that) or externally;
  48  *
  49  * [b] so that accessing bigger-than-a-bytes fields will never
  50  *     generate bus errors on any platform, even when the location of
  51  *     its descriptor inside a bundle isn't "naturally aligned", and
  52  *
  53  * [c] for consistency, removing all doubt even when it appears to
  54  *     someone that the two other points are non-issues for that
  55  *     particular descriptor type.
  56  */
  57
  58 #ifndef _CH9_H_
  59 #define _CH9_H_
  60
  61 #include <inttypes.h>
  62
  63 /*-------------------------------------------------------------------------*/
  64
  65 /* CONTROL REQUEST SUPPORT */
  66
  67 /*
  68  * USB directions
  69  *
  70  * This bit flag is used in endpoint descriptors' bEndpointAddress field.
  71  * It's also one of three fields in control requests bRequestType.
  72  */
  73 #define USB_DIR_OUT                     0               /* to device */
  74 #define USB_DIR_IN                      0x80            /* to host */
  75
  76 /*
  77  * USB types, the second of three bRequestType fields
  78  */
  79 #define USB_TYPE_MASK                   (0x03 << 5)
  80 #define USB_TYPE_STANDARD               (0x00 << 5)
  81 #define USB_TYPE_CLASS                  (0x01 << 5)
  82 #define USB_TYPE_VENDOR                 (0x02 << 5)
  83 #define USB_TYPE_RESERVED               (0x03 << 5)
  84
  85 /*
  86  * USB recipients, the third of three bRequestType fields
  87  */
  88 #define USB_RECIP_MASK                  0x1f
  89 #define USB_RECIP_DEVICE                0x00
  90 #define USB_RECIP_INTERFACE             0x01
  91 #define USB_RECIP_ENDPOINT              0x02
  92 #define USB_RECIP_OTHER                 0x03
  93
  94 /*
  95  * Standard requests, for the bRequest field of a SETUP packet.
  96  *
  97  * These are qualified by the bRequestType field, so that for example
  98  * TYPE_CLASS or TYPE_VENDOR specific feature flags could be retrieved
  99  * by a GET_STATUS request.
 100  */
 101 #define USB_REQ_GET_STATUS              0x00
 102 #define USB_REQ_CLEAR_FEATURE           0x01
 103 #define USB_REQ_SET_FEATURE             0x03
 104 #define USB_REQ_SET_ADDRESS             0x05
 105 #define USB_REQ_GET_DESCRIPTOR          0x06
 106 #define USB_REQ_SET_DESCRIPTOR          0x07
 107 #define USB_REQ_GET_CONFIGURATION       0x08
 108 #define USB_REQ_SET_CONFIGURATION       0x09
 109 #define USB_REQ_GET_INTERFACE           0x0A
 110 #define USB_REQ_SET_INTERFACE           0x0B
 111 #define USB_REQ_SYNCH_FRAME             0x0C
 112 /*
 113  * USB feature flags are written using USB_REQ_{CLEAR,SET}_FEATURE, and
 114  * are read as a bit array returned by USB_REQ_GET_STATUS.  (So there
 115  * are at most sixteen features of each type.)  Hubs may also support a
 116  * new USB_REQ_TEST_AND_SET_FEATURE to put ports into L1 suspend.
 117  */
 118 #define USB_DEVICE_SELF_POWERED         0   /* (read only) */
 119 #define USB_DEVICE_REMOTE_WAKEUP        1   /* dev may initiate wakeup */
 120 #define USB_DEVICE_TEST_MODE            2   /* (wired high speed only) */
 121 #define USB_DEVICE_BATTERY              2   /* (wireless) */
 122 #define USB_DEVICE_B_HNP_ENABLE         3   /* (otg) dev may initiate HNP */
 123 #define USB_DEVICE_WUSB_DEVICE          3   /* (wireless)*/
 124 #define USB_DEVICE_A_HNP_SUPPORT        4   /* (otg) RH port supports HNP */
 125 #define USB_DEVICE_A_ALT_HNP_SUPPORT    5   /* (otg) other RH port does */
 126 #define USB_DEVICE_DEBUG_MODE           6   /* (special devices only) */
 127
 128 #define USB_ENDPOINT_HALT       0   /* IN/OUT will STALL */
 129
 130
 131 /**
 132  * struct usb_ctrlrequest - SETUP data for a USB device control request
 133  * @bRequestType: matches the USB bmRequestType field
 134  * @bRequest: matches the USB bRequest field
 135  * @wValue: matches the USB wValue field (le16 byte order)
 136  * @wIndex: matches the USB wIndex field (le16 byte order)
 137  * @wLength: matches the USB wLength field (le16 byte order)
 138  *
 139  * This structure is used to send control requests to a USB device.  It matches
 140  * the different fields of the USB 2.0 Spec section 9.3, table 9-2.  See the
 141  * USB spec for a fuller description of the different fields, and what they are
 142  * used for.
 143  *
 144  * Note that the driver for any interface can issue control requests.
 145  * For most devices, interfaces don't coordinate with each other, so
 146  * such requests may be made at any time.
 147  */
 148 struct usb_ctrlrequest {
 149         uint8_t bRequestType;
 150         uint8_t bRequest;
 151         uint16_t wValue;
 152         uint16_t wIndex;
 153         uint16_t wLength;
 154 } __attribute__ ((packed));
 155
 156 /*-------------------------------------------------------------------------*/
 157
 158 /*
 159  * STANDARD DESCRIPTORS ... as returned by GET_DESCRIPTOR, or
 160  * (rarely) accepted by SET_DESCRIPTOR.
 161  *
 162  * Note that all multi-byte values here are encoded in little endian
 163  * byte order "on the wire".  But when exposed through Linux-USB APIs,
 164  * they've been converted to cpu byte order.
 165  */
 166
 167 /*
 168  * Descriptor types ... USB 2.0 spec table 9.5
 169  */
 170 #define USB_DT_DEVICE                   0x01
 171 #define USB_DT_CONFIG                   0x02
 172 #define USB_DT_STRING                   0x03
 173 #define USB_DT_INTERFACE                0x04
 174 #define USB_DT_ENDPOINT                 0x05
 175 #define USB_DT_DEVICE_QUALIFIER         0x06
 176 #define USB_DT_OTHER_SPEED_CONFIG       0x07
 177 #define USB_DT_INTERFACE_POWER          0x08
 178 /* these are from a minor usb 2.0 revision (ECN) */
 179 #define USB_DT_OTG                      0x09
 180 #define USB_DT_DEBUG                    0x0a
 181 #define USB_DT_INTERFACE_ASSOCIATION    0x0b
 182 /* these are from the Wireless USB spec */
 183 #define USB_DT_SECURITY                 0x0c
 184 #define USB_DT_KEY                      0x0d
 185 #define USB_DT_ENCRYPTION_TYPE          0x0e
 186 #define USB_DT_BOS                      0x0f
 187 #define USB_DT_DEVICE_CAPABILITY        0x10
 188 #define USB_DT_WIRELESS_ENDPOINT_COMP   0x11
 189 #define USB_DT_WIRE_ADAPTER             0x21
 190 #define USB_DT_RPIPE                    0x22
 191 #define USB_DT_CS_RADIO_CONTROL         0x23
 192
 193 /* Conventional codes for class-specific descriptors.  The convention is
 194  * defined in the USB "Common Class" Spec (3.11).  Individual class specs
 195  * are authoritative for their usage, not the "common class" writeup.
 196  */
 197 #define USB_DT_CS_DEVICE                (USB_TYPE_CLASS | USB_DT_DEVICE)
 198 #define USB_DT_CS_CONFIG                (USB_TYPE_CLASS | USB_DT_CONFIG)
 199 #define USB_DT_CS_STRING                (USB_TYPE_CLASS | USB_DT_STRING)
 200 #define USB_DT_CS_INTERFACE             (USB_TYPE_CLASS | USB_DT_INTERFACE)
 201 #define USB_DT_CS_ENDPOINT              (USB_TYPE_CLASS | USB_DT_ENDPOINT)
 202
 203 /* All standard descriptors have these 2 fields at the beginning */
 204 struct usb_descriptor_header {
 205         uint8_t  bLength;
 206         uint8_t  bDescriptorType;
 207 } __attribute__ ((packed));
 208
 209
 210 /*-------------------------------------------------------------------------*/
 211
 212 /* USB_DT_DEVICE: Device descriptor */
 213 struct usb_device_descriptor {
 214         uint8_t  bLength;
 215         uint8_t  bDescriptorType;
 216
 217         uint16_t bcdUSB;
 218         uint8_t  bDeviceClass;
 219         uint8_t  bDeviceSubClass;
 220         uint8_t  bDeviceProtocol;
 221         uint8_t  bMaxPacketSize0;
 222         uint16_t idVendor;
 223         uint16_t idProduct;
 224         uint16_t bcdDevice;
 225         uint8_t  iManufacturer;
 226         uint8_t  iProduct;
 227         uint8_t  iSerialNumber;
 228         uint8_t  bNumConfigurations;
 229 } __attribute__ ((packed));
 230
 231 #define USB_DT_DEVICE_SIZE              18
 232
 233
 234 /*
 235  * Device and/or Interface Class codes
 236  * as found in bDeviceClass or bInterfaceClass
 237  * and defined by www.usb.org documents
 238  */
 239 #define USB_CLASS_PER_INTERFACE         0       /* for DeviceClass */
 240 #define USB_CLASS_AUDIO                 1
 241 #define USB_CLASS_COMM                  2
 242 #define USB_CLASS_HID                   3
 243 #define USB_CLASS_PHYSICAL              5
 244 #define USB_CLASS_STILL_IMAGE           6
 245 #define USB_CLASS_PRINTER               7
 246 #define USB_CLASS_MASS_STORAGE          8
 247 #define USB_CLASS_HUB                   9
 248 #define USB_CLASS_CDC_DATA              0x0a
 249 #define USB_CLASS_CSCID                 0x0b    /* chip+ smart card */
 250 #define USB_CLASS_CONTENT_SEC           0x0d    /* content security */
 251 #define USB_CLASS_VIDEO                 0x0e
 252 #define USB_CLASS_WIRELESS_CONTROLLER   0xe0
 253 #define USB_CLASS_MISC                  0xef
 254 #define USB_CLASS_APP_SPEC              0xfe
 255 #define USB_CLASS_VENDOR_SPEC           0xff
 256
 257 /*-------------------------------------------------------------------------*/
 258
 259 /* USB_DT_CONFIG: Configuration descriptor information.
 260  *
 261  * USB_DT_OTHER_SPEED_CONFIG is the same descriptor, except that the
 262  * descriptor type is different.  Highspeed-capable devices can look
 263  * different depending on what speed they're currently running.  Only
 264  * devices with a USB_DT_DEVICE_QUALIFIER have any OTHER_SPEED_CONFIG
 265  * descriptors.
 266  */
 267 struct usb_config_descriptor {
 268        uint8_t  bLength;
 269        uint8_t  bDescriptorType;
 270
 271        uint16_t wTotalLength;
 272        uint8_t  bNumInterfaces;
 273        uint8_t  bConfigurationValue;
 274        uint8_t  iConfiguration;
 275        uint8_t  bmAttributes;
 276        uint8_t  bMaxPower;
 277 } __attribute__ ((packed));
 278
 279 #define USB_DT_CONFIG_SIZE              9
 280
 281 /* from config descriptor bmAttributes */
 282 #define USB_CONFIG_ATT_ONE              (1 << 7)        /* must be set */
 283 #define USB_CONFIG_ATT_SELFPOWER        (1 << 6)        /* self powered */
 284 #define USB_CONFIG_ATT_WAKEUP           (1 << 5)        /* can wakeup */
 285 #define USB_CONFIG_ATT_BATTERY          (1 << 4)        /* battery powered */
 286
 287 /*-------------------------------------------------------------------------*/
 288
 289 /* USB_DT_STRING: String descriptor */
 290 struct usb_string_descriptor {
 291         uint8_t  bLength;
 292         uint8_t  bDescriptorType;
 293
 294         uint16_t wString[];             /* UTF-16LE encoded */
 295 } __attribute__ ((packed));
 296
 297 /* note that "string" zero is special, it holds language codes that
 298  * the device supports, not Unicode characters.
 299  */
 300
 301 /*-------------------------------------------------------------------------*/
 302
 303 /* USB_DT_INTERFACE: Interface descriptor */
 304 struct usb_interface_descriptor {
 305         uint8_t  bLength;
 306         uint8_t  bDescriptorType;
 307
 308         uint8_t  bInterfaceNumber;
 309         uint8_t  bAlternateSetting;
 310         uint8_t  bNumEndpoints;
 311         uint8_t  bInterfaceClass;
 312         uint8_t  bInterfaceSubClass;
 313         uint8_t  bInterfaceProtocol;
 314         uint8_t  iInterface;
 315 } __attribute__ ((packed));
 316
 317 #define USB_DT_INTERFACE_SIZE           9
 318
 319 /*-------------------------------------------------------------------------*/
 320
 321 /* USB_DT_ENDPOINT: Endpoint descriptor */
 322 struct usb_endpoint_descriptor {
 323         uint8_t  bLength;
 324         uint8_t  bDescriptorType;
 325
 326         uint8_t  bEndpointAddress;
 327         uint8_t  bmAttributes;
 328         uint16_t wMaxPacketSize;
 329         uint8_t  bInterval;
 330 } __attribute__ ((packed));
 331
 332 #define USB_DT_ENDPOINT_SIZE            7
 333 #define USB_DT_ENDPOINT_AUDIO_SIZE      9       /* Audio extension */
 334
 335
 336 /*
 337  * Endpoints
 338  */
 339 #define USB_ENDPOINT_NUMBER_MASK        0x0f    /* in bEndpointAddress */
 340 #define USB_ENDPOINT_DIR_MASK           0x80
 341
 342 #define USB_ENDPOINT_XFERTYPE_MASK      0x03    /* in bmAttributes */
 343 #define USB_ENDPOINT_XFER_CONTROL       0
 344 #define USB_ENDPOINT_XFER_ISOC          1
 345 #define USB_ENDPOINT_XFER_BULK          2
 346 #define USB_ENDPOINT_XFER_INT           3
 347 #define USB_ENDPOINT_MAX_ADJUSTABLE     0x80
 348
 349
 350 /*-------------------------------------------------------------------------*/
 351
 352 /* USB_DT_DEVICE_QUALIFIER: Device Qualifier descriptor */
 353 struct usb_qualifier_descriptor {
 354         uint8_t  bLength;
 355         uint8_t  bDescriptorType;
 356
 357         uint16_t bcdUSB;
 358         uint8_t  bDeviceClass;
 359         uint8_t  bDeviceSubClass;
 360         uint8_t  bDeviceProtocol;
 361         uint8_t  bMaxPacketSize0;
 362         uint8_t  bNumConfigurations;
 363         uint8_t  bRESERVED;
 364 } __attribute__ ((packed));
 365
 366
 367 /*-------------------------------------------------------------------------*/
 368
 369 /* USB_DT_OTG (from OTG 1.0a supplement) */
 370 struct usb_otg_descriptor {
 371         uint8_t  bLength;
 372         uint8_t  bDescriptorType;
 373
 374         uint8_t  bmAttributes;  /* support for HNP, SRP, etc */
 375 } __attribute__ ((packed));
 376
 377 /* from usb_otg_descriptor.bmAttributes */
 378 #define USB_OTG_SRP             (1 << 0)
 379 #define USB_OTG_HNP             (1 << 1)        /* swap host/device roles */
 380
 381 /*-------------------------------------------------------------------------*/
 382
 383 /* USB_DT_DEBUG:  for special highspeed devices, replacing serial console */
 384 struct usb_debug_descriptor {
 385         uint8_t  bLength;
 386         uint8_t  bDescriptorType;
 387
 388         /* bulk endpoints with 8 byte maxpacket */
 389         uint8_t  bDebugInEndpoint;
 390         uint8_t  bDebugOutEndpoint;
 391 } __attribute__((packed));
 392
 393 /*-------------------------------------------------------------------------*/
 394 /* USB 2.0 defines three speeds, here's how Linux identifies them */
 395
 396 enum usb_device_speed {
 397         USB_SPEED_UNKNOWN = 0,                  /* enumerating */
 398         USB_SPEED_LOW, USB_SPEED_FULL,          /* usb 1.1 */
 399         USB_SPEED_HIGH,                         /* usb 2.0 */
 400         USB_SPEED_VARIABLE,                     /* wireless (usb 2.5) */
 401 };
 402
 403 enum usb_device_state {
 404         /* NOTATTACHED isn't in the USB spec, and this state acts
 405          * the same as ATTACHED ... but it's clearer this way.
 406          */
 407         USB_STATE_NOTATTACHED = 0,
 408
 409         /* chapter 9 and authentication (wireless) device states */
 410         USB_STATE_ATTACHED,
 411         USB_STATE_POWERED,                      /* wired */
 412         USB_STATE_UNAUTHENTICATED,              /* auth */
 413         USB_STATE_RECONNECTING,                 /* auth */
 414         USB_STATE_DEFAULT,                      /* limited function */
 415         USB_STATE_ADDRESS,
 416         USB_STATE_CONFIGURED,                   /* most functions */
 417
 418         USB_STATE_SUSPENDED
 419
 420         /* NOTE:  there are actually four different SUSPENDED
 421          * states, returning to POWERED, DEFAULT, ADDRESS, or
 422          * CONFIGURED respectively when SOF tokens flow again.
 423          * At this level there's no difference between L1 and L2
 424          * suspend states.  (L2 being original USB 1.1 suspend.)
 425          */
 426 };
 427
 428 /**
 429  * struct usb_string - wraps a C string and its USB id
 430  * @id:the (nonzero) ID for this string
 431  * @s:the string, in UTF-8 encoding
 432  *
 433  * If you're using usb_gadget_get_string(), use this to wrap a string
 434  * together with its ID.
 435  */
 436 struct usb_string {
 437         uint8_t id;
 438         const char* s;
 439 };
 440
 441 /**
 442  * struct usb_gadget_strings - a set of USB strings in a given language
 443  * @language:identifies the strings' language (0x0409 for en-us)
 444  * @strings:array of strings with their ids
 445  *
 446  * If you're using usb_gadget_get_string(), use this to wrap all the
 447  * strings for a given language.
 448  */
 449 struct usb_gadget_strings {
 450         uint16_t language;                      /* 0x0409 for en-us */
 451         struct usb_string* strings;
 452 };
 453
 454 #endif /*_CH9_H_*/