Update Hob Instance to remove the unused InternalHobLib.h file.

[mirror_edk2.git] / MdePkg / Include / Library / UsbLib.h

diff --git a/MdePkg/Include/Library/UsbLib.h b/MdePkg/Include/Library/UsbLib.h
index f3b56fbb80f4ebf551abb44281dbda27028458cc..ad482188820d6c2f6be04b96171748915d93a342 100644 (file)
--- a/MdePkg/Include/Library/UsbLib.h
+++ b/MdePkg/Include/Library/UsbLib.h
@@ -1,7 +1,7 @@
 /** @file\r
-  Common Dxe Libarary  for USB\r
+  Common Dxe Libarary  for USB.\r
 \r
-  Copyright (c) 2006, Intel Corporation<BR>\r
+  Copyright (c) 2006 - 2008, Intel Corporation<BR>\r
   All rights reserved. This program and the accompanying materials\r
   are licensed and made available under the terms and conditions of the BSD License\r
   which accompanies this distribution.  The full text of the license may be found at\r
@@ -18,11 +18,23 @@
 \r
 #include <Protocol/UsbIo.h>\r
 \r
-//\r
-// define the timeout time as 3ms\r
-//\r
+///\r
+/// define the timeout time as 3ms\r
+///\r
 #define TIMEOUT_VALUE 3 * 1000\r
 \r
+/**\r
+  Get Hid Descriptor.\r
+\r
+  @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  InterfaceNum      Hid interface number.\r
+  @param  HidDescriptor     Caller allocated buffer to store Usb hid descriptor if\r
+                            successfully returned.\r
+\r
+  @return Status of getting HID descriptor through USB I/O\r
+          protocol's UsbControlTransfer().\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbGetHidDescriptor (\r
@@ -31,6 +43,20 @@ UsbGetHidDescriptor (
   OUT EFI_USB_HID_DESCRIPTOR     *HidDescriptor\r
   );\r
 \r
+\r
+/**\r
+  get Report Class descriptor.\r
+\r
+  @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  InterfaceNum      Report interface number.\r
+  @param  DescriptorSize    Length of DescriptorBuffer.\r
+  @param  DescriptorBuffer  Caller allocated buffer to store Usb report descriptor\r
+                            if successfully returned.\r
+\r
+  @return Status of getting Report Class descriptor through USB\r
+          I/O protocol's UsbControlTransfer().\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbGetReportDescriptor (\r
@@ -40,6 +66,17 @@ UsbGetReportDescriptor (
   OUT UINT8                   *DescriptorBuffer\r
   );\r
 \r
+/**\r
+  Get Hid Protocol Request.\r
+\r
+  @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Interface         Which interface the caller wants to get protocol.\r
+  @param  Protocol          Protocol value returned.\r
+\r
+  @return Status of getting Protocol Request through USB I/O\r
+          protocol's UsbControlTransfer().\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbGetProtocolRequest (\r
@@ -48,6 +85,17 @@ UsbGetProtocolRequest (
   IN UINT8                   *Protocol\r
   );\r
 \r
+/**\r
+  Set Hid Protocol Request.\r
+\r
+  @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Interface         Which interface the caller wants to set protocol.\r
+  @param  Protocol          Protocol value the caller wants to set.\r
+\r
+  @return Status of setting Protocol Request through USB I/O\r
+          protocol's UsbControlTransfer().\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbSetProtocolRequest (\r
@@ -56,6 +104,18 @@ UsbSetProtocolRequest (
   IN UINT8                   Protocol\r
   );\r
 \r
+/**\r
+  Set Idel request.\r
+\r
+  @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Interface         Which interface the caller wants to set.\r
+  @param  ReportId          Which report the caller wants to set.\r
+  @param  Duration          Idle rate the caller wants to set.\r
+\r
+  @return Status of setting IDLE Request through USB I/O\r
+          protocol's UsbControlTransfer().\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbSetIdleRequest (\r
@@ -65,6 +125,18 @@ UsbSetIdleRequest (
   IN UINT8                   Duration\r
   );\r
 \r
+/**\r
+  Get Idel request.\r
+\r
+  @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Interface         Which interface the caller wants to get.\r
+  @param  ReportId          Which report the caller wants to get.\r
+  @param  Duration          Idle rate the caller wants to get.\r
+\r
+  @return Status of getting IDLE Request through USB I/O\r
+          protocol's UsbControlTransfer().\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbGetIdleRequest (\r
@@ -74,6 +146,20 @@ UsbGetIdleRequest (
   OUT UINT8                   *Duration\r
   );\r
 \r
+/**\r
+  Hid Set Report request.\r
+\r
+  @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Interface         Which interface the caller wants to set.\r
+  @param  ReportId          Which report the caller wants to set.\r
+  @param  ReportType        Type of report.\r
+  @param  ReportLen         Length of report descriptor.\r
+  @param  Report            Report Descriptor buffer.\r
+\r
+  @return Status of setting Report Request through USB I/O\r
+          protocol's UsbControlTransfer().\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbSetReportRequest (\r
@@ -85,6 +171,20 @@ UsbSetReportRequest (
   IN UINT8                   *Report\r
   );\r
 \r
+/**\r
+  Hid Set Report request.\r
+\r
+  @param  UsbIo             A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Interface         Which interface the caller wants to set.\r
+  @param  ReportId          Which report the caller wants to set.\r
+  @param  ReportType        Type of report.\r
+  @param  ReportLen         Length of report descriptor.\r
+  @param  Report            Caller allocated buffer to store Report Descriptor.\r
+\r
+  @return Status of getting Report Request through USB I/O\r
+          protocol's UsbControlTransfer().\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbGetReportRequest (\r
@@ -96,7 +196,23 @@ UsbGetReportRequest (
   IN UINT8                   *Report\r
   );\r
 \r
+/**\r
+  Usb Get Descriptor.\r
+\r
+  @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Value                  Device Request Value.\r
+  @param  Index                  Device Request Index.\r
+  @param  DescriptorLength       Descriptor Length.\r
+  @param  Descriptor             Descriptor buffer to contain result.\r
+  @param  Status                 Transfer Status.\r
+\r
+  @retval EFI_INVALID_PARAMETER  Parameter is error.\r
+  @retval EFI_SUCCESS            Success.\r
+  @retval EFI_TIMEOUT            Device has no response.\r
+\r
+**/\r
 EFI_STATUS\r
+EFIAPI\r
 UsbGetDescriptor (\r
   IN  EFI_USB_IO_PROTOCOL     *UsbIo,\r
   IN  UINT16                  Value,\r
@@ -106,6 +222,21 @@ UsbGetDescriptor (
   OUT UINT32                  *Status\r
   );\r
 \r
+/**\r
+  Usb Set Descriptor.\r
+\r
+  @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Value                  Device Request Value.\r
+  @param  Index                  Device Request Index.\r
+  @param  DescriptorLength       Descriptor Length.\r
+  @param  Descriptor             Descriptor buffer to set.\r
+  @param  Status                 Transfer Status.\r
+\r
+  @retval EFI_INVALID_PARAMETER  Parameter is error.\r
+  @retval EFI_SUCCESS            Success.\r
+  @retval EFI_TIMEOUT            Device has no response.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbSetDescriptor (\r
@@ -117,6 +248,19 @@ UsbSetDescriptor (
   OUT UINT32                  *Status\r
   );\r
 \r
+/**\r
+  Usb Get Device Interface.\r
+\r
+  @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Index                  Interface index value.\r
+  @param  AltSetting             Alternate setting.\r
+  @param  Status                 Trasnsfer status.\r
+\r
+  @retval EFI_INVALID_PARAMETER  Parameter is error.\r
+  @retval EFI_SUCCESS            Success.\r
+  @retval EFI_TIMEOUT            Device has no response.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbGetInterface (\r
@@ -126,6 +270,19 @@ UsbGetInterface (
   OUT UINT32                  *Status\r
   );\r
 \r
+/**\r
+  Usb Set Device Interface.\r
+\r
+  @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  InterfaceNo            Interface Number.\r
+  @param  AltSetting             Alternate setting.\r
+  @param  Status                 Trasnsfer status.\r
+\r
+  @retval EFI_INVALID_PARAMETER  Parameter is error.\r
+  @retval EFI_SUCCESS            Success.\r
+  @retval EFI_TIMEOUT            Device has no response.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbSetInterface (\r
@@ -135,6 +292,18 @@ UsbSetInterface (
   OUT UINT32                  *Status\r
   );\r
 \r
+/**\r
+  Usb Get Device Configuration.\r
+\r
+  @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  ConfigValue            Config Value.\r
+  @param  Status                 Transfer Status.\r
+\r
+  @retval EFI_INVALID_PARAMETER  Parameter is error.\r
+  @retval EFI_SUCCESS            Success.\r
+  @retval EFI_TIMEOUT            Device has no response.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbGetConfiguration (\r
@@ -143,6 +312,18 @@ UsbGetConfiguration (
   OUT UINT32                  *Status\r
   );\r
 \r
+/**\r
+  Usb Set Device Configuration.\r
+\r
+  @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Value                  Configuration Value to set.\r
+  @param  Status                 Transfer status.\r
+\r
+  @retval EFI_INVALID_PARAMETER  Parameter is error.\r
+  @retval EFI_SUCCESS            Success.\r
+  @retval EFI_TIMEOUT            Device has no response.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbSetConfiguration (\r
@@ -151,6 +332,20 @@ UsbSetConfiguration (
   OUT UINT32                  *Status\r
   );\r
 \r
+/**\r
+  Usb Set Device Feature.\r
+\r
+  @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Recipient              Interface/Device/Endpoint.\r
+  @param  Value                  Request value.\r
+  @param  Target                 Request Index.\r
+  @param  Status                 Transfer status.\r
+\r
+  @retval EFI_INVALID_PARAMETER  Parameter is error.\r
+  @retval EFI_SUCCESS            Success.\r
+  @retval EFI_TIMEOUT            Device has no response.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbSetFeature (\r
@@ -161,6 +356,20 @@ UsbSetFeature (
   OUT UINT32                  *Status\r
   );\r
 \r
+/**\r
+  Usb Clear Device Feature.\r
+\r
+  @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Recipient              Interface/Device/Endpoint.\r
+  @param  Value                  Request value.\r
+  @param  Target                 Request Index.\r
+  @param  Status                 Transfer status.\r
+\r
+  @retval EFI_INVALID_PARAMETER  Parameter is error.\r
+  @retval EFI_SUCCESS            Success.\r
+  @retval EFI_TIMEOUT            Device has no response.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbClearFeature (\r
@@ -171,6 +380,20 @@ UsbClearFeature (
   OUT UINT32                  *Status\r
   );\r
 \r
+/**\r
+  Usb Get Device Status.\r
+\r
+  @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  Recipient              Interface/Device/Endpoint.\r
+  @param  Target                 Request index.\r
+  @param  DevStatus              Device status.\r
+  @param  Status                 Transfer status.\r
+\r
+  @retval EFI_INVALID_PARAMETER  Parameter is error.\r
+  @retval EFI_SUCCESS            Success.\r
+  @retval EFI_TIMEOUT            Device has no response.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbGetStatus (\r
@@ -181,9 +404,18 @@ UsbGetStatus (
   OUT UINT32                  *Status\r
   );\r
 \r
-//\r
-// Clear endpoint stall\r
-//\r
+/**\r
+  Clear endpoint stall.\r
+\r
+  @param  UsbIo                  A pointer to EFI_USB_IO_PROTOCOL.\r
+  @param  EndpointNo             Endpoint Number.\r
+  @param  Status                 Transfer Status.\r
+\r
+  @retval EFI_NOT_FOUND          Can't find the Endpoint.\r
+  @retval EFI_DEVICE_ERROR       Hardware error.\r
+  @retval EFI_SUCCESS            Success.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbClearEndpointHalt (\r