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