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

7 files changed, 161 insertions, 172 deletions

diff --git a/MdePkg/Include/Ppi/ReadOnlyVariable2.h b/MdePkg/Include/Ppi/ReadOnlyVariable2.h
index 49a455017e..329266a879 100644
--- a/MdePkg/Include/Ppi/ReadOnlyVariable2.h
+++ b/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  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  Attributes      If non-NULL, on return, points to the variable's attributes. See "Related Definitons"

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

+  @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  VendorGuid            A pointer to an EFI_GUID that is the variable's GUID. The combination of

+                                VariableGuid and VariableName must be unique.

+  @param  Attributes            If non-NULL, on return, points to the variable's attributes.

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

-  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

-

-**/

+///

+/// This PPI provides a lightweight, read-only variant of the full EFI 

+/// 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 717f5df506..b6d9beab50 100644
--- a/MdePkg/Include/Ppi/Reset.h
+++ b/MdePkg/Include/Ppi/Reset.h
@@ -29,15 +29,20 @@
     0xef398d58, 0x9dfd, 0x4103, {0xbf, 0x94, 0x78, 0xc6, 0xf4, 0xfe, 0x71, 0x2f } \

   }

 

-/**

-  @par Ppi Description:

-  This PPI provides provide a simple reset service. 

-

-  @param ResetSystem

-  A service to reset the entire platform.

-

-**/

+//

+// EFI_PEI_RESET_PPI.ResetSystem() is equivalent to the

+// PEI Service ResetSystem().

+// It is defined in PiPeiCis.h. 

+//

+

+///

+/// 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 fc5c366869..573939af3d 100644
--- a/MdePkg/Include/Ppi/SecPlatformInformation.h
+++ b/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_BUFFER_TOO_SMALL  The buffer was too small.

+  @retval EFI_SUCCESS               The data was successfully returned.

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

-  to convey this information to the PEI Foundation so that it can 

-  discover where to begin dispatching PEIMs.

-

-  @param PlatformInformation 

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

-

-**/

+///

+/// This service abstracts platform-specific information. It is necessary 

+/// to convey this information to the PEI Foundation so that it can 

+/// 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 5dbcd1a123..c18da3fd5e 100644
--- a/MdePkg/Include/Ppi/Security2.h
+++ b/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

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

+  fails should still be executed.

+

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

+

+  @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 CONST  EFI_PEI_FV_HANDLE     FvHandle,

-  IN CONST  EFI_PEI_FV_HANDLE     FileHandle,

+  IN UINT32                       AuthenticationStatus,

+  IN EFI_PEI_FV_HANDLE            FvHandle,

+  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

-  a response to a PEIM's authentication state. This can be in

-  the form of a requirement for the PEI Foundation to skip a

-  module using the DeferExecution Boolean output in the

-  AuthenticationState() member function. Alternately, the

-  Security PPI can invoke something like a cryptographic PPI

-  that hashes the PEIM contents to log attestations, for which

-  the FileHandle parameter in AuthenticationState() will be

-  useful. If this PPI does not exist, PEIMs will be considered

-  trusted.

-

-  @param AuthenticationState  Allows the platform builder to

-                              implement a security policy in

-                              response to varying file

-                              authentication states. See the

-                              AuthenticationState() function

-                              description.

-

-**/

+///

+/// This PPI is a means by which the platform builder can indicate

+/// a response to a PEIM's authentication state. This can be in

+/// the form of a requirement for the PEI Foundation to skip a

+/// module using the DeferExecution Boolean output in the

+/// AuthenticationState() member function. Alternately, the

+/// Security PPI can invoke something like a cryptographic PPI

+/// that hashes the PEIM contents to log attestations, for which

+/// the FileHandle parameter in AuthenticationState() will be

+/// useful. If this PPI does not exist, PEIMs will be considered

+/// 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/Stall.h b/MdePkg/Include/Ppi/Stall.h
index 41031744b3..710b3b88b2 100644
--- a/MdePkg/Include/Ppi/Stall.h
+++ b/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. 

-

-  @param Resolution

-  The resolution in microseconds of the stall services.

-

-  @param Stall

-  The actual stall procedure call. 

-

-**/

+///

+/// This service provides a simple, blocking stall with platform-specific resolution. 

+///

 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 1283e5ee12..0aa2a558ea 100644
--- a/MdePkg/Include/Ppi/StatusCode.h
+++ b/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:

-  This ppi provides the sevice to report status code. There can be only one instance 

-  of this service in the system.

-

-  @param ReportStatusCode

-  Service that allows PEIMs to report status codes. This function is defined in PiPeicis.h

-

-**/

+//

+// EFI_PEI_PROGRESS_CODE_PPI.ReportStatusCode() is equivalent to the

+// PEI Service ReportStatusCode().

+// It 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;

 

diff --git a/MdePkg/Include/Ppi/TemporaryRamSupport.h b/MdePkg/Include/Ppi/TemporaryRamSupport.h
index 76e7c923ee..648127fc22 100644
--- a/MdePkg/Include/Ppi/TemporaryRamSupport.h
+++ b/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 TemporaryMemoryBase >

-                                PermanentMemoryBase.

+  @retval EFI_INVALID_PARAMETER PermanentMemoryBase + CopySize > 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.

-

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

-

-**/

+///

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