#include <PiPei.h>
#include <Guid/AcpiS3Context.h>
#include <Guid/BootScriptExecutorVariable.h>
#include <Guid/ExtendedFirmwarePerformance.h>
#include <Guid/EndOfS3Resume.h>
#include <Guid/S3SmmInitDone.h>
#include <Ppi/S3Resume2.h>
#include <Ppi/SmmAccess.h>
#include <Ppi/PostBootScriptTable.h>
#include <Ppi/EndOfPeiPhase.h>
#include <Ppi/SmmCommunication.h>
#include <Ppi/MpServices2.h>
#include <Library/DebugLib.h>
#include <Library/BaseLib.h>
#include <Library/PeimEntryPoint.h>
#include <Library/PeiServicesLib.h>
#include <Library/HobLib.h>
#include <Library/PerformanceLib.h>
#include <Library/PeiServicesTablePointerLib.h>
#include <Library/IoLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/PcdLib.h>
#include <Library/DebugAgentLib.h>
#include <Library/LocalApicLib.h>
#include <Library/ReportStatusCodeLib.h>
#include <Library/MtrrLib.h>
#include <Library/LockBoxLib.h>
#include <IndustryStandard/Acpi.h>

Data Structures
union	IA32_GDT

union	PAGE_MAP_AND_DIRECTORY_POINTER

union	PAGE_TABLE_ENTRY

union	PAGE_TABLE_1G_ENTRY

struct	SMM_COMMUNICATE_HEADER_32

struct	SMM_COMMUNICATE_HEADER_64

Macros
#define	STACK_ALIGN_DOWN(Ptr) ((UINTN)(Ptr) & ~(UINTN)(CPU_STACK_ALIGNMENT - 1))

#define	PAGING_1G_ADDRESS_MASK_64 0x000FFFFFC0000000ull

#define	DATA_SEGEMENT_SELECTOR 0x18

Typedefs
typedef VOID(EFIAPI *	ASM_TRANSFER_CONTROL) (IN UINT32 S3WakingVector, IN UINT32 AcpiLowMemoryBase)

Functions
EFI_STATUS EFIAPI	S3RestoreConfig2 (IN EFI_PEI_S3_RESUME2_PPI *This)

VOID EFIAPI	AsmSetDataSelectors (IN UINT16 SelectorValue)

BOOLEAN	IsLongModeWakingVector (IN ACPI_S3_CONTEXT *AcpiS3Context)

VOID	SignalToSmmByCommunication (IN EFI_GUID *HandlerType)

VOID EFIAPI	S3ResumeBootOs (IN ACPI_S3_CONTEXT AcpiS3Context, IN PEI_S3_RESUME_STATE PeiS3ResumeState)

VOID	RestoreS3PageTables (IN UINTN S3NvsPageTableAddress, IN BOOLEAN Build4GPageTableOnly)

VOID EFIAPI	S3ResumeExecuteBootScript (IN ACPI_S3_CONTEXT AcpiS3Context, IN BOOT_SCRIPT_EXECUTOR_VARIABLE EfiBootScriptExecutorVariable)

VOID EFIAPI	LoadMtrrData (IN VOID *MtrrTable)

EFI_STATUS EFIAPI	PeimS3ResumeEntryPoint (IN EFI_PEI_FILE_HANDLE FileHandle, IN CONST EFI_PEI_SERVICES **PeiServices)

Detailed Description

This module produces the EFI_PEI_S3_RESUME2_PPI. This module works with StandAloneBootScriptExecutor to S3 resume to OS. This module will execute the boot script saved during last boot and after that, control is passed to OS waking up handler.

SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file S3Resume.c.

Macro Definition Documentation

◆ DATA_SEGEMENT_SELECTOR

#define DATA_SEGEMENT_SELECTOR 0x18

Definition at line 303 of file S3Resume.c.

◆ PAGING_1G_ADDRESS_MASK_64

#define PAGING_1G_ADDRESS_MASK_64 0x000FFFFFC0000000ull

Definition at line 58 of file S3Resume.c.

◆ STACK_ALIGN_DOWN

#define STACK_ALIGN_DOWN ( Ptr ) ((UINTN)(Ptr) & ~(UINTN)(CPU_STACK_ALIGNMENT - 1))

This macro aligns the address of a variable with auto storage duration down to CPU_STACK_ALIGNMENT.

Since the stack grows downward, the result preserves more of the stack than the original address (or the same amount), not less.

Definition at line 55 of file S3Resume.c.

Typedef Documentation

◆ ASM_TRANSFER_CONTROL

typedef VOID(EFIAPI * ASM_TRANSFER_CONTROL) (IN UINT32 S3WakingVector, IN UINT32 AcpiLowMemoryBase)

a ASM function to transfer control to OS.

Parameters

S3WakingVector	The S3 waking up vector saved in ACPI Facs table
AcpiLowMemoryBase	a buffer under 1M which could be used during the transfer

Definition at line 179 of file S3Resume.c.

Function Documentation

◆ AsmSetDataSelectors()

VOID EFIAPI AsmSetDataSelectors ( IN UINT16 SelectorValue )

Set data segment selectors value including DS/ES/FS/GS/SS.

Parameters

[in] SelectorValue Segment selector value to be set.

◆ IsLongModeWakingVector()

BOOLEAN IsLongModeWakingVector ( IN ACPI_S3_CONTEXT * AcpiS3Context )

The function will check if current waking vector is long mode.

Parameters

AcpiS3Context a pointer to a structure of ACPI_S3_CONTEXT

Return values

TRUE	Current context need long mode waking vector.
FALSE	Current context need not long mode waking vector.

Definition at line 322 of file S3Resume.c.

◆ LoadMtrrData()

VOID EFIAPI LoadMtrrData ( IN VOID * MtrrTable )

Sync up the MTRR values for all processors.

Parameters

[in] MtrrTable Address of MTRR setting.

Definition at line 962 of file S3Resume.c.

◆ PeimS3ResumeEntryPoint()

EFI_STATUS EFIAPI PeimS3ResumeEntryPoint	(	IN EFI_PEI_FILE_HANDLE	FileHandle,
		IN CONST EFI_PEI_SERVICES **	PeiServices
	)

Main entry for S3 Resume PEIM.

This routine is to install EFI_PEI_S3_RESUME2_PPI.

Parameters

FileHandle	Handle of the file being invoked.
PeiServices	Pointer to PEI Services table.

Return values

EFI_SUCCESS S3Resume Ppi is installed successfully.

Definition at line 1258 of file S3Resume.c.

◆ RestoreS3PageTables()

VOID RestoreS3PageTables	(	IN UINTN	S3NvsPageTableAddress,
		IN BOOLEAN	Build4GPageTableOnly
	)

Restore S3 page table because we do not trust ACPINvs content. If BootScriptExecutor driver will not run in 64-bit mode, this function will do nothing.

Parameters

S3NvsPageTableAddress	PageTableAddress in ACPINvs
Build4GPageTableOnly	If BIOS just build 4G page table only

Definition at line 634 of file S3Resume.c.

◆ S3RestoreConfig2()

EFI_STATUS EFIAPI S3RestoreConfig2 ( IN EFI_PEI_S3_RESUME2_PPI * This )

Restores the platform to its preboot configuration for an S3 resume and jumps to the OS waking vector.

This function will restore the platform to its pre-boot configuration that was pre-stored in the boot script table and transfer control to OS waking vector. Upon invocation, this function is responsible for locating the following information before jumping to OS waking vector:

ACPI tables
boot script table
any other information that it needs

The S3RestoreConfig() function then executes the pre-stored boot script table and transitions the platform to the pre-boot state. The boot script is recorded during regular boot using the EFI_S3_SAVE_STATE_PROTOCOL.Write() and EFI_S3_SMM_SAVE_STATE_PROTOCOL.Write() functions. Finally, this function transfers control to the OS waking vector. If the OS supports only a real-mode waking vector, this function will switch from flat mode to real mode before jumping to the waking vector. If all platform pre-boot configurations are successfully restored and all other necessary information is ready, this function will never return and instead will directly jump to the OS waking vector. If this function returns, it indicates that the attempt to resume from the ACPI S3 sleep state failed.

Parameters

[in] This Pointer to this instance of the PEI_S3_RESUME_PPI

Return values

EFI_ABORTED	Execution of the S3 resume boot script table failed.
EFI_NOT_FOUND	Some necessary information that is used for the S3 resume boot path could not be located.

Definition at line 1002 of file S3Resume.c.

◆ S3ResumeBootOs()

VOID EFIAPI S3ResumeBootOs	(	IN ACPI_S3_CONTEXT *	AcpiS3Context,
		IN PEI_S3_RESUME_STATE *	PeiS3ResumeState
	)

Jump to OS waking vector. The function will install boot script done PPI, report S3 resume status code, and then jump to OS waking vector.

Parameters

AcpiS3Context	a pointer to a structure of ACPI_S3_CONTEXT
PeiS3ResumeState	a pointer to a structure of PEI_S3_RESUME_STATE

Definition at line 422 of file S3Resume.c.

◆ S3ResumeExecuteBootScript()

VOID EFIAPI S3ResumeExecuteBootScript	(	IN ACPI_S3_CONTEXT *	AcpiS3Context,
		IN BOOT_SCRIPT_EXECUTOR_VARIABLE *	EfiBootScriptExecutorVariable
	)

Jump to boot script executor driver.

The function will close and lock SMRAM and then jump to boot script execute driver to executing S3 boot script table.

Parameters

AcpiS3Context	a pointer to a structure of ACPI_S3_CONTEXT
EfiBootScriptExecutorVariable	The function entry to executing S3 boot Script table. This function is build in boot script execute driver

Definition at line 810 of file S3Resume.c.

◆ SignalToSmmByCommunication()

VOID SignalToSmmByCommunication ( IN EFI_GUID * HandlerType )

Signal to SMM through communication buffer way.

Parameters

[in] HandlerType SMI handler type to be signaled.

Definition at line 358 of file S3Resume.c.

Variable Documentation

◆ mGdt

GLOBAL_REMOVE_IF_UNREFERENCED CONST IA32_DESCRIPTOR mGdt

Initial value:

= {
  sizeof (mGdtEntries) - 1,
  (UINTN)mGdtEntries
}

Definition at line 308 of file S3Resume.c.

◆ mGdtEntries

GLOBAL_REMOVE_IF_UNREFERENCED IA32_GDT mGdtEntries[]

Initial value:

= {
  
   {
    { 0,      0, 0, 0,   0, 0, 0, 0,   0, 0, 0, 0, 0 }
  },
   {
    { 0,      0, 0, 0,   0, 0, 0, 0,   0, 0, 0, 0, 0 }
  },
   {
    { 0xFFFF, 0, 0, 0xB, 1, 0, 1, 0xF, 0, 0, 1, 1, 0 }
  },
   {
    { 0xFFFF, 0, 0, 0x3, 1, 0, 1, 0xF, 0, 0, 1, 1, 0 }
  },
   {
    { 0,      0, 0, 0,   0, 0, 0, 0,   0, 0, 0, 0, 0 }
  },
   {
    { 0xFFFF, 0, 0, 0xB, 1, 0, 1, 0xF, 0, 0, 0, 1, 0 }
  },
   {
    { 0xFFFF, 0, 0, 0x3, 1, 0, 1, 0xF, 0, 0, 0, 1, 0 }
  },
   {
    { 0xFFFF, 0, 0, 0xB, 1, 0, 1, 0xF, 0, 1, 0, 1, 0 }
  },
   {
    { 0,      0, 0, 0,   0, 0, 0, 0,   0, 0, 0, 0, 0 }
  },
}

Definition at line 272 of file S3Resume.c.

◆ mPpiList

EFI_PEI_PPI_DESCRIPTOR mPpiList

Initial value:

= {
  (EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST),
  &gEfiPeiS3Resume2PpiGuid,
  &mS3ResumePpi
}

Definition at line 239 of file S3Resume.c.

◆ mPpiListEndOfPeiTable

EFI_PEI_PPI_DESCRIPTOR mPpiListEndOfPeiTable

Initial value:

= {
  (EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST),
  &gEfiEndOfPeiSignalPpiGuid,
  0
}

Definition at line 251 of file S3Resume.c.

◆ mPpiListEndOfS3ResumeTable

EFI_PEI_PPI_DESCRIPTOR mPpiListEndOfS3ResumeTable

Initial value:

= {
  (EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST),
  &gEdkiiEndOfS3ResumeGuid,
  0
}

Definition at line 263 of file S3Resume.c.

◆ mPpiListPostScriptTable

EFI_PEI_PPI_DESCRIPTOR mPpiListPostScriptTable

Initial value:

= {
  (EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST),
  &gPeiPostScriptTablePpiGuid,
  0
}

Definition at line 245 of file S3Resume.c.

◆ mPpiListS3SmmInitDoneTable

EFI_PEI_PPI_DESCRIPTOR mPpiListS3SmmInitDoneTable

Initial value:

= {
  (EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST),
  &gEdkiiS3SmmInitDoneGuid,
  0
}

Definition at line 257 of file S3Resume.c.

◆ mS3ResumePpi

EFI_PEI_S3_RESUME2_PPI mS3ResumePpi = { S3RestoreConfig2 }

Definition at line 237 of file S3Resume.c.

Variables
EFI_PEI_S3_RESUME2_PPI	mS3ResumePpi = { S3RestoreConfig2 }

EFI_PEI_PPI_DESCRIPTOR	mPpiList

EFI_PEI_PPI_DESCRIPTOR	mPpiListPostScriptTable

EFI_PEI_PPI_DESCRIPTOR	mPpiListEndOfPeiTable

EFI_PEI_PPI_DESCRIPTOR	mPpiListS3SmmInitDoneTable

EFI_PEI_PPI_DESCRIPTOR	mPpiListEndOfS3ResumeTable

GLOBAL_REMOVE_IF_UNREFERENCED IA32_GDT	mGdtEntries []

GLOBAL_REMOVE_IF_UNREFERENCED CONST IA32_DESCRIPTOR	mGdt

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ DATA_SEGEMENT_SELECTOR

◆ PAGING_1G_ADDRESS_MASK_64

◆ STACK_ALIGN_DOWN

Typedef Documentation

◆ ASM_TRANSFER_CONTROL

Function Documentation

◆ AsmSetDataSelectors()

◆ IsLongModeWakingVector()

◆ LoadMtrrData()

◆ PeimS3ResumeEntryPoint()

◆ RestoreS3PageTables()

◆ S3RestoreConfig2()

◆ S3ResumeBootOs()

◆ S3ResumeExecuteBootScript()

◆ SignalToSmmByCommunication()

Variable Documentation

◆ mGdt

◆ mGdtEntries

◆ mPpiList

◆ mPpiListEndOfPeiTable

◆ mPpiListEndOfS3ResumeTable

◆ mPpiListPostScriptTable

◆ mPpiListS3SmmInitDoneTable

◆ mS3ResumePpi