EdkModulePkg/Include/Library/EdkUsbLib.h

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