1) Add in Doxygen comment.

2) Update package dependency list.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5231 6f19259b-4bc3-4df7-8a09-765794883524

EdkCompatibilityPkg/Compatibility/PciCfg2ToPciCfgThunk/PciCfg2ToPciCfgThunk.c

@@ -1,4 +1,28 @@
-/*++
+/** @file
+Module produces PciCfgPpi2 on top of PciCfgPpi. It also updates the 
+PciCfg2Ppi pointer in the EFI_PEI_SERVICES upon a installation of
+EcpPeiPciCfgPpi. EcpPeiPciCfgPpi is installed in a framework module which
+produce PciCfgPpi originally. This framework module is updated based on the 
+following rule:
+Search pattern:
+	   PeiServices->PciCfg = <*>;
+Replace pattern:
+        {
+          static EFI_PEI_PPI_DESCRIPTOR gEcpPeiPciCfgPpiList = {
+            (EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST),
+            &gEcpPeiPciCfgPpiGuid,
+            <*>
+          };
+          (**PeiServices).InstallPpi (PeiServices, gEcpPeiPciCfgPpiList);
+        }
+
+PIWG's PI specification replaces Inte's EFI Specification 1.10.
+EFI_PEI_PCI_CFG_PPI defined in Inte's EFI Specification 1.10 is replaced by
+EFI_PEI_PCI_CFG2_PPI in PI 1.0.
+This module produces PciCfgPpi on top of PciCfgPpi2. This module is used on platform when both of
+these two conditions are true:
+1) Framework module present that produces PCI CFG PPI  AND
+2) PI module that produces PCI CFG2 is not present
 
 Copyright (c) 2006 - 2008 Intel Corporation. <BR>
 All rights reserved. This program and the accompanying materials
@@ -8,15 +32,8 @@ http://opensource.org/licenses/bsd-license.php
 
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-Module Name:
 
-  Variable.c
+**/
-
-Abstract:
-
-  PEIM to provide the Variable functionality
-
---*/
 
 #include <PiPei.h>
 #include <Ppi/PciCfg.h>
@@ -25,8 +42,21 @@ Abstract:
 #include <Library/DebugLib.h>
 
 //
-// Function Prototypes - Callbacks
+// Function Prototypes 
 //
+
+/**
+  Notification service to be called when gEcpPeiPciCfgPpiGuid is installed.
+
+  @param  PeiServices                 Indirect reference to the PEI Services Table.
+  @param  NotifyDescriptor          Address of the notification descriptor data structure. Type
+          EFI_PEI_NOTIFY_DESCRIPTOR is defined above.
+  @param  Ppi                             Address of the PPI that was installed.
+
+  @retval   EFI_STATUS                This function will install a PPI to PPI database. The status
+                                                  code will be the code for (*PeiServices)->InstallPpi.
+
+**/
 EFI_STATUS
 EFIAPI
 EcpPciCfgPpiNotifyCallback (
@@ -38,6 +68,30 @@ EcpPciCfgPpiNotifyCallback (
 //
 // Function Prototypes
 //
+/**
+  Reads from a given location in the PCI configuration space.
+
+  @param  PeiServices                   An indirect pointer to the PEI Services Table published by the PEI Foundation.
+
+  @param  This                              Pointer to local data for the interface.
+
+  @param  Width                           The width of the access. Enumerated in bytes.
+                                                   See EFI_PEI_PCI_CFG_PPI_WIDTH above.
+
+  @param  Address                       The physical address of the access. The format of
+                                                  the address is described by EFI_PEI_PCI_CFG_PPI_PCI_ADDRESS.
+
+  @param  Buffer                           A pointer to the buffer of data..
+
+
+  @retval EFI_SUCCESS                 The function completed successfully.
+
+  @retval EFI_DEVICE_ERROR        There was a problem with the transaction.
+
+  @retval EFI_DEVICE_NOT_READY  The device is not capable of supporting the operation at this
+                                                    time.
+
+**/
 EFI_STATUS
 EFIAPI
 PciCfg2Read (
@@ -48,6 +102,30 @@ PciCfg2Read (
   IN OUT    VOID                      *Buffer
   );
 
+/**
+  Write to a given location in the PCI configuration space.
+
+  @param  PeiServices                   An indirect pointer to the PEI Services Table published by the PEI Foundation.
+
+  @param  This                              Pointer to local data for the interface.
+
+  @param  Width                            The width of the access. Enumerated in bytes.
+                                                    See EFI_PEI_PCI_CFG_PPI_WIDTH above.
+
+  @param  Address                         The physical address of the access. The format of
+                                                    the address is described by EFI_PEI_PCI_CFG_PPI_PCI_ADDRESS.
+
+  @param  Buffer                            A pointer to the buffer of data..
+
+
+  @retval EFI_SUCCESS                   The function completed successfully.
+
+  @retval EFI_DEVICE_ERROR          There was a problem with the transaction.
+
+  @retval EFI_DEVICE_NOT_READY  The device is not capable of supporting the operation at this
+                                                     time.
+
+**/
 EFI_STATUS
 EFIAPI
 PciCfg2Write (
@@ -58,6 +136,34 @@ PciCfg2Write (
   IN OUT    VOID                      *Buffer
   );
 
+/**
+  PCI read-modify-write operation.
+
+  @param  PeiServices                     An indirect pointer to the PEI Services Table
+                                                      published by the PEI Foundation.
+
+  @param  This                                Pointer to local data for the interface.
+
+  @param  Width                             The width of the access. Enumerated in bytes. Type
+                                                      EFI_PEI_PCI_CFG_PPI_WIDTH is defined in Read().
+
+  @param  Address                           The physical address of the access.
+
+  @param  SetBits                            Points to value to bitwise-OR with the read configuration value.
+                                                      The size of the value is determined by Width.
+
+  @param  ClearBits                         Points to the value to negate and bitwise-AND with the read configuration value.
+                                                      The size of the value is determined by Width.
+
+
+  @retval EFI_SUCCESS                   The function completed successfully.
+
+  @retval EFI_DEVICE_ERROR          There was a problem with the transaction.
+
+  @retval EFI_DEVICE_NOT_READY  The device is not capable of supporting
+                                                    the operation at this time.
+
+**/
 EFI_STATUS
 EFIAPI
 PciCfg2Modify (
@@ -92,31 +198,33 @@ EFI_PEI_PPI_DESCRIPTOR mPpiListPciCfg2 = {
 };
 
 
+/**
+
+  Standard PEIM entry point.
+
+  @param FfsHeadher   The FFS file header
+  @param PeiServices   General purpose services available to every PEIM.
+
+
+  @retval EFI_SUCCESS if the interface could be successfully
+                                    installed
+
+--*/
 EFI_STATUS
 EFIAPI
 PeimInitializePciCfg2 (
   IN EFI_FFS_FILE_HEADER     *FfsHeader,
   IN CONST EFI_PEI_SERVICES  **PeiServices
   )
-/*++
-
-Routine Description:
-
-  Provide the functionality of the variable services.
-
-Arguments:
-
-  FfsHeadher  - The FFS file header
-  PeiServices - General purpose services available to every PEIM.
-
-Returns:
-
-  Status -  EFI_SUCCESS if the interface could be successfully
-            installed
-
---*/
 {
   EFI_STATUS  Status;
+  VOID        *Ppi;
+
+  //
+  // Make sure no other module has install the first instance of gEfiPciCfg2PpiGuid.
+  //
+  Status = (*PeiServices)->LocatePpi (PeiServices, &gEfiPciCfg2PpiGuid, 0, NULL, &Ppi);
+  ASSERT (Status == EFI_NOT_FOUND);
 
   //
   // Register a notification for ECP PCI CFG PPI
@@ -126,6 +234,19 @@ Returns:
   return Status;
 }
 
+
+/**
+  Notification service to be called when gEcpPeiPciCfgPpiGuid is installed.
+
+  @param  PeiServices                 Indirect reference to the PEI Services Table.
+  @param  NotifyDescriptor          Address of the notification descriptor data structure. Type
+          EFI_PEI_NOTIFY_DESCRIPTOR is defined above.
+  @param  Ppi                             Address of the PPI that was installed.
+
+  @retval   EFI_STATUS                This function will install a PPI to PPI database. The status
+                                                  code will be the code for (*PeiServices)->InstallPpi.
+
+**/
 EFI_STATUS
 EFIAPI
 EcpPciCfgPpiNotifyCallback (
@@ -142,6 +263,30 @@ EcpPciCfgPpiNotifyCallback (
   return (*PeiServices)->InstallPpi ((CONST EFI_PEI_SERVICES **)PeiServices, &mPpiListPciCfg2);
 }
 
+/**
+  Reads from a given location in the PCI configuration space.
+
+  @param  PeiServices                   An indirect pointer to the PEI Services Table published by the PEI Foundation.
+
+  @param  This                              Pointer to local data for the interface.
+
+  @param  Width                           The width of the access. Enumerated in bytes.
+                                                   See EFI_PEI_PCI_CFG_PPI_WIDTH above.
+
+  @param  Address                       The physical address of the access. The format of
+                                                  the address is described by EFI_PEI_PCI_CFG_PPI_PCI_ADDRESS.
+
+  @param  Buffer                           A pointer to the buffer of data..
+
+
+  @retval EFI_SUCCESS                 The function completed successfully.
+
+  @retval EFI_DEVICE_ERROR        There was a problem with the transaction.
+
+  @retval EFI_DEVICE_NOT_READY  The device is not capable of supporting the operation at this
+                                                    time.
+
+**/
 EFI_STATUS
 EFIAPI
 PciCfg2Read (
@@ -167,6 +312,30 @@ PciCfg2Read (
   return PciCfg->Read ((EFI_PEI_SERVICES **)PeiServices, PciCfg, Width, Address, Buffer);
 }
 
+/**
+  Write to a given location in the PCI configuration space.
+
+  @param  PeiServices                   An indirect pointer to the PEI Services Table published by the PEI Foundation.
+
+  @param  This                              Pointer to local data for the interface.
+
+  @param  Width                            The width of the access. Enumerated in bytes.
+                                                    See EFI_PEI_PCI_CFG_PPI_WIDTH above.
+
+  @param  Address                         The physical address of the access. The format of
+                                                    the address is described by EFI_PEI_PCI_CFG_PPI_PCI_ADDRESS.
+
+  @param  Buffer                            A pointer to the buffer of data..
+
+
+  @retval EFI_SUCCESS                   The function completed successfully.
+
+  @retval EFI_DEVICE_ERROR          There was a problem with the transaction.
+
+  @retval EFI_DEVICE_NOT_READY  The device is not capable of supporting the operation at this
+                                                     time.
+
+**/
 EFI_STATUS
 EFIAPI
 PciCfg2Write (
@@ -192,6 +361,34 @@ PciCfg2Write (
   return PciCfg->Write ((EFI_PEI_SERVICES **)PeiServices, PciCfg, Width, Address, Buffer);
 }
 
+/**
+  PCI read-modify-write operation.
+
+  @param  PeiServices                     An indirect pointer to the PEI Services Table
+                                                      published by the PEI Foundation.
+
+  @param  This                                Pointer to local data for the interface.
+
+  @param  Width                             The width of the access. Enumerated in bytes. Type
+                                                      EFI_PEI_PCI_CFG_PPI_WIDTH is defined in Read().
+
+  @param  Address                           The physical address of the access.
+
+  @param  SetBits                            Points to value to bitwise-OR with the read configuration value.
+                                                      The size of the value is determined by Width.
+
+  @param  ClearBits                         Points to the value to negate and bitwise-AND with the read configuration value.
+                                                      The size of the value is determined by Width.
+
+
+  @retval EFI_SUCCESS                   The function completed successfully.
+
+  @retval EFI_DEVICE_ERROR          There was a problem with the transaction.
+
+  @retval EFI_DEVICE_NOT_READY  The device is not capable of supporting
+                                                    the operation at this time.
+
+**/
 EFI_STATUS
 EFIAPI
 PciCfg2Modify (

EdkCompatibilityPkg/Compatibility/PciCfg2ToPciCfgThunk/PciCfg2ToPciCfgThunk.inf

@@ -1,5 +1,29 @@
 #/** @file
-# Component description file for PeiVariable module.
+# Module produces PciCfgPpi2 on top of PciCfgPpi. It also updates the 
+# PciCfg2Ppi pointer in the EFI_PEI_SERVICES upon a installation of
+# EcpPeiPciCfgPpi. EcpPeiPciCfgPpi is installed in a framework module which
+# produce PciCfgPpi originally. This framework module is updated based on the 
+# following rule:
+# Search pattern:
+# 	   PeiServices->PciCfg = <*>;
+# Replace pattern:
+#         {
+#           static EFI_PEI_PPI_DESCRIPTOR gEcpPeiPciCfgPpiList = {
+#             (EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST),
+#             &gEcpPeiPciCfgPpiGuid,
+#             <*>
+#           };
+#           (**PeiServices).InstallPpi (PeiServices, gEcpPeiPciCfgPpiList);
+#         }
+
+# PIWG's PI specification replaces Inte's EFI Specification 1.10.
+# EFI_PEI_PCI_CFG_PPI defined in Inte's EFI Specification 1.10 is replaced by
+# EFI_PEI_PCI_CFG2_PPI in PI 1.0.
+# This module produces PciCfgPpi on top of PciCfgPpi2. This module is used on platform when both of
+# these two conditions are true:
+# 1) Framework module present that produces PCI CFG PPI  AND
+# 2) PI module that produces PCI CFG2 is not present
+
 #
 # PEIM to provide the Variable functionality.
 # Copyright (c) 2006 - 2007, Intel Corporation
@@ -50,4 +74,3 @@
 
 [Depex]
   TRUE
-#  gEcpPeiPciCfgPpiGuid