1 /** @file 2 This protocol is used to prepare all information that is needed for the S3 resume boot path. This 3 protocol is not required for all platforms. 4 5 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> 6 This program and the accompanying materials are licensed and made available under 7 the terms and conditions of the BSD License that accompanies this distribution. 8 The full text of the license may be found at 9 http://opensource.org/licenses/bsd-license.php. 10 11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 13 14 @par Revision Reference: 15 This Protocol is defined in Framework of S3 Resume Boot Path Spec. 16 Version 0.9. 17 18 **/ 19 20 #ifndef _ACPI_S3_SAVE_PROTOCOL_H_ 21 #define _ACPI_S3_SAVE_PROTOCOL_H_ 22 23 // 24 // Forward reference for pure ANSI compatability 25 // 26 typedef struct _EFI_ACPI_S3_SAVE_PROTOCOL EFI_ACPI_S3_SAVE_PROTOCOL; 27 28 // 29 // S3 Save Protocol GUID 30 // 31 #define EFI_ACPI_S3_SAVE_GUID \ 32 { \ 33 0x125f2de1, 0xfb85, 0x440c, {0xa5, 0x4c, 0x4d, 0x99, 0x35, 0x8a, 0x8d, 0x38 } \ 34 } 35 36 // 37 // Protocol Data Structures 38 // 39 40 /** 41 This function is used to: 42 43 - Prepare all information that is needed in the S3 resume boot path. This information can include 44 the following: 45 -- Framework boot script table 46 -- RSDT pointer 47 -- Reserved memory for the S3 resume 48 49 - Get the minimum legacy memory length (meaning below 1 MB) that is required for the S3 resume boot path. 50 If LegacyMemoryAddress is NULL, the firmware will be unable to jump into a real-mode 51 waking vector. However, it might still be able to jump into a flat-mode waking vector as long as the 52 OS provides a flat-mode waking vector. It is the caller's responsibility to ensure the 53 LegacyMemoryAddress is valid. If the LegacyMemoryAddress is higher than 1 MB, 54 EFI_INVALID_PARAMETER will be returned. 55 56 @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance. 57 @param LegacyMemoryAddress The base of legacy memory. 58 59 @retval EFI_SUCCESS All information was saved successfully. 60 @retval EFI_INVALID_PARAMETER The memory range is not located below 1 MB. 61 @retval EFI_OUT_OF_RESOURCES Resources were insufficient to save all the information. 62 @retval EFI_NOT_FOUND Some necessary information cannot be found. 63 64 **/ 65 typedef 66 EFI_STATUS 67 (EFIAPI *EFI_ACPI_S3_SAVE)( 68 IN EFI_ACPI_S3_SAVE_PROTOCOL * This, 69 IN VOID * LegacyMemoryAddress 70 ); 71 72 /** 73 This function returns the size of the legacy memory (meaning below 1 MB) that is required during an S3 74 resume. Before the Framework-based firmware transfers control to the OS, it has to transition from 75 flat mode into real mode in case the OS supplies only a real-mode waking vector. This transition 76 requires a certain amount of legacy memory. After getting the size of legacy memory 77 below, the caller is responsible for allocating the legacy memory below 1 MB according to 78 the size that is returned. The specific implementation of allocating the legacy memory is out of the 79 scope of this specification. 80 81 @param This A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance. 82 @param Size The returned size of legacy memory below 1MB. 83 84 @retval EFI_SUCCESS Size was successfully returned. 85 @retval EFI_INVALID_PARAMETER The pointer Size is NULL. 86 87 **/ 88 typedef 89 EFI_STATUS 90 (EFIAPI *EFI_ACPI_GET_LEGACY_MEMORY_SIZE)( 91 IN EFI_ACPI_S3_SAVE_PROTOCOL * This, 92 OUT UINTN * Size 93 ); 94 95 /** 96 The EFI_ACPI_S3_SAVE_PROTOCOL is responsible for preparing all the information that the 97 Framework needs to restore the platform's preboot state during an S3 resume boot. This 98 information can include the following: 99 - The Framework boot script table, containing all necessary operations to initialize the platform. 100 - ACPI table information, such as RSDT, through which the OS waking vector can be located. 101 - The range of reserved memory that can be used on the S3 resume boot path. 102 This protocol can be used after the Framework makes sure that the boot process is complete and 103 that no hardware has been left unconfigured. Where to call this protocol to save information is implementation-specific. 104 In the case of an EFI-aware OS, ExitBootServices() can be a choice to provide this hook. 105 The currently executing EFI OS loader image calls ExitBootServices()to terminate all boot 106 services. After ExitBootServices() successfully completes, the loader becomes responsible 107 for the continued operation of the system. 108 On a normal boot, ExitBootServices() checks if the platform supports S3 by looking for 109 EFI_ACPI_S3_SAVE_PROTOCOL. If the protocol exists, ExitBootServices()will assume 110 that the target platform supports an S3 resume and then call EFI_ACPI_S3_SAVE_PROTOCOL 111 to save the S3 resume information. The entire Framework boot script table will then be generated, 112 assuming the platform currently is in the preboot state. 113 **/ 114 struct _EFI_ACPI_S3_SAVE_PROTOCOL { 115 /// 116 /// Gets the size of legacy memory below 1 MB that is required for S3 resume. 117 /// 118 EFI_ACPI_GET_LEGACY_MEMORY_SIZE GetLegacyMemorySize; 119 120 /// 121 /// Prepare all information for an S3 resume. 122 /// 123 EFI_ACPI_S3_SAVE S3Save; 124 }; 125 126 extern EFI_GUID gEfiAcpiS3SaveProtocolGuid; 127 128 #endif 129
