#include "PeiMain.h"

Macros
#define	MINIMUM_INITIAL_MEMORY_SIZE 0x10000

Functions
BOOLEAN	DelayedDispatchDispatcher (IN DELAYED_DISPATCH_TABLE DelayedDispatchTable, IN EFI_GUID DelayedGroupId OPTIONAL)

EFI_STATUS EFIAPI	PeiDelayedDispatchOnEndOfPei (IN EFI_PEI_SERVICES *PeiServices, IN EFI_PEI_NOTIFY_DESCRIPTOR NotifyDesc, IN VOID *Ppi)

DELAYED_DISPATCH_TABLE *	GetDelayedDispatchTable (VOID)

EFI_STATUS EFIAPI	PeiDelayedDispatchRegister (IN EFI_DELAYED_DISPATCH_PPI This, IN EFI_DELAYED_DISPATCH_FUNCTION Function, IN UINT64 Context, IN EFI_GUID DelayedGroupId OPTIONAL, IN UINT32 Delay)

EFI_STATUS EFIAPI	PeiDelayedDispatchWaitOnEvent (IN EFI_DELAYED_DISPATCH_PPI *This, IN EFI_GUID DelayedGroupId)

VOID	DiscoverPeimsAndOrderWithApriori (IN PEI_CORE_INSTANCE Private, IN PEI_CORE_FV_HANDLE CoreFileHandle)

BOOLEAN	PeiLoadFixAddressIsMemoryRangeAvailable (IN PEI_CORE_INSTANCE PrivateData, IN EFI_HOB_RESOURCE_DESCRIPTOR ResourceHob)

VOID	PeiLoadFixAddressHook (IN PEI_CORE_INSTANCE *PrivateData)

VOID EFIAPI	PeiCoreEntry (IN CONST EFI_SEC_PEI_HAND_OFF SecCoreData, IN PEI_CORE_INSTANCE Private)

VOID	PeiCheckAndSwitchStack (IN CONST EFI_SEC_PEI_HAND_OFF SecCoreData, IN PEI_CORE_INSTANCE Private)

EFI_STATUS EFIAPI	MigratePeim (IN EFI_PEI_FILE_HANDLE FileHandle, IN EFI_PEI_FILE_HANDLE MigratedFileHandle)

VOID	ConvertStatusCodeCallbacks (IN UINTN OrgFvHandle, IN UINTN FvHandle, IN UINTN FvSize)

EFI_STATUS EFIAPI	MigratePeimsInFv (IN PEI_CORE_INSTANCE *Private, IN UINTN FvIndex, IN UINTN OrgFvHandle, IN UINTN FvHandle)

EFI_STATUS EFIAPI	EvacuateTempRam (IN PEI_CORE_INSTANCE Private, IN CONST EFI_SEC_PEI_HAND_OFF SecCoreData)

VOID	PeiDispatcher (IN CONST EFI_SEC_PEI_HAND_OFF SecCoreData, IN PEI_CORE_INSTANCE Private)

VOID	InitializeDispatcherData (IN PEI_CORE_INSTANCE PrivateData, IN PEI_CORE_INSTANCE OldCoreData, IN CONST EFI_SEC_PEI_HAND_OFF *SecCoreData)

BOOLEAN	DepexSatisfied (IN PEI_CORE_INSTANCE *Private, IN EFI_PEI_FILE_HANDLE FileHandle, IN UINTN PeimCount)

EFI_STATUS EFIAPI	PeiRegisterForShadow (IN EFI_PEI_FILE_HANDLE FileHandle)

Variables
EFI_DELAYED_DISPATCH_PPI	mDelayedDispatchPpi = { PeiDelayedDispatchRegister, PeiDelayedDispatchWaitOnEvent }

EFI_PEI_PPI_DESCRIPTOR	mDelayedDispatchDesc

EFI_PEI_NOTIFY_DESCRIPTOR	mDelayedDispatchNotifyDesc

Detailed Description

EFI PEI Core dispatch services

Copyright (c) 2006 - 2024, Intel Corporation. All rights reserved.
(C) Copyright 2016 Hewlett Packard Enterprise Development LP
Copyright (c) Microsoft Corporation. SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file Dispatcher.c.

Macro Definition Documentation

◆ MINIMUM_INITIAL_MEMORY_SIZE

#define MINIMUM_INITIAL_MEMORY_SIZE 0x10000

Definition at line 596 of file Dispatcher.c.

Function Documentation

◆ ConvertStatusCodeCallbacks()

VOID ConvertStatusCodeCallbacks	(	IN UINTN	OrgFvHandle,
		IN UINTN	FvHandle,
		IN UINTN	FvSize
	)

Migrate Status Code Callback function pointers inside an FV from temporary memory to permanent memory.

Parameters

OrgFvHandle	Address of FV handle in temporary memory.
FvHandle	Address of FV handle in permanent memory.
FvSize	Size of the FV.

Definition at line 1436 of file Dispatcher.c.

◆ DelayedDispatchDispatcher()

BOOLEAN DelayedDispatchDispatcher	(	IN DELAYED_DISPATCH_TABLE *	DelayedDispatchTable,
		IN EFI_GUID *DelayedGroupId	OPTIONAL
	)

DelayedDispatchDispatcher

Delayed Dispach cycle (ie one pass) through each entry, calling functions when their time has expired. When DelayedGroupId is specified, if there are any of the specified entries in the dispatch queue during dispatch, repeat the DelayedDispatch cycle.

Parameters

DelayedDispatchTable	Pointer to dispatch table
OPTIONAL	DelayedGroupId used to insure particular time is met.

Returns: BOOLEAN

Definition at line 200 of file Dispatcher.c.

◆ DepexSatisfied()

BOOLEAN DepexSatisfied	(	IN PEI_CORE_INSTANCE *	Private,
		IN EFI_PEI_FILE_HANDLE	FileHandle,
		IN UINTN	PeimCount
	)

This routine parses the Dependency Expression, if available, and decides if the module can be executed.

Parameters

Private	PeiCore's private data structure
FileHandle	PEIM's file handle
PeimCount	Peim count in all dispatched PEIMs.

Return values

TRUE	Can be dispatched
FALSE	Cannot be dispatched

Definition at line 2179 of file Dispatcher.c.

◆ DiscoverPeimsAndOrderWithApriori()

VOID DiscoverPeimsAndOrderWithApriori	(	IN PEI_CORE_INSTANCE *	Private,
		IN PEI_CORE_FV_HANDLE *	CoreFileHandle
	)

Discover all PEIMs and optional Apriori file in one FV. There is at most one Apriori file in one FV.

Parameters

Private	Pointer to the private data passed in from caller
CoreFileHandle	The instance of PEI_CORE_FV_HANDLE.

Definition at line 397 of file Dispatcher.c.

◆ EvacuateTempRam()

EFI_STATUS EFIAPI EvacuateTempRam	(	IN PEI_CORE_INSTANCE *	Private,
		IN CONST EFI_SEC_PEI_HAND_OFF *	SecCoreData
	)

Migrate FVs out of temporary RAM before the cache is flushed.

Parameters

Private	PeiCore's private data structure
SecCoreData	Points to a data structure containing information about the PEI core's operating environment, such as the size and location of temporary RAM, the stack location and the BFV location.

Return values

EFI_SUCCESS	Successfully migrated installed FVs from temporary RAM to permanent memory.
EFI_OUT_OF_RESOURCES	Insufficient memory exists to allocate needed pages.

Definition at line 1551 of file Dispatcher.c.

◆ GetDelayedDispatchTable()

DELAYED_DISPATCH_TABLE * GetDelayedDispatchTable ( VOID )

Helper function to look up DELAYED_DISPATCH_TABLE published in HOB.

Returns: Pointer to DELAYED_DISPATCH_TABLE from HOB

Definition at line 73 of file Dispatcher.c.

◆ InitializeDispatcherData()

VOID InitializeDispatcherData	(	IN PEI_CORE_INSTANCE *	PrivateData,
		IN PEI_CORE_INSTANCE *	OldCoreData,
		IN CONST EFI_SEC_PEI_HAND_OFF *	SecCoreData
	)

Initialize the Dispatcher's data members

Parameters

PrivateData	PeiCore's private data structure
OldCoreData	Old data from SecCore NULL if being run in non-permanent memory mode.
SecCoreData	Points to a data structure containing information about the PEI core's operating environment, such as the size and location of temporary RAM, the stack location and the BFV location.

Returns: None.

Definition at line 2149 of file Dispatcher.c.

◆ MigratePeim()

EFI_STATUS EFIAPI MigratePeim	(	IN EFI_PEI_FILE_HANDLE	FileHandle,
		IN EFI_PEI_FILE_HANDLE	MigratedFileHandle
	)

Migrate a PEIM from temporary RAM to permanent memory.

Parameters

PeimFileHandle	Pointer to the FFS file header of the image.
MigratedFileHandle	Pointer to the FFS file header of the migrated image.

Return values

EFI_SUCCESS Successfully migrated the PEIM to permanent memory.

Definition at line 1385 of file Dispatcher.c.

◆ MigratePeimsInFv()

EFI_STATUS EFIAPI MigratePeimsInFv	(	IN PEI_CORE_INSTANCE *	Private,
		IN UINTN	FvIndex,
		IN UINTN	OrgFvHandle,
		IN UINTN	FvHandle
	)

Migrates PEIMs in the given firmware volume.

Parameters

Private	Pointer to the PeiCore's private data structure.
FvIndex	The firmware volume index to migrate.
OrgFvHandle	The handle to the firmware volume in temporary memory.
FvHandle	The handle to the firmware volume in permanent memory.

Return values

EFI_SUCCESS	The PEIMs in the FV were migrated successfully
EFI_INVALID_PARAMETER	The Private pointer is NULL or FvCount is invalid.

Definition at line 1496 of file Dispatcher.c.

◆ PeiCheckAndSwitchStack()

VOID PeiCheckAndSwitchStack	(	IN CONST EFI_SEC_PEI_HAND_OFF *	SecCoreData,
		IN PEI_CORE_INSTANCE *	Private
	)

Check SwitchStackSignal and switch stack if SwitchStackSignal is TRUE.

Parameters

[in]	SecCoreData	Points to a data structure containing information about the PEI core's operating environment, such as the size and location of temporary RAM, the stack location and the BFV location.
[in]	Private	Pointer to the private data passed in from caller.

Definition at line 1058 of file Dispatcher.c.

◆ PeiCoreEntry()

VOID EFIAPI PeiCoreEntry	(	IN CONST EFI_SEC_PEI_HAND_OFF *	SecCoreData,
		IN PEI_CORE_INSTANCE *	Private
	)

This routine is invoked in switch stack as PeiCore Entry.

Parameters

SecCoreData	Points to a data structure containing information about the PEI core's operating environment, such as the size and location of temporary RAM, the stack location and the BFV location.
Private	Pointer to old core data that is used to initialize the core's data areas.

Definition at line 1037 of file Dispatcher.c.

◆ PeiDelayedDispatchOnEndOfPei()

EFI_STATUS EFIAPI PeiDelayedDispatchOnEndOfPei	(	IN EFI_PEI_SERVICES **	PeiServices,
		IN EFI_PEI_NOTIFY_DESCRIPTOR *	NotifyDesc,
		IN VOID *	Ppi
	)

DelayedDispatch End of PEI callback function. Insure that all of the delayed dispatch entries are complete before exiting PEI.

Parameters

[in]	PeiServices	- Pointer to PEI Services Table.
[in]	NotifyDesc	- Pointer to the descriptor for the Notification event that caused this function to execute.
[in]	Ppi	- Pointer to the PPI data associated with this function.

Return values

EFI_STATUS - Always return EFI_SUCCESS

Definition at line 361 of file Dispatcher.c.

◆ PeiDelayedDispatchRegister()

EFI_STATUS EFIAPI PeiDelayedDispatchRegister	(	IN EFI_DELAYED_DISPATCH_PPI *	This,
		IN EFI_DELAYED_DISPATCH_FUNCTION	Function,
		IN UINT64	Context,
		IN EFI_GUID *DelayedGroupId	OPTIONAL,
		IN UINT32	Delay
	)

Register a callback to be called after a minimum delay has occurred.

This service is the single member function of the EFI_DELAYED_DISPATCH_PPI

Parameters

[in]	This	Pointer to the EFI_DELAYED_DISPATCH_PPI instance
[in]	Function	Function to call back
[in]	Context	Context data
[in]	DelayedGroupId	GUID for this Delayed Dispatch request.
[in]	Delay	Delay interval

Return values

EFI_SUCCESS	Function successfully loaded
EFI_INVALID_PARAMETER	One of the Arguments is not supported
EFI_OUT_OF_RESOURCES	No more entries

Definition at line 109 of file Dispatcher.c.

◆ PeiDelayedDispatchWaitOnEvent()

EFI_STATUS EFIAPI PeiDelayedDispatchWaitOnEvent	(	IN EFI_DELAYED_DISPATCH_PPI *	This,
		IN EFI_GUID	DelayedGroupId
	)

Wait on a registered Delayed Dispatch unit that has a DelayedGroupId. Continue to dispatch all registered delayed dispatch entries until ALL entries with DelayedGroupId have completed.

Example usage:

Register a Delayed Dispatch entry with a DelayedGroupId.
Call this function with the DelayedGroupId
The registered function in #1 will be called after the specified delay.
This function will wait until all entries with the DelayedGroupId have completed.

Parameters

[in]	This	The Delayed Dispatch PPI pointer.
[in]	DelayedGroupId	Delayed dispatch request ID the caller will wait on

Return values

EFI_SUCCESS	The operation succeeds.
EFI_INVALID_PARAMETER	The parameters are invalid.

Definition at line 313 of file Dispatcher.c.

◆ PeiDispatcher()

VOID PeiDispatcher	(	IN CONST EFI_SEC_PEI_HAND_OFF *	SecCoreData,
		IN PEI_CORE_INSTANCE *	Private
	)

Conduct PEIM dispatch.

Parameters

SecCoreData	Points to a data structure containing information about the PEI core's operating environment, such as the size and location of temporary RAM, the stack location and the BFV location.
Private	Pointer to the private data passed in from caller

Definition at line 1791 of file Dispatcher.c.

◆ PeiLoadFixAddressHook()

VOID PeiLoadFixAddressHook ( IN PEI_CORE_INSTANCE * PrivateData )

Hook function for Loading Module at Fixed Address feature

This function should only be invoked when Loading Module at Fixed Address(LMFA) feature is enabled. When feature is configured as Load Modules at Fix Absolute Address, this function is to validate the top address assigned by user. When feature is configured as Load Modules at Fixed Offset, the function is to find the top address which is TOLM-TSEG in general. And also the function will re-install PEI memory.

Parameters

PrivateData Pointer to the private data passed in from caller

Definition at line 656 of file Dispatcher.c.

◆ PeiLoadFixAddressIsMemoryRangeAvailable()

BOOLEAN PeiLoadFixAddressIsMemoryRangeAvailable	(	IN PEI_CORE_INSTANCE *	PrivateData,
		IN EFI_HOB_RESOURCE_DESCRIPTOR *	ResourceHob
	)

This function is to test if the memory range described in resource HOB is available or not.

This function should only be invoked when Loading Module at Fixed Address(LMFA) feature is enabled. Some platform may allocate the memory before PeiLoadFixAddressHook in invoked. so this function is to test if the memory range described by the input resource HOB is available or not.

Parameters

PrivateData	Pointer to the private data passed in from caller
ResourceHob	Pointer to a resource HOB which described the memory range described by the input resource HOB

Definition at line 609 of file Dispatcher.c.

◆ PeiRegisterForShadow()

EFI_STATUS EFIAPI PeiRegisterForShadow ( IN EFI_PEI_FILE_HANDLE FileHandle )

This routine enables a PEIM to register itself for shadow when the PEI Foundation discovers permanent memory.

Parameters

FileHandle File handle of a PEIM.

Return values

EFI_NOT_FOUND	The file handle doesn't point to PEIM itself.
EFI_ALREADY_STARTED	Indicate that the PEIM has been registered itself.
EFI_SUCCESS	Successfully to register itself.

Definition at line 2240 of file Dispatcher.c.

Variable Documentation

◆ mDelayedDispatchDesc

EFI_PEI_PPI_DESCRIPTOR mDelayedDispatchDesc

Initial value:

= {
  (EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST),
  &gEfiPeiDelayedDispatchPpiGuid,
  &mDelayedDispatchPpi
}

Definition at line 55 of file Dispatcher.c.

◆ mDelayedDispatchNotifyDesc

EFI_PEI_NOTIFY_DESCRIPTOR mDelayedDispatchNotifyDesc

Initial value:

= {
  EFI_PEI_PPI_DESCRIPTOR_NOTIFY_CALLBACK | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST,
  &gEfiEndOfPeiSignalPpiGuid,
  PeiDelayedDispatchOnEndOfPei
}

Definition at line 61 of file Dispatcher.c.

◆ mDelayedDispatchPpi

EFI_DELAYED_DISPATCH_PPI mDelayedDispatchPpi = { PeiDelayedDispatchRegister, PeiDelayedDispatchWaitOnEvent }

Definition at line 54 of file Dispatcher.c.

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ MINIMUM_INITIAL_MEMORY_SIZE

Function Documentation

◆ ConvertStatusCodeCallbacks()

◆ DelayedDispatchDispatcher()

◆ DepexSatisfied()

◆ DiscoverPeimsAndOrderWithApriori()

◆ EvacuateTempRam()

◆ GetDelayedDispatchTable()

◆ InitializeDispatcherData()

◆ MigratePeim()

◆ MigratePeimsInFv()

◆ PeiCheckAndSwitchStack()

◆ PeiCoreEntry()

◆ PeiDelayedDispatchOnEndOfPei()

◆ PeiDelayedDispatchRegister()

◆ PeiDelayedDispatchWaitOnEvent()

◆ PeiDispatcher()

◆ PeiLoadFixAddressHook()

◆ PeiLoadFixAddressIsMemoryRangeAvailable()

◆ PeiRegisterForShadow()

Variable Documentation

◆ mDelayedDispatchDesc

◆ mDelayedDispatchNotifyDesc

◆ mDelayedDispatchPpi