Refine code for MdePkg/Include/Ppi according to code review comments.

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

MdePkg/Include/Ppi/ReadOnlyVariable2.h

@@ -34,32 +34,21 @@ typedef struct _EFI_PEI_READ_ONLY_VARIABLE2_PPI  EFI_PEI_READ_ONLY_VARIABLE2_PPI
   the error EFI_BUFFER_TOO_SMALL is returned and DataSize is set to the
   required buffer size to obtain the data.
 
-  @param  This            A pointer to this instance of the EFI_PEI_READ_ONLY_VARIABLE2_PPI.
+  @param  This                  A pointer to this instance of the EFI_PEI_READ_ONLY_VARIABLE2_PPI.
-
+  @param  VariableName          A pointer to a null-terminated string that is the variable's name.
-  @param  VariableName    A pointer to a null-terminated string that is the variable's name.
+  @param  VendorGuid            A pointer to an EFI_GUID that is the variable's GUID. The combination of
-
+                                VariableGuid and VariableName must be unique.
-  @param  VendorGuid      A pointer to an EFI_GUID that is the variable's GUID. The combination of
+  @param  Attributes            If non-NULL, on return, points to the variable's attributes.
-                          VariableGuid and VariableName must be unique.
+  @param  DataSize              On entry, points to the size in bytes of the Data buffer.
-
+                                On return, points to the size of the data returned in Data.
-  @param  Attributes      If non-NULL, on return, points to the variable's attributes. See "Related Definitons"
+  @param  Data                  Points to the buffer which will hold the returned variable value.
-                          below for possible attribute values.
-
-  @param  DataSize        On entry, points to the size in bytes of the Data buffer. On return, points to the size of
-                          the data returned in Data.
-
-  @param  Data            Points to the buffer which will hold the returned variable value.
-
-
-  @retval EFI_SUCCESS           The function completed successfully.
-
-  @retval EFI_NOT_FOUND         The variable was not found.
 
+  @retval EFI_SUCCESS           The variable was read successfully.
+  @retval EFI_NOT_FOUND         The variable could not be found.
   @retval EFI_BUFFER_TOO_SMALL  The DataSize is too small for the resulting data. 
                                 DataSize is updated with the size required for 
                                 the specified variable.
-
   @retval EFI_INVALID_PARAMETER VariableName, VariableGuid, DataSize or Data is NULL.
-
   @retval EFI_DEVICE_ERROR      The variable could not be retrieved because of a device error.
 
 **/
@@ -88,25 +77,19 @@ EFI_STATUS
   @param  This              A pointer to this instance of the EFI_PEI_READ_ONLY_VARIABLE2_PPI.
 
   @param  VariableNameSize  On entry, points to the size of the buffer pointed to by VariableName.
-
   @param  VariableName      On entry, a pointer to a null-terminated string that is the variable's name.
                             On return, points to the next variable's null-terminated name string.
 
   @param  VendorGuid        On entry, a pointer to an UEFI _GUID that is the variable's GUID. 
                             On return, a pointer to the next variable's GUID.
 
-
   @retval EFI_SUCCESS           The variable was read successfully.
-
   @retval EFI_NOT_FOUND         The variable could not be found.
-
   @retval EFI_BUFFER_TOO_SMALL  The VariableNameSize is too small for the resulting
                                 data. VariableNameSize is updated with the size
                                 required for the specified variable.
-
   @retval EFI_INVALID_PARAMETER VariableName, VariableGuid or
                                 VariableNameSize is NULL.
-
   @retval EFI_DEVICE_ERROR      The variable could not be retrieved because of a device error.
 
 **/
@@ -119,20 +102,18 @@ EFI_STATUS
   IN OUT    EFI_GUID                        *VariableGuid
   );
 
-/**
+///
-  @par Ppi Description:
+/// This PPI provides a lightweight, read-only variant of the full EFI 
-  This PPI provides a lightweight, read-only variant of the full EFI 
+/// variable services. 
-  variable services. 
+///
-
-  @param GetVariable
-  A service to ascertain a given variable name.
-
-  @param GetNextVariableName
-  A service to ascertain a variable based upon a given, known variable
-
-**/
 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;
 };
 

MdePkg/Include/Ppi/Reset.h

@@ -29,15 +29,20 @@
     0xef398d58, 0x9dfd, 0x4103, {0xbf, 0x94, 0x78, 0xc6, 0xf4, 0xfe, 0x71, 0x2f } \
   }
 
-/**
+//
-  @par Ppi Description:
+// EFI_PEI_RESET_PPI.ResetSystem() is equivalent to the
-  This PPI provides provide a simple reset service. 
+// PEI Service ResetSystem().
+// It is defined in PiPeiCis.h. 
+//
 
-  @param ResetSystem
+///
-  A service to reset the entire platform.
+/// 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;
 

MdePkg/Include/Ppi/SecPlatformInformation.h

@@ -39,13 +39,47 @@ typedef struct _EFI_SEC_PLATFORM_INFORMATION_PPI EFI_SEC_PLATFORM_INFORMATION_PP
 ///
 typedef union {
   struct {
+    ///
+    /// A 2-bit field indicating self-test state after reset.
+    ///
     UINT32   Status                   : 2;
+    ///
+    /// A 1-bit field indicating whether testing has occurred.
+    /// If this field is zero, the processor has not been tested,
+    /// and no further fields in the self-test State parameter are valid.
+    ///
     UINT32   Tested                   : 1;
+    ///
+    /// Reserved 13 bits.
+    ///
     UINT32   Reserved1                :13;
+    ///
+    /// A 1-bit field. If set to 1, indicates that virtual
+    /// memory features are not available.
+    ///
     UINT32   VirtualMemoryUnavailable : 1;
+    ///
+    /// A 1-bit field. If set to 1, indicates that IA-32 execution
+    /// is not available.
+    ///
     UINT32   Ia32ExecutionUnavailable : 1;
+    ///
+    /// A 1-bit field. If set to 1, indicates that the floating
+    /// point unit is not available.
+    ///
     UINT32   FloatingPointUnavailable : 1;
+    ///
+    /// A 1-bit field. If set to 1, indicates miscellaneous
+    /// functional failure other than vm, ia, or fp.
+    /// The test status field provides additional information on
+    /// test failures when the State field returns a value of
+    /// performance restricted or functionally restricted.
+    /// The value returned is implementation dependent.
+    ///
     UINT32   MiscFeaturesUnavailable  : 1;
+    ///
+    /// Reserved 12 bits.
+    ///
     UINT32   Reserved2                :12;
   } Bits;
   UINT32     Uint32;
@@ -74,8 +108,15 @@ typedef struct {
 
 } IPF_HANDOFF_STATUS;
 
-
+///
+/// EFI_SEC_PLATFORM_INFORMATION_RECORD
+///
 typedef struct {
+  ///
+  /// Contains information generated by microcode, hardware,
+  /// and/or the Itanium processor PAL code about the state
+  /// of the processor upon reset.
+  ///
   EFI_HEALTH_FLAGS HealthFlags;
 } EFI_SEC_PLATFORM_INFORMATION_RECORD;
 
@@ -84,12 +125,20 @@ typedef struct {
 /**
   This interface conveys state information out of the Security (SEC) phase into PEI.
 
+  This service is published by the SEC phase. The SEC phase handoff has an optional
+  EFI_PEI_PPI_DESCRIPTOR list as its final argument when control is passed from SEC into the
+  PEI Foundation. As such, if the platform supports the built-in self test (BIST) on IA-32 Intel
+  architecture or the PAL-A handoff state for Itanium architecture, this information is encapsulated
+  into the data structure abstracted by this service. This information is collected for the boot-strap
+  processor (BSP) on IA-32, and for Itanium architecture, it is available on all processors that execute
+  the PEI Foundation.
+
   @param  PeiServices               Pointer to the PEI Services Table.
   @param  StructureSize             Pointer to the variable describing size of the input buffer.
   @param  PlatformInformationRecord Pointer to the EFI_SEC_PLATFORM_INFORMATION_RECORD.
 
-  @retval EFI_SUCCESS           The data was successfully returned.
+  @retval EFI_SUCCESS               The data was successfully returned.
-  @retval EFI_BUFFER_TOO_SMALL  The buffer was too small.
+  @retval EFI_BUFFER_TOO_SMALL      The buffer was too small.
 
 **/
 typedef
@@ -101,17 +150,15 @@ EFI_STATUS
 );
 
 
-/**
+///
-  @par Ppi Description:
+/// This service abstracts platform-specific information. It is necessary 
-  This service abstracts platform-specific information. It is necessary 
+/// to convey this information to the PEI Foundation so that it can 
-  to convey this information to the PEI Foundation so that it can 
+/// discover where to begin dispatching PEIMs.
-  discover where to begin dispatching PEIMs.
+///
-
-  @param PlatformInformation 
-  Conveys state information out of the SEC phase into PEI.
-
-**/
 struct _EFI_SEC_PLATFORM_INFORMATION_PPI {
+  ///
+  /// Conveys state information out of the SEC phase into PEI.
+  ///
   EFI_SEC_PLATFORM_INFORMATION  PlatformInformation;
 };
 

MdePkg/Include/Ppi/Security2.h

@@ -41,56 +41,23 @@ typedef struct _EFI_PEI_SECURITY2_PPI  EFI_PEI_SECURITY2_PPI;
   priori policy in the PEI Foundation. Specifically, this
   situation leads to the question whether PEIMs that are either
   not in GUIDed sections or are in sections whose authentication
-  fails should still be executed. In fact, it is the
+  fails should still be executed.
-  responsibility of the platform builder to make this decision.
-  This platform-scoped policy is a result that a desktop system
-  might not be able to skip or not execute PEIMs because the
-  skipped PEIM could be the agent that initializes main memory.
-  Alternately, a system may require that unsigned PEIMs not be
-  executed under any circumstances. In either case, the PEI
-  Foundation simply multiplexes access to the Section Extraction
-  PPI and the Security PPI. The Section Extraction PPI determines
-  the contents of a section, and the Security PPI tells the PEI
-  Foundation whether or not to invoke the PEIM. The PEIM that
-  publishes the AuthenticationState() service uses its parameters
-  in the following ways: ?? AuthenticationStatus conveys the
-  source information upon which the PEIM acts. 1) The
-  DeferExecution value tells the PEI Foundation whether or not to
-  dispatch the PEIM. In addition, between receiving the
-  AuthenticationState() from the PEI Foundation and returning with
-  the DeferExecution value, the PEIM that publishes
-  AuthenticationState() can do the following: 2) Log the file
-  state. 3) Lock the firmware hubs in response to an unsigned
-  PEIM being discovered. These latter behaviors are platform-
-  and market-specific and thus outside the scope of the PEI CIS.
 
-  @param PeiServices   An indirect pointer to the PEI Services Table published by the PEI Foundation.
+  @param PeiServices             An indirect pointer to the PEI Services
+                                 Table published by the PEI Foundation.
+  @param This                    Interface pointer that implements the
+                                 particular EFI_PEI_SECURITY2_PPI instance.
+  @param AuthenticationStatus    Authentication status of the file.
+  @param FvHandle                Handle of the volume in which the file
+                                 resides. This allows different policies
+                                 depending on different firmware volumes.
+  @param FileHandle              Handle of the file under review.
+  @param DeferExecution          Pointer to a variable that alerts the
+                                 PEI Foundation to defer execution of a
+                                 PEIM.
 
-  @param This   Interface pointer that implements the particular
+  @retval EFI_SUCCESS            The service performed its action successfully.
-                EFI_PEI_SECURITY2_PPI instance.
+  @retval EFI_SECURITY_VIOLATION The object cannot be trusted.
-
-
-  @param AuthenticationStatus   Authentication status of the
-                                file.
-
-  @param FvHandle   Handle of the volume in which the file
-                    resides. Type EFI_PEI_FV_HANDLE is defined
-                    in FfsFindNextVolume. This allows different
-                    policies depending on different firmware
-                    volumes.
-
-  @param FileHandle   Handle of the file under review. Type
-                      EFI_PEI FILE HANDLE is defined in
-                      FfsFindNextFile.
-
-  @param DeferExecution   Pointer to a variable that alerts the
-                          PEI Foundation to defer execution of a
-                          PEIM.
-
-  @retval EFI_SUCCESS   The service performed its action
-                        successfully.
-
-  @retval EFI_SECURITY_VIOLATION  The object cannot be trusted.
 
 **/
 typedef
@@ -98,34 +65,29 @@ EFI_STATUS
 (EFIAPI *EFI_PEI_SECURITY_AUTHENTICATION_STATE)(
   IN CONST  EFI_PEI_SERVICES      **PeiServices,
   IN CONST  EFI_PEI_SECURITY2_PPI *This,
-  IN CONST  UINT32                AuthenticationStatus,
+  IN UINT32                       AuthenticationStatus,
-  IN CONST  EFI_PEI_FV_HANDLE     FvHandle,
+  IN EFI_PEI_FV_HANDLE            FvHandle,
-  IN CONST  EFI_PEI_FV_HANDLE     FileHandle,
+  IN EFI_PEI_FV_HANDLE            FileHandle,
   IN OUT    BOOLEAN               *DeferExecution
 );
 
-/**
+///
-  @par Ppi Description: 
+/// This PPI is a means by which the platform builder can indicate
-  This PPI is a means by which the platform builder can indicate
+/// a response to a PEIM's authentication state. This can be in
-  a response to a PEIM's authentication state. This can be in
+/// the form of a requirement for the PEI Foundation to skip a
-  the form of a requirement for the PEI Foundation to skip a
+/// module using the DeferExecution Boolean output in the
-  module using the DeferExecution Boolean output in the
+/// AuthenticationState() member function. Alternately, the
-  AuthenticationState() member function. Alternately, the
+/// Security PPI can invoke something like a cryptographic PPI
-  Security PPI can invoke something like a cryptographic PPI
+/// that hashes the PEIM contents to log attestations, for which
-  that hashes the PEIM contents to log attestations, for which
+/// the FileHandle parameter in AuthenticationState() will be
-  the FileHandle parameter in AuthenticationState() will be
+/// useful. If this PPI does not exist, PEIMs will be considered
-  useful. If this PPI does not exist, PEIMs will be considered
+/// trusted.
-  trusted.
+///
-
-  @param AuthenticationState  Allows the platform builder to
-                              implement a security policy in
-                              response to varying file
-                              authentication states. See the
-                              AuthenticationState() function
-                              description.
-
-**/
 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;
 };
 

MdePkg/Include/Ppi/Stall.h

@@ -46,19 +46,17 @@ EFI_STATUS
   IN UINTN                      Microseconds
   );
 
-/**
+///
-  @par Ppi Description:
+/// This service provides a simple, blocking stall with platform-specific resolution. 
-  This service provides a simple, blocking stall with platform-specific resolution. 
+///
-
-  @param Resolution
-  The resolution in microseconds of the stall services.
-
-  @param Stall
-  The actual stall procedure call. 
-
-**/
 struct _EFI_PEI_STALL_PPI {
+  ///
+  /// The resolution in microseconds of the stall services.
+  ///
   UINTN          Resolution;
+  ///
+  /// The actual stall procedure call. 
+  ///
   EFI_PEI_STALL  Stall;
 };
 

MdePkg/Include/Ppi/StatusCode.h

@@ -25,16 +25,21 @@
 #define EFI_PEI_REPORT_PROGRESS_CODE_PPI_GUID \
   { 0x229832d3, 0x7a30, 0x4b36, {0xb8, 0x27, 0xf4, 0xc, 0xb7, 0xd4, 0x54, 0x36 } }
 
-/**
+//
-  @par Ppi Description:
+// EFI_PEI_PROGRESS_CODE_PPI.ReportStatusCode() is equivalent to the
-  This ppi provides the sevice to report status code. There can be only one instance 
+// PEI Service ReportStatusCode().
-  of this service in the system.
+// It is defined in PiPeiCis.h. 
+//
 
-  @param ReportStatusCode
+///
-  Service that allows PEIMs to report status codes. This function is defined in PiPeicis.h
+/// This PPI provides the sevice to report status code.
-
+/// 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;
 

MdePkg/Include/Ppi/TemporaryRamSupport.h

@@ -29,22 +29,15 @@
   permanent memory.
 
   @param PeiServices            Pointer to the PEI Services Table.
-
   @param TemporaryMemoryBase    Source Address in temporary memory from which the SEC or PEIM will copy the
                                 Temporary RAM contents.
-
   @param PermanentMemoryBase    Destination Address in permanent memory into which the SEC or PEIM will copy the
                                 Temporary RAM contents.
-
   @param CopySize               Amount of memory to migrate from temporary to permanent memory.
 
-
-
   @retval EFI_SUCCESS           The data was successfully returned.
-
+  @retval EFI_INVALID_PARAMETER PermanentMemoryBase + CopySize > TemporaryMemoryBase when
-  @retval EFI_INVALID_PARAMETER PermanentMemoryBase + CopySize >
+                                TemporaryMemoryBase > PermanentMemoryBase.
-                                TemporaryMemoryBase when TemporaryMemoryBase >
-                                PermanentMemoryBase.
 
 **/
 typedef
@@ -56,16 +49,14 @@ EFI_STATUS
   IN UINTN                    CopySize
 );
 
-/**
+///
-  @par Ppi Description:
+/// This service abstracts the ability to migrate contents of the platform early memory store.
-  This service abstracts the ability to migrate contents of the platform early memory store.
+///
-
-  @param ResetSystem
-  Perform the migration of contents of Temporary RAM to Permanent RAM.
-  Terminate the Temporary RAM if it cannot coexist with the Permanent RAM.
-
-**/
 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;