MdePkg/Include/Library/UsbLib.h

   1 /** @file
   2   Common Dxe Libarary  for USB
   3
   4   Copyright (c) 2006, Intel Corporation<BR>
   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
  16 #ifndef __USB_DXE_LIB_H__
  17 #define __USB_DXE_LIB_H__
  18
  19 #include <Protocol/UsbIo.h>
  20
  21 //
  22 // Standard device request and request type
  23 // By [Spec-USB20/Chapter-9.4]
  24 //
  25 #define USB_DEV_GET_STATUS                  0x00
  26 #define USB_DEV_GET_STATUS_REQ_TYPE_D       0x80 // Receiver : Device
  27 #define USB_DEV_GET_STATUS_REQ_TYPE_I       0x81 // Receiver : Interface
  28 #define USB_DEV_GET_STATUS_REQ_TYPE_E       0x82 // Receiver : Endpoint
  29
  30 #define USB_DEV_CLEAR_FEATURE               0x01
  31 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_D    0x00 // Receiver : Device
  32 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_I    0x01 // Receiver : Interface
  33 #define USB_DEV_CLEAR_FEATURE_REQ_TYPE_E    0x02 // Receiver : Endpoint
  34
  35 #define USB_DEV_SET_FEATURE                 0x03
  36 #define USB_DEV_SET_FEATURE_REQ_TYPE_D      0x00 // Receiver : Device
  37 #define USB_DEV_SET_FEATURE_REQ_TYPE_I      0x01 // Receiver : Interface
  38 #define USB_DEV_SET_FEATURE_REQ_TYPE_E      0x02 // Receiver : Endpoint
  39
  40 #define USB_DEV_SET_ADDRESS                 0x05
  41 #define USB_DEV_SET_ADDRESS_REQ_TYPE        0x00
  42
  43 #define USB_DEV_GET_DESCRIPTOR              0x06
  44 #define USB_DEV_GET_DESCRIPTOR_REQ_TYPE     0x80
  45
  46 #define USB_DEV_SET_DESCRIPTOR              0x07
  47 #define USB_DEV_SET_DESCRIPTOR_REQ_TYPE     0x00
  48
  49 #define USB_DEV_GET_CONFIGURATION           0x08
  50 #define USB_DEV_GET_CONFIGURATION_REQ_TYPE  0x80
  51
  52 #define USB_DEV_SET_CONFIGURATION           0x09
  53 #define USB_DEV_SET_CONFIGURATION_REQ_TYPE  0x00
  54
  55 #define USB_DEV_GET_INTERFACE               0x0A
  56 #define USB_DEV_GET_INTERFACE_REQ_TYPE      0x81
  57
  58 #define USB_DEV_SET_INTERFACE               0x0B
  59 #define USB_DEV_SET_INTERFACE_REQ_TYPE      0x01
  60
  61 #define USB_DEV_SYNCH_FRAME                 0x0C
  62 #define USB_DEV_SYNCH_FRAME_REQ_TYPE        0x82
  63
  64 //
  65 // define the timeout time as 3ms
  66 //
  67 #define TIMEOUT_VALUE 3 * 1000
  68
  69 //
  70 // HID constants definition, see HID rev1.0
  71 //
  72 //
  73 // HID report item format
  74 //
  75 #define HID_ITEM_FORMAT_SHORT 0
  76 #define HID_ITEM_FORMAT_LONG  1
  77
  78 //
  79 // Special tag indicating long items
  80 //
  81 #define HID_ITEM_TAG_LONG 15
  82
  83 //
  84 // HID report descriptor item type (prefix bit 2,3)
  85 //
  86 #define HID_ITEM_TYPE_MAIN      0
  87 #define HID_ITEM_TYPE_GLOBAL    1
  88 #define HID_ITEM_TYPE_LOCAL     2
  89 #define HID_ITEM_TYPE_RESERVED  3
  90
  91 //
  92 // HID report descriptor main item tags
  93 //
  94 #define HID_MAIN_ITEM_TAG_INPUT             8
  95 #define HID_MAIN_ITEM_TAG_OUTPUT            9
  96 #define HID_MAIN_ITEM_TAG_FEATURE           11
  97 #define HID_MAIN_ITEM_TAG_BEGIN_COLLECTION  10
  98 #define HID_MAIN_ITEM_TAG_END_COLLECTION    12
  99
 100 //
 101 // HID report descriptor main item contents
 102 //
 103 #define HID_MAIN_ITEM_CONSTANT      0x001
 104 #define HID_MAIN_ITEM_VARIABLE      0x002
 105 #define HID_MAIN_ITEM_RELATIVE      0x004
 106 #define HID_MAIN_ITEM_WRAP          0x008
 107 #define HID_MAIN_ITEM_NONLINEAR     0x010
 108 #define HID_MAIN_ITEM_NO_PREFERRED  0x020
 109 #define HID_MAIN_ITEM_NULL_STATE    0x040
 110 #define HID_MAIN_ITEM_VOLATILE      0x080
 111 #define HID_MAIN_ITEM_BUFFERED_BYTE 0x100
 112
 113 //
 114 // HID report descriptor collection item types
 115 //
 116 #define HID_COLLECTION_PHYSICAL     0
 117 #define HID_COLLECTION_APPLICATION  1
 118 #define HID_COLLECTION_LOGICAL      2
 119
 120 //
 121 // HID report descriptor global item tags
 122 //
 123 #define HID_GLOBAL_ITEM_TAG_USAGE_PAGE        0
 124 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MINIMUM   1
 125 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MAXIMUM   2
 126 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MINIMUM  3
 127 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MAXIMUM  4
 128 #define HID_GLOBAL_ITEM_TAG_UNIT_EXPONENT     5
 129 #define HID_GLOBAL_ITEM_TAG_UNIT              6
 130 #define HID_GLOBAL_ITEM_TAG_REPORT_SIZE       7
 131 #define HID_GLOBAL_ITEM_TAG_REPORT_ID         8
 132 #define HID_GLOBAL_ITEM_TAG_REPORT_COUNT      9
 133 #define HID_GLOBAL_ITEM_TAG_PUSH              10
 134 #define HID_GLOBAL_ITEM_TAG_POP               11
 135
 136 //
 137 // HID report descriptor local item tags
 138 //
 139 #define HID_LOCAL_ITEM_TAG_USAGE              0
 140 #define HID_LOCAL_ITEM_TAG_USAGE_MINIMUM      1
 141 #define HID_LOCAL_ITEM_TAG_USAGE_MAXIMUM      2
 142 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_INDEX   3
 143 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MINIMUM 4
 144 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MAXIMUM 5
 145 #define HID_LOCAL_ITEM_TAG_STRING_INDEX       7
 146 #define HID_LOCAL_ITEM_TAG_STRING_MINIMUM     8
 147 #define HID_LOCAL_ITEM_TAG_STRING_MAXIMUM     9
 148 #define HID_LOCAL_ITEM_TAG_DELIMITER          10
 149
 150 //
 151 // HID usage tables
 152 //
 153 #define HID_USAGE_PAGE    0xffff0000
 154
 155 #define HID_UP_GENDESK    0x00010000
 156 #define HID_UP_KEYBOARD   0x00070000
 157 #define HID_UP_LED        0x00080000
 158 #define HID_UP_BUTTON     0x00090000
 159 #define HID_UP_CONSUMER   0x000c0000
 160 #define HID_UP_DIGITIZER  0x000d0000
 161 #define HID_UP_PID        0x000f0000
 162
 163 #define HID_USAGE         0x0000ffff
 164
 165 #define HID_GD_POINTER    0x00010001
 166 #define HID_GD_MOUSE      0x00010002
 167 #define HID_GD_JOYSTICK   0x00010004
 168 #define HID_GD_GAMEPAD    0x00010005
 169 #define HID_GD_HATSWITCH  0x00010039
 170
 171 //
 172 // HID report types
 173 //
 174 #define HID_INPUT_REPORT    1
 175 #define HID_OUTPUT_REPORT   2
 176 #define HID_FEATURE_REPORT  3
 177
 178 //
 179 // HID device quirks.
 180 //
 181 #define HID_QUIRK_INVERT  0x01
 182 #define HID_QUIRK_NOTOUCH 0x02
 183
 184 //
 185 // HID class protocol request
 186 //
 187 #define EFI_USB_GET_REPORT_REQUEST    0x01
 188 #define EFI_USB_GET_IDLE_REQUEST      0x02
 189 #define EFI_USB_GET_PROTOCOL_REQUEST  0x03
 190 #define EFI_USB_SET_REPORT_REQUEST    0x09
 191 #define EFI_USB_SET_IDLE_REQUEST      0x0a
 192 #define EFI_USB_SET_PROTOCOL_REQUEST  0x0b
 193
 194 #pragma pack(1)
 195 //
 196 // Descriptor header for Report/Physical Descriptors
 197 //
 198 typedef struct hid_class_descriptor {
 199   UINT8   DescriptorType;
 200   UINT16  DescriptorLength;
 201 } EFI_USB_HID_CLASS_DESCRIPTOR;
 202
 203 typedef struct hid_descriptor {
 204   UINT8                         Length;
 205   UINT8                         DescriptorType;
 206   UINT16                        BcdHID;
 207   UINT8                         CountryCode;
 208   UINT8                         NumDescriptors;
 209   EFI_USB_HID_CLASS_DESCRIPTOR  HidClassDesc[1];
 210 } EFI_USB_HID_DESCRIPTOR;
 211
 212 #pragma pack()
 213
 214 EFI_STATUS
 215 UsbGetHidDescriptor (
 216   IN  EFI_USB_IO_PROTOCOL        *UsbIo,
 217   IN  UINT8                      InterfaceNum,
 218   OUT EFI_USB_HID_DESCRIPTOR     *HidDescriptor
 219   );
 220
 221 EFI_STATUS
 222 UsbGetReportDescriptor (
 223   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 224   IN  UINT8                   InterfaceNum,
 225   IN  UINT16                  DescriptorSize,
 226   OUT UINT8                   *DescriptorBuffer
 227   );
 228
 229 EFI_STATUS
 230 UsbGetProtocolRequest (
 231   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 232   IN UINT8                   Interface,
 233   IN UINT8                   *Protocol
 234   );
 235
 236 EFI_STATUS
 237 UsbSetProtocolRequest (
 238   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 239   IN UINT8                   Interface,
 240   IN UINT8                   Protocol
 241   );
 242
 243 EFI_STATUS
 244 UsbSetIdleRequest (
 245   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 246   IN UINT8                   Interface,
 247   IN UINT8                   ReportId,
 248   IN UINT8                   Duration
 249   );
 250
 251 EFI_STATUS
 252 UsbGetIdleRequest (
 253   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 254   IN  UINT8                   Interface,
 255   IN  UINT8                   ReportId,
 256   OUT UINT8                   *Duration
 257   );
 258
 259 EFI_STATUS
 260 UsbSetReportRequest (
 261   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 262   IN UINT8                   Interface,
 263   IN UINT8                   ReportId,
 264   IN UINT8                   ReportType,
 265   IN UINT16                  ReportLen,
 266   IN UINT8                   *Report
 267   );
 268
 269 EFI_STATUS
 270 UsbGetReportRequest (
 271   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 272   IN UINT8                   Interface,
 273   IN UINT8                   ReportId,
 274   IN UINT8                   ReportType,
 275   IN UINT16                  ReportLen,
 276   IN UINT8                   *Report
 277   );
 278
 279 typedef enum {
 280   EfiUsbEndpointHalt,
 281   EfiUsbDeviceRemoteWakeup
 282 } EFI_USB_STANDARD_FEATURE_SELECTOR;
 283
 284 EFI_STATUS
 285 UsbGetDescriptor (
 286   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 287   IN  UINT16                  Value,
 288   IN  UINT16                  Index,
 289   IN  UINT16                  DescriptorLength,
 290   OUT VOID                    *Descriptor,
 291   OUT UINT32                  *Status
 292   );
 293
 294 EFI_STATUS
 295 UsbSetDescriptor (
 296   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 297   IN  UINT16                  Value,
 298   IN  UINT16                  Index,
 299   IN  UINT16                  DescriptorLength,
 300   IN  VOID                    *Descriptor,
 301   OUT UINT32                  *Status
 302   );
 303
 304 EFI_STATUS
 305 UsbGetInterface (
 306   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 307   IN  UINT16                  Index,
 308   OUT UINT8                   *AltSetting,
 309   OUT UINT32                  *Status
 310   );
 311
 312 EFI_STATUS
 313 UsbSetInterface (
 314   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 315   IN  UINT16                  InterfaceNo,
 316   IN  UINT16                  AltSetting,
 317   OUT UINT32                  *Status
 318   );
 319
 320 EFI_STATUS
 321 UsbGetConfiguration (
 322   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 323   OUT UINT8                   *ConfigValue,
 324   OUT UINT32                  *Status
 325   );
 326
 327 EFI_STATUS
 328 UsbSetConfiguration (
 329   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 330   IN  UINT16                  Value,
 331   OUT UINT32                  *Status
 332   );
 333
 334 EFI_STATUS
 335 UsbSetFeature (
 336   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 337   IN  UINTN                   Recipient,
 338   IN  UINT16                  Value,
 339   IN  UINT16                  Target,
 340   OUT UINT32                  *Status
 341   );
 342
 343 EFI_STATUS
 344 UsbClearFeature (
 345   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 346   IN  UINTN                   Recipient,
 347   IN  UINT16                  Value,
 348   IN  UINT16                  Target,
 349   OUT UINT32                  *Status
 350   );
 351
 352 EFI_STATUS
 353 UsbGetStatus (
 354   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 355   IN  UINTN                   Recipient,
 356   IN  UINT16                  Target,
 357   OUT UINT16                  *DevStatus,
 358   OUT UINT32                  *Status
 359   );
 360
 361 EFI_STATUS
 362 UsbGetHubDescriptor (
 363   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 364   IN  UINT16                  Value,
 365   IN  UINT16                  Index,
 366   IN  UINT16                  DescriptorLength,
 367   OUT VOID                    *Descriptor,
 368   OUT UINT32                  *Status
 369   );
 370
 371 //
 372 // Clear endpoint stall
 373 //
 374 EFI_STATUS
 375 UsbClearEndpointHalt (
 376   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 377   IN  UINT8                   EndpointNo,
 378   OUT UINT32                  *Status
 379   );
 380
 381 #endif