IntelFrameworkPkg/Include/Protocol/AcpiS3Save.h

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