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 - 2012, 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 <IndustryStandard/Acpi.h>
33 #include "AcpiS3Save.h"
36 Hook point for AcpiVariableThunkPlatform for InstallAcpiS3Save.
39 InstallAcpiS3SaveThunk (
44 Hook point for AcpiVariableThunkPlatform for S3Ready.
46 @param AcpiS3Context ACPI s3 context
49 S3ReadyThunkPlatform (
50 IN ACPI_S3_CONTEXT
*AcpiS3Context
53 UINTN mLegacyRegionSize
;
55 EFI_ACPI_S3_SAVE_PROTOCOL mS3Save
= {
56 LegacyGetS3MemorySize
,
60 EFI_GUID mAcpiS3IdtrProfileGuid
= {
61 0xdea652b0, 0xd587, 0x4c54, { 0xb5, 0xb4, 0xc6, 0x82, 0xe7, 0xa0, 0xaa, 0x3d }
65 Allocate EfiACPIMemoryNVS below 4G memory address.
67 This function allocates EfiACPIMemoryNVS below 4G memory address.
69 @param Size Size of memory to allocate.
71 @return Allocated address for output.
75 AllocateAcpiNvsMemoryBelow4G (
80 EFI_PHYSICAL_ADDRESS Address
;
84 Pages
= EFI_SIZE_TO_PAGES (Size
);
87 Status
= gBS
->AllocatePages (
93 ASSERT_EFI_ERROR (Status
);
95 Buffer
= (VOID
*) (UINTN
) Address
;
96 ZeroMem (Buffer
, Size
);
102 To find Facs in Acpi tables.
104 To find Firmware ACPI control strutcure in Acpi Tables since the S3 waking vector is stored
107 @param AcpiTableGuid The guid used to find ACPI table in UEFI ConfigurationTable.
109 @return Facs table pointer.
111 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*
112 FindAcpiFacsTableByAcpiGuid (
113 IN EFI_GUID
*AcpiTableGuid
116 EFI_ACPI_2_0_ROOT_SYSTEM_DESCRIPTION_POINTER
*Rsdp
;
117 EFI_ACPI_DESCRIPTION_HEADER
*Rsdt
;
118 EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE
*Fadt
;
119 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
126 // found ACPI table RSD_PTR from system table
128 for (Index
= 0; Index
< gST
->NumberOfTableEntries
; Index
++) {
129 if (CompareGuid (&(gST
->ConfigurationTable
[Index
].VendorGuid
), AcpiTableGuid
)) {
131 // A match was found.
133 Rsdp
= gST
->ConfigurationTable
[Index
].VendorTable
;
142 Rsdt
= (EFI_ACPI_DESCRIPTION_HEADER
*)(UINTN
) Rsdp
->RsdtAddress
;
143 if (Rsdt
== NULL
|| Rsdt
->Signature
!= EFI_ACPI_2_0_ROOT_SYSTEM_DESCRIPTION_TABLE_SIGNATURE
) {
147 for (Index
= sizeof (EFI_ACPI_DESCRIPTION_HEADER
); Index
< Rsdt
->Length
; Index
= Index
+ sizeof (UINT32
)) {
149 Data32
= *(UINT32
*) ((UINT8
*) Rsdt
+ Index
);
150 Fadt
= (EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE
*) (UINT32
*) (UINTN
) Data32
;
151 if (Fadt
->Header
.Signature
== EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE_SIGNATURE
) {
156 if (Fadt
== NULL
|| Fadt
->Header
.Signature
!= EFI_ACPI_2_0_FIXED_ACPI_DESCRIPTION_TABLE_SIGNATURE
) {
160 Facs
= (EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*)(UINTN
)Fadt
->FirmwareCtrl
;
166 To find Facs in Acpi tables.
168 To find Firmware ACPI control strutcure in Acpi Tables since the S3 waking vector is stored
171 @return Facs table pointer.
173 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*
178 EFI_ACPI_2_0_FIRMWARE_ACPI_CONTROL_STRUCTURE
*Facs
;
180 Facs
= FindAcpiFacsTableByAcpiGuid (&gEfiAcpi20TableGuid
);
185 return FindAcpiFacsTableByAcpiGuid (&gEfiAcpi10TableGuid
);
189 Allocates and fills in the Page Directory and Page Table Entries to
190 establish a 1:1 Virtual to Physical mapping.
191 If BootScriptExector driver will run in 64-bit mode, this function will establish the 1:1
192 virtual to physical mapping page table.
193 If BootScriptExector driver will not run in 64-bit mode, this function will do nothing.
195 @return the 1:1 Virtual to Physical identity mapping page table base address.
199 S3CreateIdentityMappingPageTables (
203 if (FeaturePcdGet (PcdDxeIplSwitchToLongMode
)) {
206 UINT8 PhysicalAddressBits
;
207 EFI_PHYSICAL_ADDRESS PageAddress
;
208 UINTN IndexOfPml4Entries
;
209 UINTN IndexOfPdpEntries
;
210 UINTN IndexOfPageDirectoryEntries
;
211 UINT32 NumberOfPml4EntriesNeeded
;
212 UINT32 NumberOfPdpEntriesNeeded
;
213 PAGE_MAP_AND_DIRECTORY_POINTER
*PageMapLevel4Entry
;
214 PAGE_MAP_AND_DIRECTORY_POINTER
*PageMap
;
215 PAGE_MAP_AND_DIRECTORY_POINTER
*PageDirectoryPointerEntry
;
216 PAGE_TABLE_ENTRY
*PageDirectoryEntry
;
217 EFI_PHYSICAL_ADDRESS S3NvsPageTableAddress
;
218 UINTN TotalPageTableSize
;
220 BOOLEAN Page1GSupport
;
221 PAGE_TABLE_1G_ENTRY
*PageDirectory1GEntry
;
223 Page1GSupport
= FALSE
;
224 if (PcdGetBool(PcdUse1GPageTable
)) {
225 AsmCpuid (0x80000000, &RegEax
, NULL
, NULL
, NULL
);
226 if (RegEax
>= 0x80000001) {
227 AsmCpuid (0x80000001, NULL
, NULL
, NULL
, &RegEdx
);
228 if ((RegEdx
& BIT26
) != 0) {
229 Page1GSupport
= TRUE
;
235 // Get physical address bits supported.
237 Hob
= GetFirstHob (EFI_HOB_TYPE_CPU
);
239 PhysicalAddressBits
= ((EFI_HOB_CPU
*) Hob
)->SizeOfMemorySpace
;
241 AsmCpuid (0x80000000, &RegEax
, NULL
, NULL
, NULL
);
242 if (RegEax
>= 0x80000008) {
243 AsmCpuid (0x80000008, &RegEax
, NULL
, NULL
, NULL
);
244 PhysicalAddressBits
= (UINT8
) RegEax
;
246 PhysicalAddressBits
= 36;
251 // IA-32e paging translates 48-bit linear addresses to 52-bit physical addresses.
253 ASSERT (PhysicalAddressBits
<= 52);
254 if (PhysicalAddressBits
> 48) {
255 PhysicalAddressBits
= 48;
259 // Calculate the table entries needed.
261 if (PhysicalAddressBits
<= 39 ) {
262 NumberOfPml4EntriesNeeded
= 1;
263 NumberOfPdpEntriesNeeded
= (UINT32
)LShiftU64 (1, (PhysicalAddressBits
- 30));
265 NumberOfPml4EntriesNeeded
= (UINT32
)LShiftU64 (1, (PhysicalAddressBits
- 39));
266 NumberOfPdpEntriesNeeded
= 512;
270 // We need calculate whole page size then allocate once, because S3 restore page table does not know each page in Nvs.
272 if (!Page1GSupport
) {
273 TotalPageTableSize
= (UINTN
)(1 + NumberOfPml4EntriesNeeded
+ NumberOfPml4EntriesNeeded
* NumberOfPdpEntriesNeeded
);
275 TotalPageTableSize
= (UINTN
)(1 + NumberOfPml4EntriesNeeded
);
277 DEBUG ((EFI_D_ERROR
, "TotalPageTableSize - %x pages\n", TotalPageTableSize
));
280 // By architecture only one PageMapLevel4 exists - so lets allocate storgage for it.
282 S3NvsPageTableAddress
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateAcpiNvsMemoryBelow4G (EFI_PAGES_TO_SIZE(TotalPageTableSize
));
283 ASSERT (S3NvsPageTableAddress
!= 0);
284 PageMap
= (PAGE_MAP_AND_DIRECTORY_POINTER
*)(UINTN
)S3NvsPageTableAddress
;
285 S3NvsPageTableAddress
+= SIZE_4KB
;
287 PageMapLevel4Entry
= PageMap
;
289 for (IndexOfPml4Entries
= 0; IndexOfPml4Entries
< NumberOfPml4EntriesNeeded
; IndexOfPml4Entries
++, PageMapLevel4Entry
++) {
291 // Each PML4 entry points to a page of Page Directory Pointer entires.
292 // So lets allocate space for them and fill them in in the IndexOfPdpEntries loop.
294 PageDirectoryPointerEntry
= (PAGE_MAP_AND_DIRECTORY_POINTER
*)(UINTN
)S3NvsPageTableAddress
;
295 S3NvsPageTableAddress
+= SIZE_4KB
;
299 PageMapLevel4Entry
->Uint64
= (UINT64
)(UINTN
)PageDirectoryPointerEntry
;
300 PageMapLevel4Entry
->Bits
.ReadWrite
= 1;
301 PageMapLevel4Entry
->Bits
.Present
= 1;
304 PageDirectory1GEntry
= (PAGE_TABLE_1G_ENTRY
*)(UINTN
)PageDirectoryPointerEntry
;
306 for (IndexOfPageDirectoryEntries
= 0; IndexOfPageDirectoryEntries
< 512; IndexOfPageDirectoryEntries
++, PageDirectory1GEntry
++, PageAddress
+= SIZE_1GB
) {
308 // Fill in the Page Directory entries
310 PageDirectory1GEntry
->Uint64
= (UINT64
)PageAddress
;
311 PageDirectory1GEntry
->Bits
.ReadWrite
= 1;
312 PageDirectory1GEntry
->Bits
.Present
= 1;
313 PageDirectory1GEntry
->Bits
.MustBe1
= 1;
316 for (IndexOfPdpEntries
= 0; IndexOfPdpEntries
< NumberOfPdpEntriesNeeded
; IndexOfPdpEntries
++, PageDirectoryPointerEntry
++) {
318 // Each Directory Pointer entries points to a page of Page Directory entires.
319 // So allocate space for them and fill them in in the IndexOfPageDirectoryEntries loop.
321 PageDirectoryEntry
= (PAGE_TABLE_ENTRY
*)(UINTN
)S3NvsPageTableAddress
;
322 S3NvsPageTableAddress
+= SIZE_4KB
;
325 // Fill in a Page Directory Pointer Entries
327 PageDirectoryPointerEntry
->Uint64
= (UINT64
)(UINTN
)PageDirectoryEntry
;
328 PageDirectoryPointerEntry
->Bits
.ReadWrite
= 1;
329 PageDirectoryPointerEntry
->Bits
.Present
= 1;
331 for (IndexOfPageDirectoryEntries
= 0; IndexOfPageDirectoryEntries
< 512; IndexOfPageDirectoryEntries
++, PageDirectoryEntry
++, PageAddress
+= SIZE_2MB
) {
333 // Fill in the Page Directory entries
335 PageDirectoryEntry
->Uint64
= (UINT64
)PageAddress
;
336 PageDirectoryEntry
->Bits
.ReadWrite
= 1;
337 PageDirectoryEntry
->Bits
.Present
= 1;
338 PageDirectoryEntry
->Bits
.MustBe1
= 1;
343 return (EFI_PHYSICAL_ADDRESS
) (UINTN
) PageMap
;
346 // If DXE is running 32-bit mode, no need to establish page table.
348 return (EFI_PHYSICAL_ADDRESS
) 0;
353 Gets the buffer of legacy memory below 1 MB
354 This function is to get the buffer in legacy memory below 1MB that is required during S3 resume.
356 @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.
357 @param Size The returned size of legacy memory below 1 MB.
359 @retval EFI_SUCCESS Size is successfully returned.
360 @retval EFI_INVALID_PARAMETER The pointer Size is NULL.
365 LegacyGetS3MemorySize (
366 IN EFI_ACPI_S3_SAVE_PROTOCOL
*This
,
371 return EFI_INVALID_PARAMETER
;
374 *Size
= mLegacyRegionSize
;
379 Prepares all information that is needed in the S3 resume boot path.
381 Allocate the resources or prepare informations and save in ACPI variable set for S3 resume boot path
383 @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.
384 @param LegacyMemoryAddress The base address of legacy memory.
386 @retval EFI_NOT_FOUND Some necessary information cannot be found.
387 @retval EFI_SUCCESS All information was saved successfully.
388 @retval EFI_OUT_OF_RESOURCES Resources were insufficient to save all the information.
389 @retval EFI_INVALID_PARAMETER The memory range is not located below 1 MB.
395 IN EFI_ACPI_S3_SAVE_PROTOCOL
*This
,
396 IN VOID
*LegacyMemoryAddress
400 EFI_PHYSICAL_ADDRESS AcpiS3ContextBuffer
;
401 ACPI_S3_CONTEXT
*AcpiS3Context
;
402 STATIC BOOLEAN AlreadyEntered
;
403 IA32_DESCRIPTOR
*Idtr
;
404 IA32_IDT_GATE_DESCRIPTOR
*IdtGate
;
406 DEBUG ((EFI_D_INFO
, "S3Ready!\n"));
409 // Platform may invoke AcpiS3Save->S3Save() before ExitPmAuth, because we need save S3 information there, while BDS ReadyToBoot may invoke it again.
410 // So if 2nd S3Save() is triggered later, we need ignore it.
412 if (AlreadyEntered
) {
415 AlreadyEntered
= TRUE
;
417 AcpiS3Context
= AllocateAcpiNvsMemoryBelow4G (sizeof(*AcpiS3Context
));
418 ASSERT (AcpiS3Context
!= NULL
);
419 AcpiS3ContextBuffer
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AcpiS3Context
;
422 // Get ACPI Table because we will save its position to variable
424 AcpiS3Context
->AcpiFacsTable
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)FindAcpiFacsTable ();
425 ASSERT (AcpiS3Context
->AcpiFacsTable
!= 0);
427 IdtGate
= AllocateAcpiNvsMemoryBelow4G (sizeof(IA32_IDT_GATE_DESCRIPTOR
) * 0x100 + sizeof(IA32_DESCRIPTOR
));
428 Idtr
= (IA32_DESCRIPTOR
*)(IdtGate
+ 0x100);
429 Idtr
->Base
= (UINTN
)IdtGate
;
430 Idtr
->Limit
= (UINT16
)(sizeof(IA32_IDT_GATE_DESCRIPTOR
) * 0x100 - 1);
431 AcpiS3Context
->IdtrProfile
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)Idtr
;
433 Status
= SaveLockBox (
434 &mAcpiS3IdtrProfileGuid
,
436 (UINTN
)sizeof(IA32_DESCRIPTOR
)
438 ASSERT_EFI_ERROR (Status
);
440 Status
= SetLockBoxAttributes (&mAcpiS3IdtrProfileGuid
, LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE
);
441 ASSERT_EFI_ERROR (Status
);
444 // Allocate page table
446 AcpiS3Context
->S3NvsPageTableAddress
= S3CreateIdentityMappingPageTables ();
451 AcpiS3Context
->BootScriptStackSize
= PcdGet32 (PcdS3BootScriptStackSize
);
452 AcpiS3Context
->BootScriptStackBase
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateAcpiNvsMemoryBelow4G (PcdGet32 (PcdS3BootScriptStackSize
));
453 ASSERT (AcpiS3Context
->BootScriptStackBase
!= 0);
456 // Allocate a code buffer < 4G for S3 debug to load external code, set invalid code instructions in it.
458 AcpiS3Context
->S3DebugBufferAddress
= (EFI_PHYSICAL_ADDRESS
)(UINTN
)AllocateAcpiNvsMemoryBelow4G (EFI_PAGE_SIZE
);
459 SetMem ((VOID
*)(UINTN
)AcpiS3Context
->S3DebugBufferAddress
, EFI_PAGE_SIZE
, 0xff);
461 DEBUG((EFI_D_INFO
, "AcpiS3Context: AcpiFacsTable is 0x%8x\n", AcpiS3Context
->AcpiFacsTable
));
462 DEBUG((EFI_D_INFO
, "AcpiS3Context: IdtrProfile is 0x%8x\n", AcpiS3Context
->IdtrProfile
));
463 DEBUG((EFI_D_INFO
, "AcpiS3Context: S3NvsPageTableAddress is 0x%8x\n", AcpiS3Context
->S3NvsPageTableAddress
));
464 DEBUG((EFI_D_INFO
, "AcpiS3Context: S3DebugBufferAddress is 0x%8x\n", AcpiS3Context
->S3DebugBufferAddress
));
466 Status
= SaveLockBox (
467 &gEfiAcpiVariableGuid
,
468 &AcpiS3ContextBuffer
,
469 sizeof(AcpiS3ContextBuffer
)
471 ASSERT_EFI_ERROR (Status
);
473 Status
= SaveLockBox (
474 &gEfiAcpiS3ContextGuid
,
475 (VOID
*)(UINTN
)AcpiS3Context
,
476 (UINTN
)sizeof(*AcpiS3Context
)
478 ASSERT_EFI_ERROR (Status
);
480 Status
= SetLockBoxAttributes (&gEfiAcpiS3ContextGuid
, LOCK_BOX_ATTRIBUTE_RESTORE_IN_PLACE
);
481 ASSERT_EFI_ERROR (Status
);
483 if (FeaturePcdGet(PcdFrameworkCompatibilitySupport
)) {
484 S3ReadyThunkPlatform (AcpiS3Context
);
491 The Driver Entry Point.
493 The function is the driver Entry point which will produce AcpiS3SaveProtocol.
495 @param ImageHandle A handle for the image that is initializing this driver
496 @param SystemTable A pointer to the EFI system table
498 @retval EFI_SUCCESS: Driver initialized successfully
499 @retval EFI_LOAD_ERROR: Failed to Initialize or has been loaded
500 @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources
506 IN EFI_HANDLE ImageHandle
,
507 IN EFI_SYSTEM_TABLE
*SystemTable
512 if (!FeaturePcdGet(PcdPlatformCsmSupport
)) {
514 // More memory for no CSM tip, because GDT need relocation
516 mLegacyRegionSize
= 0x250;
518 mLegacyRegionSize
= 0x100;
521 if (FeaturePcdGet(PcdFrameworkCompatibilitySupport
)) {
522 InstallAcpiS3SaveThunk ();
525 Status
= gBS
->InstallProtocolInterface (
527 &gEfiAcpiS3SaveProtocolGuid
,
528 EFI_NATIVE_INTERFACE
,
531 ASSERT_EFI_ERROR (Status
);