From dafa11b191748a841a2a6a4ebab5e40c21026401 Mon Sep 17 00:00:00 2001 From: xli24 Date: Thu, 4 Sep 2008 09:15:21 +0000 Subject: [PATCH] Update MdePkg/Include/Ppi according to code review comments. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5818 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Ppi/CpuIo.h | 302 +++++++++---------- MdePkg/Include/Ppi/Decompress.h | 46 ++- MdePkg/Include/Ppi/DxeIpl.h | 31 +- MdePkg/Include/Ppi/EndOfPeiPhase.h | 4 +- MdePkg/Include/Ppi/FirmwareVolume.h | 237 +++++++-------- MdePkg/Include/Ppi/FirmwareVolumeInfo.h | 57 ++-- MdePkg/Include/Ppi/GuidedSectionExtraction.h | 97 +++--- MdePkg/Include/Ppi/LoadFile.h | 86 ++---- MdePkg/Include/Ppi/LoadImage.h | 31 +- 9 files changed, 416 insertions(+), 475 deletions(-) diff --git a/MdePkg/Include/Ppi/CpuIo.h b/MdePkg/Include/Ppi/CpuIo.h index cdb83a92d4..3966432028 100644 --- a/MdePkg/Include/Ppi/CpuIo.h +++ b/MdePkg/Include/Ppi/CpuIo.h @@ -20,7 +20,6 @@ #ifndef __PEI_CPUIO_PPI_H__ #define __PEI_CPUIO_PPI_H__ -#include #include #define EFI_PEI_CPU_IO_PPI_INSTALLED_GUID \ @@ -52,12 +51,13 @@ typedef enum { /** Memory-based access services and I/O-based access services. - @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. - @param Address The physical address of the access. - @param Count The number of accesses to perform. - @param Buffer A pointer to the buffer of data. + @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. + @param Address The physical address of the access. + @param Count The number of accesses to perform. + @param Buffer A pointer to the buffer of data. @retval EFI_SUCCESS The function completed successfully. @retval EFI_NOT_YET_AVAILABLE The service has not been installed. @@ -66,8 +66,8 @@ typedef enum { typedef EFI_STATUS (EFIAPI *EFI_PEI_CPU_IO_PPI_IO_MEM)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, IN EFI_PEI_CPU_IO_PPI_WIDTH Width, IN UINT64 Address, IN UINTN Count, @@ -80,7 +80,13 @@ EFI_STATUS /// ******************************************************* /// typedef struct { + /// + /// This service provides the various modalities of memory and I/O read. + /// EFI_PEI_CPU_IO_PPI_IO_MEM Read; + /// + /// This service provides the various modalities of memory and I/O write. + /// EFI_PEI_CPU_IO_PPI_IO_MEM Write; } EFI_PEI_CPU_IO_PPI_ACCESS; @@ -91,15 +97,15 @@ typedef struct { @param This Pointer to local data for the interface. @param Address The physical address of the access. - @return UINT8 An 8-bit value is returned from the I/O space. + @return An 8-bit value returned from the I/O space. **/ typedef UINT8 (EFIAPI *EFI_PEI_CPU_IO_PPI_IO_READ8)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address ); /** @@ -109,15 +115,15 @@ UINT8 @param This Pointer to local data for the interface. @param Address The physical address of the access. - @return UINT16 A 16-bit value is returned from the I/O space. + @return A 16-bit value returned from the I/O space. **/ typedef UINT16 (EFIAPI *EFI_PEI_CPU_IO_PPI_IO_READ16)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address ); /** @@ -127,15 +133,15 @@ UINT16 @param This Pointer to local data for the interface. @param Address The physical address of the access. - @return UINT32 A 32-bit value is returned from the I/O space. + @return A 32-bit value returned from the I/O space. **/ typedef UINT32 (EFIAPI *EFI_PEI_CPU_IO_PPI_IO_READ32)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address ); /** @@ -145,15 +151,15 @@ UINT32 @param This Pointer to local data for the interface. @param Address The physical address of the access. - @return UINT64 A 64-bit value is returned from the I/O space. + @return A 64-bit value returned from the I/O space. **/ typedef UINT64 (EFIAPI *EFI_PEI_CPU_IO_PPI_IO_READ64)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address ); /** @@ -164,16 +170,14 @@ UINT64 @param Address The physical address of the access. @param Data The data to write. - @return None - **/ typedef VOID (EFIAPI *EFI_PEI_CPU_IO_PPI_IO_WRITE8)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address, - IN UINT8 Data + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address, + IN UINT8 Data ); /** @@ -184,16 +188,14 @@ VOID @param Address The physical address of the access. @param Data The data to write. - @return None - **/ typedef VOID (EFIAPI *EFI_PEI_CPU_IO_PPI_IO_WRITE16)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address, - IN UINT16 Data + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address, + IN UINT16 Data ); /** @@ -204,16 +206,14 @@ VOID @param Address The physical address of the access. @param Data The data to write. - @return None - **/ typedef VOID (EFIAPI *EFI_PEI_CPU_IO_PPI_IO_WRITE32)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address, - IN UINT32 Data + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address, + IN UINT32 Data ); /** @@ -224,248 +224,236 @@ VOID @param Address The physical address of the access. @param Data The data to write. - @return None - **/ typedef VOID (EFIAPI *EFI_PEI_CPU_IO_PPI_IO_WRITE64)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address, - IN UINT64 Data + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address, + IN UINT64 Data ); /** - 8-bit Memory read operations. + 8-bit memory read operations. @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 Address The physical address of the access. - @return UINT8 An 8-bit value is returned from the memory space. + @return An 8-bit value returned from the memory space. **/ typedef UINT8 (EFIAPI *EFI_PEI_CPU_IO_PPI_MEM_READ8)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address ); /** - 16-bit Memory read operations. + 16-bit memory read operations. @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 Address The physical address of the access. - @return UINT16 A 16-bit value is returned from the memory space. + @return A 16-bit value returned from the memory space. **/ typedef UINT16 (EFIAPI *EFI_PEI_CPU_IO_PPI_MEM_READ16)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address ); /** - 32-bit Memory read operations. + 32-bit memory read operations. @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 Address The physical address of the access. - @return UINT32 A 32-bit value is returned from the memory space. + @return A 32-bit value returned from the memory space. **/ typedef UINT32 (EFIAPI *EFI_PEI_CPU_IO_PPI_MEM_READ32)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address ); /** - 64-bit Memory read operations. + 64-bit memory read operations. @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 Address The physical address of the access. - @return UINT64 A 64-bit value is returned from the memory space. + @return A 64-bit value returned from the memory space. **/ typedef UINT64 (EFIAPI *EFI_PEI_CPU_IO_PPI_MEM_READ64)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address ); /** - 8-bit Memory write operations. + 8-bit memory write operations. @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 Address The physical address of the access. @param Data The data to write. - @return None - **/ typedef VOID (EFIAPI *EFI_PEI_CPU_IO_PPI_MEM_WRITE8)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address, - IN UINT8 Data + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address, + IN UINT8 Data ); /** - 16-bit Memory write operations. + 16-bit memory write operations. @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 Address The physical address of the access. @param Data The data to write. - @return None - **/ typedef VOID (EFIAPI *EFI_PEI_CPU_IO_PPI_MEM_WRITE16)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address, - IN UINT16 Data + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address, + IN UINT16 Data ); /** - 32-bit Memory write operations. + 32-bit memory write operations. @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 Address The physical address of the access. @param Data The data to write. - @return None - **/ typedef VOID (EFIAPI *EFI_PEI_CPU_IO_PPI_MEM_WRITE32)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address, - IN UINT32 Data + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address, + IN UINT32 Data ); /** - 64-bit Memory write operations. + 64-bit memory write operations. @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 Address The physical address of the access. @param Data The data to write. - @return None - **/ typedef VOID (EFIAPI *EFI_PEI_CPU_IO_PPI_MEM_WRITE64)( - IN EFI_PEI_SERVICES **PeiServices, - IN EFI_PEI_CPU_IO_PPI *This, - IN UINT64 Address, - IN UINT64 Data + IN CONST EFI_PEI_SERVICES **PeiServices, + IN CONST EFI_PEI_CPU_IO_PPI *This, + IN UINT64 Address, + IN UINT64 Data ); -/** - @par Ppi Description: - EFI_PEI_CPU_IO_PPI provides a set of memory and I/O-based services. - The perspective of the services is that of the processor, not the bus or system. - - @param Mem - Collection of memory-access services. - - @param I/O - Collection of I/O-access services. - - @param IoRead8 - 8-bit read service. - - @param IoRead16 - 16-bit read service. - - @param IoRead32 - 32-bit read service. - - @param IoRead64 - 64-bit read service. - - @param IoWrite8 - 8-bit write service. - - @param IoWrite16 - 16-bit write service. - - @param IoWrite32 - 32-bit write service. - - @param IoWrite64 - 64-bit write service. - - @param MemRead8 - 8-bit read service. - - @param MemRead16 - 16-bit read service. - - @param MemRead32 - 32-bit read service. - - @param MemRead64 - 64-bit read service. - - @param MemWrite8 - 8-bit write service. - - @param MemWrite16 - 16-bit write service. - - @param MemWrite32 - 32-bit write service. - - @param MemWrite64 - 64-bit write service. - -**/ +/// +/// EFI_PEI_CPU_IO_PPI provides a set of memory and I/O-based services. +/// 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_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 5cbfd8be4e..074b057928 100644 --- a/MdePkg/Include/Ppi/Decompress.h +++ b/MdePkg/Include/Ppi/Decompress.h @@ -30,48 +30,44 @@ typedef struct _EFI_PEI_DECOMPRESS_PPI EFI_PEI_DECOMPRESS_PPI; as a series of standard PI Firmware File Sections. The required memory is allocated from permanent memory. - @param This Points to this instance of the - EFI_PEI_DECOMPRESS_PEI PPI. InputSection Points to - the compressed section. - - @param OutputBuffer Holds the returned pointer to the - decompressed sections. - - @param OutputSize Holds the returned size of the decompress - section streams. + @param This Points to this instance of the + EFI_PEI_DECOMPRESS_PEI PPI. + @param InputSection Points to the compressed section. + @param OutputBuffer Holds the returned pointer to the + decompressed sections. + @param OutputSize Holds the returned size of the decompress + section streams. @retval EFI_SUCCESS The section was decompressed successfully. OutputBuffer contains the resulting data and OutputSize contains the resulting size. - @retval EFI_OUT_OF_RESOURCES Unable to allocate sufficient memory to hold the decompressed data. - @retval EFI_UNSUPPORTED The compression type specified in the compression header is unsupported. + **/ typedef EFI_STATUS (EFIAPI *EFI_PEI_DECOMPRESS_DECOMPRESS)( - IN CONST EFI_PEI_DECOMPRESS_PPI *This, - IN CONST EFI_COMPRESSION_SECTION *InputSection, - OUT VOID **OutputBuffer, - OUT UINTN *OutputSize + IN CONST EFI_PEI_DECOMPRESS_PPI *This, + IN CONST EFI_COMPRESSION_SECTION *InputSection, + OUT VOID **OutputBuffer, + OUT UINTN *OutputSize ); -/** - @par Ppi Description: - This PPI's single member function decompresses a compression - encapsulated section. It is used by the PEI Foundation to - process sectioned files. Prior to the installation of this PPI, - compression sections will be ignored. - - @param Decompress Decompress a single compression section in - a firmware file. -**/ +/// +/// This PPI's single member function decompresses a compression +/// encapsulated section. It is used by the PEI Foundation to +/// process sectioned files. Prior to the installation of this PPI, +/// 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 29c4df51b9..1ea629a011 100644 --- a/MdePkg/Include/Ppi/DxeIpl.h +++ b/MdePkg/Include/Ppi/DxeIpl.h @@ -31,6 +31,17 @@ typedef struct _EFI_DXE_IPL_PPI EFI_DXE_IPL_PPI; The architectural PPI that the PEI Foundation invokes when there are no additional PEIMs to invoke. + This function is invoked by the PEI Foundation. + The PEI Foundation will invoke this service when there are + no additional PEIMs to invoke in the system. + If this PPI does not exist, it is an error condition and + an ill-formed firmware set. The DXE IPL PPI should never + return after having been invoked by the PEI Foundation. + The DXE IPL PPI can do many things internally, including the following: + - Invoke the DXE entry point from a firmware volume + - Invoke the recovery processing modules + - Invoke the S3 resume modules + @param This Pointer to the DXE IPL PPI instance @param PeiServices Pointer to the PEI Services Table. @param HobList Pointer to the list of Hand-Off Block (HOB) entries. @@ -43,22 +54,20 @@ typedef struct _EFI_DXE_IPL_PPI EFI_DXE_IPL_PPI; typedef EFI_STATUS (EFIAPI *EFI_DXE_IPL_ENTRY)( - IN EFI_DXE_IPL_PPI *This, + IN CONST EFI_DXE_IPL_PPI *This, IN EFI_PEI_SERVICES **PeiServices, IN EFI_PEI_HOB_POINTERS HobList ); -/** - @par Ppi Description: - Final service to be invoked by the PEI Foundation. - The DXE IPL PPI is responsible for locating and loading the DXE Foundation. - The DXE IPL PPI may use PEI services to locate and load the DXE Foundation. - - @param Entry - The entry point to the DXE IPL PPI. - -**/ +/// +/// Final service to be invoked by the PEI Foundation. +/// The DXE IPL PPI is responsible for locating and loading the DXE Foundation. +/// 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/EndOfPeiPhase.h b/MdePkg/Include/Ppi/EndOfPeiPhase.h index a5a89b4bb4..e12e5c4a48 100644 --- a/MdePkg/Include/Ppi/EndOfPeiPhase.h +++ b/MdePkg/Include/Ppi/EndOfPeiPhase.h @@ -19,8 +19,8 @@ **/ -#ifndef __END_OF_PEI_SIGNAL_PPI_H__ -#define __END_OF_PEI_SIGNAL_PPI_H__ +#ifndef __END_OF_PEI_PHASE_PPI_H__ +#define __END_OF_PEI_PHASE_PPI_H__ #define EFI_PEI_END_OF_PEI_PHASE_PPI_GUID \ { \ diff --git a/MdePkg/Include/Ppi/FirmwareVolume.h b/MdePkg/Include/Ppi/FirmwareVolume.h index 1bc96796ab..4cb22649d2 100644 --- a/MdePkg/Include/Ppi/FirmwareVolume.h +++ b/MdePkg/Include/Ppi/FirmwareVolume.h @@ -21,10 +21,9 @@ /// /// The GUID for this PPI is the same as the firmware volume format GUID. -/// can be EFI_FIRMWARE_FILE_SYSTEM2_GUID or the GUID for a user-defined format. The -/// EFI_FIRMWARE_FILE_SYSTEM2_GUID is the PI Firmware Volume format. +/// The FV format can be EFI_FIRMWARE_FILE_SYSTEM2_GUID or the GUID for a user-defined +/// format. The EFI_FIRMWARE_FILE_SYSTEM2_GUID is the PI Firmware Volume format. /// - typedef struct _EFI_PEI_FIRMWARE_VOLUME_PPI EFI_PEI_FIRMWARE_VOLUME_PPI; @@ -40,26 +39,25 @@ typedef struct _EFI_PEI_FIRMWARE_VOLUME_PPI EFI_PEI_FIRMWARE_VOLUME_PPI; from the EFI_FIRMWARE_VOLUME_INFO_PPI. - @param This Points to this instance of the - EFI_PEI_FIRMWARE_VOLUME_PPI - @param Buffer Points to the start of the buffer. - @param BufferSize Size of the buffer. - @param FvHandle Points to the returned firmware volume - handle. The firmware volume handle must - be unique within the system. - + @param This Points to this instance of the + EFI_PEI_FIRMWARE_VOLUME_PPI. + @param Buffer Points to the start of the buffer. + @param BufferSize Size of the buffer. + @param FvHandle Points to the returned firmware volume + handle. The firmware volume handle must + be unique within the system. - @retval EFI_SUCCESS Firmware volume handle. + @retval EFI_SUCCESS Firmware volume handle created. @retval EFI_VOLUME_CORRUPTED Volume was corrupt. **/ typedef EFI_STATUS (EFIAPI *EFI_PEI_FV_PROCESS_FV)( - IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, - IN CONST VOID *Buffer, - IN CONST UINTN BufferSize, - OUT EFI_PEI_FV_HANDLE *FvHandle + IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, + IN VOID *Buffer, + IN UINTN BufferSize, + OUT EFI_PEI_FV_HANDLE *FvHandle ); /** @@ -68,29 +66,29 @@ EFI_STATUS This service enables PEI modules to discover additional firmware files. The FileHandle must be unique within the system. - @param This Points to this instance of the - EFI_PEI_FIRMWARE_VOLUME_PPI. SearchType A filter - to find only files of this type. Type - EFI_FV_FILETYPE_ALL causes no filtering to be - done. - @param FvHandle Handle of firmware volume in which to - search. - - @param FileHandle Points to the current handle from which to - begin searching or NULL to start at the - beginning of the firmware volume. Updated - upon return to reflect the file found. - + @param This Points to this instance of the + EFI_PEI_FIRMWARE_VOLUME_PPI. + @param SearchType A filter to find only files of this type. Type + EFI_FV_FILETYPE_ALL causes no filtering to be + done. + @param FvHandle Handle of firmware volume in which to + search. + @param FileHandle Points to the current handle from which to + begin searching or NULL to start at the + beginning of the firmware volume. Updated + upon return to reflect the file found. @retval EFI_SUCCESS The file was found. @retval EFI_NOT_FOUND The file was not found. FileHandle contains NULL. + **/ -typedef EFI_STATUS +typedef +EFI_STATUS (EFIAPI *EFI_PEI_FV_FIND_FILE_TYPE)( - IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, - IN CONST EFI_FV_FILETYPE SearchType, - IN CONST EFI_PEI_FV_HANDLE FvHandle, - IN OUT EFI_PEI_FILE_HANDLE *FileHandle + IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, + IN EFI_FV_FILETYPE SearchType, + IN EFI_PEI_FV_HANDLE FvHandle, + IN OUT EFI_PEI_FILE_HANDLE *FileHandle ); @@ -100,26 +98,21 @@ typedef EFI_STATUS This service searches for files with a specific name, within either the specified firmware volume or all firmware volumes. - @param This Points to this instance of the - EFI_PEI_FIRMWARE_VOLUME_PPI. - - @param FileName A pointer to the name of the file to find - within the firmware volume. - - @param FvHandle Upon entry, the pointer to the firmware - volume to search or NULL if all firmware - volumes should be searched. Upon exit, the - actual firmware volume in which the file was - found. - - @param FileHandle Upon exit, points to the found file's - handle or NULL if it could not be found. - - @retval EFI_SUCCESS File was found. - - @param EFI_NOT_FOUND File was not found. - - @param EFI_INVALID_PARAMETER FvHandle or FileHandle or + @param This Points to this instance of the + EFI_PEI_FIRMWARE_VOLUME_PPI. + @param FileName A pointer to the name of the file to find + within the firmware volume. + @param FvHandle Upon entry, the pointer to the firmware + volume to search or NULL if all firmware + volumes should be searched. Upon exit, the + actual firmware volume in which the file was + found. + @param FileHandle Upon exit, points to the found file's + handle or NULL if it could not be found. + + @retval EFI_SUCCESS File was found. + @retval EFI_NOT_FOUND File was not found. + @retval EFI_INVALID_PARAMETER FvHandle or FileHandle or FileName was NULL. @@ -127,10 +120,10 @@ typedef EFI_STATUS typedef EFI_STATUS (EFIAPI *EFI_PEI_FV_FIND_FILE_NAME)( - IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, - IN CONST EFI_GUID *FileName, - IN CONST EFI_PEI_FV_HANDLE FvHandle, - OUT EFI_PEI_FILE_HANDLE *FileHandle + IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, + IN CONST EFI_GUID *FileName, + IN EFI_PEI_FV_HANDLE FvHandle, + OUT EFI_PEI_FILE_HANDLE *FileHandle ); @@ -141,109 +134,105 @@ EFI_STATUS file, including its file name, type, attributes, starting address and size. - @param This Points to this instance of the - EFI_PEI_FIRMWARE_VOLUME_PPI. - - @param FileHandle Handle of the file. - - @param FileInfo Upon exit, points to the file????s - information. + @param This Points to this instance of the + EFI_PEI_FIRMWARE_VOLUME_PPI. + @param FileHandle Handle of the file. + @param FileInfo Upon exit, points to the file's + information. @retval EFI_SUCCESS File information returned. - @retval EFI_INVALID_PARAMETER If FileHandle does not represent a valid file. - EFI_INVALID_PARAMETER If - FileInfo is NULL + @retval EFI_INVALID_PARAMETER If FileInfo is NULL. **/ - typedef -EFI_STATUS (EFIAPI *EFI_PEI_FV_GET_FILE_INFO)( +EFI_STATUS +(EFIAPI *EFI_PEI_FV_GET_FILE_INFO)( IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, - IN CONST EFI_PEI_FILE_HANDLE FileHandle, - OUT EFI_FV_FILE_INFO *FileInfo + IN EFI_PEI_FILE_HANDLE FileHandle, + OUT EFI_FV_FILE_INFO *FileInfo ); /** - This function returns information about the firmware - volume. - - @param This Points to this instance of the - EFI_PEI_FIRMWARE_VOLUME_PPI. + This function returns information about the firmware volume. - @param FvHandle Handle to the firmware handle. - - @param VolumeInfo Points to the returned firmware volume - information. - - - @retval EFI_SUCCESS Information returned - successfully. - - @retval EFI_INVALID_PARAMETER FvHandle does not indicate a - valid firmware volume or VolumeInfo is NULL + @param This Points to this instance of the + EFI_PEI_FIRMWARE_VOLUME_PPI. + @param FvHandle Handle to the firmware handle. + @param VolumeInfo Points to the returned firmware volume + information. + + @retval EFI_SUCCESS Information returned successfully. + @retval EFI_INVALID_PARAMETER FvHandle does not indicate a valid + firmware volume or VolumeInfo is NULL. + **/ typedef -EFI_STATUS (EFIAPI *EFI_PEI_FV_GET_INFO)( - IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, - IN CONST EFI_PEI_FV_HANDLE FvHandle, - OUT EFI_FV_INFO *VolumeInfo +EFI_STATUS +(EFIAPI *EFI_PEI_FV_GET_INFO)( + IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, + IN EFI_PEI_FV_HANDLE FvHandle, + OUT EFI_FV_INFO *VolumeInfo ); /** Find the next matching section in the firmware file. - This service enables PEI modules to discover sections of a given type within a valid file. - - @param This Points to this instance of the - EFI_PEI_FIRMWARE_VOLUME_PPI. - - @param SearchType A filter to find only sections of this - type. + This service enables PEI modules to discover sections + of a given type within a valid file. - @param FileHandle Handle of firmware file in which to - search. - - @param SectionData Updated upon return to point to the - section found. + @param This Points to this instance of the + EFI_PEI_FIRMWARE_VOLUME_PPI. + @param SearchType A filter to find only sections of this + type. + @param FileHandle Handle of firmware file in which to + search. + @param SectionData Updated upon return to point to the + section found. @retval EFI_SUCCESS Section was found. - @retval EFI_NOT_FOUND Section of the specified type was not found. SectionData contains NULL. **/ typedef EFI_STATUS (EFIAPI *EFI_PEI_FV_FIND_SECTION)( - IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, - IN CONST EFI_SECTION_TYPE SearchType, - IN CONST EFI_PEI_FILE_HANDLE FileHandle, - OUT VOID **SectionData + IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, + IN EFI_SECTION_TYPE SearchType, + IN EFI_PEI_FILE_HANDLE FileHandle, + OUT VOID **SectionData ); - - -/* - @par Ppi Description: - This PPI provides functions for accessing a memory-mapped firmware volume of a specific format. - - @param ProcessVolume Process a firmware volume and create a volume handle. - @param FindFileByType Find all files of a specific type. - @param FindFileByName Find the file with a specific name. - @param GetFileInfo Return the information about a specific file - @param GetVolumeInfo Return the firmware volume attributes. - @param FindSectionByType Find all sections of a specific type. - -**/ +/// +/// 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; -} ; +}; extern EFI_GUID gEfiPeiFirmwareVolumePpiGuid; diff --git a/MdePkg/Include/Ppi/FirmwareVolumeInfo.h b/MdePkg/Include/Ppi/FirmwareVolumeInfo.h index 1a7487bce0..338b60ace1 100644 --- a/MdePkg/Include/Ppi/FirmwareVolumeInfo.h +++ b/MdePkg/Include/Ppi/FirmwareVolumeInfo.h @@ -26,39 +26,40 @@ typedef struct _EFI_PEI_FIRMWARE_VOLUME_INFO_PPI EFI_PEI_FIRMWARE_VOLUME_INFO_PPI; -/** - @par Ppi Description: - This PPI describes the location and format of a firmware volume. - The FvFormat can be EFI_FIRMWARE_FILE_SYSTEM2_GUID or the GUID for - a user-defined format. The EFI_FIRMWARE_FILE_SYSTEM2_GUID is - the PI Firmware Volume format. - - @param FvFormat Unique identifier of the format of the memory-mapped firmware volume. - - @param FvInfo Points to a buffer which allows the EFI_PEI_FIRMWARE_VOLUME_PPI to - process the volume. The format of this buffer is - specific to the FvFormat. For memory-mapped firmware volumes, - this typically points to the first byte of the firmware volume. - - @param FvInfoSize Size of the data provided by FvInfo. For memory-mapped firmware volumes, - this is typically the size of the firmware volume. - - @param ParentFvName If the firmware volume originally came from a firmware file, - then these point to the parent firmware volume - name and firmware volume file. If it did not originally come - from a firmware file, these should be NULL. - - @param ParentFileName If the firmware volume originally came from a firmware file, - then these point to the parent firmware volume - name and firmware volume file. If it did not originally come - from a firmware file, these should be NULL. - -**/ +/// +/// This PPI describes the location and format of a firmware volume. +/// The FvFormat can be EFI_FIRMWARE_FILE_SYSTEM2_GUID or the GUID for +/// a user-defined format. The EFI_FIRMWARE_FILE_SYSTEM2_GUID is +/// the PI Firmware Volume format. +/// struct _EFI_PEI_FIRMWARE_VOLUME_INFO_PPI { + /// + /// Unique identifier of the format of the memory-mapped firmware volume. + /// EFI_GUID FvFormat; + /// + /// Points to a buffer which allows the EFI_PEI_FIRMWARE_VOLUME_PPI to process + /// the volume. The format of this buffer is specific to the FvFormat. + /// For memory-mapped firmware volumes, this typically points to the first byte + /// of the firmware volume. + /// VOID *FvInfo; + /// + /// Size of the data provided by FvInfo. For memory-mapped firmware volumes, + /// this is typically the size of the firmware volume. + /// UINT32 FvInfoSize; + /// + /// If the firmware volume originally came from a firmware file, then these + /// point to the parent firmware volume name and firmware volume file. + /// If it did not originally come from a firmware file, these should be NULL. + /// EFI_GUID *ParentFvName; + /// + /// If the firmware volume originally came from a firmware file, then these + /// point to the parent firmware volume name and firmware volume file. + /// If it did not originally come from a firmware file, these should be NULL. + /// EFI_GUID *ParentFileName; }; diff --git a/MdePkg/Include/Ppi/GuidedSectionExtraction.h b/MdePkg/Include/Ppi/GuidedSectionExtraction.h index 27f3e18073..b25bbf3253 100644 --- a/MdePkg/Include/Ppi/GuidedSectionExtraction.h +++ b/MdePkg/Include/Ppi/GuidedSectionExtraction.h @@ -51,75 +51,54 @@ typedef struct _EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI EFI_PEI_GUIDED_SECTION_E section's contents. Otherwise, *Buffer must be allocated from PEI permanent memory. - @param This Indicates the - EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI instance. - Buffer containing the input GUIDed section to be - processed. OutputBuffer OutputBuffer is - allocated from PEI permanent memory and contains - the new section stream. + @param This Indicates the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI + instance. + @param InputSection Buffer containing the input GUIDed section to be + processed. + @param OutputBuffer *OutputBuffer is allocated from PEI permanent memory + and contains the new section stream. + @param OutputSize A pointer to a caller-allocated UINTN in which + the size of *OutputBuffer allocation is stored. + If the function returns anything other than + EFI_SUCCESS, the value of *OutputSize is undefined. + @param AuthenticationStatus A pointer to a caller-allocated UINT32 that indicates + the authentication status of the output buffer. + If the input section's + GuidedSectionHeader.Attributes field has the + EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit as clear, + *AuthenticationStatus must return zero. These bits + reflect the status of the extraction operation. + If the function returns anything other than EFI_SUCCESS, + the value of *AuthenticationStatus is undefined. - @param OutputSize A pointer to a caller-allocated - UINTN in which the size of *OutputBuffer - allocation is stored. If the function - returns anything other than EFI_SUCCESS, - the value of OutputSize is undefined. - - @param AuthenticationStatus A pointer to a caller-allocated - UINT32 that indicates the - authentication status of the - output buffer. If the input - section's GuidedSectionHeader. - Attributes field has the - EFI_GUIDED_SECTION_AUTH_STATUS_VALID - bit as clear, - AuthenticationStatus must return - zero. These bits reflect the - status of the extraction - operation. If the function - returns anything other than - EFI_SUCCESS, the value of - AuthenticationStatus is - undefined. - - @retval EFI_SUCCESS The InputSection was - successfully processed and the + @retval EFI_SUCCESS The InputSection was successfully processed and the section contents were returned. - - @retval EFI_OUT_OF_RESOURCES The system has insufficient - resources to process the request. - - @retval EFI_INVALID_PARAMETER The GUID in InputSection does - not match this instance of the + @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process the request. + @retval EFI_INVALID_PARAMETER The GUID in InputSection does not match this instance of the GUIDed Section Extraction PPI. **/ typedef EFI_STATUS (EFIAPI *EFI_PEI_EXTRACT_GUIDED_SECTION)( - IN CONST EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI *This, - IN CONST VOID *InputSection, - OUT VOID **OutputBuffer, - OUT UINTN *OutputSize, - OUT UINT32 *AuthenticationStatus + IN CONST EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI *This, + IN CONST VOID *InputSection, + OUT VOID **OutputBuffer, + OUT UINTN *OutputSize, + OUT UINT32 *AuthenticationStatus ); - - -/** - @par Ppi Description: - If a GUID-defined section is encountered when doing section extraction, - the PEI Foundation or the EFI_PEI_FILE_LOADER_PPI instance - calls the appropriate instance of the GUIDed Section - Extraction PPI to extract the section stream contained - therein. - - - @param ExtractSection Takes the GUIDed section as input and - produces the section stream data. See - the ExtractSection() function - description. - -**/ +/// +/// If a GUID-defined section is encountered when doing section extraction, +/// the PEI Foundation or the EFI_PEI_FILE_LOADER_PPI instance +/// calls the appropriate instance of the GUIDed Section +/// Extraction PPI to extract the section stream contained +/// 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 96955f764a..79cf0cd299 100644 --- a/MdePkg/Include/Ppi/LoadFile.h +++ b/MdePkg/Include/Ppi/LoadFile.h @@ -27,70 +27,48 @@ typedef struct _EFI_PEI_LOAD_FILE_PPI EFI_PEI_LOAD_FILE_PPI; /** Loads a PEIM into memory for subsequent execution. - This service is the single member function of EFI_LOAD_FILE_PPI. This service separates - image loading and relocating from the PEI Foundation. + This service is the single member function of EFI_LOAD_FILE_PPI. + This service separates image loading and relocating from the PEI Foundation. - @param This Interface pointer that implements - the Load File PPI instance. - - @param FileHandle File handle of the file to load. - Type EFI_PEI_FILE_HANDLE is defined in - FfsFindNextFile(). - - @param ImageAddress Pointer to the address of the - loaded image. - - @param ImageSize Pointer to the size of the loaded - image. - - @param EntryPoint Pointer to the entry point of the - image. - - @param AuthenticationState On exit, points to the attestation - authentication state of the image - or 0 if no attestation was - performed. The format of - AuthenticationState is defined in - EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI.ExtractSection() - - - @retval EFI_SUCCESS The image was loaded successfully. - + @param This Interface pointer that implements + the Load File PPI instance. + @param FileHandle File handle of the file to load. + @param ImageAddress Pointer to the address of the loaded image. + @param ImageSize Pointer to the size of the loaded image. + @param EntryPoint Pointer to the entry point of the image. + @param AuthenticationState On exit, points to the attestation + authentication state of the image + or 0 if no attestation was performed. + + @retval EFI_SUCCESS The image was loaded successfully. @retval EFI_OUT_OF_RESOURCES There was not enough memory. - - @retval EFI_LOAD_ERROR There was no supported image in - the file. - @retval EFI_INVALID_PARAMETER EntryPoint was NULL. - Or FileHandle was not a valid firmware file handle. - @retval EFI_NOT_SUPPORTED An image requires relocations or - is not memory mapped. + @retval EFI_LOAD_ERROR There was no supported image in the file. + @retval EFI_INVALID_PARAMETER FileHandle was not a valid firmware file handle. + @retval EFI_INVALID_PARAMETER EntryPoint was NULL. + @retval EFI_NOT_SUPPORTED An image requires relocations or is not + memory mapped. **/ typedef EFI_STATUS (EFIAPI *EFI_PEI_LOAD_FILE)( - IN CONST EFI_PEI_LOAD_FILE_PPI *This, - IN CONST EFI_PEI_FILE_HANDLE FileHandle, - OUT EFI_PHYSICAL_ADDRESS *ImageAddress, - OUT UINT64 *ImageSize, - OUT EFI_PHYSICAL_ADDRESS *EntryPoint, - OUT UINT32 *AuthenticationState + IN CONST EFI_PEI_LOAD_FILE_PPI *This, + IN EFI_PEI_FILE_HANDLE FileHandle, + OUT EFI_PHYSICAL_ADDRESS *ImageAddress, + OUT UINT64 *ImageSize, + OUT EFI_PHYSICAL_ADDRESS *EntryPoint, + OUT UINT32 *AuthenticationState ); - -/** - @par Ppi Description: - This PPI is a pointer to the Load File service. - This service will be published by a PEIM. The PEI Foundation - will use this service to launch the known PEI module images. - - - @param LoadFile Loads a PEIM into memory for subsequent - execution. See the LoadFile() function - description. - -**/ +/// +/// This PPI is a pointer to the Load File service. +/// This service will be published by a PEIM. The PEI Foundation +/// 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/LoadImage.h b/MdePkg/Include/Ppi/LoadImage.h index 5d07fd96b8..8bd3e576ac 100644 --- a/MdePkg/Include/Ppi/LoadImage.h +++ b/MdePkg/Include/Ppi/LoadImage.h @@ -1,5 +1,5 @@ /** @file - The file descript the PPI which notifies other drivers + The file describes the PPI which notifies other drivers of the PEIM being initialized by the PEI Dispatcher. Copyright (c) 2006 - 2008, Intel Corporation @@ -26,23 +26,24 @@ typedef struct _EFI_PEI_LOADED_IMAGE_PPI EFI_PEI_LOADED_IMAGE_PPI; -/** - @par Ppi Description: - This interface is installed by the PEI Dispatcher after the image has been - loaded and after all security checks have been performed, - to notify other PEIMs of the files which are being loaded. - - @param ImageAddress Address of the image at the address where it will be executed. - - @param ImageSize Size of the image as it will be executed. - - @param FileHandle File handle from which the image was loaded. Can be NULL, - indicating the image was not loaded from a handle. - -**/ +/// +/// This interface is installed by the PEI Dispatcher after the image has been +/// loaded and after all security checks have been performed, +/// to notify other PEIMs of the files which are being loaded. +/// struct _EFI_PEI_LOADED_IMAGE_PPI { + /// + /// Address of the image at the address where it will be executed. + /// EFI_PHYSICAL_ADDRESS ImageAddress; + /// + /// Size of the image as it will be executed. + /// UINT64 ImageSize; + /// + /// File handle from which the image was loaded. + /// Can be NULL, indicating the image was not loaded from a handle. + /// EFI_PEI_FILE_HANDLE FileHandle; }; -- 2.39.2