Update doxygen comments.

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

diff --git a/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.c b/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.c
index 9821253fa986a9839a9201ad4fed2d5cd82d40c5..e6592cf1acfd843f3c88f8ef75590783c83b1c95 100644 (file)
--- a/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.c
+++ b/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.c
@@ -1,4 +1,14 @@
-/*++\r
+/**\r
+Module produce PciCfgPpi on top of PciCfgPpi2.\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 is present that consumes PCI CFG  AND\r
+2) R9 module is present that produces PCI CFG2 but not PCI CFG\r
+\r
 \r
 Copyright (c) 2006 - 2008 Intel Corporation. <BR>\r
 All rights reserved. This program and the accompanying materials\r
@@ -9,14 +19,7 @@ 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
 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
@@ -26,6 +29,31 @@ Abstract:
 //\r
 // Function Prototypes\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
 PciCfgRead (\r
@@ -36,6 +64,30 @@ PciCfgRead (
   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
 PciCfgWrite (\r
@@ -46,6 +98,34 @@ PciCfgWrite (
   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
 PciCfgModify (\r
@@ -72,36 +152,55 @@ EFI_PEI_PPI_DESCRIPTOR     mPpiListPciCfg = {
   &mPciCfgPpi\r
 };\r
 \r
+/**\r
+\r
+  Standard PEIM entry point.\r
+\r
+  @param FfsHeadher   The FFS file header\r
+  @param PeiServices   General purpose services available to every PEIM.\r
+\r
+\r
+  @retval EFI_SUCCESS if the interface could be successfully\r
+                                    installed\r
+\r
+--*/\r
 EFI_STATUS\r
 EFIAPI\r
 PeimInitializePciCfg (\r
-  IN EFI_FFS_FILE_HEADER     *FfsHeader,\r
+  IN EFI_PEI_FILE_HANDLE     FfsHeader,\r
   IN CONST EFI_PEI_SERVICES  **PeiServices\r
   )\r
-/*++\r
+{\r
+  //\r
+  // Publish the PciCfgToPciCfg2 Thunk capability to other modules\r
+  //\r
+  return (*PeiServices)->InstallPpi (PeiServices, &mPpiListPciCfg);\r
+}\r
 \r
-Routine Description:\r
+/**\r
+  Reads from a given location in the PCI configuration space.\r
 \r
-  Provide the functionality of the variable services.\r
+  @param  PeiServices                   An indirect pointer to the PEI Services Table published by the PEI Foundation.\r
 \r
-Arguments:\r
+  @param  This                              Pointer to local data for the interface.\r
 \r
-  FfsHeadher  - The FFS file header\r
-  PeiServices - General purpose services available to every PEIM.\r
+  @param  Width                           The width of the access. Enumerated in bytes.\r
+                                                   See EFI_PEI_PCI_CFG_PPI_WIDTH above.\r
 \r
-Returns:\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
-  Status -  EFI_SUCCESS if the interface could be successfully\r
-            installed\r
+  @param  Buffer                           A pointer to the buffer of data..\r
 \r
---*/\r
-{\r
-  //\r
-  // Publish the variable capability to other modules\r
-  //\r
-  return (*PeiServices)->InstallPpi (PeiServices, &mPpiListPciCfg);\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
 PciCfgRead (\r
@@ -119,6 +218,31 @@ PciCfgRead (
   return PciCfg2->Read ((CONST EFI_PEI_SERVICES **)PeiServices, PciCfg2, Width, Address, Buffer);\r
 }\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
 PciCfgWrite (\r
@@ -136,6 +260,34 @@ PciCfgWrite (
   return PciCfg2->Write ((CONST EFI_PEI_SERVICES **)PeiServices, PciCfg2, 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
 PciCfgModify (\r

diff --git a/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.inf b/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.inf
index a264ab4b93650be0e6fdb77dec009dafbca49fc3..e1fbae31b6c4d53955a17848d6b5bd24113661cb 100644 (file)
--- a/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.inf
+++ b/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.inf
@@ -1,5 +1,14 @@
 #/** @file\r
-# Component description file for PeiVariable module.\r
+# Module produce PciCfgPpi on top of PciCfgPpi2.\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 is present that consumes PCI CFG  AND\r
+# 2) R9 module is present that produces PCI CFG2 but not PCI CFG\r
+\r
 #\r
 # PEIM to provide the Variable functionality.\r
 # Copyright (c) 2006 - 2007, Intel Corporation\r