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 <Guid/AcpiVariableCompatibility.h>
28 #include <Guid/AcpiS3Context.h>
29 #include <Guid/Acpi.h>
30 #include <Protocol/AcpiS3Save.h>
31 #include <Protocol/S3SaveState.h>
32 #include <Protocol/DxeSmmReadyToLock.h>
33 #include <IndustryStandard/Acpi.h>
35 #include "AcpiS3Save.h"
37 UINTN mLegacyRegionSize
;
39 EFI_ACPI_S3_SAVE_PROTOCOL mS3Save
= {
40 LegacyGetS3MemorySize
,
44 EFI_GUID mAcpiS3IdtrProfileGuid
= {
45 0xdea652b0, 0xd587, 0x4c54, { 0xb5, 0xb4, 0xc6, 0x82, 0xe7, 0xa0, 0xaa, 0x3d }
49 Allocate memory below 4G memory address.
51 This function allocates memory below 4G memory address.
53 @param MemoryType Memory type of memory to allocate.
54 @param Size Size of memory to allocate.
56 @return Allocated address for output.
60 AllocateMemoryBelow4G (
61 IN EFI_MEMORY_TYPE MemoryType
,
66 EFI_PHYSICAL_ADDRESS Address
;
70 Pages
= EFI_SIZE_TO_PAGES (Size
);
73 Status
= gBS
->AllocatePages (
79 ASSERT_EFI_ERROR (Status
);
81 Buffer
= (VOID
*) (UINTN
) Address
;
82 ZeroMem (Buffer
, Size
);
89 This function scan ACPI table in RSDT.
92 @param Signature ACPI table signature
99 IN EFI_ACPI_DESCRIPTION_HEADER
*Rsdt
,
106 EFI_ACPI_DESCRIPTION_HEADER
*Table
;
112 EntryCount
= (Rsdt
->Length
- sizeof (EFI_ACPI_DESCRIPTION_HEADER
)) / sizeof(UINT32
);
114 EntryPtr
= (UINT32
*)(Rsdt
+ 1);
115 for (Index
= 0; Index
< EntryCount
; Index
++, EntryPtr
++) {
116 Table
= (EFI_ACPI_DESCRIPTION_HEADER
*)((UINTN
)(*EntryPtr
));
117 if (Table
->Signature
== Signature
) {
127 This function scan ACPI table in XSDT.
129 @param Xsdt ACPI XSDT
130 @param Signature ACPI table signature
137 IN EFI_ACPI_DESCRIPTION_HEADER
*Xsdt
,
145 EFI_ACPI_DESCRIPTION_HEADER
*Table
;
151 EntryCount
= (Xsdt
->Length
- sizeof (EFI_ACPI_DESCRIPTION_HEADER
)) / sizeof(UINT64
);
153 BasePtr
= (UINTN
)(Xsdt
+ 1);
154 for (Index
= 0; Index
< EntryCount
; Index
++) {
155 CopyMem (&EntryPtr
, (VOID
*)(BasePtr
+ Index
* sizeof(UINT64
)), sizeof(UINT64
));
156 Table
= (EFI_ACPI_DESCRIPTION_HEADER
*)((UINTN
)(EntryPtr
));
157 if (Table
->Signature
== Signature
) {
166 To find Facs in FADT.
168 @param Fadt FADT table pointer
170 @return Facs table pointer.
172 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*
173 FindAcpiFacsFromFadt (
174 IN EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE
*Fadt
177 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
184 if (Fadt
->Header
.Revision
< EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE_REVISION
) {
185 Facs
= (EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*)(UINTN
)Fadt
->FirmwareCtrl
;
187 if (Fadt
->FirmwareCtrl
!= 0) {
188 Facs
= (EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*)(UINTN
)Fadt
->FirmwareCtrl
;
190 CopyMem (&Data64
, &Fadt
->XFirmwareCtrl
, sizeof(UINT64
));
191 Facs
= (EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*)(UINTN
)Data64
;
198 To find Facs in Acpi tables.
200 To find Firmware ACPI control strutcure in Acpi Tables since the S3 waking vector is stored
203 @param AcpiTableGuid The guid used to find ACPI table in UEFI ConfigurationTable.
205 @return Facs table pointer.
207 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*
208 FindAcpiFacsTableByAcpiGuid (
209 IN EFI_GUID
*AcpiTableGuid
212 EFI_ACPI_2_0_ROOT_SYSTEM_DESCRIPTION_POINTER
*Rsdp
;
213 EFI_ACPI_DESCRIPTION_HEADER
*Rsdt
;
214 EFI_ACPI_DESCRIPTION_HEADER
*Xsdt
;
215 EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE
*Fadt
;
216 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
221 // found ACPI table RSD_PTR from system table
223 for (Index
= 0; Index
< gST
->NumberOfTableEntries
; Index
++) {
224 if (CompareGuid (&(gST
->ConfigurationTable
[Index
].VendorGuid
), AcpiTableGuid
)) {
226 // A match was found.
228 Rsdp
= gST
->ConfigurationTable
[Index
].VendorTable
;
240 if (Rsdp
->Revision
>= EFI_ACPI_2_0_ROOT_SYSTEM_DESCRIPTION_POINTER_REVISION
) {
241 Xsdt
= (EFI_ACPI_DESCRIPTION_HEADER
*)(UINTN
) Rsdp
->XsdtAddress
;
242 Fadt
= ScanTableInXSDT (Xsdt
, EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE_SIGNATURE
);
244 Facs
= FindAcpiFacsFromFadt (Fadt
);
254 Rsdt
= (EFI_ACPI_DESCRIPTION_HEADER
*)(UINTN
) Rsdp
->RsdtAddress
;
255 Fadt
= ScanTableInRSDT (Rsdt
, EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE_SIGNATURE
);
257 Facs
= FindAcpiFacsFromFadt (Fadt
);
267 To find Facs in Acpi tables.
269 To find Firmware ACPI control strutcure in Acpi Tables since the S3 waking vector is stored
272 @return Facs table pointer.
274 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*
279 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
281 Facs
= FindAcpiFacsTableByAcpiGuid (&gEfiAcpi20TableGuid
);
286 return FindAcpiFacsTableByAcpiGuid (&gEfiAcpi10TableGuid
);
290 Allocates and fills in the Page Directory and Page Table Entries to
291 establish a 1:1 Virtual to Physical mapping.
292 If BootScriptExector driver will run in 64-bit mode, this function will establish the 1:1
293 virtual to physical mapping page table.
294 If BootScriptExector driver will not run in 64-bit mode, this function will do nothing.
296 @return the 1:1 Virtual to Physical identity mapping page table base address.
300 S3CreateIdentityMappingPageTables (
304 if (FeaturePcdGet (PcdDxeIplSwitchToLongMode
)) {
307 UINT8 PhysicalAddressBits
;
308 UINT32 NumberOfPml4EntriesNeeded
;
309 UINT32 NumberOfPdpEntriesNeeded
;
310 EFI_PHYSICAL_ADDRESS S3NvsPageTableAddress
;
311 UINTN TotalPageTableSize
;
313 BOOLEAN Page1GSupport
;
315 Page1GSupport
= FALSE
;
316 if (PcdGetBool(PcdUse1GPageTable
)) {
317 AsmCpuid (0x80000000, &RegEax
, NULL
, NULL
, NULL
);
318 if (RegEax
>= 0x80000001) {
319 AsmCpuid (0x80000001, NULL
, NULL
, NULL
, &RegEdx
);
320 if ((RegEdx
& BIT26
) != 0) {
321 Page1GSupport
= TRUE
;
327 // Get physical address bits supported.
329 Hob
= GetFirstHob (EFI_HOB_TYPE_CPU
);
331 PhysicalAddressBits
= ((EFI_HOB_CPU
*) Hob
)->SizeOfMemorySpace
;
333 AsmCpuid (0x80000000, &RegEax
, NULL
, NULL
, NULL
);
334 if (RegEax
>= 0x80000008) {
335 AsmCpuid (0x80000008, &RegEax
, NULL
, NULL
, NULL
);
336 PhysicalAddressBits
= (UINT8
) RegEax
;
338 PhysicalAddressBits
= 36;
343 // IA-32e paging translates 48-bit linear addresses to 52-bit physical addresses.
345 ASSERT (PhysicalAddressBits
<= 52);
346 if (PhysicalAddressBits
> 48) {
347 PhysicalAddressBits
= 48;
351 // Calculate the table entries needed.
353 if (PhysicalAddressBits
<= 39 ) {
354 NumberOfPml4EntriesNeeded
= 1;
355 NumberOfPdpEntriesNeeded
= (UINT32
)LShiftU64 (1, (PhysicalAddressBits
- 30));
357 NumberOfPml4EntriesNeeded
= (UINT32
)LShiftU64 (1, (PhysicalAddressBits
- 39));
358 NumberOfPdpEntriesNeeded
= 512;
362 // We need calculate whole page size then allocate once, because S3 restore page table does not know each page in Nvs.
364 if (!Page1GSupport
) {
365 TotalPageTableSize
= (UINTN
)(1 + NumberOfPml4EntriesNeeded
+ NumberOfPml4EntriesNeeded
* NumberOfPdpEntriesNeeded
);
367 TotalPageTableSize
= (UINTN
)(1 + NumberOfPml4EntriesNeeded
);
369 DEBUG ((EFI_D_ERROR
, "TotalPageTableSize - %x pages\n", TotalPageTableSize
));
372 // By architecture only one PageMapLevel4 exists - so lets allocate storage for it.
374 S3NvsPageTableAddress
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateMemoryBelow4G (EfiReservedMemoryType
, EFI_PAGES_TO_SIZE(TotalPageTableSize
));
375 ASSERT (S3NvsPageTableAddress
!= 0);
376 return S3NvsPageTableAddress
;
379 // If DXE is running 32-bit mode, no need to establish page table.
381 return (EFI_PHYSICAL_ADDRESS
) 0;
386 Gets the buffer of legacy memory below 1 MB
387 This function is to get the buffer in legacy memory below 1MB that is required during S3 resume.
389 @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.
390 @param Size The returned size of legacy memory below 1 MB.
392 @retval EFI_SUCCESS Size is successfully returned.
393 @retval EFI_INVALID_PARAMETER The pointer Size is NULL.
398 LegacyGetS3MemorySize (
399 IN EFI_ACPI_S3_SAVE_PROTOCOL
*This
,
404 return EFI_INVALID_PARAMETER
;
407 *Size
= mLegacyRegionSize
;
412 Save the S3 boot script.
414 Note that we trigger DxeSmmReadyToLock here -- otherwise the script wouldn't
415 be saved actually. Triggering this protocol installation event in turn locks
416 down SMM, so no further changes to LockBoxes or SMRAM are possible
427 EFI_S3_SAVE_STATE_PROTOCOL
*BootScript
;
429 STATIC CONST UINT8 Info
[] = { 0xDE, 0xAD, 0xBE, 0xEF };
431 Status
= gBS
->LocateProtocol (&gEfiS3SaveStateProtocolGuid
, NULL
,
432 (VOID
**) &BootScript
);
433 ASSERT_EFI_ERROR (Status
);
436 // Despite the opcode documentation in the PI spec, the protocol
437 // implementation embeds a deep copy of the info in the boot script, rather
438 // than storing just a pointer to runtime or NVS storage.
440 Status
= BootScript
->Write(BootScript
, EFI_BOOT_SCRIPT_INFORMATION_OPCODE
,
441 (UINT32
) sizeof Info
,
442 (EFI_PHYSICAL_ADDRESS
)(UINTN
) &Info
);
443 ASSERT_EFI_ERROR (Status
);
446 Status
= gBS
->InstallProtocolInterface (&Handle
,
447 &gEfiDxeSmmReadyToLockProtocolGuid
, EFI_NATIVE_INTERFACE
,
449 ASSERT_EFI_ERROR (Status
);
454 Prepares all information that is needed in the S3 resume boot path.
456 Allocate the resources or prepare informations and save in ACPI variable set for S3 resume boot path
458 @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.
459 @param LegacyMemoryAddress The base address of legacy memory.
461 @retval EFI_NOT_FOUND Some necessary information cannot be found.
462 @retval EFI_SUCCESS All information was saved successfully.
463 @retval EFI_OUT_OF_RESOURCES Resources were insufficient to save all the information.
464 @retval EFI_INVALID_PARAMETER The memory range is not located below 1 MB.
470 IN EFI_ACPI_S3_SAVE_PROTOCOL
*This
,
471 IN VOID
*LegacyMemoryAddress
475 EFI_PHYSICAL_ADDRESS AcpiS3ContextBuffer
;
476 ACPI_S3_CONTEXT
*AcpiS3Context
;
477 STATIC BOOLEAN AlreadyEntered
;
478 IA32_DESCRIPTOR
*Idtr
;
479 IA32_IDT_GATE_DESCRIPTOR
*IdtGate
;
481 DEBUG ((EFI_D_INFO
, "S3Ready!\n"));
484 // Platform may invoke AcpiS3Save->S3Save() before ExitPmAuth, because we need save S3 information there, while BDS ReadyToBoot may invoke it again.
485 // So if 2nd S3Save() is triggered later, we need ignore it.
487 if (AlreadyEntered
) {
490 AlreadyEntered
= TRUE
;
492 AcpiS3Context
= AllocateMemoryBelow4G (EfiReservedMemoryType
, sizeof(*AcpiS3Context
));
493 ASSERT (AcpiS3Context
!= NULL
);
494 AcpiS3ContextBuffer
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AcpiS3Context
;
497 // Get ACPI Table because we will save its position to variable
499 AcpiS3Context
->AcpiFacsTable
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)FindAcpiFacsTable ();
500 ASSERT (AcpiS3Context
->AcpiFacsTable
!= 0);
502 IdtGate
= AllocateMemoryBelow4G (EfiReservedMemoryType
, sizeof(IA32_IDT_GATE_DESCRIPTOR
) * 0x100 + sizeof(IA32_DESCRIPTOR
));
503 Idtr
= (IA32_DESCRIPTOR
*)(IdtGate
+ 0x100);
504 Idtr
->Base
= (UINTN
)IdtGate
;
505 Idtr
->Limit
= (UINT16
)(sizeof(IA32_IDT_GATE_DESCRIPTOR
) * 0x100 - 1);
506 AcpiS3Context
->IdtrProfile
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)Idtr
;
508 Status
= SaveLockBox (
509 &mAcpiS3IdtrProfileGuid
,
511 (UINTN
)sizeof(IA32_DESCRIPTOR
)
513 ASSERT_EFI_ERROR (Status
);
515 Status
= SetLockBoxAttributes (&mAcpiS3IdtrProfileGuid
, LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE
);
516 ASSERT_EFI_ERROR (Status
);
519 // Allocate page table
521 AcpiS3Context
->S3NvsPageTableAddress
= S3CreateIdentityMappingPageTables ();
526 AcpiS3Context
->BootScriptStackSize
= PcdGet32 (PcdS3BootScriptStackSize
);
527 AcpiS3Context
->BootScriptStackBase
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateMemoryBelow4G (EfiReservedMemoryType
, PcdGet32 (PcdS3BootScriptStackSize
));
528 ASSERT (AcpiS3Context
->BootScriptStackBase
!= 0);
531 // Allocate a code buffer < 4G for S3 debug to load external code, set invalid code instructions in it.
533 AcpiS3Context
->S3DebugBufferAddress
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateMemoryBelow4G (EfiReservedMemoryType
, EFI_PAGE_SIZE
);
534 SetMem ((VOID
*)(UINTN
)AcpiS3Context
->S3DebugBufferAddress
, EFI_PAGE_SIZE
, 0xff);
536 DEBUG((EFI_D_INFO
, "AcpiS3Context: AcpiFacsTable is 0x%8x\n", AcpiS3Context
->AcpiFacsTable
));
537 DEBUG((EFI_D_INFO
, "AcpiS3Context: IdtrProfile is 0x%8x\n", AcpiS3Context
->IdtrProfile
));
538 DEBUG((EFI_D_INFO
, "AcpiS3Context: S3NvsPageTableAddress is 0x%8x\n", AcpiS3Context
->S3NvsPageTableAddress
));
539 DEBUG((EFI_D_INFO
, "AcpiS3Context: S3DebugBufferAddress is 0x%8x\n", AcpiS3Context
->S3DebugBufferAddress
));
541 Status
= SaveLockBox (
542 &gEfiAcpiVariableGuid
,
543 &AcpiS3ContextBuffer
,
544 sizeof(AcpiS3ContextBuffer
)
546 ASSERT_EFI_ERROR (Status
);
548 Status
= SaveLockBox (
549 &gEfiAcpiS3ContextGuid
,
550 (VOID
*)(UINTN
)AcpiS3Context
,
551 (UINTN
)sizeof(*AcpiS3Context
)
553 ASSERT_EFI_ERROR (Status
);
555 Status
= SetLockBoxAttributes (&gEfiAcpiS3ContextGuid
, LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE
);
556 ASSERT_EFI_ERROR (Status
);
559 // Save the boot script too. Note that this requires/includes emitting the
560 // DxeSmmReadyToLock event, which in turn locks down SMM.
567 The Driver Entry Point.
569 The function is the driver Entry point which will produce AcpiS3SaveProtocol.
571 @param ImageHandle A handle for the image that is initializing this driver
572 @param SystemTable A pointer to the EFI system table
574 @retval EFI_SUCCESS: Driver initialized successfully
575 @retval EFI_LOAD_ERROR: Failed to Initialize or has been loaded
576 @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources
582 IN EFI_HANDLE ImageHandle
,
583 IN EFI_SYSTEM_TABLE
*SystemTable
588 if (!FeaturePcdGet(PcdPlatformCsmSupport
)) {
590 // More memory for no CSM tip, because GDT need relocation
592 mLegacyRegionSize
= 0x250;
594 mLegacyRegionSize
= 0x100;
597 Status
= gBS
->InstallProtocolInterface (
599 &gEfiAcpiS3SaveProtocolGuid
,
600 EFI_NATIVE_INTERFACE
,
603 ASSERT_EFI_ERROR (Status
);