]> git.proxmox.com Git - mirror_edk2.git/blobdiff - PcAtChipsetPkg/PciHostBridgeDxe/PciHostBridge.c
Refine the file/function comments to follow doxygen format
[mirror_edk2.git] / PcAtChipsetPkg / PciHostBridgeDxe / PciHostBridge.c
index c8790578468bb821f23a6bb457f13b14c31aea7d..c2f04ec8072ea6a4f765ec987b3b9e1222dcedd2 100644 (file)
@@ -1,15 +1,14 @@
 /** @file\r
-  Pci Host Bridge driver: \r
   Provides the basic interfaces to abstract a PCI Host Bridge Resource Allocation\r
 \r
-  Copyright (c) 2008 - 2009, Intel Corporation<BR> All rights\r
-  reserved. This program and the accompanying materials are\r
-  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
-  http://opensource.org/licenses/bsd-license.php\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
+Copyright (c) 2008 - 2010, Intel Corporation. All rights reserved. <BR>\r
+This program and the accompanying materials are\r
+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
+http://opensource.org/licenses/bsd-license.php\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
 **/ \r
 \r
@@ -79,26 +78,22 @@ PCI_HOST_BRIDGE_INSTANCE mPciHostBridgeInstanceTemplate = {
 //\r
 // Implementation\r
 //\r
+/**\r
+  Entry point of this driver\r
+\r
+  @param ImageHandle     Handle of driver image\r
+  @param SystemTable     Point to EFI_SYSTEM_TABLE\r
+\r
+  @retval EFI_OUT_OF_RESOURCES  Can not allocate memory resource\r
+  @retval EFI_DEVICE_ERROR      Can not install the protocol instance\r
+  @retval EFI_SUCCESS           Success to initialize the Pci host bridge.\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 InitializePciHostBridge (\r
   IN EFI_HANDLE        ImageHandle,\r
   IN EFI_SYSTEM_TABLE  *SystemTable\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  Entry point of this driver\r
-\r
-Arguments:\r
-\r
-    ImageHandle -\r
-\r
-    SystemTable -\r
-    \r
-Returns:\r
-\r
---*/\r
 {\r
   EFI_STATUS                  Status;\r
   UINTN                       Loop1;\r
@@ -194,24 +189,76 @@ Returns:
 }\r
 \r
 \r
+/**\r
+   These are the notifications from the PCI bus driver that it is about to enter a certain\r
+   phase of the PCI enumeration process.\r
+\r
+   This member function can be used to notify the host bridge driver to perform specific actions,\r
+   including any chipset-specific initialization, so that the chipset is ready to enter the next phase.\r
+   Eight notification points are defined at this time. See belows:\r
+   EfiPciHostBridgeBeginEnumeration       Resets the host bridge PCI apertures and internal data\r
+                                          structures. The PCI enumerator should issue this notification\r
+                                          before starting a fresh enumeration process. Enumeration cannot\r
+                                          be restarted after sending any other notification such as\r
+                                          EfiPciHostBridgeBeginBusAllocation.\r
+   EfiPciHostBridgeBeginBusAllocation     The bus allocation phase is about to begin. No specific action is\r
+                                          required here. This notification can be used to perform any\r
+                                          chipset-specific programming.\r
+   EfiPciHostBridgeEndBusAllocation       The bus allocation and bus programming phase is complete. No\r
+                                          specific action is required here. This notification can be used to\r
+                                          perform any chipset-specific programming.\r
+   EfiPciHostBridgeBeginResourceAllocation\r
+                                          The resource allocation phase is about to begin. No specific\r
+                                          action is required here. This notification can be used to perform\r
+                                          any chipset-specific programming.\r
+   EfiPciHostBridgeAllocateResources      Allocates resources per previously submitted requests for all the PCI\r
+                                          root bridges. These resource settings are returned on the next call to\r
+                                          GetProposedResources(). Before calling NotifyPhase() with a Phase of\r
+                                          EfiPciHostBridgeAllocateResource, the PCI bus enumerator is responsible\r
+                                          for gathering I/O and memory requests for\r
+                                          all the PCI root bridges and submitting these requests using\r
+                                          SubmitResources(). This function pads the resource amount\r
+                                          to suit the root bridge hardware, takes care of dependencies between\r
+                                          the PCI root bridges, and calls the Global Coherency Domain (GCD)\r
+                                          with the allocation request. In the case of padding, the allocated range\r
+                                          could be bigger than what was requested.\r
+   EfiPciHostBridgeSetResources           Programs the host bridge hardware to decode previously allocated\r
+                                          resources (proposed resources) for all the PCI root bridges. After the\r
+                                          hardware is programmed, reassigning resources will not be supported.\r
+                                          The bus settings are not affected.\r
+   EfiPciHostBridgeFreeResources          Deallocates resources that were previously allocated for all the PCI\r
+                                          root bridges and resets the I/O and memory apertures to their initial\r
+                                          state. The bus settings are not affected. If the request to allocate\r
+                                          resources fails, the PCI enumerator can use this notification to\r
+                                          deallocate previous resources, adjust the requests, and retry\r
+                                          allocation.\r
+   EfiPciHostBridgeEndResourceAllocation  The resource allocation phase is completed. No specific action is\r
+                                          required here. This notification can be used to perform any chipsetspecific\r
+                                          programming.\r
+\r
+   @param[in] PciResAlloc         The instance pointer of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL\r
+   @param[in] Phase               The phase during enumeration\r
+\r
+   @retval EFI_NOT_READY          This phase cannot be entered at this time. For example, this error\r
+                                  is valid for a Phase of EfiPciHostBridgeAllocateResources if\r
+                                  SubmitResources() has not been called for one or more\r
+                                  PCI root bridges before this call\r
+   @retval EFI_DEVICE_ERROR       Programming failed due to a hardware error. This error is valid\r
+                                  for a Phase of EfiPciHostBridgeSetResources.\r
+   @retval EFI_INVALID_PARAMETER  Invalid phase parameter\r
+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.\r
+                                  This error is valid for a Phase of EfiPciHostBridgeAllocateResources if the\r
+                                  previously submitted resource requests cannot be fulfilled or\r
+                                  were only partially fulfilled.\r
+   @retval EFI_SUCCESS            The notification was accepted without any errors.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 NotifyPhase(\r
   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,\r
   IN EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PHASE    Phase\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  Enter a certain phase of the PCI enumeration process\r
-\r
-Arguments:\r
-  This  -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance\r
-  Phase -- The phase during enumeration\r
-    \r
-Returns:\r
-\r
---*/  \r
 {\r
   PCI_HOST_BRIDGE_INSTANCE              *HostBridgeInstance;\r
   PCI_ROOT_BRIDGE_INSTANCE              *RootBridgeInstance;\r
@@ -460,28 +507,34 @@ Returns:
   return EFI_SUCCESS;  \r
 }\r
 \r
+/**\r
+   Return the device handle of the next PCI root bridge that is associated with this Host Bridge.\r
+\r
+   This function is called multiple times to retrieve the device handles of all the PCI root bridges that\r
+   are associated with this PCI host bridge. Each PCI host bridge is associated with one or more PCI\r
+   root bridges. On each call, the handle that was returned by the previous call is passed into the\r
+   interface, and on output the interface returns the device handle of the next PCI root bridge. The\r
+   caller can use the handle to obtain the instance of the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL\r
+   for that root bridge. When there are no more PCI root bridges to report, the interface returns\r
+   EFI_NOT_FOUND. A PCI enumerator must enumerate the PCI root bridges in the order that they\r
+   are returned by this function.\r
+   For D945 implementation, there is only one root bridge in PCI host bridge.\r
+\r
+   @param[in]       This              The instance pointer of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL\r
+   @param[in][out]  RootBridgeHandle  Returns the device handle of the next PCI root bridge.\r
+   \r
+   @retval EFI_SUCCESS            If parameter RootBridgeHandle = NULL, then return the first Rootbridge handle of the\r
+                                  specific Host bridge and return EFI_SUCCESS. \r
+   @retval EFI_NOT_FOUND          Can not find the any more root bridge in specific host bridge.\r
+   @retval EFI_INVALID_PARAMETER  RootBridgeHandle is not an EFI_HANDLE that was\r
+                                  returned on a previous call to GetNextRootBridge().\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 GetNextRootBridge(\r
   IN       EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL *This,\r
   IN OUT   EFI_HANDLE                                       *RootBridgeHandle\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  Return the device handle of the next PCI root bridge that is associated with \r
-  this Host Bridge\r
-\r
-Arguments:\r
-  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
-  RootBridgeHandle -- Returns the device handle of the next PCI Root Bridge. \r
-                      On input, it holds the RootBridgeHandle returned by the most \r
-                      recent call to GetNextRootBridge().The handle for the first \r
-                      PCI Root Bridge is returned if RootBridgeHandle is NULL on input\r
-    \r
-Returns:\r
-\r
---*/  \r
 {\r
   BOOLEAN                               NoRootBridge; \r
   LIST_ENTRY                            *List; \r
@@ -528,6 +581,44 @@ Returns:
   }\r
 }\r
 \r
+/**\r
+   Returns the allocation attributes of a PCI root bridge.\r
+\r
+   The function returns the allocation attributes of a specific PCI root bridge. The attributes can vary\r
+   from one PCI root bridge to another. These attributes are different from the decode-related\r
+   attributes that are returned by the EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.GetAttributes() member function. The\r
+   RootBridgeHandle parameter is used to specify the instance of the PCI root bridge. The device\r
+   handles of all the root bridges that are associated with this host bridge must be obtained by calling\r
+   GetNextRootBridge(). The attributes are static in the sense that they do not change during or\r
+   after the enumeration process. The hardware may provide mechanisms to change the attributes on\r
+   the fly, but such changes must be completed before EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL is \r
+   installed. The permitted values of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ATTRIBUTES are defined in\r
+   "Related Definitions" below. The caller uses these attributes to combine multiple resource requests.\r
+   For example, if the flag EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM is set, the PCI bus enumerator needs to \r
+   include requests for the prefetchable memory in the nonprefetchable memory pool and not request any \r
+   prefetchable memory.\r
+      Attribute                                 Description\r
+   ------------------------------------         ----------------------------------------------------------------------\r
+   EFI_PCI_HOST_BRIDGE_COMBINE_MEM_PMEM         If this bit is set, then the PCI root bridge does not support separate\r
+                                                windows for nonprefetchable and prefetchable memory. A PCI bus\r
+                                                driver needs to include requests for prefetchable memory in the\r
+                                                nonprefetchable memory pool.\r
+\r
+   EFI_PCI_HOST_BRIDGE_MEM64_DECODE             If this bit is set, then the PCI root bridge supports 64-bit memory\r
+                                                windows. If this bit is not set, the PCI bus driver needs to include\r
+                                                requests for a 64-bit memory address in the corresponding 32-bit\r
+                                                memory pool.\r
+\r
+   @param[in]   This               The instance pointer of EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL\r
+   @param[in]   RootBridgeHandle   The device handle of the PCI root bridge in which the caller is interested. Type\r
+                                   EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.0 Specification.\r
+   @param[out]  Attributes         The pointer to attribte of root bridge, it is output parameter\r
+   \r
+   @retval EFI_INVALID_PARAMETER   Attribute pointer is NULL\r
+   @retval EFI_INVALID_PARAMETER   RootBridgehandle is invalid.\r
+   @retval EFI_SUCCESS             Success to get attribute of interested root bridge.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 GetAttributes(\r
@@ -535,20 +626,6 @@ GetAttributes(
   IN  EFI_HANDLE                                       RootBridgeHandle,\r
   OUT UINT64                                           *Attributes\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  Returns the attributes of a PCI Root Bridge.\r
-\r
-Arguments:\r
-  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
-  RootBridgeHandle -- The device handle of the PCI Root Bridge \r
-                      that the caller is interested in\r
-  Attribute -- The pointer to attributes of the PCI Root Bridge                    \r
-    \r
-Returns:\r
-\r
---*/    \r
 {\r
   LIST_ENTRY                            *List; \r
   PCI_HOST_BRIDGE_INSTANCE              *HostBridgeInstance;\r
@@ -577,6 +654,21 @@ Returns:
   return EFI_INVALID_PARAMETER;\r
 }\r
 \r
+/**\r
+   Sets up the specified PCI root bridge for the bus enumeration process.\r
+\r
+   This member function sets up the root bridge for bus enumeration and returns the PCI bus range\r
+   over which the search should be performed in ACPI 2.0 resource descriptor format.\r
+\r
+   @param[in]   This              The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance.\r
+   @param[in]   RootBridgeHandle  The PCI Root Bridge to be set up.\r
+   @param[out]  Configuration     Pointer to the pointer to the PCI bus resource descriptor.\r
+   \r
+   @retval EFI_INVALID_PARAMETER Invalid Root bridge's handle\r
+   @retval EFI_OUT_OF_RESOURCES  Fail to allocate ACPI resource descriptor tag.\r
+   @retval EFI_SUCCESS           Sucess to allocate ACPI resource descriptor.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 StartBusEnumeration(\r
@@ -584,20 +676,6 @@ StartBusEnumeration(
   IN  EFI_HANDLE                                       RootBridgeHandle,\r
   OUT VOID                                             **Configuration\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  This is the request from the PCI enumerator to set up \r
-  the specified PCI Root Bridge for bus enumeration process. \r
-\r
-Arguments:\r
-  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
-  RootBridgeHandle -- The PCI Root Bridge to be set up\r
-  Configuration -- Pointer to the pointer to the PCI bus resource descriptor\r
-    \r
-Returns:\r
-\r
---*/\r
 {\r
   LIST_ENTRY                            *List; \r
   PCI_HOST_BRIDGE_INSTANCE              *HostBridgeInstance;\r
@@ -653,6 +731,30 @@ Returns:
   return EFI_INVALID_PARAMETER;\r
 }\r
 \r
+/**\r
+   Programs the PCI root bridge hardware so that it decodes the specified PCI bus range.\r
+\r
+   This member function programs the specified PCI root bridge to decode the bus range that is\r
+   specified by the input parameter Configuration.\r
+   The bus range information is specified in terms of the ACPI 2.0 resource descriptor format.\r
+\r
+   @param[in] This              The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
+   @param[in] RootBridgeHandle  The PCI Root Bridge whose bus range is to be programmed\r
+   @param[in] Configuration     The pointer to the PCI bus resource descriptor\r
+   \r
+   @retval EFI_INVALID_PARAMETER  RootBridgeHandle is not a valid root bridge handle.\r
+   @retval EFI_INVALID_PARAMETER  Configuration is NULL.\r
+   @retval EFI_INVALID_PARAMETER  Configuration does not point to a valid ACPI 2.0 resource descriptor.\r
+   @retval EFI_INVALID_PARAMETER  Configuration does not include a valid ACPI 2.0 bus resource descriptor.\r
+   @retval EFI_INVALID_PARAMETER  Configuration includes valid ACPI 2.0 resource descriptors other than \r
+                                  bus descriptors.\r
+   @retval EFI_INVALID_PARAMETER  Configuration contains one or more invalid ACPI resource descriptors.\r
+   @retval EFI_INVALID_PARAMETER  "Address Range Minimum" is invalid for this root bridge.\r
+   @retval EFI_INVALID_PARAMETER  "Address Range Length" is invalid for this root bridge.\r
+   @retval EFI_DEVICE_ERROR       Programming failed due to a hardware error.\r
+   @retval EFI_SUCCESS            The bus range for the PCI root bridge was programmed.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 SetBusNumbers(\r
@@ -660,20 +762,6 @@ SetBusNumbers(
   IN EFI_HANDLE                                       RootBridgeHandle,\r
   IN VOID                                             *Configuration\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  This function programs the PCI Root Bridge hardware so that \r
-  it decodes the specified PCI bus range\r
-\r
-Arguments:\r
-  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
-  RootBridgeHandle -- The PCI Root Bridge whose bus range is to be programmed\r
-  Configuration -- The pointer to the PCI bus resource descriptor\r
-    \r
-Returns:\r
-\r
---*/    \r
 {\r
   LIST_ENTRY                            *List; \r
   PCI_HOST_BRIDGE_INSTANCE              *HostBridgeInstance;\r
@@ -746,6 +834,31 @@ Returns:
 }\r
 \r
 \r
+/**\r
+   Submits the I/O and memory resource requirements for the specified PCI root bridge.\r
+\r
+   This function is used to submit all the I/O and memory resources that are required by the specified\r
+   PCI root bridge. The input parameter Configuration is used to specify the following:\r
+   - The various types of resources that are required\r
+   - The associated lengths in terms of ACPI 2.0 resource descriptor format\r
+\r
+   @param[in] This              Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.\r
+   @param[in] RootBridgeHandle  The PCI root bridge whose I/O and memory resource requirements are being submitted.\r
+   @param[in] Configuration     The pointer to the PCI I/O and PCI memory resource descriptor.\r
+   \r
+   @retval EFI_SUCCESS            The I/O and memory resource requests for a PCI root bridge were accepted.\r
+   @retval EFI_INVALID_PARAMETER  RootBridgeHandle is not a valid root bridge handle.\r
+   @retval EFI_INVALID_PARAMETER  Configuration is NULL.\r
+   @retval EFI_INVALID_PARAMETER  Configuration does not point to a valid ACPI 2.0 resource descriptor.\r
+   @retval EFI_INVALID_PARAMETER  Configuration includes requests for one or more resource types that are \r
+                                  not supported by this PCI root bridge. This error will happen if the caller \r
+                                  did not combine resources according to Attributes that were returned by\r
+                                  GetAllocAttributes().\r
+   @retval EFI_INVALID_PARAMETER  Address Range Maximum" is invalid.\r
+   @retval EFI_INVALID_PARAMETER  "Address Range Length" is invalid for this PCI root bridge.\r
+   @retval EFI_INVALID_PARAMETER  "Address Space Granularity" is invalid for this PCI root bridge.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 SubmitResources(\r
@@ -753,19 +866,6 @@ SubmitResources(
   IN EFI_HANDLE                                       RootBridgeHandle,\r
   IN VOID                                             *Configuration\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  Submits the I/O and memory resource requirements for the specified PCI Root Bridge\r
-  \r
-Arguments:\r
-  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
-  RootBridgeHandle -- The PCI Root Bridge whose I/O and memory resource requirements \r
-                      are being submitted\r
-  Configuration -- The pointer to the PCI I/O and PCI memory resource descriptor                    \r
-Returns:\r
-\r
---*/    \r
 {\r
   LIST_ENTRY                            *List; \r
   PCI_HOST_BRIDGE_INSTANCE              *HostBridgeInstance;\r
@@ -883,6 +983,26 @@ Returns:
   return EFI_INVALID_PARAMETER;\r
 }\r
 \r
+/**\r
+   Returns the proposed resource settings for the specified PCI root bridge.\r
+\r
+   This member function returns the proposed resource settings for the specified PCI root bridge. The\r
+   proposed resource settings are prepared when NotifyPhase() is called with a Phase of\r
+   EfiPciHostBridgeAllocateResources. The output parameter Configuration\r
+   specifies the following:\r
+   - The various types of resources, excluding bus resources, that are allocated\r
+   - The associated lengths in terms of ACPI 2.0 resource descriptor format\r
+\r
+   @param[in]  This              Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.\r
+   @param[in]  RootBridgeHandle  The PCI root bridge handle. Type EFI_HANDLE is defined in InstallProtocolInterface() in the UEFI 2.0 Specification.\r
+   @param[out] Configuration     The pointer to the pointer to the PCI I/O and memory resource descriptor.\r
+   \r
+   @retval EFI_SUCCESS            The requested parameters were returned.\r
+   @retval EFI_INVALID_PARAMETER  RootBridgeHandle is not a valid root bridge handle.\r
+   @retval EFI_DEVICE_ERROR       Programming failed due to a hardware error.\r
+   @retval EFI_OUT_OF_RESOURCES   The request could not be completed due to a lack of resources.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 GetProposedResources(\r
@@ -890,21 +1010,6 @@ GetProposedResources(
   IN  EFI_HANDLE                                       RootBridgeHandle,\r
   OUT VOID                                             **Configuration\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  This function returns the proposed resource settings for the specified \r
-  PCI Root Bridge\r
-\r
-Arguments:\r
-  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
-  RootBridgeHandle -- The PCI Root Bridge handle\r
-  Configuration -- The pointer to the pointer to the PCI I/O \r
-                   and memory resource descriptor\r
-    \r
-Returns:\r
-\r
---*/    \r
 {\r
   LIST_ENTRY                            *List; \r
   PCI_HOST_BRIDGE_INSTANCE              *HostBridgeInstance;\r
@@ -1053,6 +1158,12 @@ Returns:
   return EFI_INVALID_PARAMETER;\r
 }\r
 \r
+/**\r
+  Update attribute for PCI root bridge for specifc device.\r
+\r
+  @param RootBridge      Point to PCI root bridge.\r
+  @param PciAddress      The specific device PCI address\r
+**/\r
 STATIC\r
 VOID\r
 UpdateRootBridgeAttributes (\r
@@ -1151,6 +1262,33 @@ UpdateRootBridgeAttributes (
   RootBridge->Supports = Attributes;\r
 }\r
 \r
+/**\r
+   Provides the hooks from the PCI bus driver to every PCI controller (device/function) at various\r
+   stages of the PCI enumeration process that allow the host bridge driver to preinitialize individual\r
+   PCI controllers before enumeration.\r
+\r
+   This function is called during the PCI enumeration process. No specific action is expected from this\r
+   member function. It allows the host bridge driver to preinitialize individual PCI controllers before\r
+   enumeration.\r
+\r
+   @param This              Pointer to the EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_PROTOCOL instance.\r
+   @param RootBridgeHandle  The associated PCI root bridge handle. Type EFI_HANDLE is defined in\r
+                            InstallProtocolInterface() in the UEFI 2.0 Specification.\r
+   @param PciAddress        The address of the PCI device on the PCI bus. This address can be passed to the\r
+                            EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL member functions to access the PCI\r
+                            configuration space of the device. See Table 12-1 in the UEFI 2.0 Specification for\r
+                            the definition of EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS.\r
+   @param Phase             The phase of the PCI device enumeration. \r
+   \r
+   @retval EFI_SUCCESS              The requested parameters were returned.\r
+   @retval EFI_INVALID_PARAMETER    RootBridgeHandle is not a valid root bridge handle.\r
+   @retval EFI_INVALID_PARAMETER    Phase is not a valid phase that is defined in\r
+                                    EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE.\r
+   @retval EFI_DEVICE_ERROR         Programming failed due to a hardware error. The PCI enumerator should\r
+                                    not enumerate this device, including its child devices if it is a PCI-to-PCI\r
+                                    bridge.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 PreprocessController (\r
@@ -1159,21 +1297,6 @@ PreprocessController (
   IN  EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_PCI_ADDRESS               PciAddress,\r
   IN  EFI_PCI_CONTROLLER_RESOURCE_ALLOCATION_PHASE              Phase\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-  This function is called for all the PCI controllers that the PCI \r
-  bus driver finds. Can be used to Preprogram the controller.\r
-\r
-Arguments:\r
-  This -- The EFI_PCI_HOST_BRIDGE_RESOURCE_ALLOCATION_ PROTOCOL instance\r
-  RootBridgeHandle -- The PCI Root Bridge handle\r
-  PciBusAddress -- Address of the controller on the PCI bus\r
-  Phase         -- The Phase during resource allocation\r
-    \r
-Returns:\r
-  EFI_SUCCESS\r
---*/    \r
 {\r
   PCI_HOST_BRIDGE_INSTANCE              *HostBridgeInstance;\r
   PCI_ROOT_BRIDGE_INSTANCE              *RootBridgeInstance;\r