MdePkg/Include/Ppi/S3Resume.h

   1 /** @file
   2   This PPI produces functions to interpret and execute the PI boot script table.
   3
   4   This PPI is published by a PEIM and provides for the restoration of the platform's
   5   configuration when resuming from the ACPI S3 power state. The ability to execute
   6   the boot script may depend on the availability of other PPIs. For example, if
   7   the boot script includes an SMBus command, this PEIM looks for the relevant PPI
   8   that is able to execute that command.
   9
  10   Copyright (c) 2007 - 2009, Intel Corporation
  11   All rights reserved. This program and the accompanying materials
  12   are licensed and made available under the terms and conditions of the BSD License
  13   which accompanies this distribution.  The full text of the license may be found at
  14   http://opensource.org/licenses/bsd-license.php
  15
  16   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  17   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  18
  19   @par Revision Reference:
  20   This PPI is defined in UEFI Platform Initialization Specification 1.2 Volume 5:
  21   Standards
  22
  23 **/
  24
  25 #ifndef __PEI_S3_RESUME_PPI_H__
  26 #define __PEI_S3_RESUME_PPI_H__
  27
  28 ///
  29 /// Global ID for EFI_PEI_S3_RESUME_PPI
  30 ///
  31 #define EFI_PEI_S3_RESUME_PPI_GUID \
  32   { \
  33     0x4426CCB2, 0xE684, 0x4a8a, {0xAE, 0x40, 0x20, 0xD4, 0xB0, 0x25, 0xB7, 0x10 } \
  34   }
  35
  36 ///
  37 /// Forward declaration for EFI_PEI_S3_RESUME_PPI
  38 ///
  39 typedef struct _EFI_PEI_S3_RESUME_PPI  EFI_PEI_S3_RESUME_PPI;
  40
  41 /**
  42   Restores the platform to its preboot configuration for an S3 resume and
  43   jumps to the OS waking vector.
  44
  45   This function will restore the platform to its pre-boot configuration that was
  46   pre-stored in the boot script table and transfer control to OS waking vector.
  47   Upon invocation, this function is responsible for locating the following
  48   information before jumping to OS waking vector:
  49     - ACPI tables
  50     - boot script table
  51     - any other information that it needs
  52
  53   The S3RestoreConfig() function then executes the pre-stored boot script table
  54   and transitions the platform to the pre-boot state. The boot script is recorded
  55   during regular boot using the EFI_S3_SAVE_STATE_PROTOCOL.Write() and
  56   EFI_S3_SMM_SAVE_STATE_PROTOCOL.Write() functions.  Finally, this function
  57   transfers control to the OS waking vector. If the OS supports only a real-mode
  58   waking vector, this function will switch from flat mode to real mode before
  59   jumping to the waking vector.  If all platform pre-boot configurations are
  60   successfully restored and all other necessary information is ready, this
  61   function will never return and instead will directly jump to the OS waking
  62   vector. If this function returns, it indicates that the attempt to resume
  63   from the ACPI S3 sleep state failed.
  64
  65   @param[in] PeiServices   Pointer to the PEI Services Table
  66
  67   @retval EFI_ABORTED     Execution of the S3 resume boot script table failed.
  68   @retval EFI_NOT_FOUND   Some necessary information that is used for the S3
  69                           resume boot path could not be located.
  70
  71 **/
  72 typedef
  73 EFI_STATUS
  74 (EFIAPI *EFI_PEI_S3_RESUME_PPI_RESTORE_CONFIG)(
  75   IN EFI_PEI_SERVICES  **PeiServices
  76   );
  77
  78 /**
  79   EFI_PEI_S3_RESUME_PPI accomplishes the firmware S3 resume boot
  80   path and transfers control to OS.
  81 **/
  82 struct _EFI_PEI_S3_RESUME_PPI {
  83   ///
  84   /// Restores the platform to its preboot configuration for an S3 resume and
  85   /// jumps to the OS waking vector.
  86   ///
  87   EFI_PEI_S3_RESUME_PPI_RESTORE_CONFIG  S3RestoreConfig;
  88 };
  89
  90 extern EFI_GUID gEfiPeiS3ResumePpiGuid;
  91
  92 #endif