MdePkg/Include/Library/UefiUsbLib.h

   1 /** @file
   2   Provides most USB APIs to support the Hid requests defined in USB Hid 1.1 spec
   3   and the standard requests defined in USB 1.1 spec.
   4
   5 Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __USB_DXE_LIB_H__
  11 #define __USB_DXE_LIB_H__
  12
  13 #include <Protocol/UsbIo.h>
  14
  15 /**
  16   Get the descriptor of the specified USB HID interface.
  17
  18   Submit a UsbGetHidDescriptor() request for the USB device specified by UsbIo
  19   and Interface, and return the HID descriptor in HidDescriptor.
  20   If UsbIo is NULL, then ASSERT().
  21   If HidDescriptor is NULL, then ASSERT().
  22
  23   @param  UsbIo          A pointer to the USB I/O Protocol instance for the specific USB target.
  24   @param  Interface      The index of the HID interface on the USB target.
  25   @param  HidDescriptor  Pointer to the USB HID descriptor that was retrieved from
  26                          the specified USB target and interface. Type EFI_USB_HID_DESCRIPTOR
  27                          is defined in the MDE Package Industry Standard include file Usb.h.
  28
  29   @retval EFI_SUCCESS       The request executed successfully.
  30   @retval EFI_TIMEOUT       A timeout occurred executing the request.
  31   @retval EFI_DEVICE_ERROR  The request failed due to a device error.
  32
  33 **/
  34 EFI_STATUS
  35 EFIAPI
  36 UsbGetHidDescriptor (
  37   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
  38   IN  UINT8                   Interface,
  39   OUT EFI_USB_HID_DESCRIPTOR  *HidDescriptor
  40   );
  41
  42 /**
  43   Get the report descriptor of the specified USB HID interface.
  44
  45   Submit a USB get HID report descriptor request for the USB device specified by
  46   UsbIo and Interface, and return the report descriptor in DescriptorBuffer.
  47   If UsbIo is NULL, then ASSERT().
  48   If DescriptorBuffer is NULL, then ASSERT().
  49
  50   @param  UsbIo             A pointer to the USB I/O Protocol instance for the specific USB target.
  51   @param  Interface         The index of the report interface on the USB target.
  52   @param  DescriptorLength  The size, in bytes, of DescriptorBuffer.
  53   @param  DescriptorBuffer  A pointer to the buffer to store the report class descriptor.
  54
  55   @retval  EFI_SUCCESS           The request executed successfully.
  56   @retval  EFI_OUT_OF_RESOURCES  The request could not be completed because the
  57                                  buffer specified by DescriptorLength and DescriptorBuffer
  58                                  is not large enough to hold the result of the request.
  59   @retval  EFI_TIMEOUT           A timeout occurred executing the request.
  60   @retval  EFI_DEVICE_ERROR      The request failed due to a device error.
  61
  62 **/
  63 EFI_STATUS
  64 EFIAPI
  65 UsbGetReportDescriptor (
  66   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
  67   IN  UINT8                Interface,
  68   IN  UINT16               DescriptorLength,
  69   OUT UINT8                *DescriptorBuffer
  70   );
  71
  72 /**
  73   Get the HID protocol of the specified USB HID interface.
  74
  75   Submit a USB get HID protocol request for the USB device specified by UsbIo
  76   and Interface, and return the protocol retrieved in Protocol.
  77   If UsbIo is NULL, then ASSERT().
  78   If Protocol is NULL, then ASSERT().
  79
  80   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
  81   @param  Interface  The index of the report interface on the USB target.
  82   @param  Protocol   A pointer to the protocol for the specified USB target.
  83
  84   @retval  EFI_SUCCESS       The request executed successfully.
  85   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
  86   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
  87
  88 **/
  89 EFI_STATUS
  90 EFIAPI
  91 UsbGetProtocolRequest (
  92   IN EFI_USB_IO_PROTOCOL  *UsbIo,
  93   IN UINT8                Interface,
  94   OUT UINT8               *Protocol
  95   );
  96
  97 /**
  98   Set the HID protocol of the specified USB HID interface.
  99
 100   Submit a USB set HID protocol request for the USB device specified by UsbIo
 101   and Interface, and set the protocol to the value specified by Protocol.
 102   If UsbIo is NULL, then ASSERT().
 103
 104   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 105   @param  Interface  The index of the report interface on the USB target.
 106   @param  Protocol   The protocol value to set for the specified USB target.
 107
 108   @retval  EFI_SUCCESS       The request executed successfully.
 109   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 110   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 111
 112 **/
 113 EFI_STATUS
 114 EFIAPI
 115 UsbSetProtocolRequest (
 116   IN EFI_USB_IO_PROTOCOL  *UsbIo,
 117   IN UINT8                Interface,
 118   IN UINT8                Protocol
 119   );
 120
 121 /**
 122   Set the idle rate of the specified USB HID report.
 123
 124   Submit a USB set HID report idle request for the USB device specified by UsbIo,
 125   Interface, and ReportId, and set the idle rate to the value specified by Duration.
 126   If UsbIo is NULL, then ASSERT().
 127
 128   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 129   @param  Interface  The index of the report interface on the USB target.
 130   @param  ReportId   The identifier of the report to retrieve.
 131   @param  Duration   The idle rate to set for the specified USB target.
 132
 133   @retval  EFI_SUCCESS       The request executed successfully.
 134   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 135   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 136
 137 **/
 138 EFI_STATUS
 139 EFIAPI
 140 UsbSetIdleRequest (
 141   IN EFI_USB_IO_PROTOCOL  *UsbIo,
 142   IN UINT8                Interface,
 143   IN UINT8                ReportId,
 144   IN UINT8                Duration
 145   );
 146
 147 /**
 148   Get the idle rate of the specified USB HID report.
 149
 150   Submit a USB get HID report idle request for the USB device specified by UsbIo,
 151   Interface, and ReportId, and return the ide rate in Duration.
 152   If UsbIo is NULL, then ASSERT().
 153   If Duration is NULL, then ASSERT().
 154
 155   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 156   @param  Interface  The index of the report interface on the USB target.
 157   @param  ReportId   The identifier of the report to retrieve.
 158   @param  Duration   A pointer to the idle rate retrieved from the specified USB target.
 159
 160   @retval  EFI_SUCCESS       The request executed successfully.
 161   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 162   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 163
 164 **/
 165 EFI_STATUS
 166 EFIAPI
 167 UsbGetIdleRequest (
 168   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 169   IN  UINT8                Interface,
 170   IN  UINT8                ReportId,
 171   OUT UINT8                *Duration
 172   );
 173
 174 /**
 175   Set the report descriptor of the specified USB HID interface.
 176
 177   Submit a USB set HID report request for the USB device specified by UsbIo,
 178   Interface, ReportId, and ReportType, and set the report descriptor using the
 179   buffer specified by ReportLength and Report.
 180   If UsbIo is NULL, then ASSERT().
 181   If Report is NULL, then ASSERT().
 182
 183   @param  UsbIo         A pointer to the USB I/O Protocol instance for the specific USB target.
 184   @param  Interface     The index of the report interface on the USB target.
 185   @param  ReportId      The identifier of the report to retrieve.
 186   @param  ReportType    The type of report to retrieve.
 187   @param  ReportLength  The size, in bytes, of Report.
 188   @param  Report        A pointer to the report descriptor buffer to set.
 189
 190   @retval  EFI_SUCCESS       The request executed successfully.
 191   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 192   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 193
 194 **/
 195 EFI_STATUS
 196 EFIAPI
 197 UsbSetReportRequest (
 198   IN EFI_USB_IO_PROTOCOL  *UsbIo,
 199   IN UINT8                Interface,
 200   IN UINT8                ReportId,
 201   IN UINT8                ReportType,
 202   IN UINT16               ReportLen,
 203   IN UINT8                *Report
 204   );
 205
 206 /**
 207   Get the report descriptor of the specified USB HID interface.
 208
 209   Submit a USB get HID report request for the USB device specified by UsbIo,
 210   Interface, ReportId, and ReportType, and return the report in the buffer
 211   specified by Report.
 212   If UsbIo is NULL, then ASSERT().
 213   If Report is NULL, then ASSERT().
 214
 215   @param  UsbIo         A pointer to the USB I/O Protocol instance for the specific USB target.
 216   @param  Interface     The index of the report interface on the USB target.
 217   @param  ReportId      The identifier of the report to retrieve.
 218   @param  ReportType    The type of report to retrieve.
 219   @param  ReportLength  The size, in bytes, of Report.
 220   @param  Report        A pointer to the buffer to store the report descriptor.
 221
 222   @retval  EFI_SUCCESS           The request executed successfully.
 223   @retval  EFI_OUT_OF_RESOURCES  The request could not be completed because the
 224                                  buffer specified by ReportLength and Report is not
 225                                  large enough to hold the result of the request.
 226   @retval  EFI_TIMEOUT           A timeout occurred executing the request.
 227   @retval  EFI_DEVICE_ERROR      The request failed due to a device error.
 228
 229 **/
 230 EFI_STATUS
 231 EFIAPI
 232 UsbGetReportRequest (
 233   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 234   IN  UINT8                Interface,
 235   IN  UINT8                ReportId,
 236   IN  UINT8                ReportType,
 237   IN  UINT16               ReportLen,
 238   OUT UINT8                *Report
 239   );
 240
 241 /**
 242   Get the descriptor of the specified USB device.
 243
 244   Submit a USB get descriptor request for the USB device specified by UsbIo, Value,
 245   and Index, and return the descriptor in the buffer specified by Descriptor.
 246   The status of the transfer is returned in Status.
 247   If UsbIo is NULL, then ASSERT().
 248   If Descriptor is NULL, then ASSERT().
 249   If Status is NULL, then ASSERT().
 250
 251   @param  UsbIo             A pointer to the USB I/O Protocol instance for the specific USB target.
 252   @param  Value             The device request value.
 253   @param  Index             The device request index.
 254   @param  DescriptorLength  The size, in bytes, of Descriptor.
 255   @param  Descriptor        A pointer to the descriptor buffer to get.
 256   @param  Status            A pointer to the status of the transfer.
 257
 258   @retval EFI_SUCCESS           The request executed successfully.
 259   @retval EFI_OUT_OF_RESOURCES  The request could not be completed because the
 260                                 buffer specified by DescriptorLength and Descriptor
 261                                 is not large enough to hold the result of the request.
 262   @retval EFI_TIMEOUT           A timeout occurred executing the request.
 263   @retval EFI_DEVICE_ERROR      The request failed due to a device error. The transfer
 264                                 status is returned in Status.
 265
 266 **/
 267 EFI_STATUS
 268 EFIAPI
 269 UsbGetDescriptor (
 270   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 271   IN  UINT16               Value,
 272   IN  UINT16               Index,
 273   IN  UINT16               DescriptorLength,
 274   OUT VOID                 *Descriptor,
 275   OUT UINT32               *Status
 276   );
 277
 278 /**
 279   Set the descriptor of the specified USB device.
 280
 281   Submit a USB set descriptor request for the USB device specified by UsbIo,
 282   Value, and Index, and set the descriptor using the buffer specified by DesriptorLength
 283   and Descriptor.  The status of the transfer is returned in Status.
 284   If UsbIo is NULL, then ASSERT().
 285   If Descriptor is NULL, then ASSERT().
 286   If Status is NULL, then ASSERT().
 287
 288   @param  UsbIo             A pointer to the USB I/O Protocol instance for the specific USB target.
 289   @param  Value             The device request value.
 290   @param  Index             The device request index.
 291   @param  DescriptorLength  The size, in bytes, of Descriptor.
 292   @param  Descriptor        A pointer to the descriptor buffer to set.
 293   @param  Status            A pointer to the status of the transfer.
 294
 295   @retval  EFI_SUCCESS       The request executed successfully.
 296   @retval  EFI_TIMEOUT       A timeout occurred executing the request.
 297   @retval  EFI_DEVICE_ERROR  The request failed due to a device error.
 298                              The transfer status is returned in Status.
 299
 300 **/
 301 EFI_STATUS
 302 EFIAPI
 303 UsbSetDescriptor (
 304   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 305   IN  UINT16               Value,
 306   IN  UINT16               Index,
 307   IN  UINT16               DescriptorLength,
 308   IN  VOID                 *Descriptor,
 309   OUT UINT32               *Status
 310   );
 311
 312 /**
 313   Get the interface setting of the specified USB device.
 314
 315   Submit a USB get interface request for the USB device specified by UsbIo,
 316   and Interface, and place the result in the buffer specified by AlternateSetting.
 317   The status of the transfer is returned in Status.
 318   If UsbIo is NULL, then ASSERT().
 319   If AlternateSetting is NULL, then ASSERT().
 320   If Status is NULL, then ASSERT().
 321
 322   @param  UsbIo             A pointer to the USB I/O Protocol instance for the specific USB target.
 323   @param  Interface         The interface index value.
 324   @param  AlternateSetting  A pointer to the alternate setting to be retrieved.
 325   @param  Status            A pointer to the status of the transfer.
 326
 327   @retval EFI_SUCCESS       The request executed successfully.
 328   @retval EFI_TIMEOUT       A timeout occurred executing the request.
 329   @retval EFI_DEVICE_ERROR  The request failed due to a device error.
 330                             The transfer status is returned in Status.
 331
 332 **/
 333 EFI_STATUS
 334 EFIAPI
 335 UsbGetInterface (
 336   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 337   IN  UINT16               Interface,
 338   OUT UINT16               *AlternateSetting,
 339   OUT UINT32               *Status
 340   );
 341
 342 /**
 343   Set the interface setting of the specified USB device.
 344
 345   Submit a USB set interface request for the USB device specified by UsbIo, and
 346   Interface, and set the alternate setting to the value specified by AlternateSetting.
 347   The status of the transfer is returned in Status.
 348   If UsbIo is NULL, then ASSERT().
 349   If Status is NULL, then ASSERT().
 350
 351   @param  UsbIo             A pointer to the USB I/O Protocol instance for the specific USB target.
 352   @param  Interface         The interface index value.
 353   @param  AlternateSetting  The alternate setting to be set.
 354   @param  Status            A pointer to the status of the transfer.
 355
 356   @retval EFI_SUCCESS  The request executed successfully.
 357   @retval EFI_TIMEOUT  A timeout occurred executing the request.
 358   @retval EFI_SUCCESS  The request failed due to a device error.
 359                        The transfer status is returned in Status.
 360
 361 **/
 362 EFI_STATUS
 363 EFIAPI
 364 UsbSetInterface (
 365   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 366   IN  UINT16               Interface,
 367   IN  UINT16               AlternateSetting,
 368   OUT UINT32               *Status
 369   );
 370
 371 /**
 372   Get the device configuration.
 373
 374   Submit a USB get configuration request for the USB device specified by UsbIo
 375   and place the result in the buffer specified by ConfigurationValue. The status
 376   of the transfer is returned in Status.
 377   If UsbIo is NULL, then ASSERT().
 378   If ConfigurationValue is NULL, then ASSERT().
 379   If Status is NULL, then ASSERT().
 380
 381   @param  UsbIo               A pointer to the USB I/O Protocol instance for the specific USB target.
 382   @param  ConfigurationValue  A pointer to the device configuration to be retrieved.
 383   @param  Status              A pointer to the status of the transfer.
 384
 385   @retval EFI_SUCCESS        The request executed successfully.
 386   @retval EFI_TIMEOUT        A timeout occurred executing the request.
 387   @retval EFI_DEVICE_ERROR   The request failed due to a device error.
 388                              The transfer status is returned in Status.
 389
 390 **/
 391 EFI_STATUS
 392 EFIAPI
 393 UsbGetConfiguration (
 394   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 395   OUT UINT16               *ConfigurationValue,
 396   OUT UINT32               *Status
 397   );
 398
 399 /**
 400   Set the device configuration.
 401
 402   Submit a USB set configuration request for the USB device specified by UsbIo
 403   and set the device configuration to the value specified by ConfigurationValue.
 404   The status of the transfer is returned in Status.
 405   If UsbIo is NULL, then ASSERT().
 406   If Status is NULL, then ASSERT().
 407
 408   @param  UsbIo               A pointer to the USB I/O Protocol instance for the specific USB target.
 409   @param  ConfigurationValue  The device configuration value to be set.
 410   @param  Status              A pointer to the status of the transfer.
 411
 412   @retval EFI_SUCCESS       The request executed successfully.
 413   @retval EFI_TIMEOUT       A timeout occurred executing the request.
 414   @retval EFI_DEVICE_ERROR  The request failed due to a device error.
 415                             The transfer status is returned in Status.
 416
 417 **/
 418 EFI_STATUS
 419 EFIAPI
 420 UsbSetConfiguration (
 421   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 422   IN  UINT16               ConfigurationValue,
 423   OUT UINT32               *Status
 424   );
 425
 426 /**
 427   Set the specified feature of the specified device.
 428
 429   Submit a USB set device feature request for the USB device specified by UsbIo,
 430   Recipient, and Target to the value specified by Value.  The status of the
 431   transfer is returned in Status.
 432   If UsbIo is NULL, then ASSERT().
 433   If Status is NULL, then ASSERT().
 434
 435   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 436   @param  Recipient  The USB data recipient type (i.e. Device, Interface, Endpoint).
 437                      Type USB_TYPES_DEFINITION is defined in the MDE Package Industry
 438                      Standard include file Usb.h.
 439   @param  Value      The value of the feature to be set.
 440   @param  Target     The index of the device to be set.
 441   @param  Status     A pointer to the status of the transfer.
 442
 443   @retval EFI_SUCCESS       The request executed successfully.
 444   @retval EFI_TIMEOUT       A timeout occurred executing the request.
 445   @retval EFI_DEVICE_ERROR  The request failed due to a device error.
 446                             The transfer status is returned in Status.
 447
 448 **/
 449 EFI_STATUS
 450 EFIAPI
 451 UsbSetFeature (
 452   IN  EFI_USB_IO_PROTOCOL   *UsbIo,
 453   IN  USB_TYPES_DEFINITION  Recipient,
 454   IN  UINT16                Value,
 455   IN  UINT16                Target,
 456   OUT UINT32                *Status
 457   );
 458
 459 /**
 460   Clear the specified feature of the specified device.
 461
 462   Submit a USB clear device feature request for the USB device specified by UsbIo,
 463   Recipient, and Target to the value specified by Value.  The status of the transfer
 464   is returned in Status.
 465   If UsbIo is NULL, then ASSERT().
 466   If Status is NULL, then ASSERT().
 467
 468   @param  UsbIo      A pointer to the USB I/O Protocol instance for the specific USB target.
 469   @param  Recipient  The USB data recipient type (i.e. Device, Interface, Endpoint).
 470                      Type USB_TYPES_DEFINITION is defined in the MDE Package Industry Standard
 471                      include file Usb.h.
 472   @param  Value      The value of the feature to be cleared.
 473   @param  Target     The index of the device to be cleared.
 474   @param  Status     A pointer to the status of the transfer.
 475
 476   @retval EFI_SUCCESS       The request executed successfully.
 477   @retval EFI_TIMEOUT       A timeout occurred executing the request.
 478   @retval EFI_DEVICE_ERROR  The request failed due to a device error.
 479                             The transfer status is returned in Status.
 480
 481 **/
 482 EFI_STATUS
 483 EFIAPI
 484 UsbClearFeature (
 485   IN  EFI_USB_IO_PROTOCOL   *UsbIo,
 486   IN  USB_TYPES_DEFINITION  Recipient,
 487   IN  UINT16                Value,
 488   IN  UINT16                Target,
 489   OUT UINT32                *Status
 490   );
 491
 492 /**
 493   Get the status of the specified device.
 494
 495   Submit a USB device get status request for the USB device specified by UsbIo,
 496   Recipient, and Target, and place the result in the buffer specified by DeviceStatus.
 497   The status of the transfer is returned in Status.
 498   If UsbIo is NULL, then ASSERT().
 499   If DeviceStatus is NULL, then ASSERT().
 500   If Status is NULL, then ASSERT().
 501
 502   @param  UsbIo         A pointer to the USB I/O Protocol instance for the specific USB target.
 503   @param  Recipient     The USB data recipient type (i.e. Device, Interface, Endpoint).
 504                         Type USB_TYPES_DEFINITION is defined in the MDE Package Industry Standard
 505                         include file Usb.h.
 506   @param  Target        The index of the device to be get the status of.
 507   @param  DeviceStatus  A pointer to the device status to be retrieved.
 508   @param  Status        A pointer to the status of the transfer.
 509
 510   @retval EFI_SUCCESS       The request executed successfully.
 511   @retval EFI_TIMEOUT       A timeout occurred executing the request.
 512   @retval EFI_DEVICE_ERROR  The request failed due to a device error.
 513                             The transfer status is returned in Status.
 514
 515 **/
 516 EFI_STATUS
 517 EFIAPI
 518 UsbGetStatus (
 519   IN  EFI_USB_IO_PROTOCOL   *UsbIo,
 520   IN  USB_TYPES_DEFINITION  Recipient,
 521   IN  UINT16                Target,
 522   OUT UINT16                *DeviceStatus,
 523   OUT UINT32                *Status
 524   );
 525
 526 /**
 527   Clear halt feature of the specified usb endpoint.
 528
 529   Retrieve the USB endpoint descriptor specified by UsbIo and EndPoint.
 530   If the USB endpoint descriptor can not be retrieved, then return EFI_NOT_FOUND.
 531   If the endpoint descriptor is found, then clear the halt feature of this USB endpoint.
 532   The status of the transfer is returned in Status.
 533   If UsbIo is NULL, then ASSERT().
 534   If Status is NULL, then ASSERT().
 535
 536   @param  UsbIo     A pointer to the USB I/O Protocol instance for the specific USB target.
 537   @param  Endpoint  The endpoint address.
 538   @param  Status    A pointer to the status of the transfer.
 539
 540   @retval EFI_SUCCESS       The request executed successfully.
 541   @retval EFI_TIMEOUT       A timeout occurred executing the request.
 542   @retval EFI_DEVICE_ERROR  The request failed due to a device error.
 543                             The transfer status is returned in Status.
 544   @retval EFI_NOT_FOUND     The specified USB endpoint descriptor can not be found
 545
 546 **/
 547 EFI_STATUS
 548 EFIAPI
 549 UsbClearEndpointHalt (
 550   IN  EFI_USB_IO_PROTOCOL  *UsbIo,
 551   IN  UINT8                Endpoint,
 552   OUT UINT32               *Status
 553   );
 554
 555 #endif