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