MdePkg/Include/Library/UsbLib.h

   1 /** @file
   2    Common Dxe Libarary  for USB
   3    Add Constants & structure definitions for Usb HID
   4
   5   Copyright (c) 2006, Intel Corporation<BR>
   6   All rights reserved. This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16
  17 #ifndef __USB_DXE_LIB_H__
  18 #define __USB_DXE_LIB_H__
  19
  20 #include <Protocol/UsbIo.h>
  21 //
  22 // define the timeout time as 3ms
  23 //
  24 #define TIMEOUT_VALUE 3 * 1000
  25
  26 //
  27 // HID constants definition, see HID rev1.0
  28 //
  29 //
  30 // HID report item format
  31 //
  32 #define HID_ITEM_FORMAT_SHORT 0
  33 #define HID_ITEM_FORMAT_LONG  1
  34
  35 //
  36 // Special tag indicating long items
  37 //
  38 #define HID_ITEM_TAG_LONG 15
  39
  40 //
  41 // HID report descriptor item type (prefix bit 2,3)
  42 //
  43 #define HID_ITEM_TYPE_MAIN      0
  44 #define HID_ITEM_TYPE_GLOBAL    1
  45 #define HID_ITEM_TYPE_LOCAL     2
  46 #define HID_ITEM_TYPE_RESERVED  3
  47
  48 //
  49 // HID report descriptor main item tags
  50 //
  51 #define HID_MAIN_ITEM_TAG_INPUT             8
  52 #define HID_MAIN_ITEM_TAG_OUTPUT            9
  53 #define HID_MAIN_ITEM_TAG_FEATURE           11
  54 #define HID_MAIN_ITEM_TAG_BEGIN_COLLECTION  10
  55 #define HID_MAIN_ITEM_TAG_END_COLLECTION    12
  56
  57 //
  58 // HID report descriptor main item contents
  59 //
  60 #define HID_MAIN_ITEM_CONSTANT      0x001
  61 #define HID_MAIN_ITEM_VARIABLE      0x002
  62 #define HID_MAIN_ITEM_RELATIVE      0x004
  63 #define HID_MAIN_ITEM_WRAP          0x008
  64 #define HID_MAIN_ITEM_NONLINEAR     0x010
  65 #define HID_MAIN_ITEM_NO_PREFERRED  0x020
  66 #define HID_MAIN_ITEM_NULL_STATE    0x040
  67 #define HID_MAIN_ITEM_VOLATILE      0x080
  68 #define HID_MAIN_ITEM_BUFFERED_BYTE 0x100
  69
  70 //
  71 // HID report descriptor collection item types
  72 //
  73 #define HID_COLLECTION_PHYSICAL     0
  74 #define HID_COLLECTION_APPLICATION  1
  75 #define HID_COLLECTION_LOGICAL      2
  76
  77 //
  78 // HID report descriptor global item tags
  79 //
  80 #define HID_GLOBAL_ITEM_TAG_USAGE_PAGE        0
  81 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MINIMUM   1
  82 #define HID_GLOBAL_ITEM_TAG_LOGICAL_MAXIMUM   2
  83 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MINIMUM  3
  84 #define HID_GLOBAL_ITEM_TAG_PHYSICAL_MAXIMUM  4
  85 #define HID_GLOBAL_ITEM_TAG_UNIT_EXPONENT     5
  86 #define HID_GLOBAL_ITEM_TAG_UNIT              6
  87 #define HID_GLOBAL_ITEM_TAG_REPORT_SIZE       7
  88 #define HID_GLOBAL_ITEM_TAG_REPORT_ID         8
  89 #define HID_GLOBAL_ITEM_TAG_REPORT_COUNT      9
  90 #define HID_GLOBAL_ITEM_TAG_PUSH              10
  91 #define HID_GLOBAL_ITEM_TAG_POP               11
  92
  93 //
  94 // HID report descriptor local item tags
  95 //
  96 #define HID_LOCAL_ITEM_TAG_USAGE              0
  97 #define HID_LOCAL_ITEM_TAG_USAGE_MINIMUM      1
  98 #define HID_LOCAL_ITEM_TAG_USAGE_MAXIMUM      2
  99 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_INDEX   3
 100 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MINIMUM 4
 101 #define HID_LOCAL_ITEM_TAG_DESIGNATOR_MAXIMUM 5
 102 #define HID_LOCAL_ITEM_TAG_STRING_INDEX       7
 103 #define HID_LOCAL_ITEM_TAG_STRING_MINIMUM     8
 104 #define HID_LOCAL_ITEM_TAG_STRING_MAXIMUM     9
 105 #define HID_LOCAL_ITEM_TAG_DELIMITER          10
 106
 107 //
 108 // HID usage tables
 109 //
 110 #define HID_USAGE_PAGE    0xffff0000
 111
 112 #define HID_UP_GENDESK    0x00010000
 113 #define HID_UP_KEYBOARD   0x00070000
 114 #define HID_UP_LED        0x00080000
 115 #define HID_UP_BUTTON     0x00090000
 116 #define HID_UP_CONSUMER   0x000c0000
 117 #define HID_UP_DIGITIZER  0x000d0000
 118 #define HID_UP_PID        0x000f0000
 119
 120 #define HID_USAGE         0x0000ffff
 121
 122 #define HID_GD_POINTER    0x00010001
 123 #define HID_GD_MOUSE      0x00010002
 124 #define HID_GD_JOYSTICK   0x00010004
 125 #define HID_GD_GAMEPAD    0x00010005
 126 #define HID_GD_HATSWITCH  0x00010039
 127
 128 //
 129 // HID report types
 130 //
 131 #define HID_INPUT_REPORT    1
 132 #define HID_OUTPUT_REPORT   2
 133 #define HID_FEATURE_REPORT  3
 134
 135 //
 136 // HID device quirks.
 137 //
 138 #define HID_QUIRK_INVERT  0x01
 139 #define HID_QUIRK_NOTOUCH 0x02
 140
 141 //
 142 // HID class protocol request
 143 //
 144 #define EFI_USB_GET_REPORT_REQUEST    0x01
 145 #define EFI_USB_GET_IDLE_REQUEST      0x02
 146 #define EFI_USB_GET_PROTOCOL_REQUEST  0x03
 147 #define EFI_USB_SET_REPORT_REQUEST    0x09
 148 #define EFI_USB_SET_IDLE_REQUEST      0x0a
 149 #define EFI_USB_SET_PROTOCOL_REQUEST  0x0b
 150
 151 #pragma pack(1)
 152 //
 153 // Descriptor header for Report/Physical Descriptors
 154 //
 155 typedef struct hid_class_descriptor {
 156   UINT8   DescriptorType;
 157   UINT16  DescriptorLength;
 158 } EFI_USB_HID_CLASS_DESCRIPTOR;
 159
 160 typedef struct hid_descriptor {
 161   UINT8                         Length;
 162   UINT8                         DescriptorType;
 163   UINT16                        BcdHID;
 164   UINT8                         CountryCode;
 165   UINT8                         NumDescriptors;
 166   EFI_USB_HID_CLASS_DESCRIPTOR  HidClassDesc[1];
 167 } EFI_USB_HID_DESCRIPTOR;
 168
 169 #pragma pack()
 170
 171 EFI_STATUS
 172 UsbGetHidDescriptor (
 173   IN  EFI_USB_IO_PROTOCOL        *UsbIo,
 174   IN  UINT8                      InterfaceNum,
 175   OUT EFI_USB_HID_DESCRIPTOR     *HidDescriptor
 176   );
 177
 178 EFI_STATUS
 179 UsbGetReportDescriptor (
 180   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 181   IN  UINT8                   InterfaceNum,
 182   IN  UINT16                  DescriptorSize,
 183   OUT UINT8                   *DescriptorBuffer
 184   );
 185
 186 EFI_STATUS
 187 UsbGetProtocolRequest (
 188   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 189   IN UINT8                   Interface,
 190   IN UINT8                   *Protocol
 191   );
 192
 193 EFI_STATUS
 194 UsbSetProtocolRequest (
 195   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 196   IN UINT8                   Interface,
 197   IN UINT8                   Protocol
 198   );
 199
 200 EFI_STATUS
 201 UsbSetIdleRequest (
 202   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 203   IN UINT8                   Interface,
 204   IN UINT8                   ReportId,
 205   IN UINT8                   Duration
 206   );
 207
 208 EFI_STATUS
 209 UsbGetIdleRequest (
 210   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 211   IN  UINT8                   Interface,
 212   IN  UINT8                   ReportId,
 213   OUT UINT8                   *Duration
 214   );
 215
 216 EFI_STATUS
 217 UsbSetReportRequest (
 218   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 219   IN UINT8                   Interface,
 220   IN UINT8                   ReportId,
 221   IN UINT8                   ReportType,
 222   IN UINT16                  ReportLen,
 223   IN UINT8                   *Report
 224   );
 225
 226 EFI_STATUS
 227 UsbGetReportRequest (
 228   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 229   IN UINT8                   Interface,
 230   IN UINT8                   ReportId,
 231   IN UINT8                   ReportType,
 232   IN UINT16                  ReportLen,
 233   IN UINT8                   *Report
 234   );
 235
 236 //
 237 // Get Device Descriptor
 238 //
 239 EFI_STATUS
 240 UsbGetDescriptor (
 241   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 242   IN  UINT16                  Value,
 243   IN  UINT16                  Index,
 244   IN  UINT16                  DescriptorLength,
 245   OUT VOID                    *Descriptor,
 246   OUT UINT32                  *Status
 247   );
 248
 249 //
 250 // Set Device Descriptor
 251 //
 252 EFI_STATUS
 253 UsbSetDescriptor (
 254   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 255   IN  UINT16                  Value,
 256   IN  UINT16                  Index,
 257   IN  UINT16                  DescriptorLength,
 258   IN  VOID                    *Descriptor,
 259   OUT UINT32                  *Status
 260   );
 261
 262 //
 263 // Get device Interface
 264 //
 265 EFI_STATUS
 266 UsbGetDeviceInterface (
 267   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 268   IN  UINT16                  Index,
 269   OUT UINT8                   *AltSetting,
 270   OUT UINT32                  *Status
 271   );
 272
 273 //
 274 // Set device interface
 275 //
 276 EFI_STATUS
 277 UsbSetDeviceInterface (
 278   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 279   IN  UINT16                  InterfaceNo,
 280   IN  UINT16                  AltSetting,
 281   OUT UINT32                  *Status
 282   );
 283
 284 //
 285 // Get device configuration
 286 //
 287 EFI_STATUS
 288 UsbGetDeviceConfiguration (
 289   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 290   OUT UINT8                   *ConfigValue,
 291   OUT UINT32                  *Status
 292   );
 293
 294 //
 295 // Set device configuration
 296 //
 297 EFI_STATUS
 298 UsbSetDeviceConfiguration (
 299   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 300   IN  UINT16                  Value,
 301   OUT UINT32                  *Status
 302   );
 303
 304 //
 305 //  Set Device Feature
 306 //
 307 EFI_STATUS
 308 UsbSetDeviceFeature (
 309   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 310   IN  EFI_USB_RECIPIENT       Recipient,
 311   IN  UINT16                  Value,
 312   IN  UINT16                  Target,
 313   OUT UINT32                  *Status
 314   );
 315
 316 //
 317 // Clear Device Feature
 318 //
 319 EFI_STATUS
 320 UsbClearDeviceFeature (
 321   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 322   IN  EFI_USB_RECIPIENT       Recipient,
 323   IN  UINT16                  Value,
 324   IN  UINT16                  Target,
 325   OUT UINT32                  *Status
 326   );
 327
 328 //
 329 //  Get Device Status
 330 //
 331 EFI_STATUS
 332 UsbGetDeviceStatus (
 333   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 334   IN  EFI_USB_RECIPIENT       Recipient,
 335   IN  UINT16                  Target,
 336   OUT UINT16                  *DevStatus,
 337   OUT UINT32                  *Status
 338   );
 339
 340 //
 341 // The following APIs are not basic library, but they are common used.
 342 //
 343 //
 344 // Usb Get String
 345 //
 346 EFI_STATUS
 347 UsbGetString (
 348   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 349   IN  UINT16                  LangID,
 350   IN  UINT8                   Index,
 351   IN  VOID                    *Buf,
 352   IN  UINTN                   BufSize,
 353   OUT UINT32                  *Status
 354   );
 355
 356 //
 357 // Clear endpoint stall
 358 //
 359 EFI_STATUS
 360 UsbClearEndpointHalt (
 361   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 362   IN  UINT8                   EndpointNo,
 363   OUT UINT32                  *Status
 364   );
 365
 366 #endif