MdePkg/Library/UefiUsbLib/Hid.c

   1 /** @file
   2
   3   The library provides USB HID Class standard and specific requests defined
   4   in USB HID Firmware Specification 7 section : Requests.
   5
   6   Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #include "UefiUsbLibInternal.h"
  12
  13 //
  14 //  Hid RequestType Bits specifying characteristics of request.
  15 //  Valid values are 10100001b (0xa1) or 00100001b (0x21).
  16 //  The following description:
  17 //    7 Data transfer direction
  18 //        0 = Host to device
  19 //        1 = Device to host
  20 //    6..5 Type
  21 //        1 = Class
  22 //    4..0 Recipient
  23 //        1 = Interface
  24 //
  25
  26 /**
  27   Get the descriptor of the specified USB HID interface.
  28
  29   Submit a USB get HID descriptor request for the USB device specified by UsbIo
  30   and Interface and return the HID descriptor in HidDescriptor.
  31   If UsbIo is NULL, then ASSERT().
  32   If HidDescriptor is NULL, then ASSERT().
  33
  34   @param  UsbIo          A pointer to the USB I/O Protocol instance for the specific USB target.
  35   @param  Interface      The index of the HID interface on the USB target.
  36   @param  HidDescriptor  The pointer to the USB HID descriptor that was retrieved from
  37                          the specified USB target and interface. Type EFI_USB_HID_DESCRIPTOR
  38                          is defined in the MDE Package Industry Standard include file Usb.h.
  39
  40   @retval EFI_SUCCESS       The request executed successfully.
  41   @retval EFI_TIMEOUT       A timeout occurred executing the request.
  42   @retval EFI_DEVICE_ERROR  The request failed due to a device error.
  43
  44 **/
  45 EFI_STATUS
  46 EFIAPI
  47 UsbGetHidDescriptor (
  48   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
  49   IN  UINT8                   Interface,
  50   OUT EFI_USB_HID_DESCRIPTOR  *HidDescriptor
  51   )
  52 {
  53   UINT32                  Status;
  54   EFI_STATUS              Result;
  55   EFI_USB_DEVICE_REQUEST  Request;
  56
  57   ASSERT (UsbIo != NULL);
  58   ASSERT (HidDescriptor != NULL);
  59
  60   Request.RequestType = USB_HID_GET_DESCRIPTOR_REQ_TYPE;
  61   Request.Request     = USB_REQ_GET_DESCRIPTOR;
  62   Request.Value       = (UINT16)(USB_DESC_TYPE_HID << 8);
  63   Request.Index       = Interface;
  64   Request.Length      = (UINT16)sizeof (EFI_USB_HID_DESCRIPTOR);
  65
  66   Result = UsbIo->UsbControlTransfer (
  67                     UsbIo,
  68                     &Request,
  69                     EfiUsbDataIn,
  70                     PcdGet32 (PcdUsbTransferTimeoutValue),
  71                     HidDescriptor,
  72                     sizeof (EFI_USB_HID_DESCRIPTOR),
  73                     &Status
  74                     );
  75
  76   return Result;
  77 }
  78
  79 /**
  80   Get the report descriptor of the specified USB HID interface.
  81
  82   Submit a USB get HID report descriptor request for the USB device specified by
  83   UsbIo and Interface and return the report descriptor in DescriptorBuffer.
  84   If UsbIo is NULL, then ASSERT().
  85   If DescriptorBuffer is NULL, then ASSERT().
  86
  87   @param  UsbIo             A pointer to the USB I/O Protocol instance for the specific USB target.
  88   @param  Interface         The index of the report interface on the USB target.
  89   @param  DescriptorLength  The size, in bytes, of DescriptorBuffer.
  90   @param  DescriptorBuffer  A pointer to the buffer to store the report class descriptor.
  91
  92   @retval  EFI_SUCCESS           The request executed successfully.
  93   @retval  EFI_OUT_OF_RESOURCES  The request could not be completed because the
  94                                  buffer specified by DescriptorLength and DescriptorBuffer
  95                                  is not large enough to hold the result of the request.
  96   @retval  EFI_TIMEOUT           A timeout occurred executing the request.
  97   @retval  EFI_DEVICE_ERROR      The request failed due to a device error.
  98
  99 **/
 100 EFI_STATUS
 101 EFIAPI
 102 UsbGetReportDescriptor (
 103   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 104   IN  UINT8                Interface,
 105   IN  UINT16               DescriptorLength,
 106   OUT UINT8                *DescriptorBuffer
 107   )
 108 {
 109   UINT32                  Status;
 110   EFI_STATUS              Result;
 111   EFI_USB_DEVICE_REQUEST  Request;
 112
 113   ASSERT (UsbIo != NULL);
 114   ASSERT (DescriptorBuffer != NULL);
 115
 116   //
 117   // Fill Device request packet
 118   //
 119   Request.RequestType = USB_HID_GET_DESCRIPTOR_REQ_TYPE;
 120   Request.Request     = USB_REQ_GET_DESCRIPTOR;
 121   Request.Value       = (UINT16)(USB_DESC_TYPE_REPORT << 8);
 122   Request.Index       = Interface;
 123   Request.Length      = DescriptorLength;
 124
 125   Result = UsbIo->UsbControlTransfer (
 126                     UsbIo,
 127                     &Request,
 128                     EfiUsbDataIn,
 129                     PcdGet32 (PcdUsbTransferTimeoutValue),
 130                     DescriptorBuffer,
 131                     DescriptorLength,
 132                     &Status
 133                     );
 134
 135   return Result;
 136 }
 137
 138 /**
 139   Get the HID protocol of the specified USB HID interface.
 140
 141   Submit a USB get HID protocol request for the USB device specified by UsbIo
 142   and Interface and return the protocol retrieved in Protocol.
 143   If UsbIo is NULL, then ASSERT().
 144   If Protocol is NULL, then ASSERT().
 145
 146   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 147   @param  Interface  The index of the report interface on the USB target.
 148   @param  Protocol   A pointer to the protocol for the specified USB target.
 149
 150   @retval  EFI_SUCCESS       The request executed successfully.
 151   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 152   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 153
 154 **/
 155 EFI_STATUS
 156 EFIAPI
 157 UsbGetProtocolRequest (
 158   IN EFI_USB_IO_PROTOCOL  *UsbIo,
 159   IN UINT8                Interface,
 160   OUT UINT8               *Protocol
 161   )
 162 {
 163   UINT32                  Status;
 164   EFI_STATUS              Result;
 165   EFI_USB_DEVICE_REQUEST  Request;
 166
 167   ASSERT (UsbIo != NULL);
 168   ASSERT (Protocol != NULL);
 169
 170   //
 171   // Fill Device request packet
 172   //
 173   Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;
 174   Request.Request     = EFI_USB_GET_PROTOCOL_REQUEST;
 175   Request.Value       = 0;
 176   Request.Index       = Interface;
 177   Request.Length      = 1;
 178
 179   Result = UsbIo->UsbControlTransfer (
 180                     UsbIo,
 181                     &Request,
 182                     EfiUsbDataIn,
 183                     PcdGet32 (PcdUsbTransferTimeoutValue),
 184                     Protocol,
 185                     sizeof (UINT8),
 186                     &Status
 187                     );
 188
 189   return Result;
 190 }
 191
 192 /**
 193   Set the HID protocol of the specified USB HID interface.
 194
 195   Submit a USB set HID protocol request for the USB device specified by UsbIo
 196   and Interface and set the protocol to the value specified by Protocol.
 197   If UsbIo is NULL, then ASSERT().
 198
 199   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 200   @param  Interface  The index of the report interface on the USB target.
 201   @param  Protocol   The protocol value to set for the specified USB target.
 202
 203   @retval  EFI_SUCCESS       The request executed successfully.
 204   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 205   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 206
 207 **/
 208 EFI_STATUS
 209 EFIAPI
 210 UsbSetProtocolRequest (
 211   IN EFI_USB_IO_PROTOCOL  *UsbIo,
 212   IN UINT8                Interface,
 213   IN UINT8                Protocol
 214   )
 215 {
 216   UINT32                  Status;
 217   EFI_STATUS              Result;
 218   EFI_USB_DEVICE_REQUEST  Request;
 219
 220   ASSERT (UsbIo != NULL);
 221
 222   //
 223   // Fill Device request packet
 224   //
 225   Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;
 226   Request.Request     = EFI_USB_SET_PROTOCOL_REQUEST;
 227   Request.Value       = Protocol;
 228   Request.Index       = Interface;
 229   Request.Length      = 0;
 230
 231   Result = UsbIo->UsbControlTransfer (
 232                     UsbIo,
 233                     &Request,
 234                     EfiUsbNoData,
 235                     PcdGet32 (PcdUsbTransferTimeoutValue),
 236                     NULL,
 237                     0,
 238                     &Status
 239                     );
 240   return Result;
 241 }
 242
 243 /**
 244   Set the idle rate of the specified USB HID report.
 245
 246   Submit a USB set HID report idle request for the USB device specified by UsbIo,
 247   Interface, and ReportId, and set the idle rate to the value specified by Duration.
 248   If UsbIo is NULL, then ASSERT().
 249
 250   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 251   @param  Interface  The index of the report interface on the USB target.
 252   @param  ReportId   The identifier of the report to retrieve.
 253   @param  Duration   The idle rate to set for the specified USB target.
 254
 255   @retval  EFI_SUCCESS       The request executed successfully.
 256   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 257   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 258
 259 **/
 260 EFI_STATUS
 261 EFIAPI
 262 UsbSetIdleRequest (
 263   IN EFI_USB_IO_PROTOCOL  *UsbIo,
 264   IN UINT8                Interface,
 265   IN UINT8                ReportId,
 266   IN UINT8                Duration
 267   )
 268 {
 269   UINT32                  Status;
 270   EFI_STATUS              Result;
 271   EFI_USB_DEVICE_REQUEST  Request;
 272
 273   ASSERT (UsbIo != NULL);
 274   //
 275   // Fill Device request packet
 276   //
 277   Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;
 278   Request.Request     = EFI_USB_SET_IDLE_REQUEST;
 279   Request.Value       = (UINT16)((Duration << 8) | ReportId);
 280   Request.Index       = Interface;
 281   Request.Length      = 0;
 282
 283   Result = UsbIo->UsbControlTransfer (
 284                     UsbIo,
 285                     &Request,
 286                     EfiUsbNoData,
 287                     PcdGet32 (PcdUsbTransferTimeoutValue),
 288                     NULL,
 289                     0,
 290                     &Status
 291                     );
 292   return Result;
 293 }
 294
 295 /**
 296   Get the idle rate of the specified USB HID report.
 297
 298   Submit a USB get HID report idle request for the USB device specified by UsbIo,
 299   Interface, and ReportId, and return the ide rate in Duration.
 300   If UsbIo is NULL, then ASSERT().
 301   If Duration is NULL, then ASSERT().
 302
 303   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 304   @param  Interface  The index of the report interface on the USB target.
 305   @param  ReportId   The identifier of the report to retrieve.
 306   @param  Duration   A pointer to the idle rate retrieved from the specified USB target.
 307
 308   @retval  EFI_SUCCESS       The request executed successfully.
 309   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 310   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 311
 312 **/
 313 EFI_STATUS
 314 EFIAPI
 315 UsbGetIdleRequest (
 316   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 317   IN  UINT8                Interface,
 318   IN  UINT8                ReportId,
 319   OUT UINT8                *Duration
 320   )
 321 {
 322   UINT32                  Status;
 323   EFI_STATUS              Result;
 324   EFI_USB_DEVICE_REQUEST  Request;
 325
 326   ASSERT (UsbIo != NULL);
 327   ASSERT (Duration != NULL);
 328   //
 329   // Fill Device request packet
 330   //
 331   Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;
 332   Request.Request     = EFI_USB_GET_IDLE_REQUEST;
 333   Request.Value       = ReportId;
 334   Request.Index       = Interface;
 335   Request.Length      = 1;
 336
 337   Result = UsbIo->UsbControlTransfer (
 338                     UsbIo,
 339                     &Request,
 340                     EfiUsbDataIn,
 341                     PcdGet32 (PcdUsbTransferTimeoutValue),
 342                     Duration,
 343                     1,
 344                     &Status
 345                     );
 346
 347   return Result;
 348 }
 349
 350 /**
 351   Set the report descriptor of the specified USB HID interface.
 352
 353   Submit a USB set HID report request for the USB device specified by UsbIo,
 354   Interface, ReportId, and ReportType, and set the report descriptor using the
 355   buffer specified by ReportLength and Report.
 356   If UsbIo is NULL, then ASSERT().
 357   If Report is NULL, then ASSERT().
 358
 359   @param  UsbIo         A pointer to the USB I/O Protocol instance for the specific USB target.
 360   @param  Interface     The index of the report interface on the USB target.
 361   @param  ReportId      The identifier of the report to retrieve.
 362   @param  ReportType    The type of report to retrieve.
 363   @param  ReportLength  The size, in bytes, of Report.
 364   @param  Report        A pointer to the report descriptor buffer to set.
 365
 366   @retval  EFI_SUCCESS       The request executed successfully.
 367   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 368   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 369
 370 **/
 371 EFI_STATUS
 372 EFIAPI
 373 UsbSetReportRequest (
 374   IN EFI_USB_IO_PROTOCOL  *UsbIo,
 375   IN UINT8                Interface,
 376   IN UINT8                ReportId,
 377   IN UINT8                ReportType,
 378   IN UINT16               ReportLen,
 379   IN UINT8                *Report
 380   )
 381 {
 382   UINT32                  Status;
 383   EFI_STATUS              Result;
 384   EFI_USB_DEVICE_REQUEST  Request;
 385
 386   ASSERT (UsbIo != NULL);
 387   ASSERT (Report != NULL);
 388
 389   //
 390   // Fill Device request packet
 391   //
 392   Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;
 393   Request.Request     = EFI_USB_SET_REPORT_REQUEST;
 394   Request.Value       = (UINT16)((ReportType << 8) | ReportId);
 395   Request.Index       = Interface;
 396   Request.Length      = ReportLen;
 397
 398   Result = UsbIo->UsbControlTransfer (
 399                     UsbIo,
 400                     &Request,
 401                     EfiUsbDataOut,
 402                     PcdGet32 (PcdUsbTransferTimeoutValue),
 403                     Report,
 404                     ReportLen,
 405                     &Status
 406                     );
 407
 408   return Result;
 409 }
 410
 411 /**
 412   Get the report descriptor of the specified USB HID interface.
 413
 414   Submit a USB get HID report request for the USB device specified by UsbIo,
 415   Interface, ReportId, and ReportType, and return the report in the buffer
 416   specified by Report.
 417   If UsbIo is NULL, then ASSERT().
 418   If Report is NULL, then ASSERT().
 419
 420   @param  UsbIo         A pointer to the USB I/O Protocol instance for the specific USB target.
 421   @param  Interface     The index of the report interface on the USB target.
 422   @param  ReportId      The identifier of the report to retrieve.
 423   @param  ReportType    The type of report to retrieve.
 424   @param  ReportLength  The size, in bytes, of Report.
 425   @param  Report        A pointer to the buffer to store the report descriptor.
 426
 427   @retval  EFI_SUCCESS           The request executed successfully.
 428   @retval  EFI_OUT_OF_RESOURCES  The request could not be completed because the
 429                                  buffer specified by ReportLength and Report is not
 430                                  large enough to hold the result of the request.
 431   @retval  EFI_TIMEOUT           A timeout occurred executing the request.
 432   @retval  EFI_DEVICE_ERROR      The request failed due to a device error.
 433
 434 **/
 435 EFI_STATUS
 436 EFIAPI
 437 UsbGetReportRequest (
 438   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 439   IN  UINT8                Interface,
 440   IN  UINT8                ReportId,
 441   IN  UINT8                ReportType,
 442   IN  UINT16               ReportLen,
 443   OUT UINT8                *Report
 444   )
 445 {
 446   UINT32                  Status;
 447   EFI_STATUS              Result;
 448   EFI_USB_DEVICE_REQUEST  Request;
 449
 450   ASSERT (UsbIo != NULL);
 451   ASSERT (Report != NULL);
 452
 453   //
 454   // Fill Device request packet
 455   //
 456   Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;
 457   Request.Request     = EFI_USB_GET_REPORT_REQUEST;
 458   Request.Value       = (UINT16)((ReportType << 8) | ReportId);
 459   Request.Index       = Interface;
 460   Request.Length      = ReportLen;
 461
 462   Result = UsbIo->UsbControlTransfer (
 463                     UsbIo,
 464                     &Request,
 465                     EfiUsbDataIn,
 466                     PcdGet32 (PcdUsbTransferTimeoutValue),
 467                     Report,
 468                     ReportLen,
 469                     &Status
 470                     );
 471
 472   return Result;
 473 }