Formalize comments for Protocols and PPIs.

1. Use doxygen format for Protocol/PPI data structure
2. Remove doxygen comments for function elements in Protocol/Ppi
3. Use doxygen format for data elements in Protocol/Ppi, and add missing comments where necessary
4. PEI Services Table is also updated accordingly.

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

16 files changed, 17 insertions, 244 deletions

diff --git a/MdePkg/Include/Ppi/CpuIo.h b/MdePkg/Include/Ppi/CpuIo.h
index 3966432028..f5ec83c8b0 100644
--- a/MdePkg/Include/Ppi/CpuIo.h
+++ b/MdePkg/Include/Ppi/CpuIo.h
@@ -383,77 +383,27 @@ VOID
 /// The perspective of the services is that of the processor, not the bus or system.

 ///

 struct _EFI_PEI_CPU_IO_PPI {

-  ///

-  /// Collection of memory-access services.

-  ///

-  EFI_PEI_CPU_IO_PPI_ACCESS       Mem;

-  ///

-  /// Collection of I/O-access services.

-  ///

-  EFI_PEI_CPU_IO_PPI_ACCESS       Io;

-  ///

-  /// 8-bit I/O read service.

-  ///

+  EFI_PEI_CPU_IO_PPI_ACCESS       Mem;      ///< Collection of memory-access services.

+  EFI_PEI_CPU_IO_PPI_ACCESS       Io;       ///< Collection of I/O-access services.

+

   EFI_PEI_CPU_IO_PPI_IO_READ8     IoRead8;

-  ///

-  /// 16-bit I/O read service.

-  ///

   EFI_PEI_CPU_IO_PPI_IO_READ16    IoRead16;

-  ///

-  /// 32-bit I/O read service.

-  ///

   EFI_PEI_CPU_IO_PPI_IO_READ32    IoRead32;

-  ///

-  /// 64-bit I/O read service.

-  ///

   EFI_PEI_CPU_IO_PPI_IO_READ64    IoRead64;

-  ///

-  /// 8-bit I/O write service.

-  ///

+

   EFI_PEI_CPU_IO_PPI_IO_WRITE8    IoWrite8;

-  ///

-  /// 16-bit I/O write service.

-  ///

   EFI_PEI_CPU_IO_PPI_IO_WRITE16   IoWrite16;

-  ///

-  /// 32-bit I/O write service.

-  ///

   EFI_PEI_CPU_IO_PPI_IO_WRITE32   IoWrite32;

-  ///

-  /// 64-bit I/O write service.

-  ///

   EFI_PEI_CPU_IO_PPI_IO_WRITE64   IoWrite64;

-  ///

-  /// 8-bit memory read service.

-  ///

+

   EFI_PEI_CPU_IO_PPI_MEM_READ8    MemRead8;

-  ///

-  /// 16-bit memory read service.

-  ///

   EFI_PEI_CPU_IO_PPI_MEM_READ16   MemRead16;

-  ///

-  /// 32-bit memory read service.

-  ///

   EFI_PEI_CPU_IO_PPI_MEM_READ32   MemRead32;

-  ///

-  /// 64-bit memory read service.

-  ///

   EFI_PEI_CPU_IO_PPI_MEM_READ64   MemRead64;

-  ///

-  /// 8-bit memory write service.

-  ///

+

   EFI_PEI_CPU_IO_PPI_MEM_WRITE8   MemWrite8;

-  ///

-  /// 16-bit memory write service.

-  ///

   EFI_PEI_CPU_IO_PPI_MEM_WRITE16  MemWrite16;

-  ///

-  /// 32-bit memory write service.

-  ///

   EFI_PEI_CPU_IO_PPI_MEM_WRITE32  MemWrite32;

-  ///

-  /// 64-bit memory write service.

-  ///

   EFI_PEI_CPU_IO_PPI_MEM_WRITE64  MemWrite64;

 };

 

diff --git a/MdePkg/Include/Ppi/Decompress.h b/MdePkg/Include/Ppi/Decompress.h
index 074b057928..efd787c3f2 100644
--- a/MdePkg/Include/Ppi/Decompress.h
+++ b/MdePkg/Include/Ppi/Decompress.h
@@ -65,9 +65,6 @@ EFI_STATUS
 /// compression sections will be ignored.

 ///

 struct _EFI_PEI_DECOMPRESS_PPI {

-  ///

-  /// Decompress a single compression section in a firmware file.

-  ///

   EFI_PEI_DECOMPRESS_DECOMPRESS Decompress;

 };

 

diff --git a/MdePkg/Include/Ppi/DxeIpl.h b/MdePkg/Include/Ppi/DxeIpl.h
index 1ea629a011..35fb0aaa68 100644
--- a/MdePkg/Include/Ppi/DxeIpl.h
+++ b/MdePkg/Include/Ppi/DxeIpl.h
@@ -65,9 +65,6 @@ EFI_STATUS
 /// The DXE IPL PPI may use PEI services to locate and load the DXE Foundation.

 ///

 struct _EFI_DXE_IPL_PPI {

-  ///

-  /// The entry point to the DXE IPL PPI.

-  ///

   EFI_DXE_IPL_ENTRY Entry;

 };

 

diff --git a/MdePkg/Include/Ppi/FirmwareVolume.h b/MdePkg/Include/Ppi/FirmwareVolume.h
index 4cb22649d2..be42ac096f 100644
--- a/MdePkg/Include/Ppi/FirmwareVolume.h
+++ b/MdePkg/Include/Ppi/FirmwareVolume.h
@@ -208,29 +208,11 @@ EFI_STATUS
 /// This PPI provides functions for accessing a memory-mapped firmware volume of a specific format.

 ///

 struct _EFI_PEI_FIRMWARE_VOLUME_PPI {

-  ///

-  /// Process a firmware volume and create a volume handle.

-  ///

   EFI_PEI_FV_PROCESS_FV       ProcessVolume;

-  ///

-  /// Find all files of a specific type.

-  ///

   EFI_PEI_FV_FIND_FILE_TYPE   FindFileByType;

-  ///

-  /// Find the file with a specific name.

-  ///

   EFI_PEI_FV_FIND_FILE_NAME   FindFileByName;

-  ///

-  /// Return the information about a specific file.

-  ///

   EFI_PEI_FV_GET_FILE_INFO    GetFileInfo;

-  ///

-  /// Return the firmware volume attributes.

-  ///

   EFI_PEI_FV_GET_INFO         GetVolumeInfo;

-  ///

-  /// Find all sections of a specific type.

-  ///

   EFI_PEI_FV_FIND_SECTION     FindSectionByType;

 };

 

diff --git a/MdePkg/Include/Ppi/GuidedSectionExtraction.h b/MdePkg/Include/Ppi/GuidedSectionExtraction.h
index b25bbf3253..5170e463f7 100644
--- a/MdePkg/Include/Ppi/GuidedSectionExtraction.h
+++ b/MdePkg/Include/Ppi/GuidedSectionExtraction.h
@@ -95,10 +95,6 @@ EFI_STATUS
 /// therein.

 ///  

 struct _EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI {

-  ///  

-  /// Takes the GUIDed section as input and

-  /// produces the section stream data.

-  ///

   EFI_PEI_EXTRACT_GUIDED_SECTION ExtractSection;

 };

 

diff --git a/MdePkg/Include/Ppi/LoadFile.h b/MdePkg/Include/Ppi/LoadFile.h
index 79cf0cd299..51f71b38b2 100644
--- a/MdePkg/Include/Ppi/LoadFile.h
+++ b/MdePkg/Include/Ppi/LoadFile.h
@@ -66,9 +66,6 @@ EFI_STATUS
 /// will use this service to launch the known PEI module images.

 ///

 struct _EFI_PEI_LOAD_FILE_PPI {

-  ///

-  /// Loads a PEIM into memory for subsequent execution.

-  ///

   EFI_PEI_LOAD_FILE LoadFile;

 };

 

diff --git a/MdePkg/Include/Ppi/Pcd.h b/MdePkg/Include/Ppi/Pcd.h
index aca531f47d..a299aa9b87 100644
--- a/MdePkg/Include/Ppi/Pcd.h
+++ b/MdePkg/Include/Ppi/Pcd.h
@@ -814,107 +814,9 @@ EFI_STATUS
 

 

 

-//

-// Interface structure for the PCD PPI

-//

-/**

-  @par Ppi Description:

-  This service abstracts the ability to set/get Platform Configuration Database (PCD).

-

-  @param SetSku

-  Sets the SKU value for subsequent calls to set or get PCD token values.

-  

-  @param Get8

-  Retrieves an 8-bit value for a given PCD token.

-

-  @param Get16

-  Retrieves an 16-bit value for a given PCD token.

-

-  @param Get32

-  Retrieves an 32-bit value for a given PCD token.

-

-  @param Get64

-  Retrieves an 64-bit value for a given PCD token.

-

-  @param GetPtr

-  Retrieves a pointer to a value for a given PCD token.

-

-  @param GetBool

-  Retrieves an Boolean value for a given PCD token.

-

-  @param GetSize

-  Retrieves the size of the value for a given PCD token.

-

-  @param Get8Ex

-  Retrieves an 8-bit value for a given PCD token and token space.

-

-  @param Get16Ex

-  Retrieves an 16-bit value for a given PCD token and token space.

-

-  @param Get32Ex

-  Retrieves an 32-bit value for a given PCD token and token space.

-

-  @param Get64Ex

-  Retrieves an 64-bit value for a given PCD token and token space.

-

-  @param GetPtrEx

-  Retrieves a pointer to a value for a given PCD token and token space.

-

-  @param GetBoolEx

-  Retrieves an Boolean value for a given PCD token and token space.

-

-  @param GetSizeEx

-  Retrieves the size of the value for a given PCD token and token space.

-

-  @param Set8

-  Sets an 8-bit value for a given PCD token.

-

-  @param Set16

-  Sets an 16-bit value for a given PCD token.

-

-  @param Set32

-  Sets an 32-bit value for a given PCD token.

-

-  @param Set64

-  Sets an 64-bit value for a given PCD token.

-

-  @param SetPtr

-  Sets the buffer of a specified size for a given PCD token.

-

-  @param SetBool

-  Sets an Boolean value for a given PCD token.

-

-  @param Set8Ex

-  Sets an 8-bit value for a given PCD token and token space.

-

-  @param Set16Ex

-  Sets an 16-bit value for a given PCD token and token space.

-

-  @param Set32Ex

-  Sets an 32-bit value for a given PCD token and token space.

-

-  @param Set64Ex

-  Sets an 64-bit value for a given PCD token and token space.

-

-  @param SetPtrEx

-  Sets the buffer of a specified size for a given PCD token and token space.

-

-  @param SetBoolEx

-  Sets an Boolean value for a given PCD token and token space.

-  

-  @param CallbackOnSet

-  Specifies a function to be called anytime the value of a designated token is changed.

-  

-  @param CancelCallback

-  Cancels a previously set callback function for a particular PCD token number.

-  

-  @param GetNextToken

-  Retrieves the next valid PCD token for a given namespace.

-  

-  @param GetNextTokenSpace

-  Retrieves the next valid PCD token namespace for a given namespace.

- 

-**/

+///

+/// This service abstracts the ability to set/get Platform Configuration Database (PCD).

+///

 typedef struct {

   PCD_PPI_SET_SKU              SetSku;

 

diff --git a/MdePkg/Include/Ppi/PciCfg2.h b/MdePkg/Include/Ppi/PciCfg2.h
index fbf6fa787d..cf738fe469 100644
--- a/MdePkg/Include/Ppi/PciCfg2.h
+++ b/MdePkg/Include/Ppi/PciCfg2.h
@@ -153,24 +153,17 @@ EFI_STATUS
   IN        VOID                      *ClearBits

 );

 

-/**

-  @par Ppi Description:

-  The EFI_PEI_PCI_CFG_PPI interfaces are used to abstract accesses to PCI

-  controllers behind a PCI root bridge controller.

-

-  @param Read     PCI read services.  See the Read() function description.

-

-  @param Write    PCI write services.  See the Write() function description.

-

-  @param Modify   PCI read-modify-write services.  See the Modify() function description.

-

-  @param Segment  The PCI bus segment which the specified functions will access.

-

-**/

+///

+/// The EFI_PEI_PCI_CFG_PPI interfaces are used to abstract accesses to PCI

+/// controllers behind a PCI root bridge controller.

+///

 struct _EFI_PEI_PCI_CFG2_PPI {

   EFI_PEI_PCI_CFG2_PPI_IO  Read;

   EFI_PEI_PCI_CFG2_PPI_IO  Write;

   EFI_PEI_PCI_CFG2_PPI_RW  Modify;

+  ///

+  /// The PCI bus segment which the specified functions will access.

+  ///

   UINT16                  Segment;

 };

 

diff --git a/MdePkg/Include/Ppi/ReadOnlyVariable2.h b/MdePkg/Include/Ppi/ReadOnlyVariable2.h
index 329266a879..44f220e167 100644
--- a/MdePkg/Include/Ppi/ReadOnlyVariable2.h
+++ b/MdePkg/Include/Ppi/ReadOnlyVariable2.h
@@ -107,13 +107,7 @@ EFI_STATUS
 /// variable services. 

 ///

 struct _EFI_PEI_READ_ONLY_VARIABLE2_PPI {

-  ///

-  /// A service to read the value of a particular variable using its name.

-  ///

   EFI_PEI_GET_VARIABLE2       GetVariable;

-  ///

-  /// Find the next variable name in the variable store.

-  ///

   EFI_PEI_NEXT_VARIABLE_NAME2 NextVariableName;

 };

 

diff --git a/MdePkg/Include/Ppi/Reset.h b/MdePkg/Include/Ppi/Reset.h
index b6d9beab50..5f22d17e4e 100644
--- a/MdePkg/Include/Ppi/Reset.h
+++ b/MdePkg/Include/Ppi/Reset.h
@@ -39,10 +39,6 @@
 /// This PPI provides provide a simple reset service. 

 ///

 typedef struct {

-  ///

-  /// A service to reset the entire platform.

-  /// This function is defined in PiPeicis.h.

-  ///

   EFI_PEI_RESET_SYSTEM  ResetSystem;

 } EFI_PEI_RESET_PPI;

 

diff --git a/MdePkg/Include/Ppi/SecPlatformInformation.h b/MdePkg/Include/Ppi/SecPlatformInformation.h
index 573939af3d..b0c94f0fe4 100644
--- a/MdePkg/Include/Ppi/SecPlatformInformation.h
+++ b/MdePkg/Include/Ppi/SecPlatformInformation.h
@@ -156,9 +156,6 @@ EFI_STATUS
 /// discover where to begin dispatching PEIMs.

 ///

 struct _EFI_SEC_PLATFORM_INFORMATION_PPI {

-  ///

-  /// Conveys state information out of the SEC phase into PEI.

-  ///

   EFI_SEC_PLATFORM_INFORMATION  PlatformInformation;

 };

 

diff --git a/MdePkg/Include/Ppi/Security2.h b/MdePkg/Include/Ppi/Security2.h
index c18da3fd5e..291c1e8801 100644
--- a/MdePkg/Include/Ppi/Security2.h
+++ b/MdePkg/Include/Ppi/Security2.h
@@ -84,10 +84,6 @@ EFI_STATUS
 /// trusted.

 ///

 struct _EFI_PEI_SECURITY2_PPI {

-  ///

-  /// Allows the platform builder to implement a security policy

-  /// in response to varying file authentication states.

-  ///

   EFI_PEI_SECURITY_AUTHENTICATION_STATE   AuthenticationState;

 };

 

diff --git a/MdePkg/Include/Ppi/Smbus2.h b/MdePkg/Include/Ppi/Smbus2.h
index 1cc546782b..ce58ab310b 100644
--- a/MdePkg/Include/Ppi/Smbus2.h
+++ b/MdePkg/Include/Ppi/Smbus2.h
@@ -209,23 +209,9 @@ EFI_STATUS
 ///  its SMBus controller and the slave devices attached to it.

 ///

 struct _EFI_PEI_SMBUS2_PPI {

-  ///

-  /// Executes the SMBus operation to an SMBus slave device.

-  ///

   EFI_PEI_SMBUS2_PPI_EXECUTE_OPERATION  Execute;

-  ///

-  /// Allows an SMBus 2.0 device(s) to be Address Resolution Protocol (ARP).

-  ///

   EFI_PEI_SMBUS2_PPI_ARP_DEVICE         ArpDevice;

-  ///

-  /// Allows a PEIM to retrieve the address that was allocated by the SMBus 

-  /// host controller during enumeration/ARP.

-  ///

   EFI_PEI_SMBUS2_PPI_GET_ARP_MAP        GetArpMap;

-  ///

-  /// Allows a driver to register for a callback to the SMBus host 

-  /// controller driver when the bus issues a notification to the bus controller PEIM.

-  ///

   EFI_PEI_SMBUS2_PPI_NOTIFY             Notify;

   ///

   /// Identifier which uniquely identifies this SMBus controller in a system.

diff --git a/MdePkg/Include/Ppi/Stall.h b/MdePkg/Include/Ppi/Stall.h
index 710b3b88b2..a31213db80 100644
--- a/MdePkg/Include/Ppi/Stall.h
+++ b/MdePkg/Include/Ppi/Stall.h
@@ -54,9 +54,7 @@ struct _EFI_PEI_STALL_PPI {
   /// The resolution in microseconds of the stall services.

   ///

   UINTN          Resolution;

-  ///

-  /// The actual stall procedure call. 

-  ///

+

   EFI_PEI_STALL  Stall;

 };

 

diff --git a/MdePkg/Include/Ppi/StatusCode.h b/MdePkg/Include/Ppi/StatusCode.h
index 0aa2a558ea..537059bc4a 100644
--- a/MdePkg/Include/Ppi/StatusCode.h
+++ b/MdePkg/Include/Ppi/StatusCode.h
@@ -36,10 +36,6 @@
 /// There can be only one instance of this service in the system.

 ///

 typedef struct {

-  ///

-  /// Service that allows PEIMs to report status codes.

-  /// This function is defined in PiPeicis.h.

-  ///

   EFI_PEI_REPORT_STATUS_CODE  ReportStatusCode;

 } EFI_PEI_PROGRESS_CODE_PPI;

 

diff --git a/MdePkg/Include/Ppi/TemporaryRamSupport.h b/MdePkg/Include/Ppi/TemporaryRamSupport.h
index 648127fc22..46169fcaf5 100644
--- a/MdePkg/Include/Ppi/TemporaryRamSupport.h
+++ b/MdePkg/Include/Ppi/TemporaryRamSupport.h
@@ -53,10 +53,6 @@ EFI_STATUS
 /// This service abstracts the ability to migrate contents of the platform early memory store.

 ///

 typedef struct {

-  ///

-  /// Perform the migration of contents of Temporary RAM to Permanent RAM.

-  /// Terminate the Temporary RAM if it cannot coexist with the Permanent RAM.

-  ///

   TEMPORARY_RAM_MIGRATION   TemporaryRamMigration;

 } TEMPORARY_RAM_SUPPORT_PPI;