/** @file\r
This protocol is used to prepare all information that is needed for the S3 resume boot path. This\r
protocol is not required for all platforms.\r
- This protocol is defined in framework S3Resume v0.9, page 21.\r
\r
-Copyright (c) 2006, Intel Corporation\r
-All rights reserved. This program and the accompanying materials\r
-are licensed and made available under the terms and conditions of the BSD License\r
-which accompanies this distribution. The full text of the license may be found at\r
-http://opensource.org/licenses/bsd-license.php\r
+ Copyright (c) 2006 - 2009, Intel Corporation\r
+ All rights reserved. This program and the accompanying materials\r
+ are licensed and made available under the terms and conditions of the BSD License\r
+ which accompanies this distribution. The full text of the license may be found at\r
+ http://opensource.org/licenses/bsd-license.php\r
\r
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
+ @par Revision Reference:\r
+ This Protocol is defined in Framework of S3 Resume Boot Path Spec.\r
+ Version 0.9.\r
+ \r
**/\r
\r
-#ifndef _ACPI_S3_SAVE_PROTOCOL_H\r
-#define _ACPI_S3_SAVE_PROTOCOL_H\r
+#ifndef _ACPI_S3_SAVE_PROTOCOL_H_\r
+#define _ACPI_S3_SAVE_PROTOCOL_H_\r
\r
#include <PiDxe.h>\r
\r
//\r
// Protocol Data Structures\r
//\r
+\r
+/**\r
+ This function returns the size of the legacy memory below 1 MB that is required during an S3\r
+ resume. Before the Framework-based firmware transfers control to the OS, it has to transition from\r
+ flat mode into real mode in case the OS supplies only a real-mode waking vector. This transition\r
+ requires a certain amount of legacy memory below 1 MB. After getting the size of legacy memory\r
+ below 1 MB, the caller is responsible for allocating the legacy memory below 1 MB according to\r
+ the size that is returned. The specific implementation of allocating the legacy memory is out of the\r
+ scope of this specification.\r
+\r
+ @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.\r
+ @param LegacyMemoryAddress The returned size of legacy memory below 1MB.\r
+\r
+ @retval EFI_SUCCESS Size is successfully returned.\r
+ @retval EFI_INVALID_PARAMETER The pointer Size is NULL.\r
+\r
+**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_ACPI_S3_SAVE) (\r
+(EFIAPI *EFI_ACPI_S3_SAVE)(\r
IN EFI_ACPI_S3_SAVE_PROTOCOL * This,\r
IN VOID * LegacyMemoryAddress\r
);\r
\r
+/**\r
+ This function is used to do the following:\r
+ \r
+ - Prepare all information that is needed in the S3 resume boot path. This information can include\r
+ the following:\r
+ -- Framework boot script table\r
+ -- RSDT pointer\r
+ -- Reserved memory for the S3 resume\r
+ \r
+ - Get the minimum memory length below 1 MB that is required for the S3 resume boot path.\r
+ If LegacyMemoryAddress is NULL, the firmware will be unable to jump into a real-mode\r
+ waking vector. However, it might still be able to jump into a flat-mode waking vector as long as the\r
+ OS provides a flat-mode waking vector. It is the caller's responsibility to ensure the\r
+ LegacyMemoryAddress is valid. If the LegacyMemoryAddress is higher than 1 MB,\r
+ EFI_INVALID_PARAMETER will be returned.\r
+\r
+ @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.\r
+ @param LegacyMemoryAddress The base of legacy memory.\r
+\r
+ @retval EFI_SUCCESS All information was saved successfully.\r
+ @retval EFI_INVALID_PARAMETER The memory range is not located below 1 MB.\r
+ @retval EFI_OUT_OF_RESOURCES Resources were insufficient to save all the information.\r
+ @retval EFI_NOT_FOUND Some necessary information cannot be found.\r
+ \r
+**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_ACPI_GET_LEGACY_MEMORY_SIZE) (\r
+(EFIAPI *EFI_ACPI_GET_LEGACY_MEMORY_SIZE)(\r
IN EFI_ACPI_S3_SAVE_PROTOCOL * This,\r
OUT UINTN * Size\r
);\r
\r
+/**\r
+ The EFI_ACPI_S3_SAVE_PROTOCOL is responsible for preparing all the information that the\r
+ Framework needs to restore the platform's preboot state during an S3 resume boot. This\r
+ information can include the following:\r
+ - The Framework boot script table, containing all necessary operations to initialize the platform\r
+ - ACPI table information, such as RSDT, through which the OS waking vector can be located\r
+ - Range of reserved memory that can be used on the S3 resume boot path\r
+ This protocol can be used after the Framework makes sure that the boot process is complete and\r
+ that no hardware has been left unconfigured. It is implementation specific where to call this\r
+ protocol to save all the information.\r
+ In the case of an EFI-aware OS, ExitBootServices()can be a choice to provide this hook.\r
+ The currently executing EFI OS loader image calls ExitBootServices()to terminate all boot\r
+ services. After ExitBootServices() successfully completes, the loader becomes responsible\r
+ for the continued operation of the system.\r
+ On a normal boot, ExitBootServices() checks if the platform supports S3 by looking for\r
+ EFI_ACPI_S3_SAVE_PROTOCOL. If the protocol exists, ExitBootServices()will assume\r
+ that the target platform supports an S3 resume and then call EFI_ACPI_S3_SAVE_PROTOCOL\r
+ to save the S3 resume information. The entire Framework boot script table will then be generated,\r
+ assuming the platform currently is in the preboot state.\r
+**/\r
struct _EFI_ACPI_S3_SAVE_PROTOCOL {\r
+ ///\r
+ /// Gets the size of legacy memory below 1 MB that is required for S3 resume.\r
+ ///\r
EFI_ACPI_GET_LEGACY_MEMORY_SIZE GetLegacyMemorySize;\r
+ \r
+ ///\r
+ /// Prepare all information for an S3 resume.\r
+ ///\r
EFI_ACPI_S3_SAVE S3Save;\r
};\r
\r
projects / mirror_edk2.git / blobdiff