2 This module produces the EFI_PEI_S3_RESUME2_PPI.
3 This module works with StandAloneBootScriptExecutor to S3 resume to OS.
4 This module will execute the boot script saved during last boot and after that,
5 control is passed to OS waking up handler.
7 Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
8 Copyright (c) 2017, AMD Incorporated. All rights reserved.<BR>
10 SPDX-License-Identifier: BSD-2-Clause-Patent
16 #include <Guid/AcpiS3Context.h>
17 #include <Guid/BootScriptExecutorVariable.h>
18 #include <Guid/ExtendedFirmwarePerformance.h>
19 #include <Guid/EndOfS3Resume.h>
20 #include <Guid/S3SmmInitDone.h>
21 #include <Ppi/S3Resume2.h>
22 #include <Ppi/SmmAccess.h>
23 #include <Ppi/PostBootScriptTable.h>
24 #include <Ppi/EndOfPeiPhase.h>
25 #include <Ppi/SmmCommunication.h>
27 #include <Library/DebugLib.h>
28 #include <Library/BaseLib.h>
29 #include <Library/PeimEntryPoint.h>
30 #include <Library/PeiServicesLib.h>
31 #include <Library/HobLib.h>
32 #include <Library/PerformanceLib.h>
33 #include <Library/PeiServicesTablePointerLib.h>
34 #include <Library/IoLib.h>
35 #include <Library/BaseMemoryLib.h>
36 #include <Library/MemoryAllocationLib.h>
37 #include <Library/PcdLib.h>
38 #include <Library/DebugAgentLib.h>
39 #include <Library/LocalApicLib.h>
40 #include <Library/ReportStatusCodeLib.h>
42 #include <Library/HobLib.h>
43 #include <Library/LockBoxLib.h>
44 #include <IndustryStandard/Acpi.h>
47 This macro aligns the address of a variable with auto storage
48 duration down to CPU_STACK_ALIGNMENT.
50 Since the stack grows downward, the result preserves more of the
51 stack than the original address (or the same amount), not less.
53 #define STACK_ALIGN_DOWN(Ptr) \
54 ((UINTN)(Ptr) & ~(UINTN)(CPU_STACK_ALIGNMENT - 1))
56 #define PAGING_1G_ADDRESS_MASK_64 0x000FFFFFC0000000ull
71 UINT32 DefaultSize
: 1;
72 UINT32 Granularity
: 1;
79 // Page-Map Level-4 Offset (PML4) and
80 // Page-Directory-Pointer Offset (PDPE) entries 4K & 2MB
84 UINT64 Present
:1; // 0 = Not present in memory, 1 = Present in memory
85 UINT64 ReadWrite
:1; // 0 = Read-Only, 1= Read/Write
86 UINT64 UserSupervisor
:1; // 0 = Supervisor, 1=User
87 UINT64 WriteThrough
:1; // 0 = Write-Back caching, 1=Write-Through caching
88 UINT64 CacheDisabled
:1; // 0 = Cached, 1=Non-Cached
89 UINT64 Accessed
:1; // 0 = Not accessed, 1 = Accessed (set by CPU)
90 UINT64 Reserved
:1; // Reserved
91 UINT64 MustBeZero
:2; // Must Be Zero
92 UINT64 Available
:3; // Available for use by system software
93 UINT64 PageTableBaseAddress
:40; // Page Table Base Address
94 UINT64 AvabilableHigh
:11; // Available for use by system software
95 UINT64 Nx
:1; // No Execute bit
98 } PAGE_MAP_AND_DIRECTORY_POINTER
;
101 // Page Table Entry 2MB
105 UINT64 Present
:1; // 0 = Not present in memory, 1 = Present in memory
106 UINT64 ReadWrite
:1; // 0 = Read-Only, 1= Read/Write
107 UINT64 UserSupervisor
:1; // 0 = Supervisor, 1=User
108 UINT64 WriteThrough
:1; // 0 = Write-Back caching, 1=Write-Through caching
109 UINT64 CacheDisabled
:1; // 0 = Cached, 1=Non-Cached
110 UINT64 Accessed
:1; // 0 = Not accessed, 1 = Accessed (set by CPU)
111 UINT64 Dirty
:1; // 0 = Not Dirty, 1 = written by processor on access to page
112 UINT64 MustBe1
:1; // Must be 1
113 UINT64 Global
:1; // 0 = Not global page, 1 = global page TLB not cleared on CR3 write
114 UINT64 Available
:3; // Available for use by system software
116 UINT64 MustBeZero
:8; // Must be zero;
117 UINT64 PageTableBaseAddress
:31; // Page Table Base Address
118 UINT64 AvabilableHigh
:11; // Available for use by system software
119 UINT64 Nx
:1; // 0 = Execute Code, 1 = No Code Execution
125 // Page Table Entry 1GB
129 UINT64 Present
:1; // 0 = Not present in memory, 1 = Present in memory
130 UINT64 ReadWrite
:1; // 0 = Read-Only, 1= Read/Write
131 UINT64 UserSupervisor
:1; // 0 = Supervisor, 1=User
132 UINT64 WriteThrough
:1; // 0 = Write-Back caching, 1=Write-Through caching
133 UINT64 CacheDisabled
:1; // 0 = Cached, 1=Non-Cached
134 UINT64 Accessed
:1; // 0 = Not accessed, 1 = Accessed (set by CPU)
135 UINT64 Dirty
:1; // 0 = Not Dirty, 1 = written by processor on access to page
136 UINT64 MustBe1
:1; // Must be 1
137 UINT64 Global
:1; // 0 = Not global page, 1 = global page TLB not cleared on CR3 write
138 UINT64 Available
:3; // Available for use by system software
140 UINT64 MustBeZero
:17; // Must be zero;
141 UINT64 PageTableBaseAddress
:22; // Page Table Base Address
142 UINT64 AvabilableHigh
:11; // Available for use by system software
143 UINT64 Nx
:1; // 0 = Execute Code, 1 = No Code Execution
146 } PAGE_TABLE_1G_ENTRY
;
149 // Define two type of smm communicate headers.
150 // One for 32 bits PEI + 64 bits DXE, the other for 32 bits PEI + 32 bits DXE case.
154 UINT32 MessageLength
;
156 } SMM_COMMUNICATE_HEADER_32
;
160 UINT64 MessageLength
;
162 } SMM_COMMUNICATE_HEADER_64
;
167 // Function prototypes
170 a ASM function to transfer control to OS.
172 @param S3WakingVector The S3 waking up vector saved in ACPI Facs table
173 @param AcpiLowMemoryBase a buffer under 1M which could be used during the transfer
177 (EFIAPI
*ASM_TRANSFER_CONTROL
) (
178 IN UINT32 S3WakingVector
,
179 IN UINT32 AcpiLowMemoryBase
183 Restores the platform to its preboot configuration for an S3 resume and
184 jumps to the OS waking vector.
186 This function will restore the platform to its pre-boot configuration that was
187 pre-stored in the boot script table and transfer control to OS waking vector.
188 Upon invocation, this function is responsible for locating the following
189 information before jumping to OS waking vector:
192 - any other information that it needs
194 The S3RestoreConfig() function then executes the pre-stored boot script table
195 and transitions the platform to the pre-boot state. The boot script is recorded
196 during regular boot using the EFI_S3_SAVE_STATE_PROTOCOL.Write() and
197 EFI_S3_SMM_SAVE_STATE_PROTOCOL.Write() functions. Finally, this function
198 transfers control to the OS waking vector. If the OS supports only a real-mode
199 waking vector, this function will switch from flat mode to real mode before
200 jumping to the waking vector. If all platform pre-boot configurations are
201 successfully restored and all other necessary information is ready, this
202 function will never return and instead will directly jump to the OS waking
203 vector. If this function returns, it indicates that the attempt to resume
204 from the ACPI S3 sleep state failed.
206 @param[in] This Pointer to this instance of the PEI_S3_RESUME_PPI
208 @retval EFI_ABORTED Execution of the S3 resume boot script table failed.
209 @retval EFI_NOT_FOUND Some necessary information that is used for the S3
210 resume boot path could not be located.
216 IN EFI_PEI_S3_RESUME2_PPI
*This
220 Set data segment selectors value including DS/ES/FS/GS/SS.
222 @param[in] SelectorValue Segment selector value to be set.
227 AsmSetDataSelectors (
228 IN UINT16 SelectorValue
234 EFI_PEI_S3_RESUME2_PPI mS3ResumePpi
= { S3RestoreConfig2
};
236 EFI_PEI_PPI_DESCRIPTOR mPpiList
= {
237 (EFI_PEI_PPI_DESCRIPTOR_PPI
| EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST
),
238 &gEfiPeiS3Resume2PpiGuid
,
242 EFI_PEI_PPI_DESCRIPTOR mPpiListPostScriptTable
= {
243 (EFI_PEI_PPI_DESCRIPTOR_PPI
| EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST
),
244 &gPeiPostScriptTablePpiGuid
,
248 EFI_PEI_PPI_DESCRIPTOR mPpiListEndOfPeiTable
= {
249 (EFI_PEI_PPI_DESCRIPTOR_PPI
| EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST
),
250 &gEfiEndOfPeiSignalPpiGuid
,
254 EFI_PEI_PPI_DESCRIPTOR mPpiListS3SmmInitDoneTable
= {
255 (EFI_PEI_PPI_DESCRIPTOR_PPI
| EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST
),
256 &gEdkiiS3SmmInitDoneGuid
,
261 // Global Descriptor Table (GDT)
263 GLOBAL_REMOVE_IF_UNREFERENCED IA32_GDT mGdtEntries
[] = {
264 /* selector { Global Segment Descriptor } */
265 /* 0x00 */ {{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}},
266 /* 0x08 */ {{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}},
267 /* 0x10 */ {{0xFFFF, 0, 0, 0xB, 1, 0, 1, 0xF, 0, 0, 1, 1, 0}},
268 /* 0x18 */ {{0xFFFF, 0, 0, 0x3, 1, 0, 1, 0xF, 0, 0, 1, 1, 0}},
269 /* 0x20 */ {{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}},
270 /* 0x28 */ {{0xFFFF, 0, 0, 0xB, 1, 0, 1, 0xF, 0, 0, 0, 1, 0}},
271 /* 0x30 */ {{0xFFFF, 0, 0, 0x3, 1, 0, 1, 0xF, 0, 0, 0, 1, 0}},
272 /* 0x38 */ {{0xFFFF, 0, 0, 0xB, 1, 0, 1, 0xF, 0, 1, 0, 1, 0}},
273 /* 0x40 */ {{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}},
276 #define DATA_SEGEMENT_SELECTOR 0x18
281 GLOBAL_REMOVE_IF_UNREFERENCED CONST IA32_DESCRIPTOR mGdt
= {
282 sizeof (mGdtEntries
) - 1,
288 The function will check if current waking vector is long mode.
290 @param AcpiS3Context a pointer to a structure of ACPI_S3_CONTEXT
292 @retval TRUE Current context need long mode waking vector.
293 @retval FALSE Current context need not long mode waking vector.
296 IsLongModeWakingVector (
297 IN ACPI_S3_CONTEXT
*AcpiS3Context
300 EFI_ACPI_4_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
302 Facs
= (EFI_ACPI_4_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*) ((UINTN
) (AcpiS3Context
->AcpiFacsTable
));
303 if ((Facs
== NULL
) ||
304 (Facs
->Signature
!= EFI_ACPI_4_0_FIRMWARE_ACPI_CONTROL_STRUCTURE_SIGNATURE
) ||
305 ((Facs
->FirmwareWakingVector
== 0) && (Facs
->XFirmwareWakingVector
== 0)) ) {
306 // Something wrong with FACS
309 if (Facs
->XFirmwareWakingVector
!= 0) {
310 if ((Facs
->Version
== EFI_ACPI_4_0_FIRMWARE_ACPI_CONTROL_STRUCTURE_VERSION
) &&
311 ((Facs
->Flags
& EFI_ACPI_4_0_64BIT_WAKE_SUPPORTED_F
) != 0) &&
312 ((Facs
->OspmFlags
& EFI_ACPI_4_0_OSPM_64BIT_WAKE__F
) != 0)) {
313 // Both BIOS and OS wants 64bit vector
314 if (FeaturePcdGet (PcdDxeIplSwitchToLongMode
)) {
323 Signal to SMM through communication buffer way.
325 @param[in] HandlerType SMI handler type to be signaled.
329 SignalToSmmByCommunication (
330 IN EFI_GUID
*HandlerType
334 EFI_PEI_SMM_COMMUNICATION_PPI
*SmmCommunicationPpi
;
336 SMM_COMMUNICATE_HEADER_32 Header32
;
337 SMM_COMMUNICATE_HEADER_64 Header64
;
340 DEBUG ((DEBUG_INFO
, "Signal %g to SMM - Enter\n", HandlerType
));
343 // This buffer consumed in DXE phase, so base on DXE mode to prepare communicate buffer.
344 // Detect whether DXE is 64 bits mode.
345 // if (sizeof(UINTN) == sizeof(UINT64), PEI already 64 bits, assume DXE also 64 bits.
346 // or (FeaturePcdGet (PcdDxeIplSwitchToLongMode)), DXE will switch to 64 bits.
348 if ((sizeof(UINTN
) == sizeof(UINT64
)) || (FeaturePcdGet (PcdDxeIplSwitchToLongMode
))) {
349 CommBuffer
= &Header64
;
350 Header64
.MessageLength
= 0;
351 CommSize
= OFFSET_OF (SMM_COMMUNICATE_HEADER_64
, Data
);
353 CommBuffer
= &Header32
;
354 Header32
.MessageLength
= 0;
355 CommSize
= OFFSET_OF (SMM_COMMUNICATE_HEADER_32
, Data
);
357 CopyGuid (CommBuffer
, HandlerType
);
359 Status
= PeiServicesLocatePpi (
360 &gEfiPeiSmmCommunicationPpiGuid
,
363 (VOID
**)&SmmCommunicationPpi
365 if (EFI_ERROR (Status
)) {
366 DEBUG ((DEBUG_ERROR
, "Locate Smm Communicate Ppi failed (%r)!\n", Status
));
370 Status
= SmmCommunicationPpi
->Communicate (
375 if (EFI_ERROR (Status
)) {
376 DEBUG ((DEBUG_ERROR
, "SmmCommunicationPpi->Communicate return failure (%r)!\n", Status
));
379 DEBUG ((DEBUG_INFO
, "Signal %g to SMM - Exit (%r)\n", HandlerType
, Status
));
384 Jump to OS waking vector.
385 The function will install boot script done PPI, report S3 resume status code, and then jump to OS waking vector.
387 @param AcpiS3Context a pointer to a structure of ACPI_S3_CONTEXT
388 @param PeiS3ResumeState a pointer to a structure of PEI_S3_RESUME_STATE
393 IN ACPI_S3_CONTEXT
*AcpiS3Context
,
394 IN PEI_S3_RESUME_STATE
*PeiS3ResumeState
398 EFI_ACPI_4_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
399 ASM_TRANSFER_CONTROL AsmTransferControl
;
401 UINTN TempStack
[0x10];
406 AsmWriteIdtr (&PeiS3ResumeState
->Idtr
);
408 if (PeiS3ResumeState
->ReturnStatus
!= EFI_SUCCESS
) {
410 // Report Status code that boot script execution is failed
413 EFI_ERROR_CODE
| EFI_ERROR_MINOR
,
414 (EFI_SOFTWARE_PEI_MODULE
| EFI_SW_PEI_EC_S3_BOOT_SCRIPT_ERROR
)
419 // NOTE: Because Debug Timer interrupt and system interrupts will be disabled
420 // in BootScriptExecuteDxe, the rest code in S3ResumeBootOs() cannot be halted
424 PERF_INMODULE_END ("ScriptExec");
427 // Install BootScriptDonePpi
429 PERF_INMODULE_BEGIN ("BootScriptDonePpi");
431 Status
= PeiServicesInstallPpi (&mPpiListPostScriptTable
);
432 ASSERT_EFI_ERROR (Status
);
434 PERF_INMODULE_END ("BootScriptDonePpi");
437 // Get ACPI Table Address
439 Facs
= (EFI_ACPI_4_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*) ((UINTN
) (AcpiS3Context
->AcpiFacsTable
));
441 if ((Facs
== NULL
) ||
442 (Facs
->Signature
!= EFI_ACPI_4_0_FIRMWARE_ACPI_CONTROL_STRUCTURE_SIGNATURE
) ||
443 ((Facs
->FirmwareWakingVector
== 0) && (Facs
->XFirmwareWakingVector
== 0)) ) {
445 // Report Status code that no valid vector is found
448 EFI_ERROR_CODE
| EFI_ERROR_MAJOR
,
449 (EFI_SOFTWARE_PEI_MODULE
| EFI_SW_PEI_EC_S3_OS_WAKE_ERROR
)
456 // Install EndOfPeiPpi
458 PERF_INMODULE_BEGIN("EndOfPeiPpi");
460 Status
= PeiServicesInstallPpi (&mPpiListEndOfPeiTable
);
461 ASSERT_EFI_ERROR (Status
);
463 PERF_INMODULE_END("EndOfPeiPpi");
465 PERF_INMODULE_BEGIN("EndOfS3Resume");
467 DEBUG ((DEBUG_INFO
, "Signal EndOfS3Resume\n"));
469 // Signal EndOfS3Resume to SMM.
471 SignalToSmmByCommunication (&gEdkiiEndOfS3ResumeGuid
);
473 PERF_INMODULE_END ("EndOfS3Resume");
476 // report status code on S3 resume
478 REPORT_STATUS_CODE (EFI_PROGRESS_CODE
, EFI_SOFTWARE_PEI_MODULE
| EFI_SW_PEI_PC_OS_WAKE
);
480 AsmTransferControl
= (ASM_TRANSFER_CONTROL
)(UINTN
)PeiS3ResumeState
->AsmTransferControl
;
481 if (Facs
->XFirmwareWakingVector
!= 0) {
483 // Switch to native waking vector
485 TempStackTop
= (UINTN
)&TempStack
+ sizeof(TempStack
);
488 "%a() Stack Base: 0x%x, Stack Size: 0x%x\n",
493 if ((Facs
->Version
== EFI_ACPI_4_0_FIRMWARE_ACPI_CONTROL_STRUCTURE_VERSION
) &&
494 ((Facs
->Flags
& EFI_ACPI_4_0_64BIT_WAKE_SUPPORTED_F
) != 0) &&
495 ((Facs
->OspmFlags
& EFI_ACPI_4_0_OSPM_64BIT_WAKE__F
) != 0)) {
497 // X64 long mode waking vector
499 DEBUG ((DEBUG_INFO
, "Transfer to 64bit OS waking vector - %x\r\n", (UINTN
)Facs
->XFirmwareWakingVector
));
500 if (FeaturePcdGet (PcdDxeIplSwitchToLongMode
)) {
503 Facs
->XFirmwareWakingVector
,
506 (UINT64
)(UINTN
)TempStackTop
510 // Report Status code that no valid waking vector is found
513 EFI_ERROR_CODE
| EFI_ERROR_MAJOR
,
514 (EFI_SOFTWARE_PEI_MODULE
| EFI_SW_PEI_EC_S3_OS_WAKE_ERROR
)
516 DEBUG (( EFI_D_ERROR
, "Unsupported for 32bit DXE transfer to 64bit OS waking vector!\r\n"));
523 // IA32 protected mode waking vector (Page disabled)
525 DEBUG ((DEBUG_INFO
, "Transfer to 32bit OS waking vector - %x\r\n", (UINTN
)Facs
->XFirmwareWakingVector
));
527 (SWITCH_STACK_ENTRY_POINT
) (UINTN
) Facs
->XFirmwareWakingVector
,
530 (VOID
*)(UINTN
)TempStackTop
535 // 16bit Realmode waking vector
537 DEBUG ((DEBUG_INFO
, "Transfer to 16bit OS waking vector - %x\r\n", (UINTN
)Facs
->FirmwareWakingVector
));
538 AsmTransferControl (Facs
->FirmwareWakingVector
, 0x0);
542 // Report Status code the failure of S3Resume
545 EFI_ERROR_CODE
| EFI_ERROR_MAJOR
,
546 (EFI_SOFTWARE_PEI_MODULE
| EFI_SW_PEI_EC_S3_OS_WAKE_ERROR
)
556 Restore S3 page table because we do not trust ACPINvs content.
557 If BootScriptExector driver will not run in 64-bit mode, this function will do nothing.
559 @param S3NvsPageTableAddress PageTableAddress in ACPINvs
560 @param Build4GPageTableOnly If BIOS just build 4G page table only
563 RestoreS3PageTables (
564 IN UINTN S3NvsPageTableAddress
,
565 IN BOOLEAN Build4GPageTableOnly
568 if (FeaturePcdGet (PcdDxeIplSwitchToLongMode
)) {
571 UINT8 PhysicalAddressBits
;
572 EFI_PHYSICAL_ADDRESS PageAddress
;
573 UINTN IndexOfPml4Entries
;
574 UINTN IndexOfPdpEntries
;
575 UINTN IndexOfPageDirectoryEntries
;
576 UINT32 NumberOfPml4EntriesNeeded
;
577 UINT32 NumberOfPdpEntriesNeeded
;
578 PAGE_MAP_AND_DIRECTORY_POINTER
*PageMapLevel4Entry
;
579 PAGE_MAP_AND_DIRECTORY_POINTER
*PageMap
;
580 PAGE_MAP_AND_DIRECTORY_POINTER
*PageDirectoryPointerEntry
;
581 PAGE_TABLE_ENTRY
*PageDirectoryEntry
;
583 BOOLEAN Page1GSupport
;
584 PAGE_TABLE_1G_ENTRY
*PageDirectory1GEntry
;
585 UINT64 AddressEncMask
;
588 // Make sure AddressEncMask is contained to smallest supported address field
590 AddressEncMask
= PcdGet64 (PcdPteMemoryEncryptionAddressOrMask
) & PAGING_1G_ADDRESS_MASK_64
;
593 // NOTE: We have to ASSUME the page table generation format, because we do not know whole page table information.
594 // The whole page table is too large to be saved in SMRAM.
596 // The assumption is : whole page table is allocated in CONTINUOUS memory and CR3 points to TOP page.
598 DEBUG ((DEBUG_INFO
, "S3NvsPageTableAddress - %x (%x)\n", (UINTN
)S3NvsPageTableAddress
, (UINTN
)Build4GPageTableOnly
));
601 // By architecture only one PageMapLevel4 exists - so lets allocate storage for it.
603 PageMap
= (PAGE_MAP_AND_DIRECTORY_POINTER
*)S3NvsPageTableAddress
;
604 S3NvsPageTableAddress
+= SIZE_4KB
;
606 Page1GSupport
= FALSE
;
607 if (PcdGetBool(PcdUse1GPageTable
)) {
608 AsmCpuid (0x80000000, &RegEax
, NULL
, NULL
, NULL
);
609 if (RegEax
>= 0x80000001) {
610 AsmCpuid (0x80000001, NULL
, NULL
, NULL
, &RegEdx
);
611 if ((RegEdx
& BIT26
) != 0) {
612 Page1GSupport
= TRUE
;
618 // Get physical address bits supported.
620 Hob
= GetFirstHob (EFI_HOB_TYPE_CPU
);
622 PhysicalAddressBits
= ((EFI_HOB_CPU
*) Hob
)->SizeOfMemorySpace
;
624 AsmCpuid (0x80000000, &RegEax
, NULL
, NULL
, NULL
);
625 if (RegEax
>= 0x80000008) {
626 AsmCpuid (0x80000008, &RegEax
, NULL
, NULL
, NULL
);
627 PhysicalAddressBits
= (UINT8
) RegEax
;
629 PhysicalAddressBits
= 36;
634 // IA-32e paging translates 48-bit linear addresses to 52-bit physical addresses.
636 ASSERT (PhysicalAddressBits
<= 52);
637 if (PhysicalAddressBits
> 48) {
638 PhysicalAddressBits
= 48;
642 // NOTE: In order to save time to create full page table, we just create 4G page table by default.
643 // And let PF handler in BootScript driver to create more on request.
645 if (Build4GPageTableOnly
) {
646 PhysicalAddressBits
= 32;
647 ZeroMem (PageMap
, EFI_PAGES_TO_SIZE(2));
650 // Calculate the table entries needed.
652 if (PhysicalAddressBits
<= 39) {
653 NumberOfPml4EntriesNeeded
= 1;
654 NumberOfPdpEntriesNeeded
= (UINT32
)LShiftU64 (1, (PhysicalAddressBits
- 30));
656 NumberOfPml4EntriesNeeded
= (UINT32
)LShiftU64 (1, (PhysicalAddressBits
- 39));
657 NumberOfPdpEntriesNeeded
= 512;
660 PageMapLevel4Entry
= PageMap
;
662 for (IndexOfPml4Entries
= 0; IndexOfPml4Entries
< NumberOfPml4EntriesNeeded
; IndexOfPml4Entries
++, PageMapLevel4Entry
++) {
664 // Each PML4 entry points to a page of Page Directory Pointer entires.
665 // So lets allocate space for them and fill them in in the IndexOfPdpEntries loop.
667 PageDirectoryPointerEntry
= (PAGE_MAP_AND_DIRECTORY_POINTER
*)S3NvsPageTableAddress
;
668 S3NvsPageTableAddress
+= SIZE_4KB
;
673 PageMapLevel4Entry
->Uint64
= (UINT64
)(UINTN
)PageDirectoryPointerEntry
| AddressEncMask
;
674 PageMapLevel4Entry
->Bits
.ReadWrite
= 1;
675 PageMapLevel4Entry
->Bits
.Present
= 1;
678 PageDirectory1GEntry
= (VOID
*) PageDirectoryPointerEntry
;
680 for (IndexOfPageDirectoryEntries
= 0; IndexOfPageDirectoryEntries
< 512; IndexOfPageDirectoryEntries
++, PageDirectory1GEntry
++, PageAddress
+= SIZE_1GB
) {
682 // Fill in the Page Directory entries
684 PageDirectory1GEntry
->Uint64
= (UINT64
)PageAddress
| AddressEncMask
;
685 PageDirectory1GEntry
->Bits
.ReadWrite
= 1;
686 PageDirectory1GEntry
->Bits
.Present
= 1;
687 PageDirectory1GEntry
->Bits
.MustBe1
= 1;
690 for (IndexOfPdpEntries
= 0; IndexOfPdpEntries
< NumberOfPdpEntriesNeeded
; IndexOfPdpEntries
++, PageDirectoryPointerEntry
++) {
692 // Each Directory Pointer entries points to a page of Page Directory entires.
693 // So allocate space for them and fill them in in the IndexOfPageDirectoryEntries loop.
695 PageDirectoryEntry
= (PAGE_TABLE_ENTRY
*)S3NvsPageTableAddress
;
696 S3NvsPageTableAddress
+= SIZE_4KB
;
699 // Fill in a Page Directory Pointer Entries
701 PageDirectoryPointerEntry
->Uint64
= (UINT64
)(UINTN
)PageDirectoryEntry
| AddressEncMask
;
702 PageDirectoryPointerEntry
->Bits
.ReadWrite
= 1;
703 PageDirectoryPointerEntry
->Bits
.Present
= 1;
705 for (IndexOfPageDirectoryEntries
= 0; IndexOfPageDirectoryEntries
< 512; IndexOfPageDirectoryEntries
++, PageDirectoryEntry
++, PageAddress
+= SIZE_2MB
) {
707 // Fill in the Page Directory entries
709 PageDirectoryEntry
->Uint64
= (UINT64
)PageAddress
| AddressEncMask
;
710 PageDirectoryEntry
->Bits
.ReadWrite
= 1;
711 PageDirectoryEntry
->Bits
.Present
= 1;
712 PageDirectoryEntry
->Bits
.MustBe1
= 1;
720 // If DXE is running 32-bit mode, no need to establish page table.
727 Jump to boot script executor driver.
729 The function will close and lock SMRAM and then jump to boot script execute driver to executing S3 boot script table.
731 @param AcpiS3Context a pointer to a structure of ACPI_S3_CONTEXT
732 @param EfiBootScriptExecutorVariable The function entry to executing S3 boot Script table. This function is build in
733 boot script execute driver
737 S3ResumeExecuteBootScript (
738 IN ACPI_S3_CONTEXT
*AcpiS3Context
,
739 IN BOOT_SCRIPT_EXECUTOR_VARIABLE
*EfiBootScriptExecutorVariable
743 PEI_SMM_ACCESS_PPI
*SmmAccess
;
746 IA32_DESCRIPTOR
*IdtDescriptor
;
748 PEI_S3_RESUME_STATE
*PeiS3ResumeState
;
749 BOOLEAN InterruptStatus
;
751 DEBUG ((DEBUG_INFO
, "S3ResumeExecuteBootScript()\n"));
754 // Attempt to use content from SMRAM first
756 GuidHob
= GetFirstGuidHob (&gEfiAcpiVariableGuid
);
757 if (GuidHob
!= NULL
) {
759 // Last step for SMM - send SMI for initialization
765 SendSmiIpiAllExcludingSelf ();
769 SendSmiIpi (GetApicId ());
771 Status
= PeiServicesLocatePpi (
772 &gPeiSmmAccessPpiGuid
,
777 if (!EFI_ERROR (Status
)) {
778 DEBUG ((DEBUG_INFO
, "Close all SMRAM regions before executing boot script\n"));
780 for (Index
= 0, Status
= EFI_SUCCESS
; !EFI_ERROR (Status
); Index
++) {
781 Status
= SmmAccess
->Close ((EFI_PEI_SERVICES
**)GetPeiServicesTablePointer (), SmmAccess
, Index
);
784 DEBUG ((DEBUG_INFO
, "Lock all SMRAM regions before executing boot script\n"));
786 for (Index
= 0, Status
= EFI_SUCCESS
; !EFI_ERROR (Status
); Index
++) {
787 Status
= SmmAccess
->Lock ((EFI_PEI_SERVICES
**)GetPeiServicesTablePointer (), SmmAccess
, Index
);
791 DEBUG ((DEBUG_INFO
, "Signal S3SmmInitDone\n"));
793 // Install S3SmmInitDone PPI.
795 Status
= PeiServicesInstallPpi (&mPpiListS3SmmInitDoneTable
);
796 ASSERT_EFI_ERROR (Status
);
798 // Signal S3SmmInitDone to SMM.
800 SignalToSmmByCommunication (&gEdkiiS3SmmInitDoneGuid
);
803 if (FeaturePcdGet (PcdDxeIplSwitchToLongMode
)) {
804 AsmWriteCr3 ((UINTN
)AcpiS3Context
->S3NvsPageTableAddress
);
807 if (FeaturePcdGet (PcdFrameworkCompatibilitySupport
)) {
809 // On some platform, such as ECP, a dispatch node in boot script table may execute a 32-bit PEIM which may need PeiServices
810 // pointer. So PeiServices need preserve in (IDTBase- sizeof (UINTN)).
812 IdtDescriptor
= (IA32_DESCRIPTOR
*) (UINTN
) (AcpiS3Context
->IdtrProfile
);
814 // Make sure the newly allocated IDT align with 16-bytes
816 IdtBuffer
= AllocatePages (EFI_SIZE_TO_PAGES((IdtDescriptor
->Limit
+ 1) + 16));
817 if (IdtBuffer
== NULL
) {
819 EFI_ERROR_CODE
| EFI_ERROR_MAJOR
,
820 (EFI_SOFTWARE_PEI_MODULE
| EFI_SW_PEI_EC_S3_RESUME_FAILED
)
825 // Additional 16 bytes allocated to save IA32 IDT descriptor and Pei Service Table Pointer
826 // IA32 IDT descriptor will be used to setup IA32 IDT table for 32-bit Framework Boot Script code
828 ZeroMem (IdtBuffer
, 16);
829 AsmReadIdtr ((IA32_DESCRIPTOR
*)IdtBuffer
);
830 CopyMem ((VOID
*)((UINT8
*)IdtBuffer
+ 16),(VOID
*)(IdtDescriptor
->Base
), (IdtDescriptor
->Limit
+ 1));
831 IdtDescriptor
->Base
= (UINTN
)((UINT8
*)IdtBuffer
+ 16);
832 *(UINTN
*)(IdtDescriptor
->Base
- sizeof(UINTN
)) = (UINTN
)GetPeiServicesTablePointer ();
835 InterruptStatus
= SaveAndDisableInterrupts ();
837 // Need to make sure the GDT is loaded with values that support long mode and real mode.
839 AsmWriteGdtr (&mGdt
);
841 // update segment selectors per the new GDT.
843 AsmSetDataSelectors (DATA_SEGEMENT_SELECTOR
);
845 // Restore interrupt state.
847 SetInterruptState (InterruptStatus
);
850 // Prepare data for return back
852 PeiS3ResumeState
= AllocatePool (sizeof(*PeiS3ResumeState
));
853 if (PeiS3ResumeState
== NULL
) {
855 EFI_ERROR_CODE
| EFI_ERROR_MAJOR
,
856 (EFI_SOFTWARE_PEI_MODULE
| EFI_SW_PEI_EC_S3_RESUME_FAILED
)
860 DEBUG ((DEBUG_INFO
, "PeiS3ResumeState - %x\r\n", PeiS3ResumeState
));
861 PeiS3ResumeState
->ReturnCs
= 0x10;
862 PeiS3ResumeState
->ReturnEntryPoint
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)S3ResumeBootOs
;
863 PeiS3ResumeState
->ReturnStackPointer
= (EFI_PHYSICAL_ADDRESS
)STACK_ALIGN_DOWN (&Status
);
867 AsmReadIdtr (&PeiS3ResumeState
->Idtr
);
870 // Report Status Code to indicate S3 boot script execution
872 REPORT_STATUS_CODE (EFI_PROGRESS_CODE
, EFI_SOFTWARE_PEI_MODULE
| EFI_SW_PEI_PC_S3_BOOT_SCRIPT
);
874 PERF_INMODULE_BEGIN ("ScriptExec");
876 if (FeaturePcdGet (PcdDxeIplSwitchToLongMode
)) {
880 DEBUG ((DEBUG_INFO
, "Enable X64 and transfer control to Standalone Boot Script Executor\r\n"));
883 // Switch to long mode to complete resume.
887 EfiBootScriptExecutorVariable
->BootScriptExecutorEntrypoint
,
888 (UINT64
)(UINTN
)AcpiS3Context
,
889 (UINT64
)(UINTN
)PeiS3ResumeState
,
890 (UINT64
)(UINTN
)(AcpiS3Context
->BootScriptStackBase
+ AcpiS3Context
->BootScriptStackSize
)
896 DEBUG ((DEBUG_INFO
, "transfer control to Standalone Boot Script Executor\r\n"));
898 (SWITCH_STACK_ENTRY_POINT
) (UINTN
) EfiBootScriptExecutorVariable
->BootScriptExecutorEntrypoint
,
899 (VOID
*)AcpiS3Context
,
900 (VOID
*)PeiS3ResumeState
,
901 (VOID
*)(UINTN
)(AcpiS3Context
->BootScriptStackBase
+ AcpiS3Context
->BootScriptStackSize
)
911 Restores the platform to its preboot configuration for an S3 resume and
912 jumps to the OS waking vector.
914 This function will restore the platform to its pre-boot configuration that was
915 pre-stored in the boot script table and transfer control to OS waking vector.
916 Upon invocation, this function is responsible for locating the following
917 information before jumping to OS waking vector:
920 - any other information that it needs
922 The S3RestoreConfig() function then executes the pre-stored boot script table
923 and transitions the platform to the pre-boot state. The boot script is recorded
924 during regular boot using the EFI_S3_SAVE_STATE_PROTOCOL.Write() and
925 EFI_S3_SMM_SAVE_STATE_PROTOCOL.Write() functions. Finally, this function
926 transfers control to the OS waking vector. If the OS supports only a real-mode
927 waking vector, this function will switch from flat mode to real mode before
928 jumping to the waking vector. If all platform pre-boot configurations are
929 successfully restored and all other necessary information is ready, this
930 function will never return and instead will directly jump to the OS waking
931 vector. If this function returns, it indicates that the attempt to resume
932 from the ACPI S3 sleep state failed.
934 @param[in] This Pointer to this instance of the PEI_S3_RESUME_PPI
936 @retval EFI_ABORTED Execution of the S3 resume boot script table failed.
937 @retval EFI_NOT_FOUND Some necessary information that is used for the S3
938 resume boot path could not be located.
944 IN EFI_PEI_S3_RESUME2_PPI
*This
948 PEI_SMM_ACCESS_PPI
*SmmAccess
;
950 ACPI_S3_CONTEXT
*AcpiS3Context
;
951 EFI_PHYSICAL_ADDRESS TempEfiBootScriptExecutorVariable
;
952 EFI_PHYSICAL_ADDRESS TempAcpiS3Context
;
953 BOOT_SCRIPT_EXECUTOR_VARIABLE
*EfiBootScriptExecutorVariable
;
955 EFI_SMRAM_DESCRIPTOR
*SmramDescriptor
;
956 SMM_S3_RESUME_STATE
*SmmS3ResumeState
;
958 BOOLEAN Build4GPageTableOnly
;
959 BOOLEAN InterruptStatus
;
962 TempAcpiS3Context
= 0;
963 TempEfiBootScriptExecutorVariable
= 0;
965 DEBUG ((DEBUG_INFO
, "Enter S3 PEIM\r\n"));
967 VarSize
= sizeof (EFI_PHYSICAL_ADDRESS
);
968 Status
= RestoreLockBox (
969 &gEfiAcpiVariableGuid
,
973 ASSERT_EFI_ERROR (Status
);
975 Status
= RestoreLockBox (
976 &gEfiAcpiS3ContextGuid
,
980 ASSERT_EFI_ERROR (Status
);
982 AcpiS3Context
= (ACPI_S3_CONTEXT
*)(UINTN
)TempAcpiS3Context
;
983 ASSERT (AcpiS3Context
!= NULL
);
985 VarSize
= sizeof (EFI_PHYSICAL_ADDRESS
);
986 Status
= RestoreLockBox (
987 &gEfiBootScriptExecutorVariableGuid
,
988 &TempEfiBootScriptExecutorVariable
,
991 ASSERT_EFI_ERROR (Status
);
993 Status
= RestoreLockBox (
994 &gEfiBootScriptExecutorContextGuid
,
998 ASSERT_EFI_ERROR (Status
);
1000 EfiBootScriptExecutorVariable
= (BOOT_SCRIPT_EXECUTOR_VARIABLE
*) (UINTN
) TempEfiBootScriptExecutorVariable
;
1001 ASSERT (EfiBootScriptExecutorVariable
!= NULL
);
1003 DEBUG (( DEBUG_INFO
, "AcpiS3Context = %x\n", AcpiS3Context
));
1004 DEBUG (( DEBUG_INFO
, "Waking Vector = %x\n", ((EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*) ((UINTN
) (AcpiS3Context
->AcpiFacsTable
)))->FirmwareWakingVector
));
1005 DEBUG (( DEBUG_INFO
, "AcpiS3Context->AcpiFacsTable = %x\n", AcpiS3Context
->AcpiFacsTable
));
1006 DEBUG (( DEBUG_INFO
, "AcpiS3Context->IdtrProfile = %x\n", AcpiS3Context
->IdtrProfile
));
1007 DEBUG (( DEBUG_INFO
, "AcpiS3Context->S3NvsPageTableAddress = %x\n", AcpiS3Context
->S3NvsPageTableAddress
));
1008 DEBUG (( DEBUG_INFO
, "AcpiS3Context->S3DebugBufferAddress = %x\n", AcpiS3Context
->S3DebugBufferAddress
));
1009 DEBUG (( DEBUG_INFO
, "AcpiS3Context->BootScriptStackBase = %x\n", AcpiS3Context
->BootScriptStackBase
));
1010 DEBUG (( DEBUG_INFO
, "AcpiS3Context->BootScriptStackSize = %x\n", AcpiS3Context
->BootScriptStackSize
));
1011 DEBUG (( DEBUG_INFO
, "EfiBootScriptExecutorVariable->BootScriptExecutorEntrypoint = %x\n", EfiBootScriptExecutorVariable
->BootScriptExecutorEntrypoint
));
1014 // Additional step for BootScript integrity - we only handle BootScript and BootScriptExecutor.
1015 // Script dispatch image and context (parameter) are handled by platform.
1016 // We just use restore all lock box in place, no need restore one by one.
1018 Status
= RestoreAllLockBoxInPlace ();
1019 ASSERT_EFI_ERROR (Status
);
1020 if (EFI_ERROR (Status
)) {
1025 if (FeaturePcdGet (PcdDxeIplSwitchToLongMode
)) {
1027 // Need reconstruct page table here, since we do not trust ACPINvs.
1029 if (IsLongModeWakingVector (AcpiS3Context
)) {
1030 Build4GPageTableOnly
= FALSE
;
1032 Build4GPageTableOnly
= TRUE
;
1034 RestoreS3PageTables ((UINTN
)AcpiS3Context
->S3NvsPageTableAddress
, Build4GPageTableOnly
);
1038 // Attempt to use content from SMRAM first
1040 GuidHob
= GetFirstGuidHob (&gEfiAcpiVariableGuid
);
1041 if (GuidHob
!= NULL
) {
1043 // Below SwitchStack/AsmEnablePaging64 function has
1044 // assumption that it's in 32 bits mode now.
1045 // Add ASSERT code to indicate this assumption.
1047 ASSERT(sizeof (UINTN
) == sizeof (UINT32
));
1049 Status
= PeiServicesLocatePpi (
1050 &gPeiSmmAccessPpiGuid
,
1053 (VOID
**) &SmmAccess
1055 for (Index
= 0; !EFI_ERROR (Status
); Index
++) {
1056 Status
= SmmAccess
->Open ((EFI_PEI_SERVICES
**)GetPeiServicesTablePointer (), SmmAccess
, Index
);
1059 SmramDescriptor
= (EFI_SMRAM_DESCRIPTOR
*) GET_GUID_HOB_DATA (GuidHob
);
1060 SmmS3ResumeState
= (SMM_S3_RESUME_STATE
*)(UINTN
)SmramDescriptor
->CpuStart
;
1062 SmmS3ResumeState
->ReturnCs
= AsmReadCs ();
1063 SmmS3ResumeState
->ReturnEntryPoint
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)S3ResumeExecuteBootScript
;
1064 SmmS3ResumeState
->ReturnContext1
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AcpiS3Context
;
1065 SmmS3ResumeState
->ReturnContext2
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)EfiBootScriptExecutorVariable
;
1066 SmmS3ResumeState
->ReturnStackPointer
= (EFI_PHYSICAL_ADDRESS
)STACK_ALIGN_DOWN (&Status
);
1068 DEBUG (( DEBUG_INFO
, "SMM S3 Signature = %x\n", SmmS3ResumeState
->Signature
));
1069 DEBUG (( DEBUG_INFO
, "SMM S3 Stack Base = %x\n", SmmS3ResumeState
->SmmS3StackBase
));
1070 DEBUG (( DEBUG_INFO
, "SMM S3 Stack Size = %x\n", SmmS3ResumeState
->SmmS3StackSize
));
1071 DEBUG (( DEBUG_INFO
, "SMM S3 Resume Entry Point = %x\n", SmmS3ResumeState
->SmmS3ResumeEntryPoint
));
1072 DEBUG (( DEBUG_INFO
, "SMM S3 CR0 = %x\n", SmmS3ResumeState
->SmmS3Cr0
));
1073 DEBUG (( DEBUG_INFO
, "SMM S3 CR3 = %x\n", SmmS3ResumeState
->SmmS3Cr3
));
1074 DEBUG (( DEBUG_INFO
, "SMM S3 CR4 = %x\n", SmmS3ResumeState
->SmmS3Cr4
));
1075 DEBUG (( DEBUG_INFO
, "SMM S3 Return CS = %x\n", SmmS3ResumeState
->ReturnCs
));
1076 DEBUG (( DEBUG_INFO
, "SMM S3 Return Entry Point = %x\n", SmmS3ResumeState
->ReturnEntryPoint
));
1077 DEBUG (( DEBUG_INFO
, "SMM S3 Return Context1 = %x\n", SmmS3ResumeState
->ReturnContext1
));
1078 DEBUG (( DEBUG_INFO
, "SMM S3 Return Context2 = %x\n", SmmS3ResumeState
->ReturnContext2
));
1079 DEBUG (( DEBUG_INFO
, "SMM S3 Return Stack Pointer = %x\n", SmmS3ResumeState
->ReturnStackPointer
));
1080 DEBUG (( DEBUG_INFO
, "SMM S3 Smst = %x\n", SmmS3ResumeState
->Smst
));
1082 if (SmmS3ResumeState
->Signature
== SMM_S3_RESUME_SMM_32
) {
1084 (SWITCH_STACK_ENTRY_POINT
)(UINTN
)SmmS3ResumeState
->SmmS3ResumeEntryPoint
,
1085 (VOID
*)AcpiS3Context
,
1087 (VOID
*)(UINTN
)(SmmS3ResumeState
->SmmS3StackBase
+ SmmS3ResumeState
->SmmS3StackSize
)
1090 if (SmmS3ResumeState
->Signature
== SMM_S3_RESUME_SMM_64
) {
1092 // Switch to long mode to complete resume.
1095 InterruptStatus
= SaveAndDisableInterrupts ();
1097 // Need to make sure the GDT is loaded with values that support long mode and real mode.
1099 AsmWriteGdtr (&mGdt
);
1101 // update segment selectors per the new GDT.
1103 AsmSetDataSelectors (DATA_SEGEMENT_SELECTOR
);
1105 // Restore interrupt state.
1107 SetInterruptState (InterruptStatus
);
1109 Cr0
.UintN
= AsmReadCr0 ();
1110 if (Cr0
.Bits
.PG
!= 0) {
1112 // We're in 32-bit mode, with paging enabled. We can't set CR3 to
1113 // the 64-bit page tables without first disabling paging.
1116 AsmWriteCr0 (Cr0
.UintN
);
1118 AsmWriteCr3 ((UINTN
)SmmS3ResumeState
->SmmS3Cr3
);
1121 // Disable interrupt of Debug timer, since IDT table cannot work in long mode.
1122 // NOTE: On x64 platforms, because DisablePaging64() will disable interrupts,
1123 // the code in S3ResumeExecuteBootScript() cannot be halted by soft debugger.
1125 SaveAndSetDebugTimerInterrupt (FALSE
);
1129 SmmS3ResumeState
->SmmS3ResumeEntryPoint
,
1130 (UINT64
)(UINTN
)AcpiS3Context
,
1132 SmmS3ResumeState
->SmmS3StackBase
+ SmmS3ResumeState
->SmmS3StackSize
1138 S3ResumeExecuteBootScript (AcpiS3Context
, EfiBootScriptExecutorVariable
);
1142 Main entry for S3 Resume PEIM.
1144 This routine is to install EFI_PEI_S3_RESUME2_PPI.
1146 @param FileHandle Handle of the file being invoked.
1147 @param PeiServices Pointer to PEI Services table.
1149 @retval EFI_SUCCESS S3Resume Ppi is installed successfully.
1154 PeimS3ResumeEntryPoint (
1155 IN EFI_PEI_FILE_HANDLE FileHandle
,
1156 IN CONST EFI_PEI_SERVICES
**PeiServices
1162 // Install S3 Resume Ppi
1164 Status
= (**PeiServices
).InstallPpi (PeiServices
, &mPpiList
);
1165 ASSERT_EFI_ERROR (Status
);