#include "PiSmmCore.h"

Data Structures
struct	KNOWN_HANDLE

struct	FV_FILEPATH_DEVICE_PATH

Macros
#define	KNOWN_HANDLE_SIGNATURE SIGNATURE_32('k','n','o','w')

Functions
VOID	SmmInsertOnScheduledQueueWhileProcessingBeforeAndAfter (IN EFI_SMM_DRIVER_ENTRY *InsertedDriverEntry)

EFI_STATUS	CheckAndMarkFixLoadingMemoryUsageBitMap (IN EFI_PHYSICAL_ADDRESS ImageBase, IN UINTN ImageSize)

EFI_STATUS	GetPeCoffImageFixLoadingAssignedAddress (IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext)

EFI_STATUS EFIAPI	SmmLoadImage (IN OUT EFI_SMM_DRIVER_ENTRY *DriverEntry)

EFI_STATUS	SmmPreProcessDepex (IN EFI_SMM_DRIVER_ENTRY *DriverEntry)

EFI_STATUS	SmmGetDepexSectionAndPreProccess (IN EFI_SMM_DRIVER_ENTRY *DriverEntry)

EFI_STATUS	SmmDispatcher (VOID)

BOOLEAN	FvHasBeenProcessed (IN EFI_HANDLE FvHandle)

VOID	FvIsBeingProcessed (IN EFI_HANDLE FvHandle)

EFI_DEVICE_PATH_PROTOCOL *	SmmFvToDevicePath (IN EFI_FIRMWARE_VOLUME2_PROTOCOL Fv, IN EFI_HANDLE FvHandle, IN EFI_GUID DriverName)

EFI_STATUS	SmmAddToDriverList (IN EFI_FIRMWARE_VOLUME2_PROTOCOL Fv, IN EFI_HANDLE FvHandle, IN EFI_GUID DriverName)

EFI_STATUS EFIAPI	SmmDriverDispatchHandler (IN EFI_HANDLE DispatchHandle, IN CONST VOID Context OPTIONAL, IN OUT VOID CommBuffer OPTIONAL, IN OUT UINTN *CommBufferSize OPTIONAL)

VOID	SmmDisplayDiscoveredNotDispatched (VOID)

Variables
LIST_ENTRY	mDiscoveredList = INITIALIZE_LIST_HEAD_VARIABLE (mDiscoveredList)

LIST_ENTRY	mScheduledQueue = INITIALIZE_LIST_HEAD_VARIABLE (mScheduledQueue)

LIST_ENTRY	mFvHandleList = INITIALIZE_LIST_HEAD_VARIABLE (mFvHandleList)

BOOLEAN	gDispatcherRunning = FALSE

BOOLEAN	gRequestDispatch = FALSE

EFI_FV_FILETYPE	mSmmFileTypes []

FV_FILEPATH_DEVICE_PATH	mFvDevicePath

EFI_SECURITY_ARCH_PROTOCOL *	mSecurity = NULL

EFI_SECURITY2_ARCH_PROTOCOL *	mSecurity2 = NULL

GLOBAL_REMOVE_IF_UNREFERENCED UINT64 *	mSmmCodeMemoryRangeUsageBitMap = NULL

Detailed Description

SMM Driver Dispatcher.

Step #1 - When a FV protocol is added to the system every driver in the FV is added to the mDiscoveredList. The Before, and After Depex are pre-processed as drivers are added to the mDiscoveredList. If an Apriori file exists in the FV those drivers are addeded to the mScheduledQueue. The mFvHandleList is used to make sure a FV is only processed once.

Step #2 - Dispatch. Remove driver from the mScheduledQueue and load and start it. After mScheduledQueue is drained check the mDiscoveredList to see if any item has a Depex that is ready to be placed on the mScheduledQueue.

Step #3 - Adding to the mScheduledQueue requires that you process Before and After dependencies. This is done recursively as the call to add to the mScheduledQueue checks for Before and recursively adds all Befores. It then addes the item that was passed in and then processes the After dependencies by recursively calling the routine.

Dispatcher Rules: The rules for the dispatcher are similar to the DXE dispatcher.

The rules for DXE dispatcher are in chapter 10 of the DXE CIS. Figure 10-3 is the state diagram for the DXE dispatcher

Depex - Dependency Expression.

Copyright (c) 2014, Hewlett-Packard Development Company, L.P. Copyright (c) 2009 - 2023, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file Dispatcher.c.

Macro Definition Documentation

◆ KNOWN_HANDLE_SIGNATURE

#define KNOWN_HANDLE_SIGNATURE SIGNATURE_32('k','n','o','w')

Definition at line 41 of file Dispatcher.c.

Function Documentation

◆ CheckAndMarkFixLoadingMemoryUsageBitMap()

EFI_STATUS CheckAndMarkFixLoadingMemoryUsageBitMap	(	IN EFI_PHYSICAL_ADDRESS	ImageBase,
		IN UINTN	ImageSize
	)

To check memory usage bit map array to figure out if the memory range in which the image will be loaded is available or not. If memory range is available, the function will mark the corresponding bits to 1 which indicates the memory range is used. The function is only invoked when load modules at fixed address feature is enabled.

Parameters

ImageBase	The base address the image will be loaded at.
ImageSize	The size of the image

Return values

EFI_SUCCESS	The memory range the image will be loaded in is available
EFI_NOT_FOUND	The memory range the image will be loaded in is not available

Definition at line 140 of file Dispatcher.c.

◆ FvHasBeenProcessed()

BOOLEAN FvHasBeenProcessed ( IN EFI_HANDLE FvHandle )

Return TRUE if the Fv has been processed, FALSE if not.

Parameters

FvHandle The handle of a FV that's being tested

Return values

TRUE	Fv protocol on FvHandle has been processed
FALSE	Fv protocol on FvHandle has not yet been processed

Definition at line 1113 of file Dispatcher.c.

◆ FvIsBeingProcessed()

VOID FvIsBeingProcessed ( IN EFI_HANDLE FvHandle )

Remember that Fv protocol on FvHandle has had its drivers placed on the mDiscoveredList. This function adds entries on the mFvHandleList. Items are never removed/freed from the mFvHandleList.

Parameters

FvHandle The handle of a FV that has been processed

Definition at line 1139 of file Dispatcher.c.

◆ GetPeCoffImageFixLoadingAssignedAddress()

EFI_STATUS GetPeCoffImageFixLoadingAssignedAddress ( IN OUT PE_COFF_LOADER_IMAGE_CONTEXT * ImageContext )

Get the fixed loading address from image header assigned by build tool. This function only be called when Loading module at Fixed address feature enabled.

Parameters

ImageContext Pointer to the image context structure that describes the PE/COFF image that needs to be examined by this function.

Return values

EFI_SUCCESS	An fixed loading address is assigned to this image by build tools .
EFI_NOT_FOUND	The image has no assigned fixed loading address.

Definition at line 216 of file Dispatcher.c.

◆ SmmAddToDriverList()

EFI_STATUS SmmAddToDriverList	(	IN EFI_FIRMWARE_VOLUME2_PROTOCOL *	Fv,
		IN EFI_HANDLE	FvHandle,
		IN EFI_GUID *	DriverName
	)

Add an entry to the mDiscoveredList. Allocate memory to store the DriverEntry, and initialize any state variables. Read the Depex from the FV and store it in DriverEntry. Pre-process the Depex to set the Before and After state. The Discovered list is never free'ed and contains booleans that represent the other possible SMM driver states.

Parameters

Fv	Fv protocol, needed to read Depex info out of FLASH.
FvHandle	Handle for Fv, needed in the EFI_SMM_DRIVER_ENTRY so that the PE image can be read out of the FV at a later time.
DriverName	Name of driver to add to mDiscoveredList.

Return values

EFI_SUCCESS	If driver was added to the mDiscoveredList.
EFI_ALREADY_STARTED	The driver has already been started. Only one DriverName may be active in the system at any one time.

Definition at line 1223 of file Dispatcher.c.

◆ SmmDispatcher()

EFI_STATUS SmmDispatcher ( VOID )

This is the main Dispatcher for SMM and it exits when there are no more drivers to run. Drain the mScheduledQueue and load and start a PE image for each driver. Search the mDiscoveredList to see if any driver can be placed on the mScheduledQueue. If no drivers are placed on the mScheduledQueue exit the function.

Return values

EFI_SUCCESS	All of the SMM Drivers that could be dispatched have been run and the SMM Entry Point has been registered.
EFI_NOT_READY	The SMM Driver that registered the SMM Entry Point was just dispatched.
EFI_NOT_FOUND	There are no SMM Drivers available to be dispatched.
EFI_ALREADY_STARTED	The SMM Dispatcher is already running

Definition at line 846 of file Dispatcher.c.

◆ SmmDisplayDiscoveredNotDispatched()

VOID SmmDisplayDiscoveredNotDispatched ( VOID )

Traverse the discovered list for any drivers that were discovered but not loaded because the dependency expressions evaluated to false.

Definition at line 1521 of file Dispatcher.c.

◆ SmmDriverDispatchHandler()

EFI_STATUS EFIAPI SmmDriverDispatchHandler	(	IN EFI_HANDLE	DispatchHandle,
		IN CONST VOID *Context	OPTIONAL,
		IN OUT VOID *CommBuffer	OPTIONAL,
		IN OUT UINTN *CommBufferSize	OPTIONAL
	)

This function is the main entry point for an SMM handler dispatch or communicate-based callback.

Event notification that is fired every time a FV dispatch protocol is added. More than one protocol may have been added when this event is fired, so you must loop on SmmLocateHandle () to see how many protocols were added and do the following to each FV: If the Fv has already been processed, skip it. If the Fv has not been processed then mark it as being processed, as we are about to process it. Read the Fv and add any driver in the Fv to the mDiscoveredList.The mDiscoveredList is never free'ed and contains variables that define the other states the SMM driver transitions to.. While you are at it read the A Priori file into memory. Place drivers in the A Priori list onto the mScheduledQueue.

Parameters

DispatchHandle	The unique handle assigned to this handler by SmiHandlerRegister().
Context	Points to an optional handler context which was specified when the handler was registered.
CommBuffer	A pointer to a collection of data in memory that will be conveyed from a non-SMM environment into an SMM environment.
CommBufferSize	The size of the CommBuffer.

Returns: Status Code

Definition at line 1279 of file Dispatcher.c.

◆ SmmFvToDevicePath()

EFI_DEVICE_PATH_PROTOCOL * SmmFvToDevicePath	(	IN EFI_FIRMWARE_VOLUME2_PROTOCOL *	Fv,
		IN EFI_HANDLE	FvHandle,
		IN EFI_GUID *	DriverName
	)

Convert FvHandle and DriverName into an EFI device path

Parameters

Fv	Fv protocol, needed to read Depex info out of FLASH.
FvHandle	Handle for Fv, needed in the EFI_SMM_DRIVER_ENTRY so that the PE image can be read out of the FV at a later time.
DriverName	Name of driver to add to mDiscoveredList.

Returns: Pointer to device path constructed from FvHandle and DriverName

Definition at line 1167 of file Dispatcher.c.

◆ SmmGetDepexSectionAndPreProccess()

EFI_STATUS SmmGetDepexSectionAndPreProccess ( IN EFI_SMM_DRIVER_ENTRY * DriverEntry )

Read Depex and pre-process the Depex for Before and After. If Section Extraction protocol returns an error via ReadSection defer the reading of the Depex.

Parameters

DriverEntry Driver to work on.

Return values

EFI_SUCCESS	Depex read and preprocessed
EFI_PROTOCOL_ERROR	The section extraction protocol returned an error and Depex reading needs to be retried.
Error	DEPEX not found.

Definition at line 778 of file Dispatcher.c.

◆ SmmInsertOnScheduledQueueWhileProcessingBeforeAndAfter()

VOID SmmInsertOnScheduledQueueWhileProcessingBeforeAndAfter ( IN EFI_SMM_DRIVER_ENTRY * InsertedDriverEntry )

Insert InsertedDriverEntry onto the mScheduledQueue. To do this you must add any driver with a before dependency on InsertedDriverEntry first. You do this by recursively calling this routine. After all the Befores are processed you can add InsertedDriverEntry to the mScheduledQueue. Then you can add any driver with an After dependency on InsertedDriverEntry by recursively calling this routine.

Parameters

InsertedDriverEntry The driver to insert on the ScheduledLink Queue

Definition at line 1046 of file Dispatcher.c.

◆ SmmLoadImage()

EFI_STATUS EFIAPI SmmLoadImage ( IN OUT EFI_SMM_DRIVER_ENTRY * DriverEntry )

Loads an EFI image into SMRAM.

Parameters

DriverEntry EFI_SMM_DRIVER_ENTRY instance

Returns: EFI_STATUS

Definition at line 309 of file Dispatcher.c.

◆ SmmPreProcessDepex()

EFI_STATUS SmmPreProcessDepex ( IN EFI_SMM_DRIVER_ENTRY * DriverEntry )

Preprocess dependency expression and update DriverEntry to reflect the state of Before and After dependencies. If DriverEntry->Before or DriverEntry->After is set it will never be cleared.

Parameters

DriverEntry DriverEntry element to update .

Return values

EFI_SUCCESS It always works.

Definition at line 743 of file Dispatcher.c.

Variable Documentation

◆ gDispatcherRunning

BOOLEAN gDispatcherRunning = FALSE

Definition at line 88 of file Dispatcher.c.

◆ gRequestDispatch

BOOLEAN gRequestDispatch = FALSE

Definition at line 93 of file Dispatcher.c.

◆ mDiscoveredList

LIST_ENTRY mDiscoveredList = INITIALIZE_LIST_HEAD_VARIABLE (mDiscoveredList)

Definition at line 72 of file Dispatcher.c.

◆ mFvDevicePath

FV_FILEPATH_DEVICE_PATH mFvDevicePath

Definition at line 113 of file Dispatcher.c.

◆ mFvHandleList

LIST_ENTRY mFvHandleList = INITIALIZE_LIST_HEAD_VARIABLE (mFvHandleList)

Definition at line 83 of file Dispatcher.c.

◆ mScheduledQueue

LIST_ENTRY mScheduledQueue = INITIALIZE_LIST_HEAD_VARIABLE (mScheduledQueue)

Definition at line 78 of file Dispatcher.c.

◆ mSecurity

EFI_SECURITY_ARCH_PROTOCOL* mSecurity = NULL

Definition at line 118 of file Dispatcher.c.

◆ mSecurity2

EFI_SECURITY2_ARCH_PROTOCOL* mSecurity2 = NULL

Definition at line 119 of file Dispatcher.c.

◆ mSmmCodeMemoryRangeUsageBitMap

GLOBAL_REMOVE_IF_UNREFERENCED UINT64* mSmmCodeMemoryRangeUsageBitMap = NULL

Definition at line 126 of file Dispatcher.c.

◆ mSmmFileTypes

EFI_FV_FILETYPE mSmmFileTypes[]

Initial value:

= {
  EFI_FV_FILETYPE_SMM,
  EFI_FV_FILETYPE_COMBINED_SMM_DXE,
  EFI_FV_FILETYPE_SMM_CORE,
  
}

Definition at line 98 of file Dispatcher.c.

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ KNOWN_HANDLE_SIGNATURE

Function Documentation

◆ CheckAndMarkFixLoadingMemoryUsageBitMap()

◆ FvHasBeenProcessed()

◆ FvIsBeingProcessed()

◆ GetPeCoffImageFixLoadingAssignedAddress()

◆ SmmAddToDriverList()

◆ SmmDispatcher()

◆ SmmDisplayDiscoveredNotDispatched()

◆ SmmDriverDispatchHandler()

◆ SmmFvToDevicePath()

◆ SmmGetDepexSectionAndPreProccess()

◆ SmmInsertOnScheduledQueueWhileProcessingBeforeAndAfter()

◆ SmmLoadImage()

◆ SmmPreProcessDepex()

Variable Documentation

◆ gDispatcherRunning

◆ gRequestDispatch

◆ mDiscoveredList

◆ mFvDevicePath

◆ mFvHandleList

◆ mScheduledQueue

◆ mSecurity

◆ mSecurity2

◆ mSmmCodeMemoryRangeUsageBitMap

◆ mSmmFileTypes