modify coding style to pass ecc tool and provide comments that complied with Doxgen.

[mirror_edk2.git] / MdeModulePkg / Bus / Usb / UsbBusDxe / UsbDesc.h

diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h
index 14f3c7feb0474b0b348feb86031d0847d163426e..dd7868bc1d40cd5de12cc7c8eb327ffed808b983 100644 (file)
--- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h
+++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h
@@ -1,5 +1,7 @@
 /** @file\r
 \r
+    Manage Usb Descriptor List\r
+\r
 Copyright (c) 2007, Intel Corporation\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
@@ -9,25 +11,14 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
-  Module Name:\r
-\r
-    UsbDesc.h\r
-\r
-  Abstract:\r
-\r
-    Manage Usb Descriptor List\r
-\r
-  Revision History\r
-\r
-\r
 **/\r
 \r
 #ifndef _USB_DESCRIPTOR_H_\r
 #define _USB_DESCRIPTOR_H_\r
 \r
-enum {\r
+typedef enum {\r
   USB_MAX_INTERFACE_SETTING  = 8\r
-};\r
+}USB_INTERFACE_SETTING_MAX;\r
 \r
 //\r
 // The RequestType in EFI_USB_DEVICE_REQUEST is composed of\r
@@ -89,6 +80,26 @@ typedef struct {
   USB_CONFIG_DESC               **Configs;\r
 } USB_DEVICE_DESC;\r
 \r
+/**\r
+  USB standard control transfer support routine. This\r
+  function is used by USB device. It is possible that\r
+  the device's interfaces are still waiting to be\r
+  enumerated.\r
+\r
+  @param  UsbDev                The usb device.\r
+  @param  Direction             The direction of data transfer.\r
+  @param  Type                  Standard / class specific / vendor specific.\r
+  @param  Target                The receiving target.\r
+  @param  Request               Which request.\r
+  @param  Value                 The wValue parameter of the request.\r
+  @param  Index                 The wIndex parameter of the request.\r
+  @param  Buf                   The buffer to receive data into / transmit from.\r
+  @param  Length                The length of the buffer.\r
+\r
+  @retval EFI_SUCCESS           The control request is executed.\r
+  @retval EFI_DEVICE_ERROR      Failed to execute the control transfer.\r
+\r
+**/\r
 EFI_STATUS\r
 UsbCtrlRequest (\r
   IN USB_DEVICE             *UsbDev,\r
@@ -102,16 +113,47 @@ UsbCtrlRequest (
   IN UINTN                  Length\r
   );\r
 \r
+/**\r
+  Return the max packet size for endpoint zero. This function\r
+  is the first function called to get descriptors during bus\r
+  enumeration.\r
+\r
+  @param  UsbDev                The usb device.\r
+\r
+  @retval EFI_SUCCESS           The max packet size of endpoint zero is retrieved.\r
+  @retval EFI_DEVICE_ERROR      Failed to retrieve it.\r
+\r
+**/\r
 EFI_STATUS\r
 UsbGetMaxPacketSize0 (\r
   IN USB_DEVICE           *UsbDev\r
   );\r
 \r
+/**\r
+  Free a device descriptor with its configurations.\r
+\r
+  @param  DevDesc               The device descriptor.\r
+\r
+  @return None.\r
+\r
+**/\r
 VOID\r
 UsbFreeDevDesc (\r
   IN USB_DEVICE_DESC      *DevDesc\r
   );\r
 \r
+/**\r
+  Retrieve the indexed string for the language. It requires two\r
+  steps to get a string, first to get the string's length. Then\r
+  the string itself.\r
+\r
+  @param  UsbDev                The usb device.\r
+  @param  StringIndex           The index of the string to retrieve.\r
+  @param  LangId                Language ID.\r
+\r
+  @return The created string descriptor or NULL.\r
+\r
+**/\r
 EFI_USB_STRING_DESCRIPTOR*\r
 UsbGetOneString (\r
   IN     USB_DEVICE       *UsbDev,\r
@@ -119,23 +161,70 @@ UsbGetOneString (
   IN     UINT16           LangId\r
   );\r
 \r
+/**\r
+  Build the whole array of descriptors. This function must\r
+  be called after UsbGetMaxPacketSize0 returns the max packet\r
+  size correctly for endpoint 0.\r
+\r
+  @param  UsbDev                The Usb device.\r
+\r
+  @retval EFI_SUCCESS           The descriptor table is build.\r
+  @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the descriptor.\r
+\r
+**/\r
 EFI_STATUS\r
 UsbBuildDescTable (\r
   IN USB_DEVICE           *UsbDev\r
   );\r
 \r
+/**\r
+  Set the device's address.\r
+\r
+  @param  UsbDev                The device to set address to.\r
+  @param  Address               The address to set.\r
+\r
+  @retval EFI_SUCCESS           The device is set to the address.\r
+  @retval Others                Failed to set the device address.\r
+\r
+**/\r
 EFI_STATUS\r
 UsbSetAddress (\r
   IN USB_DEVICE           *UsbDev,\r
   IN UINT8                Address\r
   );\r
 \r
+/**\r
+  Set the device's configuration. This function changes\r
+  the device's internal state. UsbSelectConfig changes\r
+  the Usb bus's internal state.\r
+\r
+  @param  UsbDev                The USB device to set configure to.\r
+  @param  ConfigIndex           The configure index to set.\r
+\r
+  @retval EFI_SUCCESS           The device is configured now.\r
+  @retval Others                Failed to set the device configure.\r
+\r
+**/\r
 EFI_STATUS\r
 UsbSetConfig (\r
   IN USB_DEVICE           *UsbDev,\r
   IN UINT8                ConfigIndex\r
   );\r
 \r
+/**\r
+  Usb UsbIo interface to clear the feature. This is should\r
+  only be used by HUB which is considered a device driver\r
+  on top of the UsbIo interface.\r
+\r
+  @param  UsbIo                 The UsbIo interface.\r
+  @param  Target                The target of the transfer: endpoint/device.\r
+  @param  Feature               The feature to clear.\r
+  @param  Index                 The wIndex parameter.\r
+\r
+  @retval EFI_SUCCESS           The device feature is cleared.\r
+  @retval Others                Failed to clear the feature.\r
+\r
+**/\r
 EFI_STATUS\r
 UsbIoClearFeature (\r
   IN  EFI_USB_IO_PROTOCOL *UsbIo,\r