From 13c3803149943a2a54553eee6e121873dab05acd Mon Sep 17 00:00:00 2001 From: xli24 Date: Tue, 23 Sep 2008 07:55:57 +0000 Subject: 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 | 59 +++++---------- MdePkg/Include/Ppi/Reset.h | 21 ++++-- MdePkg/Include/Ppi/SecPlatformInformation.h | 73 ++++++++++++++---- MdePkg/Include/Ppi/Security2.h | 110 +++++++++------------------- MdePkg/Include/Ppi/Stall.h | 20 +++-- MdePkg/Include/Ppi/StatusCode.h | 23 +++--- MdePkg/Include/Ppi/TemporaryRamSupport.h | 27 +++---- 7 files changed, 161 insertions(+), 172 deletions(-) (limited to 'MdePkg/Include') 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; -- cgit v1.2.3