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