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
 /** @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
 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
 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
 **/\r
 \r
 #ifndef _USB_DESCRIPTOR_H_\r
 #define _USB_DESCRIPTOR_H_\r
 \r

-enum {\r
+typedef enum {\r

   USB_MAX_INTERFACE_SETTING  = 8\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
 \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
   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
 EFI_STATUS\r
 UsbCtrlRequest (\r
   IN USB_DEVICE             *UsbDev,\r


@@ -102,16 +113,47 @@ UsbCtrlRequest (
   IN UINTN                  Length\r
   );\r
 \r
   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
 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
 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
 EFI_USB_STRING_DESCRIPTOR*\r
 UsbGetOneString (\r
   IN     USB_DEVICE       *UsbDev,\r


@@ -119,23 +161,70 @@ UsbGetOneString (
   IN     UINT16           LangId\r
   );\r
 \r
   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
 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
 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
 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
 EFI_STATUS\r
 UsbIoClearFeature (\r
   IN  EFI_USB_IO_PROTOCOL *UsbIo,\r