#include <Library/BaseLib.h>
#include <Library/DebugLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/SafeIntLib.h>
#include <Library/SmmCpuSyncLib.h>
#include <Library/SynchronizationLib.h>
#include <Uefi.h>

Data Structures
struct	SMM_CPU_SYNC_SEMAPHORE_FOR_EACH_CPU

struct	SMM_CPU_SYNC_CONTEXT

Typedefs
typedef volatile UINT32	SMM_CPU_SYNC_SEMAPHORE

Functions
STATIC UINT32	InternalWaitForSemaphore (IN OUT volatile UINT32 *Sem)

STATIC UINT32	InternalReleaseSemaphore (IN OUT volatile UINT32 *Sem)

STATIC UINT32	InternalLockdownSemaphore (IN OUT volatile UINT32 *Sem)

RETURN_STATUS EFIAPI	SmmCpuSyncContextInit (IN UINTN NumberOfCpus, OUT SMM_CPU_SYNC_CONTEXT **Context)

VOID EFIAPI	SmmCpuSyncContextDeinit (IN OUT SMM_CPU_SYNC_CONTEXT *Context)

VOID EFIAPI	SmmCpuSyncContextReset (IN OUT SMM_CPU_SYNC_CONTEXT *Context)

UINTN EFIAPI	SmmCpuSyncGetArrivedCpuCount (IN SMM_CPU_SYNC_CONTEXT *Context)

RETURN_STATUS EFIAPI	SmmCpuSyncCheckInCpu (IN OUT SMM_CPU_SYNC_CONTEXT *Context, IN UINTN CpuIndex)

RETURN_STATUS EFIAPI	SmmCpuSyncCheckOutCpu (IN OUT SMM_CPU_SYNC_CONTEXT *Context, IN UINTN CpuIndex)

VOID EFIAPI	SmmCpuSyncLockDoor (IN OUT SMM_CPU_SYNC_CONTEXT Context, IN UINTN CpuIndex, OUT UINTN CpuCount)

VOID EFIAPI	SmmCpuSyncWaitForAPs (IN OUT SMM_CPU_SYNC_CONTEXT *Context, IN UINTN NumberOfAPs, IN UINTN BspIndex)

VOID EFIAPI	SmmCpuSyncReleaseOneAp (IN OUT SMM_CPU_SYNC_CONTEXT *Context, IN UINTN CpuIndex, IN UINTN BspIndex)

VOID EFIAPI	SmmCpuSyncWaitForBsp (IN OUT SMM_CPU_SYNC_CONTEXT *Context, IN UINTN CpuIndex, IN UINTN BspIndex)

VOID EFIAPI	SmmCpuSyncReleaseBsp (IN OUT SMM_CPU_SYNC_CONTEXT *Context, IN UINTN CpuIndex, IN UINTN BspIndex)

Detailed Description

SMM CPU Sync lib implementation.

The lib provides 3 sets of APIs:

ContextInit/ContextDeinit/ContextReset:

ContextInit() is called in driver's entrypoint to allocate and initialize the SMM CPU Sync context. ContextDeinit() is called in driver's unload function to deinitialize the SMM CPU Sync context. ContextReset() is called by one of CPUs after all CPUs are ready to exit SMI, which allows CPU to check into the next SMI from this point.
GetArrivedCpuCount/CheckInCpu/CheckOutCpu/LockDoor: When SMI happens, all processors including BSP enter to SMM mode by calling CheckInCpu(). CheckOutCpu() can be called in error handling flow for the CPU who calls CheckInCpu() earlier. The elected BSP calls LockDoor() so that CheckInCpu() and CheckOutCpu() will return the error code after that. GetArrivedCpuCount() returns the number of checked-in CPUs.
WaitForAPs/ReleaseOneAp/WaitForBsp/ReleaseBsp WaitForAPs() & ReleaseOneAp() are called from BSP to wait the number of APs and release one specific AP. WaitForBsp() & ReleaseBsp() are called from APs to wait and release BSP. The 4 APIs are used to synchronize the running flow among BSP and APs. BSP and AP Sync flow can be easy understand as below: BSP: ReleaseOneAp --> AP: WaitForBsp BSP: WaitForAPs <– AP: ReleaseBsp

Copyright (c) 2023, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file SmmCpuSyncLib.c.

Typedef Documentation

◆ SMM_CPU_SYNC_SEMAPHORE

typedef volatile UINT32 SMM_CPU_SYNC_SEMAPHORE

The implementation shall place one semaphore on exclusive cache line for good performance.

Definition at line 41 of file SmmCpuSyncLib.c.

Function Documentation

◆ InternalLockdownSemaphore()

STATIC UINT32 InternalLockdownSemaphore ( IN OUT volatile UINT32 * Sem )

Performs an atomic compare exchange operation to lock semaphore. The compare exchange operation must be performed using MP safe mechanisms.

Parameters

[in,out] Sem IN: 32-bit unsigned integer OUT: -1

Return values

Original integer

Definition at line 174 of file SmmCpuSyncLib.c.

◆ InternalReleaseSemaphore()

STATIC UINT32 InternalReleaseSemaphore ( IN OUT volatile UINT32 * Sem )

Performs an atomic compare exchange operation to release semaphore. The compare exchange operation must be performed using MP safe mechanisms.

Parameters

[in,out] Sem IN: 32-bit unsigned integer OUT: original integer + 1 if Sem is not locked. OUT: MAX_UINT32 if Sem is locked.

Return values

Original integer + 1 if Sem is not locked. MAX_UINT32 if Sem is locked.

Definition at line 139 of file SmmCpuSyncLib.c.

◆ InternalWaitForSemaphore()

STATIC UINT32 InternalWaitForSemaphore ( IN OUT volatile UINT32 * Sem )

Performs an atomic compare exchange operation to get semaphore. The compare exchange operation must be performed using MP safe mechanisms.

Parameters

[in,out] Sem IN: 32-bit unsigned integer OUT: original integer - 1 if Sem is not locked. OUT: MAX_UINT32 if Sem is locked.

Return values

Original integer - 1 if Sem is not locked. MAX_UINT32 if Sem is locked.

Definition at line 96 of file SmmCpuSyncLib.c.

◆ SmmCpuSyncCheckInCpu()

RETURN_STATUS EFIAPI SmmCpuSyncCheckInCpu	(	IN OUT SMM_CPU_SYNC_CONTEXT *	Context,
		IN UINTN	CpuIndex
	)

Performs an atomic operation to check in CPU.

When SMI happens, all processors including BSP enter to SMM mode by calling SmmCpuSyncCheckInCpu().

If Context is NULL, then ASSERT(). If CpuIndex exceeds the range of all CPUs in the system, then ASSERT().

Parameters

[in,out]	Context	Pointer to the SMM CPU Sync context object.
[in]	CpuIndex	Check in CPU index.

Return values

RETURN_SUCCESS	Check in CPU (CpuIndex) successfully.
RETURN_ABORTED	Check in CPU failed due to SmmCpuSyncLockDoor() has been called by one elected CPU.

Definition at line 400 of file SmmCpuSyncLib.c.

◆ SmmCpuSyncCheckOutCpu()

RETURN_STATUS EFIAPI SmmCpuSyncCheckOutCpu	(	IN OUT SMM_CPU_SYNC_CONTEXT *	Context,
		IN UINTN	CpuIndex
	)

Performs an atomic operation to check out CPU.

This function can be called in error handling flow for the CPU who calls CheckInCpu() earlier. The caller shall make sure the CPU specified by CpuIndex has already checked-in.

If Context is NULL, then ASSERT(). If CpuIndex exceeds the range of all CPUs in the system, then ASSERT().

Parameters

[in,out]	Context	Pointer to the SMM CPU Sync context object.
[in]	CpuIndex	Check out CPU index.

Return values

RETURN_SUCCESS	Check out CPU (CpuIndex) successfully.
RETURN_ABORTED	Check out CPU failed due to SmmCpuSyncLockDoor() has been called by one elected CPU.

Definition at line 437 of file SmmCpuSyncLib.c.

◆ SmmCpuSyncContextDeinit()

VOID EFIAPI SmmCpuSyncContextDeinit ( IN OUT SMM_CPU_SYNC_CONTEXT * Context )

Deinit an allocated SMM CPU Sync context. The resources allocated in SmmCpuSyncContextInit() will be freed.

If Context is NULL, then ASSERT().

Parameters

[in,out] Context Pointer to the SMM CPU Sync context object to be deinitialized.

Definition at line 317 of file SmmCpuSyncLib.c.

◆ SmmCpuSyncContextInit()

RETURN_STATUS EFIAPI SmmCpuSyncContextInit	(	IN UINTN	NumberOfCpus,
		OUT SMM_CPU_SYNC_CONTEXT **	Context
	)

Create and initialize the SMM CPU Sync context. It is to allocate and initialize the SMM CPU Sync context.

If Context is NULL, then ASSERT().

Parameters

[in]	NumberOfCpus	The number of Logical Processors in the system.
[out]	Context	Pointer to the new created and initialized SMM CPU Sync context object. NULL will be returned if any error happen during init.

Return values

RETURN_SUCCESS	The SMM CPU Sync context was successful created and initialized.
RETURN_OUT_OF_RESOURCES	There are not enough resources available to create and initialize SMM CPU Sync context.
RETURN_BUFFER_TOO_SMALL	Overflow happen

Definition at line 208 of file SmmCpuSyncLib.c.

◆ SmmCpuSyncContextReset()

VOID EFIAPI SmmCpuSyncContextReset ( IN OUT SMM_CPU_SYNC_CONTEXT * Context )

Reset SMM CPU Sync context. SMM CPU Sync context will be reset to the initialized state.

This function is called by one of CPUs after all CPUs are ready to exit SMI, which allows CPU to check into the next SMI from this point.

If Context is NULL, then ASSERT().

Parameters

[in,out] Context Pointer to the SMM CPU Sync context object to be reset.

Definition at line 341 of file SmmCpuSyncLib.c.

◆ SmmCpuSyncGetArrivedCpuCount()

UINTN EFIAPI SmmCpuSyncGetArrivedCpuCount ( IN SMM_CPU_SYNC_CONTEXT * Context )

Get current number of arrived CPU in SMI.

BSP might need to know the current number of arrived CPU in SMI to make sure all APs in SMI. This API can be for that purpose.

If Context is NULL, then ASSERT().

Parameters

[in] Context Pointer to the SMM CPU Sync context object.

Return values

Current number of arrived CPU in SMI.

Definition at line 366 of file SmmCpuSyncLib.c.

◆ SmmCpuSyncLockDoor()

VOID EFIAPI SmmCpuSyncLockDoor	(	IN OUT SMM_CPU_SYNC_CONTEXT *	Context,
		IN UINTN	CpuIndex,
		OUT UINTN *	CpuCount
	)

Performs an atomic operation lock door for CPU checkin and checkout. After this function: CPU can not check in via SmmCpuSyncCheckInCpu(). CPU can not check out via SmmCpuSyncCheckOutCpu().

The CPU specified by CpuIndex is elected to lock door. The caller shall make sure the CpuIndex is the actual CPU calling this function to avoid the undefined behavior.

If Context is NULL, then ASSERT(). If CpuCount is NULL, then ASSERT(). If CpuIndex exceeds the range of all CPUs in the system, then ASSERT().

Parameters

[in,out]	Context	Pointer to the SMM CPU Sync context object.
[in]	CpuIndex	Indicate which CPU to lock door.
[out]	CpuCount	Number of arrived CPU in SMI after look door.

Definition at line 472 of file SmmCpuSyncLib.c.

◆ SmmCpuSyncReleaseBsp()

VOID EFIAPI SmmCpuSyncReleaseBsp	(	IN OUT SMM_CPU_SYNC_CONTEXT *	Context,
		IN UINTN	CpuIndex,
		IN UINTN	BspIndex
	)

Used by the AP to release BSP.

The AP is specified by CpuIndex. The caller shall make sure the CpuIndex is the actual CPU calling this function to avoid the undefined behavior. The BSP is specified by BspIndex.

If Context is NULL, then ASSERT(). If CpuIndex == BspIndex, then ASSERT(). If BspIndex or CpuIndex exceed the range of all CPUs in the system, then ASSERT().

Parameters

[in,out]	Context	Pointer to the SMM CPU Sync context object.
[in]	CpuIndex	Indicate which AP release BSP.
[in]	BspIndex	The BSP Index to be released.

Definition at line 637 of file SmmCpuSyncLib.c.

◆ SmmCpuSyncReleaseOneAp()

VOID EFIAPI SmmCpuSyncReleaseOneAp	(	IN OUT SMM_CPU_SYNC_CONTEXT *	Context,
		IN UINTN	CpuIndex,
		IN UINTN	BspIndex
	)

Used by the BSP to release one AP.

The AP is specified by CpuIndex. The BSP is specified by BspIndex. The caller shall make sure the BspIndex is the actual CPU calling this function to avoid the undefined behavior. The caller shall make sure the CpuIndex has already checked-in to avoid the undefined behavior.

If Context is NULL, then ASSERT(). If CpuIndex == BspIndex, then ASSERT(). If BspIndex or CpuIndex exceed the range of all CPUs in the system, then ASSERT().

Parameters

[in,out]	Context	Pointer to the SMM CPU Sync context object.
[in]	CpuIndex	Indicate which AP need to be released.
[in]	BspIndex	The BSP Index to release AP.

Definition at line 562 of file SmmCpuSyncLib.c.

◆ SmmCpuSyncWaitForAPs()

VOID EFIAPI SmmCpuSyncWaitForAPs	(	IN OUT SMM_CPU_SYNC_CONTEXT *	Context,
		IN UINTN	NumberOfAPs,
		IN UINTN	BspIndex
	)

Used by the BSP to wait for APs.

The number of APs need to be waited is specified by NumberOfAPs. The BSP is specified by BspIndex. The caller shall make sure the BspIndex is the actual CPU calling this function to avoid the undefined behavior. The caller shall make sure the NumberOfAPs have already checked-in to avoid the undefined behavior.

If Context is NULL, then ASSERT(). If NumberOfAPs >= All CPUs in system, then ASSERT(). If BspIndex exceeds the range of all CPUs in the system, then ASSERT().

Note: This function is blocking mode, and it will return only after the number of APs released by calling SmmCpuSyncReleaseBsp(): BSP: WaitForAPs <– AP: ReleaseBsp

Parameters

[in,out]	Context	Pointer to the SMM CPU Sync context object.
[in]	NumberOfAPs	Number of APs need to be waited by BSP.
[in]	BspIndex	The BSP Index to wait for APs.

Definition at line 525 of file SmmCpuSyncLib.c.

◆ SmmCpuSyncWaitForBsp()

VOID EFIAPI SmmCpuSyncWaitForBsp	(	IN OUT SMM_CPU_SYNC_CONTEXT *	Context,
		IN UINTN	CpuIndex,
		IN UINTN	BspIndex
	)

Used by the AP to wait BSP.

The AP is specified by CpuIndex. The caller shall make sure the CpuIndex is the actual CPU calling this function to avoid the undefined behavior. The BSP is specified by BspIndex.

If Context is NULL, then ASSERT(). If CpuIndex == BspIndex, then ASSERT(). If BspIndex or CpuIndex exceed the range of all CPUs in the system, then ASSERT().

Note: This function is blocking mode, and it will return only after the AP released by calling SmmCpuSyncReleaseOneAp(): BSP: ReleaseOneAp --> AP: WaitForBsp

Parameters

[in,out]	Context	Pointer to the SMM CPU Sync context object.
[in]	CpuIndex	Indicate which AP wait BSP.
[in]	BspIndex	The BSP Index to be waited.

Definition at line 602 of file SmmCpuSyncLib.c.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SMM_CPU_SYNC_SEMAPHORE

Function Documentation

◆ InternalLockdownSemaphore()

◆ InternalReleaseSemaphore()

◆ InternalWaitForSemaphore()

◆ SmmCpuSyncCheckInCpu()

◆ SmmCpuSyncCheckOutCpu()

◆ SmmCpuSyncContextDeinit()

◆ SmmCpuSyncContextInit()

◆ SmmCpuSyncContextReset()

◆ SmmCpuSyncGetArrivedCpuCount()

◆ SmmCpuSyncLockDoor()

◆ SmmCpuSyncReleaseBsp()

◆ SmmCpuSyncReleaseOneAp()

◆ SmmCpuSyncWaitForAPs()

◆ SmmCpuSyncWaitForBsp()