2 This is an implementation of the ACPI S3 Save protocol. This is defined in
3 S3 boot path specification 0.9.
5 Copyright (c) 2014-2015, Red Hat, Inc.<BR>
6 Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR>
8 This program and the accompanying materials
9 are licensed and made available under the terms and conditions
10 of the BSD License which accompanies this distribution. The
11 full text of the license may be found at
12 http://opensource.org/licenses/bsd-license.php
14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
20 #include <Library/BaseLib.h>
21 #include <Library/BaseMemoryLib.h>
22 #include <Library/UefiBootServicesTableLib.h>
23 #include <Library/UefiRuntimeServicesTableLib.h>
24 #include <Library/HobLib.h>
25 #include <Library/LockBoxLib.h>
26 #include <Library/PcdLib.h>
27 #include <Library/DebugLib.h>
28 #include <Library/QemuFwCfgLib.h>
29 #include <Guid/AcpiVariableCompatibility.h>
30 #include <Guid/AcpiS3Context.h>
31 #include <Guid/Acpi.h>
32 #include <Protocol/AcpiS3Save.h>
33 #include <Protocol/S3SaveState.h>
34 #include <Protocol/DxeSmmReadyToLock.h>
35 #include <Protocol/LockBox.h>
36 #include <IndustryStandard/Acpi.h>
38 #include "AcpiS3Save.h"
40 UINTN mLegacyRegionSize
;
42 EFI_ACPI_S3_SAVE_PROTOCOL mS3Save
= {
43 LegacyGetS3MemorySize
,
47 EFI_GUID mAcpiS3IdtrProfileGuid
= {
48 0xdea652b0, 0xd587, 0x4c54, { 0xb5, 0xb4, 0xc6, 0x82, 0xe7, 0xa0, 0xaa, 0x3d }
52 Allocate memory below 4G memory address.
54 This function allocates memory below 4G memory address.
56 @param MemoryType Memory type of memory to allocate.
57 @param Size Size of memory to allocate.
59 @return Allocated address for output.
63 AllocateMemoryBelow4G (
64 IN EFI_MEMORY_TYPE MemoryType
,
69 EFI_PHYSICAL_ADDRESS Address
;
73 Pages
= EFI_SIZE_TO_PAGES (Size
);
76 Status
= gBS
->AllocatePages (
82 ASSERT_EFI_ERROR (Status
);
84 Buffer
= (VOID
*) (UINTN
) Address
;
85 ZeroMem (Buffer
, Size
);
92 This function scan ACPI table in RSDT.
95 @param Signature ACPI table signature
102 IN EFI_ACPI_DESCRIPTION_HEADER
*Rsdt
,
109 EFI_ACPI_DESCRIPTION_HEADER
*Table
;
115 EntryCount
= (Rsdt
->Length
- sizeof (EFI_ACPI_DESCRIPTION_HEADER
)) / sizeof(UINT32
);
117 EntryPtr
= (UINT32
*)(Rsdt
+ 1);
118 for (Index
= 0; Index
< EntryCount
; Index
++, EntryPtr
++) {
119 Table
= (EFI_ACPI_DESCRIPTION_HEADER
*)((UINTN
)(*EntryPtr
));
120 if (Table
->Signature
== Signature
) {
130 This function scan ACPI table in XSDT.
132 @param Xsdt ACPI XSDT
133 @param Signature ACPI table signature
140 IN EFI_ACPI_DESCRIPTION_HEADER
*Xsdt
,
148 EFI_ACPI_DESCRIPTION_HEADER
*Table
;
154 EntryCount
= (Xsdt
->Length
- sizeof (EFI_ACPI_DESCRIPTION_HEADER
)) / sizeof(UINT64
);
156 BasePtr
= (UINTN
)(Xsdt
+ 1);
157 for (Index
= 0; Index
< EntryCount
; Index
++) {
158 CopyMem (&EntryPtr
, (VOID
*)(BasePtr
+ Index
* sizeof(UINT64
)), sizeof(UINT64
));
159 Table
= (EFI_ACPI_DESCRIPTION_HEADER
*)((UINTN
)(EntryPtr
));
160 if (Table
->Signature
== Signature
) {
169 To find Facs in FADT.
171 @param Fadt FADT table pointer
173 @return Facs table pointer.
175 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*
176 FindAcpiFacsFromFadt (
177 IN EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE
*Fadt
180 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
187 if (Fadt
->Header
.Revision
< EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE_REVISION
) {
188 Facs
= (EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*)(UINTN
)Fadt
->FirmwareCtrl
;
190 if (Fadt
->FirmwareCtrl
!= 0) {
191 Facs
= (EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*)(UINTN
)Fadt
->FirmwareCtrl
;
193 CopyMem (&Data64
, &Fadt
->XFirmwareCtrl
, sizeof(UINT64
));
194 Facs
= (EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*)(UINTN
)Data64
;
201 To find Facs in Acpi tables.
203 To find Firmware ACPI control strutcure in Acpi Tables since the S3 waking vector is stored
206 @param AcpiTableGuid The guid used to find ACPI table in UEFI ConfigurationTable.
208 @return Facs table pointer.
210 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*
211 FindAcpiFacsTableByAcpiGuid (
212 IN EFI_GUID
*AcpiTableGuid
215 EFI_ACPI_2_0_ROOT_SYSTEM_DESCRIPTION_POINTER
*Rsdp
;
216 EFI_ACPI_DESCRIPTION_HEADER
*Rsdt
;
217 EFI_ACPI_DESCRIPTION_HEADER
*Xsdt
;
218 EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE
*Fadt
;
219 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
224 // found ACPI table RSD_PTR from system table
226 for (Index
= 0; Index
< gST
->NumberOfTableEntries
; Index
++) {
227 if (CompareGuid (&(gST
->ConfigurationTable
[Index
].VendorGuid
), AcpiTableGuid
)) {
229 // A match was found.
231 Rsdp
= gST
->ConfigurationTable
[Index
].VendorTable
;
243 if (Rsdp
->Revision
>= EFI_ACPI_2_0_ROOT_SYSTEM_DESCRIPTION_POINTER_REVISION
) {
244 Xsdt
= (EFI_ACPI_DESCRIPTION_HEADER
*)(UINTN
) Rsdp
->XsdtAddress
;
245 Fadt
= ScanTableInXSDT (Xsdt
, EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE_SIGNATURE
);
247 Facs
= FindAcpiFacsFromFadt (Fadt
);
257 Rsdt
= (EFI_ACPI_DESCRIPTION_HEADER
*)(UINTN
) Rsdp
->RsdtAddress
;
258 Fadt
= ScanTableInRSDT (Rsdt
, EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE_SIGNATURE
);
260 Facs
= FindAcpiFacsFromFadt (Fadt
);
270 To find Facs in Acpi tables.
272 To find Firmware ACPI control strutcure in Acpi Tables since the S3 waking vector is stored
275 @return Facs table pointer.
277 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*
282 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
284 Facs
= FindAcpiFacsTableByAcpiGuid (&gEfiAcpi20TableGuid
);
289 return FindAcpiFacsTableByAcpiGuid (&gEfiAcpi10TableGuid
);
293 Allocates and fills in the Page Directory and Page Table Entries to
294 establish a 1:1 Virtual to Physical mapping.
295 If BootScriptExector driver will run in 64-bit mode, this function will establish the 1:1
296 virtual to physical mapping page table.
297 If BootScriptExector driver will not run in 64-bit mode, this function will do nothing.
299 @return the 1:1 Virtual to Physical identity mapping page table base address.
303 S3CreateIdentityMappingPageTables (
307 if (FeaturePcdGet (PcdDxeIplSwitchToLongMode
)) {
310 UINT8 PhysicalAddressBits
;
311 UINT32 NumberOfPml4EntriesNeeded
;
312 UINT32 NumberOfPdpEntriesNeeded
;
313 EFI_PHYSICAL_ADDRESS S3NvsPageTableAddress
;
314 UINTN TotalPageTableSize
;
316 BOOLEAN Page1GSupport
;
318 Page1GSupport
= FALSE
;
319 if (PcdGetBool(PcdUse1GPageTable
)) {
320 AsmCpuid (0x80000000, &RegEax
, NULL
, NULL
, NULL
);
321 if (RegEax
>= 0x80000001) {
322 AsmCpuid (0x80000001, NULL
, NULL
, NULL
, &RegEdx
);
323 if ((RegEdx
& BIT26
) != 0) {
324 Page1GSupport
= TRUE
;
330 // Get physical address bits supported.
332 Hob
= GetFirstHob (EFI_HOB_TYPE_CPU
);
334 PhysicalAddressBits
= ((EFI_HOB_CPU
*) Hob
)->SizeOfMemorySpace
;
336 AsmCpuid (0x80000000, &RegEax
, NULL
, NULL
, NULL
);
337 if (RegEax
>= 0x80000008) {
338 AsmCpuid (0x80000008, &RegEax
, NULL
, NULL
, NULL
);
339 PhysicalAddressBits
= (UINT8
) RegEax
;
341 PhysicalAddressBits
= 36;
346 // IA-32e paging translates 48-bit linear addresses to 52-bit physical addresses.
348 ASSERT (PhysicalAddressBits
<= 52);
349 if (PhysicalAddressBits
> 48) {
350 PhysicalAddressBits
= 48;
354 // Calculate the table entries needed.
356 if (PhysicalAddressBits
<= 39 ) {
357 NumberOfPml4EntriesNeeded
= 1;
358 NumberOfPdpEntriesNeeded
= (UINT32
)LShiftU64 (1, (PhysicalAddressBits
- 30));
360 NumberOfPml4EntriesNeeded
= (UINT32
)LShiftU64 (1, (PhysicalAddressBits
- 39));
361 NumberOfPdpEntriesNeeded
= 512;
365 // We need calculate whole page size then allocate once, because S3 restore page table does not know each page in Nvs.
367 if (!Page1GSupport
) {
368 TotalPageTableSize
= (UINTN
)(1 + NumberOfPml4EntriesNeeded
+ NumberOfPml4EntriesNeeded
* NumberOfPdpEntriesNeeded
);
370 TotalPageTableSize
= (UINTN
)(1 + NumberOfPml4EntriesNeeded
);
372 DEBUG ((EFI_D_ERROR
, "TotalPageTableSize - %x pages\n", TotalPageTableSize
));
375 // By architecture only one PageMapLevel4 exists - so lets allocate storage for it.
377 S3NvsPageTableAddress
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateMemoryBelow4G (EfiReservedMemoryType
, EFI_PAGES_TO_SIZE(TotalPageTableSize
));
378 ASSERT (S3NvsPageTableAddress
!= 0);
379 return S3NvsPageTableAddress
;
382 // If DXE is running 32-bit mode, no need to establish page table.
384 return (EFI_PHYSICAL_ADDRESS
) 0;
389 Gets the buffer of legacy memory below 1 MB
390 This function is to get the buffer in legacy memory below 1MB that is required during S3 resume.
392 @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.
393 @param Size The returned size of legacy memory below 1 MB.
395 @retval EFI_SUCCESS Size is successfully returned.
396 @retval EFI_INVALID_PARAMETER The pointer Size is NULL.
401 LegacyGetS3MemorySize (
402 IN EFI_ACPI_S3_SAVE_PROTOCOL
*This
,
409 return EFI_INVALID_PARAMETER
;
412 *Size
= mLegacyRegionSize
;
417 Save the S3 boot script.
419 Note that we trigger DxeSmmReadyToLock here -- otherwise the script wouldn't
420 be saved actually. Triggering this protocol installation event in turn locks
421 down SMM, so no further changes to LockBoxes or SMRAM are possible
432 EFI_S3_SAVE_STATE_PROTOCOL
*BootScript
;
434 STATIC CONST UINT8 Info
[] = { 0xDE, 0xAD, 0xBE, 0xEF };
436 Status
= gBS
->LocateProtocol (&gEfiS3SaveStateProtocolGuid
, NULL
,
437 (VOID
**) &BootScript
);
438 ASSERT_EFI_ERROR (Status
);
441 // Despite the opcode documentation in the PI spec, the protocol
442 // implementation embeds a deep copy of the info in the boot script, rather
443 // than storing just a pointer to runtime or NVS storage.
445 Status
= BootScript
->Write(BootScript
, EFI_BOOT_SCRIPT_INFORMATION_OPCODE
,
446 (UINT32
) sizeof Info
,
447 (EFI_PHYSICAL_ADDRESS
)(UINTN
) &Info
);
448 ASSERT_EFI_ERROR (Status
);
451 Status
= gBS
->InstallProtocolInterface (&Handle
,
452 &gEfiDxeSmmReadyToLockProtocolGuid
, EFI_NATIVE_INTERFACE
,
454 ASSERT_EFI_ERROR (Status
);
459 Prepares all information that is needed in the S3 resume boot path.
461 Allocate the resources or prepare informations and save in ACPI variable set for S3 resume boot path
463 @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.
464 @param LegacyMemoryAddress The base address of legacy memory.
466 @retval EFI_NOT_FOUND Some necessary information cannot be found.
467 @retval EFI_SUCCESS All information was saved successfully.
468 @retval EFI_OUT_OF_RESOURCES Resources were insufficient to save all the information.
469 @retval EFI_INVALID_PARAMETER The memory range is not located below 1 MB.
475 IN EFI_ACPI_S3_SAVE_PROTOCOL
*This
,
476 IN VOID
*LegacyMemoryAddress
480 EFI_PHYSICAL_ADDRESS AcpiS3ContextBuffer
;
481 ACPI_S3_CONTEXT
*AcpiS3Context
;
482 STATIC BOOLEAN AlreadyEntered
;
483 IA32_DESCRIPTOR
*Idtr
;
484 IA32_IDT_GATE_DESCRIPTOR
*IdtGate
;
486 DEBUG ((EFI_D_INFO
, "S3Ready!\n"));
489 // Platform may invoke AcpiS3Save->S3Save() before ExitPmAuth, because we need save S3 information there, while BDS ReadyToBoot may invoke it again.
490 // So if 2nd S3Save() is triggered later, we need ignore it.
492 if (AlreadyEntered
) {
495 AlreadyEntered
= TRUE
;
497 ASSERT (LegacyMemoryAddress
== NULL
);
499 AcpiS3Context
= AllocateMemoryBelow4G (EfiReservedMemoryType
, sizeof(*AcpiS3Context
));
500 ASSERT (AcpiS3Context
!= NULL
);
501 AcpiS3ContextBuffer
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AcpiS3Context
;
504 // Get ACPI Table because we will save its position to variable
506 AcpiS3Context
->AcpiFacsTable
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)FindAcpiFacsTable ();
507 ASSERT (AcpiS3Context
->AcpiFacsTable
!= 0);
509 IdtGate
= AllocateMemoryBelow4G (EfiReservedMemoryType
, sizeof(IA32_IDT_GATE_DESCRIPTOR
) * 0x100 + sizeof(IA32_DESCRIPTOR
));
510 Idtr
= (IA32_DESCRIPTOR
*)(IdtGate
+ 0x100);
511 Idtr
->Base
= (UINTN
)IdtGate
;
512 Idtr
->Limit
= (UINT16
)(sizeof(IA32_IDT_GATE_DESCRIPTOR
) * 0x100 - 1);
513 AcpiS3Context
->IdtrProfile
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)Idtr
;
515 Status
= SaveLockBox (
516 &mAcpiS3IdtrProfileGuid
,
518 (UINTN
)sizeof(IA32_DESCRIPTOR
)
520 ASSERT_EFI_ERROR (Status
);
522 Status
= SetLockBoxAttributes (&mAcpiS3IdtrProfileGuid
, LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE
);
523 ASSERT_EFI_ERROR (Status
);
526 // Allocate page table
528 AcpiS3Context
->S3NvsPageTableAddress
= S3CreateIdentityMappingPageTables ();
533 AcpiS3Context
->BootScriptStackSize
= PcdGet32 (PcdS3BootScriptStackSize
);
534 AcpiS3Context
->BootScriptStackBase
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateMemoryBelow4G (EfiReservedMemoryType
, PcdGet32 (PcdS3BootScriptStackSize
));
535 ASSERT (AcpiS3Context
->BootScriptStackBase
!= 0);
538 // Allocate a code buffer < 4G for S3 debug to load external code, set invalid code instructions in it.
540 AcpiS3Context
->S3DebugBufferAddress
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateMemoryBelow4G (EfiReservedMemoryType
, EFI_PAGE_SIZE
);
541 SetMem ((VOID
*)(UINTN
)AcpiS3Context
->S3DebugBufferAddress
, EFI_PAGE_SIZE
, 0xff);
543 DEBUG((EFI_D_INFO
, "AcpiS3Context: AcpiFacsTable is 0x%8x\n", AcpiS3Context
->AcpiFacsTable
));
544 DEBUG((EFI_D_INFO
, "AcpiS3Context: IdtrProfile is 0x%8x\n", AcpiS3Context
->IdtrProfile
));
545 DEBUG((EFI_D_INFO
, "AcpiS3Context: S3NvsPageTableAddress is 0x%8x\n", AcpiS3Context
->S3NvsPageTableAddress
));
546 DEBUG((EFI_D_INFO
, "AcpiS3Context: S3DebugBufferAddress is 0x%8x\n", AcpiS3Context
->S3DebugBufferAddress
));
548 Status
= SaveLockBox (
549 &gEfiAcpiVariableGuid
,
550 &AcpiS3ContextBuffer
,
551 sizeof(AcpiS3ContextBuffer
)
553 ASSERT_EFI_ERROR (Status
);
555 Status
= SaveLockBox (
556 &gEfiAcpiS3ContextGuid
,
557 (VOID
*)(UINTN
)AcpiS3Context
,
558 (UINTN
)sizeof(*AcpiS3Context
)
560 ASSERT_EFI_ERROR (Status
);
562 Status
= SetLockBoxAttributes (&gEfiAcpiS3ContextGuid
, LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE
);
563 ASSERT_EFI_ERROR (Status
);
566 // Save the boot script too. Note that this requires/includes emitting the
567 // DxeSmmReadyToLock event, which in turn locks down SMM.
574 The Driver Entry Point.
576 The function is the driver Entry point which will produce AcpiS3SaveProtocol.
578 @param ImageHandle A handle for the image that is initializing this driver
579 @param SystemTable A pointer to the EFI system table
581 @retval EFI_SUCCESS: Driver initialized successfully
582 @retval EFI_LOAD_ERROR: Failed to Initialize or has been loaded
583 @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources
589 IN EFI_HANDLE ImageHandle
,
590 IN EFI_SYSTEM_TABLE
*SystemTable
595 if (!QemuFwCfgS3Enabled()) {
596 return EFI_LOAD_ERROR
;
599 if (!FeaturePcdGet(PcdPlatformCsmSupport
)) {
601 // More memory for no CSM tip, because GDT need relocation
603 mLegacyRegionSize
= 0x250;
605 mLegacyRegionSize
= 0x100;
608 Status
= gBS
->InstallMultipleProtocolInterfaces (
610 &gEfiAcpiS3SaveProtocolGuid
, &mS3Save
,
611 &gEfiLockBoxProtocolGuid
, NULL
,
614 ASSERT_EFI_ERROR (Status
);