MdePkg/Include/IndustryStandard/Usb.h

   1 /** @file
   2   Support for USB 2.0 standard.
   3
   4   Copyright (c) 2006 - 2008, Intel Corporation
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __USB_H__
  16 #define __USB_H__
  17
  18 //
  19 // Standard device request and request type
  20 // USB 2.0 spec, Section 9.4
  21 //
  22 #define USB_DEV_GET_STATUS                  0x00
  23 #define USB_DEV_GET_STATUS_REQ_TYPE_D       0x80 // Receiver : Device
  24 #define USB_DEV_GET_STATUS_REQ_TYPE_I       0x81 // Receiver : Interface
  25 #define USB_DEV_GET_STATUS_REQ_TYPE_E       0x82 // Receiver : Endpoint
  26
  27 #define USB_DEV_CLEAR_FEATURE               0x01
  28 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_D    0x00 // Receiver : Device
  29 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_I    0x01 // Receiver : Interface
  30 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_E    0x02 // Receiver : Endpoint
  31
  32 #define USB_DEV_SET_FEATURE                 0x03
  33 #define USB_DEV_SET_FEATURE_REQ_TYPE_D      0x00 // Receiver : Device
  34 #define USB_DEV_SET_FEATURE_REQ_TYPE_I      0x01 // Receiver : Interface
  35 #define USB_DEV_SET_FEATURE_REQ_TYPE_E      0x02 // Receiver : Endpoint
  36
  37 #define USB_DEV_SET_ADDRESS                 0x05
  38 #define USB_DEV_SET_ADDRESS_REQ_TYPE        0x00
  39
  40 #define USB_DEV_GET_DESCRIPTOR              0x06
  41 #define USB_DEV_GET_DESCRIPTOR_REQ_TYPE     0x80
  42
  43 #define USB_DEV_SET_DESCRIPTOR              0x07
  44 #define USB_DEV_SET_DESCRIPTOR_REQ_TYPE     0x00
  45
  46 #define USB_DEV_GET_CONFIGURATION           0x08
  47 #define USB_DEV_GET_CONFIGURATION_REQ_TYPE  0x80
  48
  49 #define USB_DEV_SET_CONFIGURATION           0x09
  50 #define USB_DEV_SET_CONFIGURATION_REQ_TYPE  0x00
  51
  52 #define USB_DEV_GET_INTERFACE               0x0A
  53 #define USB_DEV_GET_INTERFACE_REQ_TYPE      0x81
  54
  55 #define USB_DEV_SET_INTERFACE               0x0B
  56 #define USB_DEV_SET_INTERFACE_REQ_TYPE      0x01
  57
  58 #define USB_DEV_SYNCH_FRAME                 0x0C
  59 #define USB_DEV_SYNCH_FRAME_REQ_TYPE        0x82
  60
  61
  62 //
  63 // USB standard descriptors and reqeust
  64 //
  65
  66 ///
  67 /// Format of Setup Data for USB Device Requests
  68 /// USB 2.0 spec, Section 9.3
  69 ///
  70 typedef struct {
  71   UINT8           RequestType;
  72   UINT8           Request;
  73   UINT16          Value;
  74   UINT16          Index;
  75   UINT16          Length;
  76 } USB_DEVICE_REQUEST;
  77
  78 ///
  79 /// Standard Device Descriptor
  80 /// USB 2.0 spec, Section 9.6.1
  81 ///
  82 typedef struct {
  83   UINT8           Length;
  84   UINT8           DescriptorType;
  85   UINT16          BcdUSB;
  86   UINT8           DeviceClass;
  87   UINT8           DeviceSubClass;
  88   UINT8           DeviceProtocol;
  89   UINT8           MaxPacketSize0;
  90   UINT16          IdVendor;
  91   UINT16          IdProduct;
  92   UINT16          BcdDevice;
  93   UINT8           StrManufacturer;
  94   UINT8           StrProduct;
  95   UINT8           StrSerialNumber;
  96   UINT8           NumConfigurations;
  97 } USB_DEVICE_DESCRIPTOR;
  98
  99 ///
 100 /// Standard Configuration Descriptor
 101 /// USB 2.0 spec, Section 9.6.3
 102 ///
 103 typedef struct {
 104   UINT8           Length;
 105   UINT8           DescriptorType;
 106   UINT16          TotalLength;
 107   UINT8           NumInterfaces;
 108   UINT8           ConfigurationValue;
 109   UINT8           Configuration;
 110   UINT8           Attributes;
 111   UINT8           MaxPower;
 112 } USB_CONFIG_DESCRIPTOR;
 113
 114 ///
 115 /// Standard Interface Descriptor
 116 /// USB 2.0 spec, Section 9.6.5
 117 ///
 118 typedef struct {
 119   UINT8           Length;
 120   UINT8           DescriptorType;
 121   UINT8           InterfaceNumber;
 122   UINT8           AlternateSetting;
 123   UINT8           NumEndpoints;
 124   UINT8           InterfaceClass;
 125   UINT8           InterfaceSubClass;
 126   UINT8           InterfaceProtocol;
 127   UINT8           Interface;
 128 } USB_INTERFACE_DESCRIPTOR;
 129
 130 ///
 131 /// Standard Endpoint Descriptor
 132 /// USB 2.0 spec, Section 9.6.6
 133 ///
 134 typedef struct {
 135   UINT8           Length;
 136   UINT8           DescriptorType;
 137   UINT8           EndpointAddress;
 138   UINT8           Attributes;
 139   UINT16          MaxPacketSize;
 140   UINT8           Interval;
 141 } USB_ENDPOINT_DESCRIPTOR;
 142
 143 ///
 144 /// UNICODE String Descriptor
 145 /// USB 2.0 spec, Section 9.6.7
 146 ///
 147 typedef struct {
 148   UINT8           Length;
 149   UINT8           DescriptorType;
 150   CHAR16          String[1];
 151 } EFI_USB_STRING_DESCRIPTOR;
 152
 153 typedef enum {
 154   //
 155   // USB request type
 156   //
 157   USB_REQ_TYPE_STANDARD   = (0x00 << 5),
 158   USB_REQ_TYPE_CLASS      = (0x01 << 5),
 159   USB_REQ_TYPE_VENDOR     = (0x02 << 5),
 160
 161   //
 162   // Standard control transfer request type, or the value
 163   // to fill in EFI_USB_DEVICE_REQUEST.Request
 164   //
 165   USB_REQ_GET_STATUS      = 0x00,
 166   USB_REQ_CLEAR_FEATURE   = 0x01,
 167   USB_REQ_SET_FEATURE     = 0x03,
 168   USB_REQ_SET_ADDRESS     = 0x05,
 169   USB_REQ_GET_DESCRIPTOR  = 0x06,
 170   USB_REQ_SET_DESCRIPTOR  = 0x07,
 171   USB_REQ_GET_CONFIG      = 0x08,
 172   USB_REQ_SET_CONFIG      = 0x09,
 173   USB_REQ_GET_INTERFACE   = 0x0A,
 174   USB_REQ_SET_INTERFACE   = 0x0B,
 175   USB_REQ_SYNCH_FRAME     = 0x0C,
 176
 177   //
 178   // Usb control transfer target
 179   //
 180   USB_TARGET_DEVICE       = 0,
 181   USB_TARGET_INTERFACE    = 0x01,
 182   USB_TARGET_ENDPOINT     = 0x02,
 183   USB_TARGET_OTHER        = 0x03,
 184
 185   //
 186   // USB Descriptor types
 187   //
 188   USB_DESC_TYPE_DEVICE    = 0x01,
 189   USB_DESC_TYPE_CONFIG    = 0x02,
 190   USB_DESC_TYPE_STRING    = 0x03,
 191   USB_DESC_TYPE_INTERFACE = 0x04,
 192   USB_DESC_TYPE_ENDPOINT  = 0x05,
 193   USB_DESC_TYPE_HID       = 0x21,
 194   USB_DESC_TYPE_REPORT    = 0x22,
 195
 196   //
 197   // Features to be cleared by CLEAR_FEATURE requests
 198   //
 199   USB_FEATURE_ENDPOINT_HALT = 0,
 200
 201   //
 202   // USB endpoint types: 00: control, 01: isochronous, 10: bulk, 11: interrupt
 203   //
 204   USB_ENDPOINT_CONTROL    = 0x00,
 205   USB_ENDPOINT_ISO        = 0x01,
 206   USB_ENDPOINT_BULK       = 0x02,
 207   USB_ENDPOINT_INTERRUPT  = 0x03,
 208
 209   USB_ENDPOINT_TYPE_MASK  = 0x03,
 210   USB_ENDPOINT_DIR_IN     = 0x80,
 211
 212   //
 213   //Use 200 ms to increase the error handling response time
 214   //
 215   EFI_USB_INTERRUPT_DELAY = 2000000
 216 } USB_TYPES_DEFINITION;
 217
 218
 219 //
 220 // HID constants definition, see Device Class Definition
 221 // for Human Interface Devices (HID) rev1.11
 222 //
 223
 224 //
 225 // HID standard GET_DESCRIPTOR request.
 226 //
 227 #define USB_HID_GET_DESCRIPTOR_REQ_TYPE  0x81
 228
 229 //
 230 // HID specific requests.
 231 //
 232 #define USB_HID_CLASS_GET_REQ_TYPE       0xa1
 233 #define USB_HID_CLASS_SET_REQ_TYPE       0x21
 234
 235 //
 236 // HID report item format
 237 //
 238 #define HID_ITEM_FORMAT_SHORT 0
 239 #define HID_ITEM_FORMAT_LONG  1
 240
 241 //
 242 // Special tag indicating long items
 243 //
 244 #define HID_ITEM_TAG_LONG 15
 245
 246 //
 247 // HID report descriptor item type (prefix bit 2,3)
 248 //
 249 #define HID_ITEM_TYPE_MAIN      0
 250 #define HID_ITEM_TYPE_GLOBAL    1
 251 #define HID_ITEM_TYPE_LOCAL     2
 252 #define HID_ITEM_TYPE_RESERVED  3
 253
 254 //
 255 // HID report descriptor main item tags
 256 //
 257 #define HID_MAIN_ITEM_TAG_INPUT             8
 258 #define HID_MAIN_ITEM_TAG_OUTPUT            9
 259 #define HID_MAIN_ITEM_TAG_FEATURE           11
 260 #define HID_MAIN_ITEM_TAG_BEGIN_COLLECTION  10
 261 #define HID_MAIN_ITEM_TAG_END_COLLECTION    12
 262
 263 //
 264 // HID report descriptor main item contents
 265 //
 266 #define HID_MAIN_ITEM_CONSTANT      0x001
 267 #define HID_MAIN_ITEM_VARIABLE      0x002
 268 #define HID_MAIN_ITEM_RELATIVE      0x004
 269 #define HID_MAIN_ITEM_WRAP          0x008
 270 #define HID_MAIN_ITEM_NONLINEAR     0x010
 271 #define HID_MAIN_ITEM_NO_PREFERRED  0x020
 272 #define HID_MAIN_ITEM_NULL_STATE    0x040
 273 #define HID_MAIN_ITEM_VOLATILE      0x080
 274 #define HID_MAIN_ITEM_BUFFERED_BYTE 0x100
 275
 276 //
 277 // HID report descriptor collection item types
 278 //
 279 #define HID_COLLECTION_PHYSICAL     0
 280 #define HID_COLLECTION_APPLICATION  1
 281 #define HID_COLLECTION_LOGICAL      2
 282
 283 //
 284 // HID report descriptor global item tags
 285 //
 286 #define HID_GLOBAL_ITEM_TAG_USAGE_PAGE        0
 287 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MINIMUM   1
 288 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MAXIMUM   2
 289 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MINIMUM  3
 290 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MAXIMUM  4
 291 #define HID_GLOBAL_ITEM_TAG_UNIT_EXPONENT     5
 292 #define HID_GLOBAL_ITEM_TAG_UNIT              6
 293 #define HID_GLOBAL_ITEM_TAG_REPORT_SIZE       7
 294 #define HID_GLOBAL_ITEM_TAG_REPORT_ID         8
 295 #define HID_GLOBAL_ITEM_TAG_REPORT_COUNT      9
 296 #define HID_GLOBAL_ITEM_TAG_PUSH              10
 297 #define HID_GLOBAL_ITEM_TAG_POP               11
 298
 299 //
 300 // HID report descriptor local item tags
 301 //
 302 #define HID_LOCAL_ITEM_TAG_USAGE              0
 303 #define HID_LOCAL_ITEM_TAG_USAGE_MINIMUM      1
 304 #define HID_LOCAL_ITEM_TAG_USAGE_MAXIMUM      2
 305 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_INDEX   3
 306 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MINIMUM 4
 307 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MAXIMUM 5
 308 #define HID_LOCAL_ITEM_TAG_STRING_INDEX       7
 309 #define HID_LOCAL_ITEM_TAG_STRING_MINIMUM     8
 310 #define HID_LOCAL_ITEM_TAG_STRING_MAXIMUM     9
 311 #define HID_LOCAL_ITEM_TAG_DELIMITER          10
 312
 313 //
 314 // HID report types
 315 //
 316 #define HID_INPUT_REPORT    1
 317 #define HID_OUTPUT_REPORT   2
 318 #define HID_FEATURE_REPORT  3
 319
 320 //
 321 // HID class protocol request
 322 //
 323 #define EFI_USB_GET_REPORT_REQUEST    0x01
 324 #define EFI_USB_GET_IDLE_REQUEST      0x02
 325 #define EFI_USB_GET_PROTOCOL_REQUEST  0x03
 326 #define EFI_USB_SET_REPORT_REQUEST    0x09
 327 #define EFI_USB_SET_IDLE_REQUEST      0x0a
 328 #define EFI_USB_SET_PROTOCOL_REQUEST  0x0b
 329
 330 #pragma pack(1)
 331 ///
 332 /// Descriptor header for Report/Physical Descriptors
 333 ///
 334 typedef struct hid_class_descriptor {
 335   UINT8   DescriptorType;
 336   UINT16  DescriptorLength;
 337 } EFI_USB_HID_CLASS_DESCRIPTOR;
 338 #pragma pack()
 339
 340 ///
 341 /// The HID descriptor identifies the length and type
 342 /// of subordinate descriptors for a device.
 343 ///
 344 typedef struct hid_descriptor {
 345   UINT8                         Length;
 346   UINT8                         DescriptorType;
 347   UINT16                        BcdHID;
 348   UINT8                         CountryCode;
 349   UINT8                         NumDescriptors;
 350   EFI_USB_HID_CLASS_DESCRIPTOR  HidClassDesc[1];
 351 } EFI_USB_HID_DESCRIPTOR;
 352
 353 #endif