Update doxygen comments.

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

2 files changed, 188 insertions, 27 deletions

diff --git a/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.c b/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.c
index 9821253fa9..e6592cf1ac 100644
--- a/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.c
+++ b/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.c
@@ -1,4 +1,14 @@
-/*++

+/**

+Module produce PciCfgPpi on top of PciCfgPpi2.

+

+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 is present that consumes PCI CFG  AND

+2) R9 module is present that produces PCI CFG2 but not PCI CFG

+

 

 Copyright (c) 2006 - 2008 Intel Corporation. <BR>

 All rights reserved. This program and the accompanying materials

@@ -9,14 +19,7 @@ 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>

@@ -26,6 +29,31 @@ Abstract:
 //

 // 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

 PciCfgRead (

@@ -36,6 +64,30 @@ PciCfgRead (
   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

 PciCfgWrite (

@@ -46,6 +98,34 @@ PciCfgWrite (
   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

 PciCfgModify (

@@ -72,36 +152,55 @@ EFI_PEI_PPI_DESCRIPTOR     mPpiListPciCfg = {
   &mPciCfgPpi

 };

 

+/**

+

+  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

 PeimInitializePciCfg (

-  IN EFI_FFS_FILE_HEADER     *FfsHeader,

+  IN EFI_PEI_FILE_HANDLE     FfsHeader,

   IN CONST EFI_PEI_SERVICES  **PeiServices

   )

-/*++

+{

+  //

+  // Publish the PciCfgToPciCfg2 Thunk capability to other modules

+  //

+  return (*PeiServices)->InstallPpi (PeiServices, &mPpiListPciCfg);

+}

 

-Routine Description:

+/**

+  Reads from a given location in the PCI configuration space.

 

-  Provide the functionality of the variable services.

+  @param  PeiServices                   An indirect pointer to the PEI Services Table published by the PEI Foundation.

 

-Arguments:

+  @param  This                              Pointer to local data for the interface.

 

-  FfsHeadher  - The FFS file header

-  PeiServices - General purpose services available to every PEIM.

+  @param  Width                           The width of the access. Enumerated in bytes.

+                                                   See EFI_PEI_PCI_CFG_PPI_WIDTH above.

 

-Returns:

+  @param  Address                       The physical address of the access. The format of

+                                                  the address is described by EFI_PEI_PCI_CFG_PPI_PCI_ADDRESS.

 

-  Status -  EFI_SUCCESS if the interface could be successfully

-            installed

+  @param  Buffer                           A pointer to the buffer of data..

 

---*/

-{

-  //

-  // Publish the variable capability to other modules

-  //

-  return (*PeiServices)->InstallPpi (PeiServices, &mPpiListPciCfg);

-}

 

+  @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

 PciCfgRead (

@@ -119,6 +218,31 @@ PciCfgRead (
   return PciCfg2->Read ((CONST EFI_PEI_SERVICES **)PeiServices, PciCfg2, 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

 PciCfgWrite (

@@ -136,6 +260,34 @@ PciCfgWrite (
   return PciCfg2->Write ((CONST EFI_PEI_SERVICES **)PeiServices, PciCfg2, 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

 PciCfgModify (

diff --git a/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.inf b/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.inf
index a264ab4b93..e1fbae31b6 100644
--- a/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.inf
+++ b/EdkCompatibilityPkg/Compatibility/PciCfgToPciCfg2Thunk/PciCfgToPciCfg2Thunk.inf
@@ -1,5 +1,14 @@
 #/** @file

-# Component description file for PeiVariable module.

+# Module produce PciCfgPpi on top of PciCfgPpi2.

+# 

+# 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 is present that consumes PCI CFG  AND

+# 2) R9 module is present that produces PCI CFG2 but not PCI CFG

+

 #

 # PEIM to provide the Variable functionality.

 # Copyright (c) 2006 - 2007, Intel Corporation