/**\r
The purpose of the service is to abstract the capability of the PEI \r
Foundation to discover instances of firmware volumes in the system. \r
- Given the input file pointer, this service searches for the next \r
- matching file in the Firmware File System (FFS) volume.\r
+\r
+ This service enables PEIMs to discover additional firmware volumes. The PEI Foundation uses this\r
+ service to abstract the locations and formats of various firmware volumes. These volumes include\r
+ the Boot Firmware Volume and any other volumes exposed by EFI_PEI_FV_PPI. The service\r
+ returns a volume handle of type EFI_PEI_FV_HANDLE, which must be unique within the system.\r
\r
@param PeiServices An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.\r
- @param Instance This instance of the firmware volume to find. The value 0 is the Boot Firmware Volume (BFV).\r
- @param VolumeHandle On exit, points to the next volumn handle or NULL if it does not exist.\r
+ @param Instance This instance of the firmware volume to find.\r
+ The value 0 is the Boot Firmware Volume (BFV).\r
+ @param VolumeHandle On exit, points to the next volumn handle or NULL if it does not exist.\r
\r
@retval EFI_SUCCESS The volume was found.\r
@retval EFI_NOT_FOUND The volume was not found.\r
);\r
\r
/**\r
- The purpose of the service is to abstract the capability of the PEI \r
- Foundation to discover instances of firmware files in the system. \r
- Given the input file pointer, this service searches for the next matching \r
- file in the Firmware File System (FFS) volume.\r
+ Searches for the next matching file in the firmware volume.\r
+\r
+ This service enables PEIMs to discover firmware files within a specified volume.\r
+ To find the first instance of a firmware file, pass a FileHandle value of NULL into the service.\r
+ The service returns a file handle of type EFI_PEI_FILE_HANDLE, which must be unique within\r
+ the system.\r
\r
@param PeiServices An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.\r
@param SearchType A filter to find files only of this type.\r
- @param FwVolHeader Pointer to the firmware volume header of the volume to search.This parameter \r
- must point to a valid FFS volume.\r
- @param FileHeader Pointer to the current file from which to begin searching.This pointer will be \r
- updated upon return to reflect the file found.\r
+ @param FvHandle Handle of firmware volume in which to search.\r
+ @param FileHandle On entry, points to the current handle from which to begin searching\r
+ or NULL to start at the beginning of the firmware volume.\r
+ On exit, points the file handle of the next file in the volume or NULL\r
+ if there are no more files.\r
\r
- @retval EFI_SUCCESS The file was found.\r
- @retval EFI_NOT_FOUND The file was not found.\r
- @retval EFI_NOT_FOUND The header checksum was not zero.\r
+ @retval EFI_SUCCESS The file was found.\r
+ @retval EFI_NOT_FOUND The file was not found.\r
+ @retval EFI_NOT_FOUND The header checksum was not zero.\r
\r
**/\r
typedef\r
(EFIAPI *EFI_PEI_FFS_FIND_NEXT_FILE2)(\r
IN CONST EFI_PEI_SERVICES **PeiServices,\r
IN EFI_FV_FILETYPE SearchType,\r
- IN EFI_PEI_FV_HANDLE VolumeHandle,\r
+ IN CONST EFI_PEI_FV_HANDLE FvHandle,\r
IN OUT EFI_PEI_FILE_HANDLE *FileHandle\r
);\r
\r
/**\r
- Given the input file pointer, this service searches for the next \r
- matching file in the Firmware File System (FFS) volume. \r
+ Searches for the next matching section within the specified file.\r
+\r
+ This service enables PEI modules to discover the first section of a given type within a valid file.\r
+ This service will search within encapsulation sections (compression and GUIDed) as well. It will\r
+ search inside of a GUIDed section or a compressed section, but may not, for example, search a\r
+ GUIDed section inside a GUIDes section.\r
+ This service will not search within compression sections or GUIDed sections which require\r
+ extraction if memory is not present.\r
\r
@param PeiServices An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.\r
@param SectionType The value of the section type to find.\r
- @param FfsFileHeader A pointer to the file header that contains the set of sections to be searched.\r
+ @param FileHandle Handle of the firmware file to search.\r
@param SectionData A pointer to the discovered section, if successful.\r
\r
- @retval EFI_SUCCESS The section was found.\r
- @retval EFI_NOT_FOUND The section was not found.\r
+ @retval EFI_SUCCESS The section was found.\r
+ @retval EFI_NOT_FOUND The section was not found.\r
\r
**/\r
typedef\r
IN CONST EFI_PEI_SERVICES **PeiServices,\r
IN EFI_SECTION_TYPE SectionType,\r
IN EFI_PEI_FILE_HANDLE FileHandle,\r
- IN OUT VOID **SectionData\r
+ OUT VOID **SectionData\r
);\r
\r
/**\r
IN CONST EFI_PEI_SERVICES **PeiServices,\r
IN EFI_MEMORY_TYPE MemoryType,\r
IN UINTN Pages,\r
- IN OUT EFI_PHYSICAL_ADDRESS *Memory\r
+ OUT EFI_PHYSICAL_ADDRESS *Memory\r
);\r
\r
/**\r
/**\r
This service publishes an interface that allows PEIMs to report status codes.\r
\r
+ ReportStatusCode() is called by PEIMs that wish to report status information on their\r
+ progress. The principal use model is for a PEIM to emit one of the standard 32-bit error codes. This\r
+ will allow a platform owner to ascertain the state of the system, especially under conditions where\r
+ the full consoles might not have been installed.\r
+\r
@param PeiServices An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.\r
@param Type Indicates the type of status code being reported.\r
@param Value Describes the current status of a hardware or\r
/**\r
Resets the entire platform.\r
\r
+ This service resets the entire platform, including all processors\r
+ and devices, and reboots the system.\r
+ This service will never return EFI_SUCCESS. \r
+\r
@param PeiServices An indirect pointer to the EFI_PEI_SERVICES\r
table published by the PEI Foundation.\r
\r
- @retval EFI_SUCCESS The function completed successfully.\r
@retval EFI_NOT_AVAILABLE_YET The service has not been installed yet.\r
\r
**/\r
);\r
\r
/**\r
- \r
+ Find a file within a volume by its name.\r
+\r
This service searches for files with a specific name, within\r
either the specified firmware volume or all firmware volumes.\r
The service returns a file handle of type EFI_PEI_FILE_HANDLE,\r
\r
@param FileName A pointer to the name of the file to\r
find within the firmware volume.\r
- @param VolumeHandle The firmware volume to search FileHandle\r
- Upon exit, points to the found file's\r
+ @param VolumeHandle The firmware volume to search.\r
+ @param FileHandle Upon exit, points to the found file's\r
handle or NULL if it could not be found.\r
\r
@retval EFI_SUCCESS File was found.\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PEI_FFS_FIND_BY_NAME)(\r
- IN CONST EFI_GUID *FileName,\r
- IN CONST EFI_PEI_FV_HANDLE VolumeHandle,\r
- OUT EFI_PEI_FILE_HANDLE *FileHandle\r
+ IN CONST EFI_GUID *FileName,\r
+ IN EFI_PEI_FV_HANDLE VolumeHandle,\r
+ OUT EFI_PEI_FILE_HANDLE *FileHandle\r
);\r
\r
-\r
-/**\r
- \r
- @param FileName Name of the file.\r
- @param FileType File type. See EFI_FV_FILETYPE, which is\r
- defined in the Platform Initialization\r
- Firmware Storage Specification.\r
- @param FileAttributes Attributes of the file. Type\r
- EFI_FV_FILE_ATTRIBUTES is defined in\r
- the Platform Initialization Firmware\r
- Storage Specification.\r
- @param Buffer Points to the file's data (not the header).\r
- Not valid if EFI_FV_FILE_ATTRIB_MEMORY_MAPPED\r
- is zero.\r
- @param BufferSize Size of the file's data.\r
-\r
-**/\r
+///\r
+/// Information of FV file.\r
+///\r
typedef struct {\r
+ ///\r
+ /// Name of the file.\r
+ ///\r
EFI_GUID FileName;\r
+ ///\r
+ /// File type.\r
+ ///\r
EFI_FV_FILETYPE FileType;\r
+ ///\r
+ /// Attributes of the file.\r
+ ///\r
EFI_FV_FILE_ATTRIBUTES FileAttributes;\r
+ ///\r
+ /// Points to the file's data (not the header).\r
+ /// Not valid if EFI_FV_FILE_ATTRIB_MEMORY_MAPPED\r
+ /// is zero.\r
+ ///\r
VOID *Buffer;\r
+ ///\r
+ /// Size of the file\92s data.\r
+ ///\r
UINT32 BufferSize;\r
} EFI_FV_FILE_INFO;\r
\r
/**\r
+ Returns information about a specific file.\r
+\r
This function returns information about a specific file,\r
including its file name, type, attributes, starting address and\r
size. If the firmware volume is not memory mapped then the\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PEI_FFS_GET_FILE_INFO)(\r
- IN CONST EFI_PEI_FILE_HANDLE FileHandle,\r
+ IN EFI_PEI_FILE_HANDLE FileHandle,\r
OUT EFI_FV_FILE_INFO *FileInfo\r
);\r
\r
-\r
-/**\r
- \r
- @param FvAttributes Attributes of the firmware volume. Type\r
- EFI_FVB_ATTRIBUTES_2 is defined in the\r
- Platform Initialization Firmware Storage\r
- Specficiation.\r
-\r
- @param FvFormat Format of the firmware volume. For PI\r
- Architecture Firmware Volumes, this can\r
- be copied from FileSystemGuid in\r
- EFI_FIRMWARE_VOLUME_HEADER.\r
-\r
- @param FvName Name of the firmware volume. For PI\r
- Architecture Firmware Volumes, this can\r
- be copied from VolumeName in the\r
- extended header of\r
- EFI_FIRMWARE_VOLUME_HEADER.\r
-\r
- @param FvStart Points to the first byte of the firmware\r
- volume, if bit EFI_FVB_MEMORY_MAPPED is\r
- set in FvAttributes. FvSize Size of the\r
- firmware volume.\r
-\r
-**/\r
+///\r
+/// Information of FV volume.\r
+///\r
typedef struct {\r
+ ///\r
+ /// Attributes of the firmware volume.\r
+ ///\r
EFI_FVB_ATTRIBUTES_2 FvAttributes;\r
+ ///\r
+ /// Format of the firmware volume.\r
+ ///\r
EFI_GUID FvFormat;\r
+ ///\r
+ /// Name of the firmware volume.\r
+ ///\r
EFI_GUID FvName;\r
+ ///\r
+ /// Points to the first byte of the firmware\r
+ /// volume, if bit EFI_FVB_MEMORY_MAPPED is\r
+ /// set in FvAttributes.\r
+ ///\r
VOID *FvStart;\r
+ ///\r
+ /// Size of the firmware volume.\r
+ ///\r
UINT64 FvSize;\r
} EFI_FV_INFO;\r
\r
/**\r
Returns information about the specified volume.\r
- \r
+\r
This function returns information about a specific firmware\r
volume, including its name, type, attributes, starting address\r
and size.\r
\r
/**\r
Register a PEIM so that it will be shadowed and called again.\r
- \r
+\r
This service registers a file handle so that after memory is\r
available, the PEIM will be re-loaded into permanent memory and\r
re-initialized. The PEIM registered this way will always be\r
initialized after permanent memory is installed, even the first\r
time.\r
\r
- @param FileHandle PEIM's file handle. Must be the currently\r
+ @param FileHandle PEIM's file handle. Must be the currently\r
executing PEIM.\r
\r
@retval EFI_SUCCESS The PEIM was successfully registered for\r
/// - Creating Hand-Off Blocks (HOBs)\r
///\r
struct _EFI_PEI_SERVICES {\r
+ ///\r
+ /// The table header for the PEI Services Table.\r
+ ///\r
EFI_TABLE_HEADER Hdr;\r
- //\r
- // PPI Functions\r
- //\r
+ ///\r
+ /// Installs an interface in the PEI PEIM-to-PEIM\r
+ /// Interface (PPI) database by GUID.\r
+ ///\r
EFI_PEI_INSTALL_PPI InstallPpi;\r
+ ///\r
+ /// Reinstalls an interface in the PEI PPI database by GUID.\r
+ ///\r
EFI_PEI_REINSTALL_PPI ReInstallPpi;\r
+ ///\r
+ /// Locates an interface in the PEI PPI database by GUID.\r
+ ///\r
EFI_PEI_LOCATE_PPI LocatePpi;\r
+ ///\r
+ /// Installs the notification service to be called back\r
+ /// upon the installation or reinstallation of a given interface.\r
+ ///\r
EFI_PEI_NOTIFY_PPI NotifyPpi;\r
- //\r
- // Boot Mode Functions\r
- //\r
+ ///\r
+ /// Returns the present value of the boot mode.\r
+ ///\r
EFI_PEI_GET_BOOT_MODE GetBootMode;\r
+ ///\r
+ /// Sets the value of the boot mode.\r
+ ///\r
EFI_PEI_SET_BOOT_MODE SetBootMode;\r
- //\r
- // HOB Functions\r
- //\r
+ ///\r
+ /// Returns the pointer to the list of Hand-Off Blocks (HOBs) in memory.\r
+ ///\r
EFI_PEI_GET_HOB_LIST GetHobList;\r
+ ///\r
+ /// Abstracts the creation of HOB headers.\r
+ ///\r
EFI_PEI_CREATE_HOB CreateHob;\r
- //\r
- // Firmware Volume Functions\r
- //\r
+ ///\r
+ /// Discovers instances of firmware volumes in the system.\r
+ ///\r
EFI_PEI_FFS_FIND_NEXT_VOLUME2 FfsFindNextVolume;\r
+ ///\r
+ /// Discovers instances of firmware files in the system.\r
+ ///\r
EFI_PEI_FFS_FIND_NEXT_FILE2 FfsFindNextFile;\r
+ ///\r
+ /// Searches for a section in a firmware file.\r
+ ///\r
EFI_PEI_FFS_FIND_SECTION_DATA2 FfsFindSectionData;\r
- //\r
- // PEI Memory Functions\r
- //\r
+ ///\r
+ /// Registers the found memory configuration with the PEI Foundation.\r
+ ///\r
EFI_PEI_INSTALL_PEI_MEMORY InstallPeiMemory;\r
+ ///\r
+ /// Allocates memory ranges that are managed by the PEI Foundation.\r
+ ///\r
EFI_PEI_ALLOCATE_PAGES AllocatePages;\r
+ ///\r
+ /// Allocate memory ranges that are managed by the PEI Foundation.\r
+ ///\r
EFI_PEI_ALLOCATE_POOL AllocatePool;\r
+ ///\r
+ /// Copies the contents of one buffer to another buffer.\r
+ ///\r
EFI_PEI_COPY_MEM CopyMem;\r
+ ///\r
+ /// Fills a buffer with a specified value.\r
+ ///\r
EFI_PEI_SET_MEM SetMem;\r
- //\r
- // Status Code\r
- //\r
+ ///\r
+ /// Provides an interface that a PEIM can call to report a status code.\r
+ ///\r
EFI_PEI_REPORT_STATUS_CODE ReportStatusCode;\r
- //\r
- // Reset\r
- //\r
+ ///\r
+ /// Resets the entire platform.\r
+ ///\r
EFI_PEI_RESET_SYSTEM ResetSystem;\r
- //\r
- // (the following interfaces are installed by publishing PEIM)\r
- //\r
- // I/O Abstractions\r
- //\r
+ ///\r
+ /// Provides an interface that a PEIM can call to execute\r
+ /// an I/O transaction. This interface is installed by provider\r
+ /// PEIM by copying the interface into the PEI Service table.\r
+ ///\r
EFI_PEI_CPU_IO_PPI *CpuIo;\r
+ ///\r
+ /// Provides an interface that a PEIM can call to execute PCI\r
+ /// Configuration transactions. This interface is installed by\r
+ /// provider PEIM by copying the interface into the EFI_PEI_SERVICES table.\r
+ ///\r
EFI_PEI_PCI_CFG2_PPI *PciCfg;\r
- //\r
- // Future Installed Services\r
- //\r
+ ///\r
+ /// Discovers firmware files within a volume by name.\r
+ ///\r
EFI_PEI_FFS_FIND_BY_NAME FfsFindFileByName;\r
+ ///\r
+ /// Return information about a particular file.\r
+ ///\r
EFI_PEI_FFS_GET_FILE_INFO FfsGetFileInfo;\r
+ ///\r
+ /// Return information about a particular volume.\r
+ ///\r
EFI_PEI_FFS_GET_VOLUME_INFO FfsGetVolumeInfo;\r
+ ///\r
+ /// Register a driver to be re-loaded when memory is available.\r
+ ///\r
EFI_PEI_REGISTER_FOR_SHADOW RegisterForShadow;\r
};\r
\r
/// temporary RAM, the stack location and BFV location.\r
/// \r
typedef struct _EFI_SEC_PEI_HAND_OFF {\r
- //\r
- // Size of the data structure.\r
- // \r
+ ///\r
+ /// Size of the data structure.\r
+ /// \r
UINT16 DataSize;\r
\r
- //\r
- // Points to the first byte of the boot firmware volume, \r
- // which the PEI Dispatcher should search for \r
- // PEI modules.\r
- // \r
+ ///\r
+ /// Points to the first byte of the boot firmware volume, \r
+ /// which the PEI Dispatcher should search for \r
+ /// PEI modules.\r
+ /// \r
VOID *BootFirmwareVolumeBase;\r
\r
- //\r
- // Size of the boot firmware volume, in bytes.\r
- // \r
+ ///\r
+ /// Size of the boot firmware volume, in bytes.\r
+ /// \r
UINTN BootFirmwareVolumeSize;\r
\r
- //\r
- // Points to the first byte of the temporary RAM.\r
- // \r
+ ///\r
+ /// Points to the first byte of the temporary RAM.\r
+ /// \r
VOID *TemporaryRamBase;\r
\r
- //\r
- // Size of the temporary RAM, in bytes.\r
- // \r
+ ///\r
+ /// Size of the temporary RAM, in bytes.\r
+ /// \r
UINTN TemporaryRamSize;\r
\r
- //\r
- // Points to the first byte of the temporary RAM \r
- // available for use by the PEI Foundation. The area \r
- // described by PeiTemporaryRamBase and PeiTemporaryRamSize \r
- // must not extend outside beyond the area described by\r
- // TemporaryRamBase & TemporaryRamSize. This area should not\r
- // overlap with the area reported by StackBase and \r
- // StackSize.\r
- //\r
+ ///\r
+ /// Points to the first byte of the temporary RAM \r
+ /// available for use by the PEI Foundation. The area \r
+ /// described by PeiTemporaryRamBase and PeiTemporaryRamSize \r
+ /// must not extend outside beyond the area described by\r
+ /// TemporaryRamBase & TemporaryRamSize. This area should not\r
+ /// overlap with the area reported by StackBase and \r
+ /// StackSize.\r
+ ///\r
VOID *PeiTemporaryRamBase;\r
\r
- //\r
- // Size of the available temporary RAM available for \r
- // use by the PEI Foundation, in bytes.\r
- // \r
+ ///\r
+ /// Size of the available temporary RAM available for \r
+ /// use by the PEI Foundation, in bytes.\r
+ /// \r
UINTN PeiTemporaryRamSize;\r
\r
- //\r
- // Points to the first byte of the stack. \r
- // This are may be part of the memory described by \r
- // TemporaryRamBase and TemporaryRamSize \r
- // or may be an entirely separate area.\r
- // \r
+ ///\r
+ /// Points to the first byte of the stack. \r
+ /// This are may be part of the memory described by \r
+ /// TemporaryRamBase and TemporaryRamSize \r
+ /// or may be an entirely separate area.\r
+ /// \r
VOID *StackBase;\r
\r
- //\r
- // Size of the stack, in bytes.\r
- // \r
+ ///\r
+ /// Size of the stack, in bytes.\r
+ /// \r
UINTN StackSize;\r
} EFI_SEC_PEI_HAND_OFF;\r
\r