3. PEI Services Table

3.1. Introduction

The PEI Foundation establishes a system table named the PEI Services Table that is visible to all Pre-EFI Initialization Modules (PEIMs) in the system. A PEI Service is defined as a function, command, or other capability manifested by the PEI Foundation when that service’s initialization requirements are met. Because the PEI phase has no permanent memory available until nearly the end of the phase, the range of services created during the PEI phase cannot be as rich as those created during later phases. Because the location of the PEI Foundation and its temporary RAM is not known at build time, a pointer to the PEI Services Table is passed into each PEIM’s entry point and also to part of each PEIM-to-PEIM Interface (PPI).

Note: In the PEI Foundation use of the EFI_TABLE_HEADER for the PEI Services Table, there is special treatment of the CRC32 field. This value is ignorable for PEI and should be set to zero.

3.2. PEI Services Table

3.2.1. EFI_PEI_SERVICES

3.2.1.1. Summary

The PEI Services Table includes a list of function pointers in a table. The table is located in the temporary or permanent memory, depending upon the capabilities and phase of execution of PEI. The functions in this table are defined in PEI Services.

3.2.1.2. Related Definitions

//
// PI Specification Revision information
//
#define PI_SPECIFICATION_VERSION ((1<<16) | 90)

//
// PEI Services Table
//
#define PEI_SERVICES_SIGNATURE 0x5652455320494550
#define PEI_SERVICES_REVISION PI_SPECIFICATION_VERSION

typedef EFI_PEI_SERVICES {
  EFI_TABLE_HEADER                     Hdr;
  //
  // PPI Functions
  //
  EFI_PEI_INSTALL_PPI                 InstallPpi;
  EFI_PEI_REINSTALL_PPI               ReInstallPpi;
  EFI_PEI_LOCATE_PPI                  LocatePpi;
  EFI_PEI_NOTIFY_PPI                  NotifyPpi;

  //
  // Boot Mode Functions
  //
  EFI_PEI_GET_BOOT_MODE               GetBootMode;
  EFI_PEI_SET_BOOT_MODE               SetBootMode;

  //
  // HOB Functions
  //
  EFI_PEI_GET_HOB_LIST                GetHobList;
  EFI_PEI_CREATE_HOB                  CreateHob;

  //
  // Firmware Volume Functions
  //
  EFI_PEI_FFS_FIND_NEXT_VOLUME2       FfsFindNextVolume;
  EFI_PEI_FFS_FIND_NEXT_FILE2         FfsFindNextFile;
  EFI_PEI_FFS_FIND_SECTION_DATA2      FfsFindSectionData;

  //
  // PEI Memory Functions
  //
  EFI_PEI_INSTALL_PEI_MEMORY          InstallPeiMemory;
  EFI_PEI_ALLOCATE_PAGES              AllocatePages;
  EFI_PEI_ALLOCATE_POOL               AllocatePool;
  EFI_PEI_COPY_MEM                    CopyMem;
  EFI_PEI_SET_MEM                     SetMem;

  //
  // Status Code
  EFI_PEI_REPORT_STATUS_CODE          ReportStatusCode;

  //
  // Reset
  //
  EFI_PEI_RESET_SYSTEM                ResetSystem;
  //
  // (the following interfaces are installed by publishing PEIM)
  //
  // I/O Abstractions
  //
  EFI_PEI_CPU_IO_PPI                  *CpuIo;
  EFI_PEI_PCI_CFG2_PPI                *PciCfg;

  //
  // Additional File System-Related Services
  //
  EFI_PEI_FFS_FIND_BY_NAME            FfsFindFileByName;
  EFI_PEI_FFS_GET_FILE_INFO           FfsGetFileInfo;
  EFI_PEI_FFS_GET_VOLUME_INFO         FfsGetVolumeInfo;
  EFI_PEI_REGISTER_FOR_SHADOW         RegisterForShadow;

  EFI_PEI_FFS_FIND_SECTION_DATA3      FindSectionData3;
  EFI_PEI_FFS_GET_FILE_INFO2          FfsGetFileInfo2;
  EFI_PEI_RESET2_SYSTEM               ResetSystem2;
  EFI_PEI_FREE_PAGES                  FreePages;
} EFI_PEI_SERVICES;

3.2.1.3. Parameters

Hdr

The table header for the PEI Services Table. This header contains the PEI_SERVICES_SIGNATURE and PEI_SERVICES_REVISION values along with the size of the EFI_PEI_SERVICES structure and a 32-bit CRC to verify that the contents of the PEI Foundation Services Table are valid.

InstallPpi

Installs an interface in the PEI PEIM-to-PEIM Interface (PPI) database by GUID. See the InstallPpi() function description in this document.

ReInstallPpi

Reinstalls an interface in the PEI PPI database by GUID. See the ReinstallPpi() function description in this document.

LocatePpi

Locates an interface in the PEI PPI database by GUID. See the LocatePpi() function description in this document.

NotifyPpi

Installs the notification service to be called back upon the installation or reinstallation of a given interface. See the NotifyPpi() function description in this document.

GetBootMode

Returns the present value of the boot mode. See the GetBootMode() function description in this document.

SetBootMode

Sets the value of the boot mode. See the SetBootMode() function description in this document.

GetHobList

Returns the pointer to the list of Hand-Off Blocks (HOBs) in memory. See the GetHobList() function description in this document.

CreateHob

Abstracts the creation of HOB headers. See the CreateHob() function description in this document.

FfsFindNextVolume

Discovers instances of firmware volumes in the system. See the FfsFindNextVolume() function description in this document.

FfsFindNextFile

Discovers instances of firmware files in the system. See the FfsFindNextFile() function description in this document.

FfsFindSectionData

Searches for a section in a firmware file. See the FfsFindSectionData() function description in this document.

InstallPeiMemory

Registers the found memory configuration with the PEI Foundation. See the InstallPeiMemory() function description in this document.

AllocatePages

Allocates memory ranges that are managed by the PEI Foundation. See the AllocatePages() function description in this document.

AllocatePool

Allocates memory ranges that are managed by the PEI Foundation. See the AllocatePool() function description in this document.

CopyMem

Copies the contents of one buffer to another buffer. See the CopyMem() function description in this document.

SetMem

Fills a buffer with a specified value. See the SetMem() function description in this document.

ReportStatusCode

Provides an interface that a PEIM can call to report a status code. See the ReportStatusCode() function description in this document. This is installed by provider PEIM by copying the interface into the PEI Service table.

ResetSystem

Resets the entire platform. See the ResetSystem() function description in this document. This is installed by provider PEIM by copying the interface into the PEI Service table.

ResetSystem2

Resets the entire platform. See the ResetSystem2() function description in this document. This is installed by provider PEIM by copying the interface into the PEI Service table.

CpuIo

Provides an interface that a PEIM can call to execute an I/O transaction. This interface is installed by provider PEIM by copying the interface into the PEI Service table.

PciCfg

Provides an interface that a PEIM can call to execute PCI Configuration transactions. This interface is installed by provider PEIM by copying the interface into the EFI_PEI_SERVICES table.

FfsFindFileByName

Discovers firmware files within a volume by name. See FfsFindFileByName() in this document.

FfsGetFileInfo

Return information about a particular file. See FfsGetFileInfo() in this document.

FfsGetFileInfo2

Return information about a particular file. See FfsGetFileInfo2() in this document.

FfsGetVolumeInfo

Return information about a particular volume. See FfsGetVolumeInfo() in this document.

RegisterForShadow

Register a driver to be re-loaded when memory is available. See RegisterForShadow() in this document.

FindSectionData3

Searches for a section in a firmware file. See the FfsFindSectionData3() function description in this document.

FreePages

Releases memory previously allocated using AllocatePages().

3.2.1.4. Description

EFI_PEI_SERVICES is a collection of functions whose implementation is provided by the PEI Foundation. These services fall into various classes, including the following:

• Managing the boot mode

• Allocating both early and permanent memory

• Supporting the Firmware File System (FFS)

• Abstracting the PPI database abstraction

• Creating Hand-Off Blocks (HOBs)

A pointer to the EFI_PEI_SERVICES table is passed into each PEIM when the PEIM is invoked by the PEI Foundation. As such, every PEIM has access to these services. Unlike the UEFI Boot Services, the PEI Services have no calling restrictions, such as the UEFI 2.0 Task Priority Level (TPL) limitations. Specifically, a service can be called from a PEIM or notification service.

Some of the services are also a proxy to platform-provided services, such as the Reset Services, Status Code Services, and I/O abstractions. This partitioning has been designed to provide a consistent interface to all PEIMs without encumbering a PEI Foundation implementation with platform-specific knowledge. Any callable services beyond the set in this table should be invoked using a PPI. The latter PEIM-installed services will return EFI_NOT_AVAILABLE_YET until a PEIM copies an instance of the interface into the EFI_PEI_SERVICES table.