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<BR>
   6 All rights reserved. This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16
  17 #ifndef __USB_DXE_LIB_H__
  18 #define __USB_DXE_LIB_H__
  19
  20 #include <Protocol/UsbIo.h>
  21
  22 ///
  23 /// define the timeout time as 3ms
  24 ///
  25 #define TIMEOUT_VALUE 3 * 1000
  26
  27 /**
  28   Get Hid Descriptor.
  29
  30   @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.
  31   @param  InterfaceNum      Hid interface number.
  32   @param  HidDescriptor     Caller allocated buffer to store Usb hid descriptor if
  33                             successfully returned.
  34
  35   @return Status of getting HID descriptor through USB I/O
  36           protocol's UsbControlTransfer().
  37
  38 **/
  39 EFI_STATUS
  40 EFIAPI
  41 UsbGetHidDescriptor (
  42   IN  EFI_USB_IO_PROTOCOL        *UsbIo,
  43   IN  UINT8                      InterfaceNum,
  44   OUT EFI_USB_HID_DESCRIPTOR     *HidDescriptor
  45   );
  46
  47
  48 /**
  49   get Report Class descriptor.
  50
  51   @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.
  52   @param  InterfaceNum      Report interface number.
  53   @param  DescriptorSize    Length of DescriptorBuffer.
  54   @param  DescriptorBuffer  Caller allocated buffer to store Usb report descriptor
  55                             if successfully returned.
  56
  57   @return Status of getting Report Class descriptor through USB
  58           I/O protocol's UsbControlTransfer().
  59
  60 **/
  61 EFI_STATUS
  62 EFIAPI
  63 UsbGetReportDescriptor (
  64   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
  65   IN  UINT8                   InterfaceNum,
  66   IN  UINT16                  DescriptorSize,
  67   OUT UINT8                   *DescriptorBuffer
  68   );
  69
  70 /**
  71   Get Hid Protocol Request.
  72
  73   @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.
  74   @param  Interface         Which interface the caller wants to get protocol.
  75   @param  Protocol          Protocol value returned.
  76
  77   @return Status of getting Protocol Request through USB I/O
  78           protocol's UsbControlTransfer().
  79
  80 **/
  81 EFI_STATUS
  82 EFIAPI
  83 UsbGetProtocolRequest (
  84   IN EFI_USB_IO_PROTOCOL     *UsbIo,
  85   IN UINT8                   Interface,
  86   IN UINT8                   *Protocol
  87   );
  88
  89 /**
  90   Set Hid Protocol Request.
  91
  92   @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.
  93   @param  Interface         Which interface the caller wants to set protocol.
  94   @param  Protocol          Protocol value the caller wants to set.
  95
  96   @return Status of setting Protocol Request through USB I/O
  97           protocol's UsbControlTransfer().
  98
  99 **/
 100 EFI_STATUS
 101 EFIAPI
 102 UsbSetProtocolRequest (
 103   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 104   IN UINT8                   Interface,
 105   IN UINT8                   Protocol
 106   );
 107
 108 /**
 109   Set Idel request.
 110
 111   @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.
 112   @param  Interface         Which interface the caller wants to set.
 113   @param  ReportId          Which report the caller wants to set.
 114   @param  Duration          Idle rate the caller wants to set.
 115
 116   @return Status of setting IDLE Request through USB I/O
 117           protocol's UsbControlTransfer().
 118
 119 **/
 120 EFI_STATUS
 121 EFIAPI
 122 UsbSetIdleRequest (
 123   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 124   IN UINT8                   Interface,
 125   IN UINT8                   ReportId,
 126   IN UINT8                   Duration
 127   );
 128
 129 /**
 130   Get Idel request.
 131
 132   @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.
 133   @param  Interface         Which interface the caller wants to get.
 134   @param  ReportId          Which report the caller wants to get.
 135   @param  Duration          Idle rate the caller wants to get.
 136
 137   @return Status of getting IDLE Request through USB I/O
 138           protocol's UsbControlTransfer().
 139
 140 **/
 141 EFI_STATUS
 142 EFIAPI
 143 UsbGetIdleRequest (
 144   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 145   IN  UINT8                   Interface,
 146   IN  UINT8                   ReportId,
 147   OUT UINT8                   *Duration
 148   );
 149
 150 /**
 151   Hid Set Report request.
 152
 153   @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.
 154   @param  Interface         Which interface the caller wants to set.
 155   @param  ReportId          Which report the caller wants to set.
 156   @param  ReportType        Type of report.
 157   @param  ReportLen         Length of report descriptor.
 158   @param  Report            Report Descriptor buffer.
 159
 160   @return Status of setting Report Request through USB I/O
 161           protocol's UsbControlTransfer().
 162
 163 **/
 164 EFI_STATUS
 165 EFIAPI
 166 UsbSetReportRequest (
 167   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 168   IN UINT8                   Interface,
 169   IN UINT8                   ReportId,
 170   IN UINT8                   ReportType,
 171   IN UINT16                  ReportLen,
 172   IN UINT8                   *Report
 173   );
 174
 175 /**
 176   Hid Set Report request.
 177
 178   @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.
 179   @param  Interface         Which interface the caller wants to set.
 180   @param  ReportId          Which report the caller wants to set.
 181   @param  ReportType        Type of report.
 182   @param  ReportLen         Length of report descriptor.
 183   @param  Report            Caller allocated buffer to store Report Descriptor.
 184
 185   @return Status of getting Report Request through USB I/O
 186           protocol's UsbControlTransfer().
 187
 188 **/
 189 EFI_STATUS
 190 EFIAPI
 191 UsbGetReportRequest (
 192   IN EFI_USB_IO_PROTOCOL     *UsbIo,
 193   IN UINT8                   Interface,
 194   IN UINT8                   ReportId,
 195   IN UINT8                   ReportType,
 196   IN UINT16                  ReportLen,
 197   IN UINT8                   *Report
 198   );
 199
 200 /**
 201   Usb Get Descriptor.
 202
 203   @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.
 204   @param  Value                  Device Request Value.
 205   @param  Index                  Device Request Index.
 206   @param  DescriptorLength       Descriptor Length.
 207   @param  Descriptor             Descriptor buffer to contain result.
 208   @param  Status                 Transfer Status.
 209
 210   @retval EFI_INVALID_PARAMETER  Parameter is error.
 211   @retval EFI_SUCCESS            Success.
 212   @retval EFI_TIMEOUT            Device has no response.
 213
 214 **/
 215 EFI_STATUS
 216 EFIAPI
 217 UsbGetDescriptor (
 218   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 219   IN  UINT16                  Value,
 220   IN  UINT16                  Index,
 221   IN  UINT16                  DescriptorLength,
 222   OUT VOID                    *Descriptor,
 223   OUT UINT32                  *Status
 224   );
 225
 226 /**
 227   Usb Set Descriptor.
 228
 229   @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.
 230   @param  Value                  Device Request Value.
 231   @param  Index                  Device Request Index.
 232   @param  DescriptorLength       Descriptor Length.
 233   @param  Descriptor             Descriptor buffer to set.
 234   @param  Status                 Transfer Status.
 235
 236   @retval EFI_INVALID_PARAMETER  Parameter is error.
 237   @retval EFI_SUCCESS            Success.
 238   @retval EFI_TIMEOUT            Device has no response.
 239
 240 **/
 241 EFI_STATUS
 242 EFIAPI
 243 UsbSetDescriptor (
 244   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 245   IN  UINT16                  Value,
 246   IN  UINT16                  Index,
 247   IN  UINT16                  DescriptorLength,
 248   IN  VOID                    *Descriptor,
 249   OUT UINT32                  *Status
 250   );
 251
 252 /**
 253   Usb Get Device Interface.
 254
 255   @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.
 256   @param  Index                  Interface index value.
 257   @param  AltSetting             Alternate setting.
 258   @param  Status                 Trasnsfer status.
 259
 260   @retval EFI_INVALID_PARAMETER  Parameter is error.
 261   @retval EFI_SUCCESS            Success.
 262   @retval EFI_TIMEOUT            Device has no response.
 263
 264 **/
 265 EFI_STATUS
 266 EFIAPI
 267 UsbGetInterface (
 268   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 269   IN  UINT16                  Index,
 270   OUT UINT8                   *AltSetting,
 271   OUT UINT32                  *Status
 272   );
 273
 274 /**
 275   Usb Set Device Interface.
 276
 277   @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.
 278   @param  InterfaceNo            Interface Number.
 279   @param  AltSetting             Alternate setting.
 280   @param  Status                 Trasnsfer status.
 281
 282   @retval EFI_INVALID_PARAMETER  Parameter is error.
 283   @retval EFI_SUCCESS            Success.
 284   @retval EFI_TIMEOUT            Device has no response.
 285
 286 **/
 287 EFI_STATUS
 288 EFIAPI
 289 UsbSetInterface (
 290   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 291   IN  UINT16                  InterfaceNo,
 292   IN  UINT16                  AltSetting,
 293   OUT UINT32                  *Status
 294   );
 295
 296 /**
 297   Usb Get Device Configuration.
 298
 299   @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.
 300   @param  ConfigValue            Config Value.
 301   @param  Status                 Transfer Status.
 302
 303   @retval EFI_INVALID_PARAMETER  Parameter is error.
 304   @retval EFI_SUCCESS            Success.
 305   @retval EFI_TIMEOUT            Device has no response.
 306
 307 **/
 308 EFI_STATUS
 309 EFIAPI
 310 UsbGetConfiguration (
 311   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 312   OUT UINT8                   *ConfigValue,
 313   OUT UINT32                  *Status
 314   );
 315
 316 /**
 317   Usb Set Device Configuration.
 318
 319   @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.
 320   @param  Value                  Configuration Value to set.
 321   @param  Status                 Transfer status.
 322
 323   @retval EFI_INVALID_PARAMETER  Parameter is error.
 324   @retval EFI_SUCCESS            Success.
 325   @retval EFI_TIMEOUT            Device has no response.
 326
 327 **/
 328 EFI_STATUS
 329 EFIAPI
 330 UsbSetConfiguration (
 331   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 332   IN  UINT16                  Value,
 333   OUT UINT32                  *Status
 334   );
 335
 336 /**
 337   Usb Set Device Feature.
 338
 339   @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.
 340   @param  Recipient              Interface/Device/Endpoint.
 341   @param  Value                  Request value.
 342   @param  Target                 Request Index.
 343   @param  Status                 Transfer status.
 344
 345   @retval EFI_INVALID_PARAMETER  Parameter is error.
 346   @retval EFI_SUCCESS            Success.
 347   @retval EFI_TIMEOUT            Device has no response.
 348
 349 **/
 350 EFI_STATUS
 351 EFIAPI
 352 UsbSetFeature (
 353   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 354   IN  UINTN                   Recipient,
 355   IN  UINT16                  Value,
 356   IN  UINT16                  Target,
 357   OUT UINT32                  *Status
 358   );
 359
 360 /**
 361   Usb Clear Device Feature.
 362
 363   @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.
 364   @param  Recipient              Interface/Device/Endpoint.
 365   @param  Value                  Request value.
 366   @param  Target                 Request Index.
 367   @param  Status                 Transfer status.
 368
 369   @retval EFI_INVALID_PARAMETER  Parameter is error.
 370   @retval EFI_SUCCESS            Success.
 371   @retval EFI_TIMEOUT            Device has no response.
 372
 373 **/
 374 EFI_STATUS
 375 EFIAPI
 376 UsbClearFeature (
 377   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 378   IN  UINTN                   Recipient,
 379   IN  UINT16                  Value,
 380   IN  UINT16                  Target,
 381   OUT UINT32                  *Status
 382   );
 383
 384 /**
 385   Usb Get Device Status.
 386
 387   @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.
 388   @param  Recipient              Interface/Device/Endpoint.
 389   @param  Target                 Request index.
 390   @param  DevStatus              Device status.
 391   @param  Status                 Transfer status.
 392
 393   @retval EFI_INVALID_PARAMETER  Parameter is error.
 394   @retval EFI_SUCCESS            Success.
 395   @retval EFI_TIMEOUT            Device has no response.
 396
 397 **/
 398 EFI_STATUS
 399 EFIAPI
 400 UsbGetStatus (
 401   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 402   IN  UINTN                   Recipient,
 403   IN  UINT16                  Target,
 404   OUT UINT16                  *DevStatus,
 405   OUT UINT32                  *Status
 406   );
 407
 408 /**
 409   Clear endpoint stall.
 410
 411   @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.
 412   @param  EndpointNo             Endpoint Number.
 413   @param  Status                 Transfer Status.
 414
 415   @retval EFI_NOT_FOUND          Can't find the Endpoint.
 416   @retval EFI_DEVICE_ERROR       Hardware error.
 417   @retval EFI_SUCCESS            Success.
 418
 419 **/
 420 EFI_STATUS
 421 EFIAPI
 422 UsbClearEndpointHalt (
 423   IN  EFI_USB_IO_PROTOCOL     *UsbIo,
 424   IN  UINT8                   EndpointNo,
 425   OUT UINT32                  *Status
 426   );
 427
 428 #endif