4. Services - PEI¶

4.1. Introduction¶

A PEI Service is defined as a function, command, or other capability created by the PEI Foundation during a phase that remains available after the phase is complete. Because the PEI phase has no permanent memory available until nearly the end of the phase, the range of PEI Foundation Services created during the PEI phase cannot be as rich as those created during later phases.

PEI Services shows the PEI Services described in this section:

Table 4.1 PEI Services¶
PPI Services	Manages PEIM to PEIM Interface PPIs to facilitate intermodule calls between PEIMs Interfaces are installed and tracked on a database maintained in temporary RAM
Boot Mode Services	Manages the boot mode S3 S5 normal boot diagnostics etc of the system
HOB Services	Creates data structures called Hand Off Blocks HOBs that are used to pass information to the next phase of the PI Architecture
Firmware Volume Services	Walks the Firmware File Systems FFS in firmware volumes to find PEIMs and other firmware files in the flash device
PEI Memory Services	Provides a collection of memory management services for use both before and after permanent memory has been discovered
Status Code Services	Provides common progress and error code reporting services for example port 080h or a serial port for simple text output for debug
Reset Services	Provides a common means by which to initiate a warm or cold restart of the system

The calling convention for PEI Services is similar to PPIs. See PEIM-to-PEIM Communication for more details on PPIs.

The means by which to bind a service call into a service involves a dispatch table, EFI_PEI_SERVICES. A pointer to the table is passed into the PEIM entry point.

4.2. PPI Services¶

The following services provide the interface set for abstracting the PPI database:

InstallPpi()
ReinstallPpi()
LocatePpi()
NotifyPpi()

4.2.1. InstallPpi()¶

Summary

This service is the first one provided by the PEI Foundation. This function installs an interface in the PEI PPI database by GUID. The purpose of the service is to publish an interface that other parties can use to call additional PEIMs.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_INSTALL_PPI) (
  IN CONST EFI_PEI_SERVICES         **PeiServices,
  IN CONST EFI_PEI_PPI_DESCRIPTOR   *PpiList
);

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

PpiList: A pointer to the list of interfaces that the caller shall install. Type EFI_PEI_PPI_DESCRIPTOR is defined in “PEIM Descriptors”.

Description

This service enables a given PEIM to register an interface with the PEI Foundation. The interface takes a pointer to a list of records that adhere to the format of a EFI_PEI_PPI_DESCRIPTOR . Since the PEI Foundation maintains a pointer to the list rather than copying the list, the list must either be in the body of the PEIM or else allocated from temporary or permanent RAM.

The length of the list of described by the EFI_PEI_PPI_DESCRIPTOR that has the EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST flag set in its Flags field. There shall be at least one EFI_PEI_PPI_DESCRIPTOR in the list.

There are two types of EFI_PEI_PPI_DESCRIPTOR``s that can be installed, including the ``EFI_PEI_PPI_DESCRIPTOR_NOTIFY_DISPATCH and EFI_PEI_PPI_DESCRIPTOR_NOTIFY_CALLBACK .

Status Codes Returned

EFI_SUCCESS	The interface was successfully installed
EFI_INVALID_PARAMETER	The PpiList pointer is NULL
EFI_INVALID_PARAMETER	Any of the PEI PPI descriptors in the list do not have the EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field
EFI_OUT_OF_RESOURCES	There is no additional space in the PPI database

4.2.2. ReinstallPpi()¶

Summary

This function reinstalls an interface in the PEI PPI database by GUID. The purpose of the service is to publish an interface that other parties can use to replace an interface of the same name in the protocol database with a different interface.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_REINSTALL_PPI) (
  IN CONST EFI_PEI_SERVICES          **PeiServices,
  IN CONST EFI_PEI_PPI_DESCRIPTOR    *OldPpi,
  IN CONST EFI_PEI_PPI_DESCRIPTOR    *NewPpi
  );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

OldPpi: A pointer to the former PPI in the database. Type EFI_PEI_PPI_DESCRIPTOR is defined in “PEIM Descriptors”.

NewPpi: A pointer to the new interfaces that the caller shall install.

Description

This service enables PEIMs to replace an entry in the PPI database with an alternate entry.

Status Codes Returned

EFI_SUCCESS	The interface was successfully installed
EFI_INVALID_PARAMETER	The OldPpi or NewPpi pointer is NULL
EFI_INVALID_PARAMETER	Any of the PEI PPI descriptors in the list do not have the EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field
EFI_OUT_OF_RESOURCES	There is no additional space in the PPI database
EFI_NOT_FOUND	The PPI for which the reinstallation was requested has not been installed

4.2.3. LocatePpi()¶

Summary

This function locates an interface in the PEI PPI database by GUID.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_LOCATE_PPI) (
  IN CONST EFI_PEI_SERVICES      **PeiServices,
  IN CONST EFI_GUID              *Guid,
  IN UINTN                       Instance,
  IN OUT EFI_PEI_PPI_DESCRIPTOR  **PpiDescriptor OPTIONAL,
  IN OUT VOID                    **Ppi
  );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES published by the PEI Foundation.

Guid: A pointer to the GUID whose corresponding interface needs to be found.

Instance: The N-th instance of the interface that is required.

PpiDescriptor: A pointer to instance of the EFI_PEI_PPI_DESCRIPTOR.

Ppi: A pointer to the instance of the interface.

Description

This service enables PEIMs to discover a given instance of an interface. This interface differs from the interface discovery mechanism in the UEFI 2.0 specification, namely HandleProtocol() , in that the PEI PPI database does not expose the handle’s name space. Instead, PEI manages the interface set by maintaining a partial order on the interfaces such that the Instance of the interface, among others, can be traversed.

LocatePpi() provides the ability to traverse all of the installed instances of a given GUID-named PPI. For example, there can be multiple instances of a PPI named Foo in the PPI database. An Instance value of 0 will provide the first instance of the PPI that is installed. Correspondingly, an Instance value of 2 will provide the second, 3 the third, and so on. The Instance value designates when a PPI was installed. For an implementation that must reference all possible manifestations of a given GUID-named PPI, the code should invoke LocatePpi() with a monotonically increasing Instance number until EFI_NOT_FOUND is returned.

Status Codes Returned

EFI_SUCCESS	The interface was successfully returned.
EFI_NOT_FOUND	The PPI descriptor is not found in the database.

4.2.4. NotifyPpi()¶

Summary

This function installs a notification service to be called back when a given interface is installed or reinstalled. The purpose of the service is to publish an interface that other parties can use to call additional PPIs that may materialize later.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_NOTIFY_PPI) (
  IN CONST EFI_PEI_SERVICES            **PeiServices,
  IN CONST EFI_PEI_NOTIFY_DESCRIPTOR   *NotifyList
  );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

NotifyList: A pointer to the list of notification interfaces that the caller shall install. Type EFI_PEI_NOTIFY_DESCRIPTOR is defined in “PEIM Descriptors”.

Description

This service enables PEIMs to register a given service to be invoked when another service is installed or reinstalled. This service will fire notifications on PPIs installed prior to this service invocation. This is different behavior than the RegisterProtocolNotify of UEFI2.0, for example EFI_PEI_NOTIFY_DESCRIPTOR is defined in “PEIM Descriptors”.

In addition, the PPI pointer is passed back to the agent that registered for the notification so that it can deference private data, if so needed.

Status Codes Returned

EFI_SUCCESS	The interface was successfully installed
EFI_INVALID_PARAMETER	The NotifyList pointer is NULL
EFI_INVALID_PARAMETER	Any of the PEI notify descriptors in the list do not have the EFI_PEI_PPI_DESCRIPTOR_NOTIFY_TYPES bit set in the Flags field
EFI_OUT_OF_RESOURCES	There is no additional space in the PPI database

4.3. Boot Mode Services¶

These services provide abstraction for ascertaining and updating the boot mode:

GetBootMode()
SetBootMode()

See Boot Paths for additional information on the boot mode.

4.3.1. GetBootMode()¶

Summary

This function returns the present value of the boot mode.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_GET_BOOT_MODE) (
  IN CONST EFI_PEI_SERVICES           **PeiServices,
  OUT EFI_BOOT_MODE                   *BootMode
  );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

BootMode: A pointer to contain the value of the boot mode. Type EFI_BOOT_MODE is defined in “Related Definitions” below.

Description

This service enables PEIMs to ascertain the present value of the boot mode. The list of possible boot modes is described in “Related Definitions” below.

//************************************************************
// EFI_BOOT_MODE
//************************************************************
typedef UINT32 EFI_BOOT_MODE;

#define BOOT_WITH_FULL_CONFIGURATION                        0x00
#define BOOT_WITH_MINIMAL_CONFIGURATION                     0x01
#define BOOT_ASSUMING_NO_CONFIGURATION_CHANGES              0x02
#define BOOT_WITH_FULL_CONFIGURATION_PLUS_DIAGNOSTICS       0x03
#define BOOT_WITH_DEFAULT_SETTINGS                          0x04
#define BOOT_ON_S4_RESUME                                   0x05
#define BOOT_ON_S5_RESUME                                   0x06
#define BOOT_WITH_MFG_MODE_SETTINGS                         0x07
#define BOOT_ON_S2_RESUME                                   0x10
#define BOOT_ON_S3_RESUME                                   0x11
#define BOOT_ON_FLASH_UPDATE                                0x12
#define BOOT_IN_RECOVERY_MODE                               0x20
0x21 - 0xF..F Reserved Encodings

Boot Mode Register describes the bit values in the Boot Mode Register.

Table 4.2 Boot Mode Register¶
Register Bits	Values	Descriptions
MSBit 0	000000b	Boot with full configuration
	000001b	Boot with minimal configuration
	000010b	Boot assuming no configuration changes from last boot
	000011b	Boot with full configuration plus diagnostics
	000100b	Boot with default settings
	000101b	Boot on S4 resume
	000110b	Boot in S5 resume
	000111b	Boot with manufacturing mode settings
	000111b 001111b	Reserved for boot paths that configure memory

	010000b	Boot on S2 resume
	010001b	Boot on S3 resume
	010010b	Boot on flash update restart
	010011c 011111b	Reserved for boot paths that preserve memory context

	100000b	Boot in recovery mode
	100001b 111111b	Reserved for special boots

Status Codes Returned

EFI_SUCCESS

The boot mode was returned successfully.

4.3.2. SetBootMode()¶

Summary

This function sets the value of the boot mode.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_SET_BOOT_MODE) (
  IN CONST EFI_PEI_SERVICES       **PeiServices,
  IN EFI_BOOT_MODE                BootMode
  );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

BootMode: The value of the boot mode to set. Type EFI_BOOT_MODE is defined in GetBootMode().

Description

This service enables PEIMs to update the boot mode variable. This would be used by either the boot mode PPIs described in See Architectural PPIs. or by a PEIM that needs to engender a recovery condition. It is permissible to change the boot mode at any point during the PEI phase.

Status Codes Returned

EFI_SUCCESS

The value was successfully updated.

4.4. HOB Services¶

The following services describe the capabilities in the PEI Foundation for providing Hand-Off Block (HOB) manipulation:

GetHobList()
CreateHob()

The purpose of the abstraction is to automate the common case of HOB creation and manipulation. See Volume 3 for details on HOBs and their type definitions.

4.4.1. GetHobList()¶

Summary

This function returns the pointer to the list of Hand-Off Blocks (HOBs) in memory.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_GET_HOB_LIST) (
  IN CONST EFI_PEI_SERVICES     **PeiServices,
  IN OUT VOID                   **HobList
  );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

HobList: A pointer to the list of HOBs that the PEI Foundation will initialize.

Description

This service enables a PEIM to ascertain the address of the list of HOBs in memory. This service should not be required by many modules in that the creation of HOBs is provided by the PEI Service CreateHob().

Status Codes Returned

EFI_SUCCESS	The list was successfully returned.
EFI_NOT_AVAILABLE_YET	The HOB list is not yet published.

4.4.2. CreateHob()¶

Summary

This service published by the PEI Foundation abstracts the creation of a Hand-Off Block’s (HOB’s) headers.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_CREATE_HOB) (
IN CONST EFI_PEI_SERVICES       **PeiServices,
  IN UINT16                     Type,
  IN UINT16                     Length,
  IN OUT VOID                   **Hob
  );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

Type: The type of HOB to be installed. See the Volume 3 for a definition of this type.

Length: The length of the HOB to be added.

Hob: The address of a pointer that will contain the HOB header.

Description

This service enables PEIMs to create various types of HOBs. This service handles the common work of allocating memory on the HOB list, filling in the type and length fields, and building the end of the HOB list. The final aspect of this service is to return a pointer to the newly allocated HOB. At this point, the caller can fill in the type-specific data. This service is always available because the HOBs can also be created on temporary memory.

There will be no error checking on the Length input argument. Instead, the PI Architecture implementation of this service will round up the allocation size that is specified in the Length field to be a multiple of 8 bytes in length. This rounding is consistent with the requirement that all of the HOBs, including the PHIT HOB, begin on an 8-byte boundary. See the PHIT HOB definition in the Platform Initialization Specification, Volume 3, for more information.

Status Codes Returned

EFI_SUCCESS	The HOB was successfully created.
EFI_OUT_OF_RESOURCES	There is no additional space for HOB creation.

4.5. Firmware Volume Services¶

The following services abstract traversing the Firmware File System (FFS):

FfsFindNextVolume()
FfsFindNextFile()
FfsFindSectionData()
FfsFindFileByName()
FfsGetFileInfo()
FfsGetVolumeInfo()

The description of the FFS can be found in the Platform Initialization Specification , Volume 3.

4.5.1. FfsFindNextVolume()¶

Summary

The purpose of the service is to abstract the capability of the PEI Foundation to discover instances of firmware volumes in the system.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FFS_FIND_NEXT_VOLUME2) (
  IN CONST EFI_PEI_SERVICES          **PeiServices,
  IN UINTN                           Instance,
  OUT EFI_PEI_FV_HANDLE              *VolumeHandle
  );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

Instance: This instance of the firmware volume to find. The value 0 is the Boot Firmware Volume (BFV).

VolumeHandle: On exit, points to the next volume handle or NULL if it does not exist.

Description

This service enables PEIMs to discover additional firmware volumes. The core uses EFI_PEI_FIRMWARE_VOLUME_INFO_PPI to discover these volumes. The service returns a volume handle of type EFI_PEI_FV_HANDLE , which must be unique within the system.

typedef VOID *EFI_PEI_FV_HANDLE;

Status Codes Returned

EFI_SUCCESS	The volume was found.
EFI_NOT_FOUND	The volume was not found.
EFI_INVALID_PARAMETER	VolumeHandle is NULL

4.5.2. FfsFindNextFile()¶

Summary

Searches for the next matching file in the firmware volume.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FFS_FIND_NEXT_FILE2) (
 IN CONST EFI_PEI_SERVICES      **PeiServices,
 IN EFI_FV_FILETYPE             SearchType,
 IN CONST EFI_PEI_FV_HANDLE     FvHandle,
 IN OUT EFI_PEI_FILE_HANDLE     *FileHandle
 );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

SearchType: A filter to find files only of this type. Type EFI_FV_FILETYPE is defined in the Platform Initialization Specification, Volume 3. Type EFI_FV_FILETYPE_ALL causes no filtering to be done.

FvHandle: Handle of firmware volume in which to search. The type EFI_PEI_FV_HANDLE is defined in the PEI Services FfsFindNextVolume().

FileHandle: On entry, points to the current handle from which to begin searching or NULL to start at the beginning of the firmware volume. On exit, points the file handle of the next file in the volume or NULL if there are no more files. The type EFI_PEI_FILE_HANDLE is defined in “Related Defintions” below.

Description

This service enables PEIMs to discover firmware files within a specified volume. To find the first instance of a firmware file, pass a FileHandle value of NULL into the service.

The service returns a file handle of type EFI_PEI_FILE_HANDLE , which must be unique within the system.

The behavior of files with file types EFI_FV_FILETYPE_FFS_MIN and EFI_FV_FILETYPE_FFS_MAX depends on the firmware file system. For more information on the specific behavior for the standard PI firmware file system, see section 1.1.4.1.6 of the PI Specification, Volume 3.

typedef VOID *EFI_PEI_FILE_HANDLE;

Status Codes Returned

EFI_SUCCESS	The file was found.
EFI_NOT_FOUND	The file was not found.
EFI_NOT_FOUND	The header checksum was not zero.

4.5.3. FfsFindSectionData()¶

Summary

Searches for the next matching section within the specified file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FFS_FIND_SECTION_DATA2) (
  IN CONST EFI_PEI_SERVICES      **PeiServices,
  IN EFI_SECTION_TYPE            SectionType,
  IN EFI_PEI_FILE_HANDLE         FileHandle,
  OUT VOID                       **SectionData
  );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

SectionType: The value of the section type to find. Type EFI_SECTION_TYPE is defined in the Platform Initialization Specification, Volume 3.

FileHandle: Handle of the firmware file to search. Type EFI_PEI_FILE_HANDLE is defined in FfsFindNextFile(), “Related Definitions.” A pointer to the file header that contains the set of sections to be searched.

SectionData: A pointer to the discovered section, if successful.

Description

This service enables PEI modules to discover the first section of a given type within a valid file. This service will search within encapsulation sections (compression and GUIDed) as well. It will search inside of a GUIDed section or a compressed section, but may not, for example, search a GUIDed section inside a GUIDes section.

This service will not search within compression sections or GUIDed sections which require extraction if memory is not present.

Status Codes Returned

EFI_SUCCESS	The section was found.
EFI_NOT_FOUND	The section was not found.

4.5.4. FfsFindSectionData3()¶

Summary

Searches for the next matching section within the specified file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FFS_FIND_SECTION_DATA3) (
 IN CONST EFI_PEI_SERVICES       **PeiServices,
 IN EFI_SECTION_TYPE             SectionType,
 In UINTN                        SectionInstance
 IN EFI_PEI_FILE_HANDLE          FileHandle,
 OUT VOID                        **SectionData
 OUT UINT32                      *AuthenticationStatus
 );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

SectionType: The value of the section type to find. Type EFI_SECTION_TYPE is defined in the Platform Initialization Specification, Volume 3.
SectionInstance: Section instance to find.

FileHandle: Handle of the firmware file to search. Type EFI_PEI_FILE_HANDLE is defined in FfsFindNextFile(), “Related Definitions.” A pointer to the file header that contains the set of sections to be searched.

SectionData: A pointer to the discovered section, if successful.

AuthenticationStatus: A pointer to the authentication status for this section.

Description

This service enables PEI modules to discover the section of a given type within a valid file. This service will search within encapsulation sections (compression and GUIDed) as well. It will search inside of a GUIDed section or a compressed section, but may not, for example, search a GUIDed section inside a GUIDes section.

This service will not search within compression sections or GUIDed sections which require extraction if memory is not present.

Status Codes Returned

EFI_SUCCESS	The section was found.
EFI_NOT_FOUND	The section was not found.

4.5.5. FfsFindFileByName()¶

Summary

Find a file within a volume by its name.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FFS_FIND_BY_NAME) (
 IN CONST EFI_GUID               *FileName,
 IN EFI_PEI_FV_HANDLE            VolumeHandle,
 OUT EFI_PEI_FILE_HANDLE         *FileHandle
 );

Parameters

FileName: A pointer to the name of the file to find within the firmware volume.

VolumeHandle: The firmware volume to search

FileHandle: Upon exit, points to the found file’s handle or NULL if it could not be found.

Description

This service searches for files with a specific name, within either the specified firmware volume or all firmware volumes.

The service returns a file handle of type EFI_PEI_FILE_HANDLE, which must be unique within the system.

The behavior of files with file types EFI_FV_FILETYPE_FFS_MIN and EFI_FV_FILETYPE_FFS_MAX depends on the firmware file system. For more information on the specific behavior for the standard PI firmware file system, see section 1.1.4.1.6 of the PI Specification, Volume 3.

Status Codes Returned

Table 4.3 Status Codes Returned¶
EFI_SUCCESS	File was found
EFI_NOT_FOUND	File was not found
EFI_INVALID_PARAMETER	VolumeHandle or FileHandle or FileName was NULL

4.5.6. FfsGetFileInfo()¶

Summary

Returns information about a specific file.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_PEI_FFS_GET_FILE_INFO) (
 IN EFI_PEI_FILE_HANDLE    FileHandle,
 OUT EFI_FV_FILE_INFO      *FileInfo
 );

Parameters

FileHandle: Handle of the file.

FileInfo: Upon exit, points to the file’s information.

Description

This function returns information about a specific file, including its file name, type, attributes, starting address and size. If the firmware volume is not memory mapped then the Buffer member will be NULL.

typedef struct {
  EFI_GUID                FileName;
  EFI_FV_FILETYPE         FileType;
  EFI_FV_FILE_ATTRIBUTES  FileAttributes;
  VOID                    *Buffer;
  UINT32                  BufferSize;
} EFI_FV_FILE_INFO;

FileName: Name of the file.

FileType: File type. See EFI_FV_FILETYPE, which is defined in the Platform Initialization Firmware Storage Specification.

FileAttributes: Attributes of the file. Type EFI_FV_FILE_ATTRIBUTES is defined in the Platform Initialization Firmware Storage Specification.

Buffer: Points to the file’s data (not the header). Not valid if EFI_FV_FILE_ATTRIB_MEMORY_MAPPED is zero.

BufferSize: Size of the file’s data.

Status Codes Returned

EFI_SUCCESS	File information returned.
EFI_INVALID_PARAMETER	If FileHandle does not represent a valid file.
EFI_INVALID_PARAMETER	If FileInfo is NULL

4.5.7. FfsGetFileInfo2()¶

Summary

Returns information about a specific file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FFS_GET_FILE_INFO2) (
  IN EFI_PEI_FILE_HANDLE   FileHandle,
  OUT EFI_FV_FILE_INFO2    *FileInfo
);

Parameters

FileHandle: Handle of the file.

FileInfo: Upon exit, points to the file’s information.

Description

This function returns information about a specific file, including its file name, type, attributes, starting address, size and authentication status. If the firmware volume is not memory mapped then the Buffer member will be NULL.

typedef struct {
   EFI_GUID FileName;
   EFI_FV_FILETYPE          FileType;
   EFI_FV_FILE_ATTRIBUTES   FileAttributes;
   VOID                     *Buffer;
   UINT32                   BufferSize;
   UINT32                   AuthenticationStatus;
 } EFI_FV_FILE_INFO2;

FileName: Name of the file.

FileType: File type. See EFI_FV_FILETYPE , which is defined in the Platform Initialization Firmware Storage Specification .

FileAttributes: Attributes of the file. Type EFI_FV_FILE_ATTRIBUTES is defined in the Platform Initialization Firmware Storage Specification.

Buffer: Points to the file’s data (not the header). Not valid if EFI_FV_FILE_ATTRIB_MEMORY_MAPPED is zero.

BufferSize: Size of the file’s data.

AuthenticationStatus: Authentication status for this file.

Status Codes Returned

EFI_SUCCESS	File information returned.
EFI_INVALID_PARAMETER	If FileHandle does not represent a valid file.
EFI_INVALID_PARAMETER	If FileInfo is NULL

4.5.8. FfsGetVolumeInfo()¶

Summary

Returns information about the specified volume.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FFS_GET_VOLUME_INFO) (
 IN EFI_PEI_FV_HANDLE   VolumeHandle,
 OUT EFI_FV_INFO        *VolumeInfo
 );

Parameters

VolumeHandle: Handle of the volume.

VolumeInfo: Upon exit, points to the volume’s information.

 typedef struct {
  EFI_FVB_ATTRIBUTES_2   FvAttributes;
  EFI_GUID               FvFormat;
  EFI_GUID               FvName;
  VOID*                  FvStart;
  UINT64                 FvSize;
} EFI_FV_INFO;

FvAttributes: Attributes of the firmware volume. Type EFI_FVB_ATTRIBUTES_2 is defined in the Platform Initialization Firmware Storage Specficiation .

FvFormat: Format of the firmware volume. For PI Architecture Firmware Volumes, this can be copied from FileSystemGuid in EFI_FIRMWARE_VOLUME_HEADER.

FvName: Name of the firmware volume. For PI Architecture Firmware Volumes, this can be copied from VolumeName in the extended header of EFI_FIRMWARE_VOLUME_HEADER.

FvStart: Points to the first byte of the firmware volume, if bit EFI_FVB_MEMORY_MAPPED is set in FvAttributes.

FvSize: Size of the firmware volume.

Description

This function returns information about a specific firmware volume, including its name, type, attributes, starting address and size.

Status Codes Returned

EFI_SUCCESS	Volume information returned
EFI_INVALID_PARAMETER	If VolumeHandle does not represent a valid volume
EFI_INVALID_PARAMETER	If VolumeInfo is NULL
EFI_SUCCESS	Information successfully returned
EFI_INVALID_PARAMETER	The volume designated by the VolumeHandle is not available

4.5.9. RegisterForShadow()¶

Summary

Register a PEIM so that it will be shadowed and called again.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_REGISTER_FOR_SHADOW) (
 IN EFI_PEI_FILE_HANDLE              FileHandle
 );

Parameters

FileHandle: PEIM’s file handle. Must be the currently executing PEIM.

Description

This service registers a file handle so that after memory is available, the PEIM will be re-loaded into permanent memory and re-initialized. The PEIM registered this way will always be initialized twice. The first time, this function call will return EFI_SUCCESS. The second time, this function call will return EFI_ALREADY_STARTED.

Depending on the order in which PEIMs are dispatched, the PEIM making this call may be initialized after permanent memory is installed, even the first time.

Status Codes Returned

EFI_SUCCESS	The PEIM was successfully registered for shadowing
EFI_ALREADY_STARTED	The PEIM was previously registered for shadowing
EFI_NOT_FOUND	The FileHandle does not refer to a valid file handle

4.6. PEI Memory Services¶

The following services are a collection of memory management services for use both before and after permanent memory has been discovered:

InstallPeiMemory()
AllocatePages()
AllocatePool()
CopyMem()
SetMem()
FreePages()

4.6.1. InstallPeiMemory()¶

Summary

This function registers the found memory configuration with the PEI Foundation.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_INSTALL_PEI_MEMORY) (
 IN CONST EFI_PEI_SERVICES       **PeiServices,
 IN EFI_PHYSICAL_ADDRESS         MemoryBegin,
 IN UINT64                       MemoryLength
);

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

MemoryBegin: The value of a region of installed memory.

MemoryLength: The corresponding length of a region of installed memory.

Description

This service enables PEIMs to register the permanent memory configuration that has been initialized with the PEI Foundation. The result of this call-set is the creation of the appropriate Hand-Off Block (HOB) describing the physical memory.

The usage model is that the PEIM that discovers the permanent memory shall invoke this service. The memory reported is a single contiguous run. It should be enough to allocate a PEI stack and some HOB list. The full memory map will be reported using the appropriate memory HOBs. The PEI Foundation will follow up with an installation of EFI_PEI_PERMANENT_MEMORY_INSTALLED_PPI.

Any invocations of this service after the first invocation which returns EFI_SUCCESS will be ignored.

Status Codes Returned

EFI_SUCCESS	The region was successfully installed in a HOB or this service was successfully invoked earlier and no HOB modification will occur
EFI_INVALID_PARAMETER	`MemoryBegin` and `MemoryLength` are illegal for this system
EFI_OUT_OF_RESOURCES	There is no additional space for HOB creation

4.6.2. AllocatePages()¶

Summary

The purpose of the service is to publish an interface that allows PEIMs to allocate memory ranges that are managed by the PEI Foundation.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_ALLOCATE_PAGES) (
 IN CONST EFI_PEI_SERVICES      **PeiServices,
 IN EFI_MEMORY_TYPE             MemoryType,
 IN UINTN                       Pages,
 OUT EFI_PHYSICAL_ADDRESS       *Memory,
 );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

MemoryType: The type of memory to allocate. The only types allowed are EfiLoaderCode , EfiLoaderData , EfiRuntimeServicesCode , EfiRuntimeServicesData , EfiBootServicesCode , EfiBootServicesData , EfiACPIReclaimMemory, EfiReservedMemoryType , and EfiACPIMemoryNVS .

Pages: The number of contiguous 4 KiB pages to allocate. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI 2.0 specification.

Memory: Pointer to a physical address. On output, the address is set to the base of the page range that was allocated.

Description

This service allocates the requested number of pages and returns a pointer to the base address of the page range in the location referenced by Memory. The service scans the available memory to locate free pages. When it finds a physically contiguous block of pages that is large enough it creates a memory allocation HOB describing the region with the requested MemoryType.

Allocation made prior to permanent memory will be migrated to permanent memory and the HOB updated.

The expectation is that the implementation of this service will automate the creation of the Memory Allocation HOB types. As such, this is in the same spirit as the PEI Services to create the FV HOB, for example.

Prior to InstallPeiMemory() being called, PEI will allocate pages from the heap. After InstallPeiMemory() is called, PEI will allocate pages within the region of memory provided by InstallPeiMemory() service in a best-effort fashion. Location-specific allocations are not managed by the PEI foundation code.

The service also supports the creation of Memory Allocation HOBs that describe the stack, boot-strap processor (BSP) BSPStore (“Backing Store Pointer Store”), and the DXE Foundation allocation. This additional information is conveyed through the final two arguments in this API and the description of the appropriate HOB types can be found in the Platform Initialization Specification , Volume 3.

Status Codes Returned

EFI_SUCCESS	The memory range was successfully allocated.
EFI_OUT_OF_RESOURCES	The page could not be allocated.
EFI_INVALID_PARAMETER	Type is not equal to `EfiLoaderCode`, `EfiLoaderData`, `EfiRuntimeServicesCode`, `EfiRuntimeServicesData`, `EfiBootServices`, `EfiBootServicesData`, `EfiACPIReclaimMemory`, `EfiReservedMemoryType`, or `EfiACCPIMemoryNVS`.

4.6.3. AllocatePool()¶

Summary

The purpose of this service is to publish an interface that allows PEIMs to allocate memory ranges that are managed by the PEI Foundation.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_ALLOCATE_POOL) (
 IN CONST EFI_PEI_SERVICES      **PeiServices,
 IN UINTN                       Size,
 OUT VOID                       **Buffer
 );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

Size: The number of bytes to allocate from the pool.

Buffer: If the call succeeds, a pointer to a pointer to the allocated buffer; undefined otherwise.

Description

This service allocates memory from the Hand-Off Block (HOB) heap. Because HOBs can be allocated from either temporary or permanent memory, this service is available throughout the entire PEI phase.

This service allocates memory in multiples of eight bytes to maintain the required HOB alignment. The early allocations from temporary memory will be migrated to permanent memory when permanent main memory is installed; this migration shall occur when the HOB list is migrated to permanent memory.

Status Codes Returned

EFI_SUCCESS	The allocation was successful
EFI_OUT_OF_RESOURCES	There is not enough heap to allocate the requested size

4.6.4. CopyMem()¶

Summary

This service copies the contents of one buffer to another buffer.

Prototype

typedef
VOID
(EFIAPI *EFI_PEI_COPY_MEM) (
 IN VOID                       *Destination,
 IN VOID                       *Source,
 IN UINTN                      Length
 );

Parameters

Destination: Pointer to the destination buffer of the memory copy.

Source: Pointer to the source buffer of the memory copy.

Length: Number of bytes to copy from Source to Destination.

Description

This function copies Length bytes from the buffer Source to the buffer Destination.

Status Codes Returned

None.

4.6.5. FreePages()¶

Summary

Frees memory pages.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_FREE_PAGES) (
 IN CONST EFI_PEI_SERVICES     **PeiServices,
 IN EFI_PHYSICAL_ADDRESS       Memory
 IN UINTN                      Pages
 );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

Memory: The base physical address of the pages to be freed. Type EFI_PHYSICAL_ADDRESS is defined in the EFI_BOOT_SERVICES.AllocatePages()function description.

Pages: The number of contiguous 4KiB pages to free.

Descripotion

The FreePages() function returns memory allocated by AllocatePages() to the firmware.

Status Codes Returned

EFI_SUCCESS	The requested memory pages were freed
EFI_NOT_FOUND	The requested memory pages were not allocated with AllocatePages
EFI_INVALID_PARAMETER	Memory is not a page aligned address or Pages is invalid

4.6.6. SetMem()¶

Summary

The service fills a buffer with a specified value.

Prototype

typedef
VOID
(EFIAPI *EFI_PEI_SET_MEM) (
 IN VOID                     *Buffer,
 IN UINTN                    Size,
 IN UINT8                    Value
 );

Parameters

Buffer: Pointer to the buffer to fill.

Size: Number of bytes in Buffer to fill.

Value: Value to fill Buffer with.

Description

This function fills Size bytes of Buffer with Value.

Status Codes Returned

None.

4.7. Status Code Service¶

The PEI Foundation publishes the following status code service:

ReportStatusCode()

This service will report EFI_NOT_AVAILABLE_YET until a PEIM publishes the services for other modules. For the GUID of the PPI, see EFI_PEI_PROGRESS_CODE_PPI.

4.7.1. ReportStatusCode()¶

Summary

This service publishes an interface that allows PEIMs to report status codes.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_PEI_REPORT_STATUS_CODE) (
 IN CONST EFI_PEI_SERVICES            **PeiServices,
 IN EFI_STATUS_CODE_TYPE              Type,
 IN EFI_STATUS_CODE_VALUE             Value,
 IN UINT32                            Instance,
 IN CONST EFI_GUID                    *CallerId  OPTIONAL,
 IN CONST EFI_STATUS_CODE_DATA        *Data      OPTIONAL
 );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

Type: Indicates the type of status code being reported. The type EFI_STATUS_CODE_TYPE is defined in “Related Definitions” below.

Value: Describes the current status of a hardware or software entity. This includes information about the class and subclass that is used to classify the entity as well as an operation. For progress codes, the operation is the current activity. For error codes, it is the exception. For debug codes, it is not defined at this time. Type EFI_STATUS_CODE_VALUE is defined in “Related Definitions” below.

Instance: The enumeration of a hardware or software entity within the system. A system may contain multiple entities that match a class/subclass pairing. The instance differentiates between them. An instance of 0 indicates that instance information is unavailable, not meaningful, or not relevant. Valid instance numbers start with 1.

CallerId: This optional parameter may be used to identify the caller. This parameter allows the status code driver to apply different rules to different callers.

Data: This optional parameter may be used to pass additional data. Type EFI_STATUS_CODE_DATA is defined in “Related Definitions“ below. The contents of this data type may have additional GUID-specific data.

Description

ReportStatusCode() is called by PEIMs that wish to report status information on their progress. The principal use model is for a PEIM to emit one of the standard 32-bit error codes. This will allow a platform owner to ascertain the state of the system, especially under conditions where the full consoles might not have been installed.

This is the entry point that PEIMs shall use. This service can use all platform PEI Services, and when main memory is available, it can even construct a GUIDed HOB that conveys the pre-DXE data. This service can also publish an interface that is usable only from the DXE phase. This entry point should not be the same as that published to the PEIMs, and the implementation of this code path should not do the following:

Use any PEI Services or PPIs from other modules.
Make any presumptions about global memory allocation.

It can only operate on its local stack activation frame and must be careful about using I/O and memory-mapped I/O resources. These concerns, including the latter warning, arise because this service could be used during the “blackout” period between the termination of PEI and the beginning of DXE, prior to the loading of the DXE progress code driver. As such, the ownership of the memory map and platform resource allocation is indeterminate at this point in the platform evolution.

//
// Status Code Type Definition
//
typedef UINT32 EFI_STATUS_CODE_TYPE;

//
// A Status Code Type is made up of the code type and severity
// All values masked by EFI_STATUS_CODE_RESERVED_MASK are
// reserved for use by this specification.
//
#define EFI_STATUS_CODE_TYPE_MASK       0x000000FF
#define EFI_STATUS_CODE_SEVERITY_MASK   0xFF000000
#define EFI_STATUS_CODE_RESERVED_MASK   0x00FFFF00

//
// Definition of code types, all other values masked by
// EFI_STATUS_CODE_TYPE_MASK are reserved for use by
// this specification.
//
#define EFI_PROGRESS_CODE               0x00000001
#define EFI_ERROR_CODE                  0x00000002
#define EFI_DEBUG_CODE                  0x00000003

//
// Definitions of severities, all other values masked by
// EFI_STATUS_CODE_SEVERITY_MASK are reserved for use by
// this specification.
// Uncontained errors are major errors that could not contained
// to the specific component that is reporting the error
// For example, if a memory error was not detected early enough,
// the bad data could be consumed by other drivers.
//
#define EFI_ERROR_MINOR                 0x40000000
#define EFI_ERROR_MAJOR                 0x80000000
#define EFI_ERROR_UNRECOVERED           0x90000000
#define EFI_ERROR_UNCONTAINED           0xa0000000

//
// Status Code Value Definition
//
typedef UINT32 EFI_STATUS_CODE_VALUE;

//
// A Status Code Value is made up of the class, subclass, and
// an operation.
//
#define EFI_STATUS_CODE_CLASS_MASK      0xFF000000
#define EFI_STATUS_CODE_SUBCLASS_MASK   0x00FF0000
#define EFI_STATUS_CODE_OPERATION_MASK  0x0000FFFF

//
// Definition of Status Code extended data header.
// The data will follow HeaderSize bytes from the beginning of
// the structure and is Size bytes long.
//
typedef struct {
  UINT16      HeaderSize;
  UINT16      Size;
  EFI_GUID    Type;
} EFI_STATUS_CODE_DATA;

HeaderSize: The size of the structure. This is specified to enable future expansion.

Size: The size of the data in bytes. This does not include the size of the header structure.

Type: The GUID defining the type of the data.

Status Codes Returned

EFI_SUCCESS	The function completed successfully
EFI_NOT_AVAILABLE_YET	No progress code provider has installed an interface in the system

4.8. Reset Services¶

The PEI Foundation publishes the following reset service:

ResetSystem()

4.8.1. ResetSystem()¶

Summary

Resets the entire platform.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_PEI_RESET_SYSTEM) (
 IN CONST EFI_PEI_SERVICES      **PeiServices
 );

Parameters

PeiServices: An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

Description

This service resets the entire platform, including all processors and devices, and reboots the system. It is important to have a standard variant of this function for cases such as the following:

Resetting the processor to change frequency settings
Restarting hardware to complete chipset initialization
Responding to exceptions from a catastrophic errorReturned Status Codes

Status Codes Returned

EFI_NOT_AVAILABLE_YET

The service has not been installed yet.

4.9. I/O and PCI Services¶

The PEI Foundation publishes CPU I/O and PCI Configuration services.