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

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

diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.h b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.h
index 21d1b304bf80d36146153957500154c62bd10f55..4bee1836f9abcb9f33f254beeaeaca2f2a03fae0 100644 (file)
--- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.h
+++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.h
@@ -1,4 +1,7 @@
 /** @file\r
+\r
+    Usb Bus Driver Binding and Bus IO Protocol.\r
+\r
 Copyright (c) 2004 - 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
@@ -8,17 +11,6 @@ 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
-    UsbBus.h\r
-\r
-  Abstract:\r
-\r
-    Usb Bus Driver Binding and Bus IO Protocol\r
-\r
-  Revision History\r
-\r
-\r
 **/\r
 \r
 #ifndef _EFI_USB_BUS_H_\r
@@ -55,7 +47,7 @@ typedef struct _USB_HUB_API    USB_HUB_API;
 #include "UsbHub.h"\r
 #include "UsbEnumer.h"\r
 \r
-enum {\r
+typedef enum {\r
   USB_MAX_LANG_ID           = 16,\r
   USB_MAX_INTERFACE         = 16,\r
   USB_MAX_DEVICES           = 128,\r
@@ -125,17 +117,17 @@ enum {
   //\r
   // Send clear feature request timeout, set by experience\r
   //\r
-  USB_CLEAR_FEATURE_REQUEST_TIMEOUT  = 10 * USB_BUS_1_MILLISECOND,\r
+  USB_CLEAR_FEATURE_REQUEST_TIMEOUT  = 10 * USB_BUS_1_MILLISECOND\r
+}USB_BUS_TIMEOUT_EXPERIENCE_VALUE;\r
 \r
-  //\r
-  // Bus raises TPL to TPL_NOTIFY to serialize all its operations\r
-  // to protect shared data structures.\r
-  //\r
-  USB_BUS_TPL               = TPL_NOTIFY,\r
+//\r
+// Bus raises TPL to TPL_NOTIFY to serialize all its operations\r
+// to protect shared data structures.\r
+//\r
+#define  USB_BUS_TPL               TPL_NOTIFY\r
 \r
-  USB_INTERFACE_SIGNATURE   = EFI_SIGNATURE_32 ('U', 'S', 'B', 'I'),\r
-  USB_BUS_SIGNATURE         = EFI_SIGNATURE_32 ('U', 'S', 'B', 'B')\r
-};\r
+#define  USB_INTERFACE_SIGNATURE   EFI_SIGNATURE_32 ('U', 'S', 'B', 'I')\r
+#define  USB_BUS_SIGNATURE         EFI_SIGNATURE_32 ('U', 'S', 'B', 'B')\r
 \r
 #define USB_BIT(a)                  ((UINTN)(1 << (a)))\r
 #define USB_BIT_IS_SET(Data, Bit)   ((BOOLEAN)(((Data) & (Bit)) == (Bit)))\r
@@ -279,12 +271,32 @@ typedef struct {
   EFI_DEVICE_PATH_PROTOCOL        End;\r
 } USB_CLASS_FORMAT_DEVICE_PATH;\r
 \r
+/**\r
+  Free a DEVICE_PATH_LIST_ITEM list.\r
+\r
+  @param  UsbIoDPList            a DEVICE_PATH_LIST_ITEM list pointer.\r
+\r
+  @retval EFI_INVALID_PARAMETER  If parameters are invalid, return this value.\r
+  @retval EFI_SUCCESS            If free operation is successful, return this value.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbBusFreeUsbDPList (\r
   IN     LIST_ENTRY                                 *UsbIoDPList\r
   );\r
 \r
+/**\r
+  Store a wanted usb child device info (its Usb part of device path) which is indicated by\r
+  RemainingDevicePath in a Usb bus which  is indicated by UsbBusId.\r
+\r
+  @param  UsbBusId               Point to EFI_USB_BUS_PROTOCOL interface.\r
+  @param  RemainingDevicePath    The remaining device patch.\r
+\r
+  @retval EFI_SUCCESS            Add operation is successful.\r
+  @retval EFI_INVALID_PARAMETER  The parameters are invalid.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbBusAddWantedUsbIoDP (\r
@@ -292,6 +304,16 @@ UsbBusAddWantedUsbIoDP (
   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath\r
   );\r
 \r
+/**\r
+  Check whether a usb child device is the wanted device in a bus.\r
+\r
+  @param  Bus     The Usb bus's private data pointer.\r
+  @param  UsbIf   The usb child device inferface.\r
+\r
+  @retval True    If a usb child device is the wanted device in a bus.\r
+  @retval False   If a usb child device is *NOT* the wanted device in a bus.\r
+\r
+**/\r
 BOOLEAN\r
 EFIAPI\r
 UsbBusIsWantedUsbIO (\r
@@ -299,6 +321,16 @@ UsbBusIsWantedUsbIO (
   IN USB_INTERFACE           *UsbIf\r
   );\r
 \r
+/**\r
+  Recursively connnect every wanted usb child device to ensure they all fully connected.\r
+  Check all the child Usb IO handles in this bus, recursively connecte if it is wanted usb child device.\r
+\r
+  @param  UsbBusId                  Point to EFI_USB_BUS_PROTOCOL interface.\r
+\r
+  @retval EFI_SUCCESS               Connect is done successfully.\r
+  @retval EFI_INVALID_PARAMETER     The parameter is invalid.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 UsbBusRecursivelyConnectWantedUsbIo (\r