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

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

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