mirror of https://github.com/acidanthera/audk.git
133 lines
5.5 KiB
C
133 lines
5.5 KiB
C
/** @file
|
||
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_
|
||
|
||
#include <PiDxe.h>
|
||
|
||
//
|
||
// Forward reference for pure ANSI compatability
|
||
//
|
||
typedef struct _EFI_ACPI_S3_SAVE_PROTOCOL EFI_ACPI_S3_SAVE_PROTOCOL;
|
||
|
||
//
|
||
// S3 Save Protocol GUID
|
||
//
|
||
#define EFI_ACPI_S3_SAVE_GUID \
|
||
{ \
|
||
0x125f2de1, 0xfb85, 0x440c, {0xa5, 0x4c, 0x4d, 0x99, 0x35, 0x8a, 0x8d, 0x38 } \
|
||
}
|
||
|
||
//
|
||
// 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)(
|
||
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<65>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)(
|
||
IN EFI_ACPI_S3_SAVE_PROTOCOL * This,
|
||
OUT UINTN * Size
|
||
);
|
||
|
||
/**
|
||
@par Protocol Description:
|
||
The EFI_ACPI_S3_SAVE_PROTOCOL is responsible for preparing all the information that the
|
||
Framework needs to restore the platform<72>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.
|
||
|
||
@param GetLegacyMemorySize
|
||
Gets the size of legacy memory below 1 MB that is required for S3 resume.
|
||
|
||
@param S3Save
|
||
Prepare all information for an S3 resume.
|
||
|
||
**/
|
||
struct _EFI_ACPI_S3_SAVE_PROTOCOL {
|
||
EFI_ACPI_GET_LEGACY_MEMORY_SIZE GetLegacyMemorySize;
|
||
EFI_ACPI_S3_SAVE S3Save;
|
||
};
|
||
|
||
extern EFI_GUID gEfiAcpiS3SaveProtocolGuid;
|
||
|
||
#endif
|