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) 2006 - 2013, Intel Corporation. All rights reserved.<BR>
7 This program and the accompanying materials
8 are licensed and made available under the terms and conditions
9 of the BSD License which accompanies this distribution. The
10 full text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19 #include <Library/BaseLib.h>
20 #include <Library/BaseMemoryLib.h>
21 #include <Library/UefiBootServicesTableLib.h>
22 #include <Library/UefiRuntimeServicesTableLib.h>
23 #include <Library/HobLib.h>
24 #include <Library/LockBoxLib.h>
25 #include <Library/PcdLib.h>
26 #include <Library/DebugLib.h>
27 #include <Library/QemuFwCfgLib.h>
28 #include <Guid/AcpiVariableCompatibility.h>
29 #include <Guid/AcpiS3Context.h>
30 #include <Guid/Acpi.h>
31 #include <Protocol/AcpiS3Save.h>
32 #include <Protocol/S3SaveState.h>
33 #include <Protocol/DxeSmmReadyToLock.h>
34 #include <Protocol/LockBox.h>
35 #include <IndustryStandard/Acpi.h>
37 #include "AcpiS3Save.h"
39 UINTN mLegacyRegionSize
;
41 EFI_ACPI_S3_SAVE_PROTOCOL mS3Save
= {
42 LegacyGetS3MemorySize
,
46 EFI_GUID mAcpiS3IdtrProfileGuid
= {
47 0xdea652b0, 0xd587, 0x4c54, { 0xb5, 0xb4, 0xc6, 0x82, 0xe7, 0xa0, 0xaa, 0x3d }
51 Allocate memory below 4G memory address.
53 This function allocates memory below 4G memory address.
55 @param MemoryType Memory type of memory to allocate.
56 @param Size Size of memory to allocate.
58 @return Allocated address for output.
62 AllocateMemoryBelow4G (
63 IN EFI_MEMORY_TYPE MemoryType
,
68 EFI_PHYSICAL_ADDRESS Address
;
72 Pages
= EFI_SIZE_TO_PAGES (Size
);
75 Status
= gBS
->AllocatePages (
81 ASSERT_EFI_ERROR (Status
);
83 Buffer
= (VOID
*) (UINTN
) Address
;
84 ZeroMem (Buffer
, Size
);
91 This function scan ACPI table in RSDT.
94 @param Signature ACPI table signature
101 IN EFI_ACPI_DESCRIPTION_HEADER
*Rsdt
,
108 EFI_ACPI_DESCRIPTION_HEADER
*Table
;
114 EntryCount
= (Rsdt
->Length
- sizeof (EFI_ACPI_DESCRIPTION_HEADER
)) / sizeof(UINT32
);
116 EntryPtr
= (UINT32
*)(Rsdt
+ 1);
117 for (Index
= 0; Index
< EntryCount
; Index
++, EntryPtr
++) {
118 Table
= (EFI_ACPI_DESCRIPTION_HEADER
*)((UINTN
)(*EntryPtr
));
119 if (Table
->Signature
== Signature
) {
129 This function scan ACPI table in XSDT.
131 @param Xsdt ACPI XSDT
132 @param Signature ACPI table signature
139 IN EFI_ACPI_DESCRIPTION_HEADER
*Xsdt
,
147 EFI_ACPI_DESCRIPTION_HEADER
*Table
;
153 EntryCount
= (Xsdt
->Length
- sizeof (EFI_ACPI_DESCRIPTION_HEADER
)) / sizeof(UINT64
);
155 BasePtr
= (UINTN
)(Xsdt
+ 1);
156 for (Index
= 0; Index
< EntryCount
; Index
++) {
157 CopyMem (&EntryPtr
, (VOID
*)(BasePtr
+ Index
* sizeof(UINT64
)), sizeof(UINT64
));
158 Table
= (EFI_ACPI_DESCRIPTION_HEADER
*)((UINTN
)(EntryPtr
));
159 if (Table
->Signature
== Signature
) {
168 To find Facs in FADT.
170 @param Fadt FADT table pointer
172 @return Facs table pointer.
174 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*
175 FindAcpiFacsFromFadt (
176 IN EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE
*Fadt
179 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
186 if (Fadt
->Header
.Revision
< EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE_REVISION
) {
187 Facs
= (EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*)(UINTN
)Fadt
->FirmwareCtrl
;
189 if (Fadt
->FirmwareCtrl
!= 0) {
190 Facs
= (EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*)(UINTN
)Fadt
->FirmwareCtrl
;
192 CopyMem (&Data64
, &Fadt
->XFirmwareCtrl
, sizeof(UINT64
));
193 Facs
= (EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*)(UINTN
)Data64
;
200 To find Facs in Acpi tables.
202 To find Firmware ACPI control strutcure in Acpi Tables since the S3 waking vector is stored
205 @param AcpiTableGuid The guid used to find ACPI table in UEFI ConfigurationTable.
207 @return Facs table pointer.
209 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*
210 FindAcpiFacsTableByAcpiGuid (
211 IN EFI_GUID
*AcpiTableGuid
214 EFI_ACPI_2_0_ROOT_SYSTEM_DESCRIPTION_POINTER
*Rsdp
;
215 EFI_ACPI_DESCRIPTION_HEADER
*Rsdt
;
216 EFI_ACPI_DESCRIPTION_HEADER
*Xsdt
;
217 EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE
*Fadt
;
218 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
223 // found ACPI table RSD_PTR from system table
225 for (Index
= 0; Index
< gST
->NumberOfTableEntries
; Index
++) {
226 if (CompareGuid (&(gST
->ConfigurationTable
[Index
].VendorGuid
), AcpiTableGuid
)) {
228 // A match was found.
230 Rsdp
= gST
->ConfigurationTable
[Index
].VendorTable
;
242 if (Rsdp
->Revision
>= EFI_ACPI_2_0_ROOT_SYSTEM_DESCRIPTION_POINTER_REVISION
) {
243 Xsdt
= (EFI_ACPI_DESCRIPTION_HEADER
*)(UINTN
) Rsdp
->XsdtAddress
;
244 Fadt
= ScanTableInXSDT (Xsdt
, EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE_SIGNATURE
);
246 Facs
= FindAcpiFacsFromFadt (Fadt
);
256 Rsdt
= (EFI_ACPI_DESCRIPTION_HEADER
*)(UINTN
) Rsdp
->RsdtAddress
;
257 Fadt
= ScanTableInRSDT (Rsdt
, EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE_SIGNATURE
);
259 Facs
= FindAcpiFacsFromFadt (Fadt
);
269 To find Facs in Acpi tables.
271 To find Firmware ACPI control strutcure in Acpi Tables since the S3 waking vector is stored
274 @return Facs table pointer.
276 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*
281 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
283 Facs
= FindAcpiFacsTableByAcpiGuid (&gEfiAcpi20TableGuid
);
288 return FindAcpiFacsTableByAcpiGuid (&gEfiAcpi10TableGuid
);
292 Allocates and fills in the Page Directory and Page Table Entries to
293 establish a 1:1 Virtual to Physical mapping.
294 If BootScriptExector driver will run in 64-bit mode, this function will establish the 1:1
295 virtual to physical mapping page table.
296 If BootScriptExector driver will not run in 64-bit mode, this function will do nothing.
298 @return the 1:1 Virtual to Physical identity mapping page table base address.
302 S3CreateIdentityMappingPageTables (
306 if (FeaturePcdGet (PcdDxeIplSwitchToLongMode
)) {
309 UINT8 PhysicalAddressBits
;
310 UINT32 NumberOfPml4EntriesNeeded
;
311 UINT32 NumberOfPdpEntriesNeeded
;
312 EFI_PHYSICAL_ADDRESS S3NvsPageTableAddress
;
313 UINTN TotalPageTableSize
;
315 BOOLEAN Page1GSupport
;
317 Page1GSupport
= FALSE
;
318 if (PcdGetBool(PcdUse1GPageTable
)) {
319 AsmCpuid (0x80000000, &RegEax
, NULL
, NULL
, NULL
);
320 if (RegEax
>= 0x80000001) {
321 AsmCpuid (0x80000001, NULL
, NULL
, NULL
, &RegEdx
);
322 if ((RegEdx
& BIT26
) != 0) {
323 Page1GSupport
= TRUE
;
329 // Get physical address bits supported.
331 Hob
= GetFirstHob (EFI_HOB_TYPE_CPU
);
333 PhysicalAddressBits
= ((EFI_HOB_CPU
*) Hob
)->SizeOfMemorySpace
;
335 AsmCpuid (0x80000000, &RegEax
, NULL
, NULL
, NULL
);
336 if (RegEax
>= 0x80000008) {
337 AsmCpuid (0x80000008, &RegEax
, NULL
, NULL
, NULL
);
338 PhysicalAddressBits
= (UINT8
) RegEax
;
340 PhysicalAddressBits
= 36;
345 // IA-32e paging translates 48-bit linear addresses to 52-bit physical addresses.
347 ASSERT (PhysicalAddressBits
<= 52);
348 if (PhysicalAddressBits
> 48) {
349 PhysicalAddressBits
= 48;
353 // Calculate the table entries needed.
355 if (PhysicalAddressBits
<= 39 ) {
356 NumberOfPml4EntriesNeeded
= 1;
357 NumberOfPdpEntriesNeeded
= (UINT32
)LShiftU64 (1, (PhysicalAddressBits
- 30));
359 NumberOfPml4EntriesNeeded
= (UINT32
)LShiftU64 (1, (PhysicalAddressBits
- 39));
360 NumberOfPdpEntriesNeeded
= 512;
364 // We need calculate whole page size then allocate once, because S3 restore page table does not know each page in Nvs.
366 if (!Page1GSupport
) {
367 TotalPageTableSize
= (UINTN
)(1 + NumberOfPml4EntriesNeeded
+ NumberOfPml4EntriesNeeded
* NumberOfPdpEntriesNeeded
);
369 TotalPageTableSize
= (UINTN
)(1 + NumberOfPml4EntriesNeeded
);
371 DEBUG ((EFI_D_ERROR
, "TotalPageTableSize - %x pages\n", TotalPageTableSize
));
374 // By architecture only one PageMapLevel4 exists - so lets allocate storage for it.
376 S3NvsPageTableAddress
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateMemoryBelow4G (EfiReservedMemoryType
, EFI_PAGES_TO_SIZE(TotalPageTableSize
));
377 ASSERT (S3NvsPageTableAddress
!= 0);
378 return S3NvsPageTableAddress
;
381 // If DXE is running 32-bit mode, no need to establish page table.
383 return (EFI_PHYSICAL_ADDRESS
) 0;
388 Gets the buffer of legacy memory below 1 MB
389 This function is to get the buffer in legacy memory below 1MB that is required during S3 resume.
391 @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.
392 @param Size The returned size of legacy memory below 1 MB.
394 @retval EFI_SUCCESS Size is successfully returned.
395 @retval EFI_INVALID_PARAMETER The pointer Size is NULL.
400 LegacyGetS3MemorySize (
401 IN EFI_ACPI_S3_SAVE_PROTOCOL
*This
,
406 return EFI_INVALID_PARAMETER
;
409 *Size
= mLegacyRegionSize
;
414 Save the S3 boot script.
416 Note that we trigger DxeSmmReadyToLock here -- otherwise the script wouldn't
417 be saved actually. Triggering this protocol installation event in turn locks
418 down SMM, so no further changes to LockBoxes or SMRAM are possible
429 EFI_S3_SAVE_STATE_PROTOCOL
*BootScript
;
431 STATIC CONST UINT8 Info
[] = { 0xDE, 0xAD, 0xBE, 0xEF };
433 Status
= gBS
->LocateProtocol (&gEfiS3SaveStateProtocolGuid
, NULL
,
434 (VOID
**) &BootScript
);
435 ASSERT_EFI_ERROR (Status
);
438 // Despite the opcode documentation in the PI spec, the protocol
439 // implementation embeds a deep copy of the info in the boot script, rather
440 // than storing just a pointer to runtime or NVS storage.
442 Status
= BootScript
->Write(BootScript
, EFI_BOOT_SCRIPT_INFORMATION_OPCODE
,
443 (UINT32
) sizeof Info
,
444 (EFI_PHYSICAL_ADDRESS
)(UINTN
) &Info
);
445 ASSERT_EFI_ERROR (Status
);
448 Status
= gBS
->InstallProtocolInterface (&Handle
,
449 &gEfiDxeSmmReadyToLockProtocolGuid
, EFI_NATIVE_INTERFACE
,
451 ASSERT_EFI_ERROR (Status
);
456 Prepares all information that is needed in the S3 resume boot path.
458 Allocate the resources or prepare informations and save in ACPI variable set for S3 resume boot path
460 @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.
461 @param LegacyMemoryAddress The base address of legacy memory.
463 @retval EFI_NOT_FOUND Some necessary information cannot be found.
464 @retval EFI_SUCCESS All information was saved successfully.
465 @retval EFI_OUT_OF_RESOURCES Resources were insufficient to save all the information.
466 @retval EFI_INVALID_PARAMETER The memory range is not located below 1 MB.
472 IN EFI_ACPI_S3_SAVE_PROTOCOL
*This
,
473 IN VOID
*LegacyMemoryAddress
477 EFI_PHYSICAL_ADDRESS AcpiS3ContextBuffer
;
478 ACPI_S3_CONTEXT
*AcpiS3Context
;
479 STATIC BOOLEAN AlreadyEntered
;
480 IA32_DESCRIPTOR
*Idtr
;
481 IA32_IDT_GATE_DESCRIPTOR
*IdtGate
;
483 DEBUG ((EFI_D_INFO
, "S3Ready!\n"));
486 // Platform may invoke AcpiS3Save->S3Save() before ExitPmAuth, because we need save S3 information there, while BDS ReadyToBoot may invoke it again.
487 // So if 2nd S3Save() is triggered later, we need ignore it.
489 if (AlreadyEntered
) {
492 AlreadyEntered
= TRUE
;
494 AcpiS3Context
= AllocateMemoryBelow4G (EfiReservedMemoryType
, sizeof(*AcpiS3Context
));
495 ASSERT (AcpiS3Context
!= NULL
);
496 AcpiS3ContextBuffer
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AcpiS3Context
;
499 // Get ACPI Table because we will save its position to variable
501 AcpiS3Context
->AcpiFacsTable
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)FindAcpiFacsTable ();
502 ASSERT (AcpiS3Context
->AcpiFacsTable
!= 0);
504 IdtGate
= AllocateMemoryBelow4G (EfiReservedMemoryType
, sizeof(IA32_IDT_GATE_DESCRIPTOR
) * 0x100 + sizeof(IA32_DESCRIPTOR
));
505 Idtr
= (IA32_DESCRIPTOR
*)(IdtGate
+ 0x100);
506 Idtr
->Base
= (UINTN
)IdtGate
;
507 Idtr
->Limit
= (UINT16
)(sizeof(IA32_IDT_GATE_DESCRIPTOR
) * 0x100 - 1);
508 AcpiS3Context
->IdtrProfile
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)Idtr
;
510 Status
= SaveLockBox (
511 &mAcpiS3IdtrProfileGuid
,
513 (UINTN
)sizeof(IA32_DESCRIPTOR
)
515 ASSERT_EFI_ERROR (Status
);
517 Status
= SetLockBoxAttributes (&mAcpiS3IdtrProfileGuid
, LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE
);
518 ASSERT_EFI_ERROR (Status
);
521 // Allocate page table
523 AcpiS3Context
->S3NvsPageTableAddress
= S3CreateIdentityMappingPageTables ();
528 AcpiS3Context
->BootScriptStackSize
= PcdGet32 (PcdS3BootScriptStackSize
);
529 AcpiS3Context
->BootScriptStackBase
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateMemoryBelow4G (EfiReservedMemoryType
, PcdGet32 (PcdS3BootScriptStackSize
));
530 ASSERT (AcpiS3Context
->BootScriptStackBase
!= 0);
533 // Allocate a code buffer < 4G for S3 debug to load external code, set invalid code instructions in it.
535 AcpiS3Context
->S3DebugBufferAddress
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateMemoryBelow4G (EfiReservedMemoryType
, EFI_PAGE_SIZE
);
536 SetMem ((VOID
*)(UINTN
)AcpiS3Context
->S3DebugBufferAddress
, EFI_PAGE_SIZE
, 0xff);
538 DEBUG((EFI_D_INFO
, "AcpiS3Context: AcpiFacsTable is 0x%8x\n", AcpiS3Context
->AcpiFacsTable
));
539 DEBUG((EFI_D_INFO
, "AcpiS3Context: IdtrProfile is 0x%8x\n", AcpiS3Context
->IdtrProfile
));
540 DEBUG((EFI_D_INFO
, "AcpiS3Context: S3NvsPageTableAddress is 0x%8x\n", AcpiS3Context
->S3NvsPageTableAddress
));
541 DEBUG((EFI_D_INFO
, "AcpiS3Context: S3DebugBufferAddress is 0x%8x\n", AcpiS3Context
->S3DebugBufferAddress
));
543 Status
= SaveLockBox (
544 &gEfiAcpiVariableGuid
,
545 &AcpiS3ContextBuffer
,
546 sizeof(AcpiS3ContextBuffer
)
548 ASSERT_EFI_ERROR (Status
);
550 Status
= SaveLockBox (
551 &gEfiAcpiS3ContextGuid
,
552 (VOID
*)(UINTN
)AcpiS3Context
,
553 (UINTN
)sizeof(*AcpiS3Context
)
555 ASSERT_EFI_ERROR (Status
);
557 Status
= SetLockBoxAttributes (&gEfiAcpiS3ContextGuid
, LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE
);
558 ASSERT_EFI_ERROR (Status
);
561 // Save the boot script too. Note that this requires/includes emitting the
562 // DxeSmmReadyToLock event, which in turn locks down SMM.
569 The Driver Entry Point.
571 The function is the driver Entry point which will produce AcpiS3SaveProtocol.
573 @param ImageHandle A handle for the image that is initializing this driver
574 @param SystemTable A pointer to the EFI system table
576 @retval EFI_SUCCESS: Driver initialized successfully
577 @retval EFI_LOAD_ERROR: Failed to Initialize or has been loaded
578 @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources
584 IN EFI_HANDLE ImageHandle
,
585 IN EFI_SYSTEM_TABLE
*SystemTable
590 if (!QemuFwCfgS3Enabled()) {
591 return EFI_LOAD_ERROR
;
594 if (!FeaturePcdGet(PcdPlatformCsmSupport
)) {
596 // More memory for no CSM tip, because GDT need relocation
598 mLegacyRegionSize
= 0x250;
600 mLegacyRegionSize
= 0x100;
603 Status
= gBS
->InstallMultipleProtocolInterfaces (
605 &gEfiAcpiS3SaveProtocolGuid
, &mS3Save
,
606 &gEfiLockBoxProtocolGuid
, NULL
,
609 ASSERT_EFI_ERROR (Status
);