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 /**
  81   Get the report descriptor of the specified USB HID interface.
  82
  83   Submit a USB get HID report descriptor request for the USB device specified by
  84   UsbIo and Interface and return the report descriptor in DescriptorBuffer.
  85   If UsbIo is NULL, then ASSERT().
  86   If DescriptorBuffer is NULL, then ASSERT().
  87
  88   @param  UsbIo             A pointer to the USB I/O Protocol instance for the specific USB target.
  89   @param  Interface         The index of the report interface on the USB target.
  90   @param  DescriptorLength  The size, in bytes, of DescriptorBuffer.
  91   @param  DescriptorBuffer  A pointer to the buffer to store the report class descriptor.
  92
  93   @retval  EFI_SUCCESS           The request executed successfully.
  94   @retval  EFI_OUT_OF_RESOURCES  The request could not be completed because the
  95                                  buffer specified by DescriptorLength and DescriptorBuffer
  96                                  is not large enough to hold the result of the request.
  97   @retval  EFI_TIMEOUT           A timeout occurred executing the request.
  98   @retval  EFI_DEVICE_ERROR      The request failed due to a device error.
  99
 100 **/
 101 EFI_STATUS
 102 EFIAPI
 103 UsbGetReportDescriptor (
 104   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 105   IN  UINT8                   Interface,
 106   IN  UINT16                  DescriptorLength,
 107   OUT UINT8                   *DescriptorBuffer
 108   )
 109 {
 110   UINT32                  Status;
 111   EFI_STATUS              Result;
 112   EFI_USB_DEVICE_REQUEST  Request;
 113
 114   ASSERT (UsbIo != NULL);
 115   ASSERT (DescriptorBuffer != NULL);
 116
 117   //
 118   // Fill Device request packet
 119   //
 120   Request.RequestType = USB_HID_GET_DESCRIPTOR_REQ_TYPE;
 121   Request.Request     = USB_REQ_GET_DESCRIPTOR;
 122   Request.Value       = (UINT16) (USB_DESC_TYPE_REPORT << 8);
 123   Request.Index       = Interface;
 124   Request.Length      = DescriptorLength;
 125
 126   Result = UsbIo->UsbControlTransfer (
 127                     UsbIo,
 128                     &Request,
 129                     EfiUsbDataIn,
 130                     PcdGet32 (PcdUsbTransferTimeoutValue),
 131                     DescriptorBuffer,
 132                     DescriptorLength,
 133                     &Status
 134                     );
 135
 136   return Result;
 137
 138 }
 139
 140 /**
 141   Get the HID protocol of the specified USB HID interface.
 142
 143   Submit a USB get HID protocol request for the USB device specified by UsbIo
 144   and Interface and return the protocol retrieved in Protocol.
 145   If UsbIo is NULL, then ASSERT().
 146   If Protocol is NULL, then ASSERT().
 147
 148   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 149   @param  Interface  The index of the report interface on the USB target.
 150   @param  Protocol   A pointer to the protocol for the specified USB target.
 151
 152   @retval  EFI_SUCCESS       The request executed successfully.
 153   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 154   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 155
 156 **/
 157 EFI_STATUS
 158 EFIAPI
 159 UsbGetProtocolRequest (
 160   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 161   IN UINT8                   Interface,
 162   OUT UINT8                   *Protocol
 163   )
 164 {
 165   UINT32                  Status;
 166   EFI_STATUS              Result;
 167   EFI_USB_DEVICE_REQUEST  Request;
 168
 169   ASSERT (UsbIo != NULL);
 170   ASSERT (Protocol != NULL);
 171
 172   //
 173   // Fill Device request packet
 174   //
 175   Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;
 176   Request.Request = EFI_USB_GET_PROTOCOL_REQUEST;
 177   Request.Value   = 0;
 178   Request.Index   = Interface;
 179   Request.Length  = 1;
 180
 181   Result = UsbIo->UsbControlTransfer (
 182                     UsbIo,
 183                     &Request,
 184                     EfiUsbDataIn,
 185                     PcdGet32 (PcdUsbTransferTimeoutValue),
 186                     Protocol,
 187                     sizeof (UINT8),
 188                     &Status
 189                     );
 190
 191   return Result;
 192 }
 193
 194
 195
 196 /**
 197   Set the HID protocol of the specified USB HID interface.
 198
 199   Submit a USB set HID protocol request for the USB device specified by UsbIo
 200   and Interface and set the protocol to the value specified by Protocol.
 201   If UsbIo is NULL, then ASSERT().
 202
 203   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 204   @param  Interface  The index of the report interface on the USB target.
 205   @param  Protocol   The protocol value to set for the specified USB target.
 206
 207   @retval  EFI_SUCCESS       The request executed successfully.
 208   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 209   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 210
 211 **/
 212 EFI_STATUS
 213 EFIAPI
 214 UsbSetProtocolRequest (
 215   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 216   IN UINT8                   Interface,
 217   IN UINT8                   Protocol
 218   )
 219 {
 220   UINT32                  Status;
 221   EFI_STATUS              Result;
 222   EFI_USB_DEVICE_REQUEST  Request;
 223
 224   ASSERT (UsbIo != NULL);
 225
 226   //
 227   // Fill Device request packet
 228   //
 229   Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;
 230   Request.Request = EFI_USB_SET_PROTOCOL_REQUEST;
 231   Request.Value   = Protocol;
 232   Request.Index   = Interface;
 233   Request.Length  = 0;
 234
 235   Result = UsbIo->UsbControlTransfer (
 236                     UsbIo,
 237                     &Request,
 238                     EfiUsbNoData,
 239                     PcdGet32 (PcdUsbTransferTimeoutValue),
 240                     NULL,
 241                     0,
 242                     &Status
 243                     );
 244   return Result;
 245 }
 246
 247
 248 /**
 249   Set the idle rate of the specified USB HID report.
 250
 251   Submit a USB set HID report idle request for the USB device specified by UsbIo,
 252   Interface, and ReportId, and set the idle rate to the value specified by Duration.
 253   If UsbIo is NULL, then ASSERT().
 254
 255   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 256   @param  Interface  The index of the report interface on the USB target.
 257   @param  ReportId   The identifier of the report to retrieve.
 258   @param  Duration   The idle rate to set for the specified USB target.
 259
 260   @retval  EFI_SUCCESS       The request executed successfully.
 261   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 262   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 263
 264 **/
 265 EFI_STATUS
 266 EFIAPI
 267 UsbSetIdleRequest (
 268   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 269   IN UINT8                   Interface,
 270   IN UINT8                   ReportId,
 271   IN UINT8                   Duration
 272   )
 273 {
 274   UINT32                  Status;
 275   EFI_STATUS              Result;
 276   EFI_USB_DEVICE_REQUEST  Request;
 277
 278   ASSERT (UsbIo != NULL);
 279   //
 280   // Fill Device request packet
 281   //
 282   Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;
 283   Request.Request = EFI_USB_SET_IDLE_REQUEST;
 284   Request.Value   = (UINT16) ((Duration << 8) | ReportId);
 285   Request.Index   = Interface;
 286   Request.Length  = 0;
 287
 288   Result = UsbIo->UsbControlTransfer (
 289                     UsbIo,
 290                     &Request,
 291                     EfiUsbNoData,
 292                     PcdGet32 (PcdUsbTransferTimeoutValue),
 293                     NULL,
 294                     0,
 295                     &Status
 296                     );
 297   return Result;
 298 }
 299
 300
 301 /**
 302   Get the idle rate of the specified USB HID report.
 303
 304   Submit a USB get HID report idle request for the USB device specified by UsbIo,
 305   Interface, and ReportId, and return the ide rate in Duration.
 306   If UsbIo is NULL, then ASSERT().
 307   If Duration is NULL, then ASSERT().
 308
 309   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 310   @param  Interface  The index of the report interface on the USB target.
 311   @param  ReportId   The identifier of the report to retrieve.
 312   @param  Duration   A pointer to the idle rate retrieved from the specified USB target.
 313
 314   @retval  EFI_SUCCESS       The request executed successfully.
 315   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 316   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 317
 318 **/
 319 EFI_STATUS
 320 EFIAPI
 321 UsbGetIdleRequest (
 322   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 323   IN  UINT8                   Interface,
 324   IN  UINT8                   ReportId,
 325   OUT UINT8                   *Duration
 326   )
 327 {
 328   UINT32                  Status;
 329   EFI_STATUS              Result;
 330   EFI_USB_DEVICE_REQUEST  Request;
 331
 332   ASSERT (UsbIo != NULL);
 333   ASSERT (Duration != NULL);
 334   //
 335   // Fill Device request packet
 336   //
 337   Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;
 338   Request.Request = EFI_USB_GET_IDLE_REQUEST;
 339   Request.Value   = ReportId;
 340   Request.Index   = Interface;
 341   Request.Length  = 1;
 342
 343   Result = UsbIo->UsbControlTransfer (
 344                     UsbIo,
 345                     &Request,
 346                     EfiUsbDataIn,
 347                     PcdGet32 (PcdUsbTransferTimeoutValue),
 348                     Duration,
 349                     1,
 350                     &Status
 351                     );
 352
 353   return Result;
 354 }
 355
 356
 357
 358 /**
 359   Set the report descriptor of the specified USB HID interface.
 360
 361   Submit a USB set HID report request for the USB device specified by UsbIo,
 362   Interface, ReportId, and ReportType, and set the report descriptor using the
 363   buffer specified by ReportLength and Report.
 364   If UsbIo is NULL, then ASSERT().
 365   If Report is NULL, then ASSERT().
 366
 367   @param  UsbIo         A pointer to the USB I/O Protocol instance for the specific USB target.
 368   @param  Interface     The index of the report interface on the USB target.
 369   @param  ReportId      The identifier of the report to retrieve.
 370   @param  ReportType    The type of report to retrieve.
 371   @param  ReportLength  The size, in bytes, of Report.
 372   @param  Report        A pointer to the report descriptor buffer to set.
 373
 374   @retval  EFI_SUCCESS       The request executed successfully.
 375   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 376   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 377
 378 **/
 379 EFI_STATUS
 380 EFIAPI
 381 UsbSetReportRequest (
 382   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 383   IN UINT8                   Interface,
 384   IN UINT8                   ReportId,
 385   IN UINT8                   ReportType,
 386   IN UINT16                  ReportLen,
 387   IN UINT8                   *Report
 388   )
 389 {
 390   UINT32                  Status;
 391   EFI_STATUS              Result;
 392   EFI_USB_DEVICE_REQUEST  Request;
 393
 394   ASSERT (UsbIo != NULL);
 395   ASSERT (Report != NULL);
 396
 397   //
 398   // Fill Device request packet
 399   //
 400   Request.RequestType = USB_HID_CLASS_SET_REQ_TYPE;
 401   Request.Request = EFI_USB_SET_REPORT_REQUEST;
 402   Request.Value   = (UINT16) ((ReportType << 8) | ReportId);
 403   Request.Index   = Interface;
 404   Request.Length  = ReportLen;
 405
 406   Result = UsbIo->UsbControlTransfer (
 407                     UsbIo,
 408                     &Request,
 409                     EfiUsbDataOut,
 410                     PcdGet32 (PcdUsbTransferTimeoutValue),
 411                     Report,
 412                     ReportLen,
 413                     &Status
 414                     );
 415
 416   return Result;
 417 }
 418
 419
 420 /**
 421   Get the report descriptor of the specified USB HID interface.
 422
 423   Submit a USB get HID report request for the USB device specified by UsbIo,
 424   Interface, ReportId, and ReportType, and return the report in the buffer
 425   specified by Report.
 426   If UsbIo is NULL, then ASSERT().
 427   If Report is NULL, then ASSERT().
 428
 429   @param  UsbIo         A pointer to the USB I/O Protocol instance for the specific USB target.
 430   @param  Interface     The index of the report interface on the USB target.
 431   @param  ReportId      The identifier of the report to retrieve.
 432   @param  ReportType    The type of report to retrieve.
 433   @param  ReportLength  The size, in bytes, of Report.
 434   @param  Report        A pointer to the buffer to store the report descriptor.
 435
 436   @retval  EFI_SUCCESS           The request executed successfully.
 437   @retval  EFI_OUT_OF_RESOURCES  The request could not be completed because the
 438                                  buffer specified by ReportLength and Report is not
 439                                  large enough to hold the result of the request.
 440   @retval  EFI_TIMEOUT           A timeout occurred executing the request.
 441   @retval  EFI_DEVICE_ERROR      The request failed due to a device error.
 442
 443 **/
 444 EFI_STATUS
 445 EFIAPI
 446 UsbGetReportRequest (
 447   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 448   IN  UINT8                   Interface,
 449   IN  UINT8                   ReportId,
 450   IN  UINT8                   ReportType,
 451   IN  UINT16                  ReportLen,
 452   OUT UINT8                   *Report
 453   )
 454 {
 455   UINT32                  Status;
 456   EFI_STATUS              Result;
 457   EFI_USB_DEVICE_REQUEST  Request;
 458
 459   ASSERT (UsbIo != NULL);
 460   ASSERT (Report != NULL);
 461
 462   //
 463   // Fill Device request packet
 464   //
 465   Request.RequestType = USB_HID_CLASS_GET_REQ_TYPE;
 466   Request.Request = EFI_USB_GET_REPORT_REQUEST;
 467   Request.Value   = (UINT16) ((ReportType << 8) | ReportId);
 468   Request.Index   = Interface;
 469   Request.Length  = ReportLen;
 470
 471   Result = UsbIo->UsbControlTransfer (
 472                     UsbIo,
 473                     &Request,
 474                     EfiUsbDataIn,
 475                     PcdGet32 (PcdUsbTransferTimeoutValue),
 476                     Report,
 477                     ReportLen,
 478                     &Status
 479                     );
 480
 481   return Result;
 482 }