Add the following PI 1.2 PPIs to the MdePkg

1) Block I/O PPI 
2) Device Recovery PPI 
3) Recovery Module PPI
4) S3 Resume PPI

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8914 6f19259b-4bc3-4df7-8a09-765794883524

4 files changed, 560 insertions, 0 deletions

diff --git a/MdePkg/Include/Ppi/BlockIo.h b/MdePkg/Include/Ppi/BlockIo.h
new file mode 100644
index 0000000000..ab86ff485a
--- /dev/null
+++ b/MdePkg/Include/Ppi/BlockIo.h
@@ -0,0 +1,233 @@
+/** @file

+  Provides the services required to access a block I/O device during PEI recovery 

+  boot mode.

+

+  The Recovery Module PPI and the Device Recovery Module PPI are device neutral. 

+  This PPI is device specific and addresses the most common form of recovery 

+  media-block I/O devices such as legacy floppy, CD-ROM, or IDE devices.

+

+  The Recovery Block I/O PPI is used to access block devices. Because the Recovery 

+  Block I/O PPIs that are provided by the PEI ATAPI driver and PEI legacy floppy 

+  driver are the same, here we define a set of general PPIs for both drivers to use.

+  

+  Copyright (c) 2007 - 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 PPI is defined in UEFI Platform Initialization Specification 1.2 Volume 1: 

+  Pre-EFI Initalization Core Interface

+

+**/

+

+#ifndef _PEI_BLOCK_IO_H_

+#define _PEI_BLOCK_IO_H_

+

+///

+/// Global ID for EFI_PEI_RECOVERY_BLOCK_IO_PPI

+///

+#define EFI_PEI_RECOVERY_BLOCK_IO_PPI_GUID \

+  { \

+    0x695d8aa1, 0x42ee, 0x4c46, { 0x80, 0x5c, 0x6e, 0xa6, 0xbc, 0xe7, 0x99, 0xe3 } \

+  }

+

+///

+/// Forward declaration for EFI_PEI_RECOVERY_BLOCK_IO_PPI

+///

+typedef struct _EFI_PEI_RECOVERY_BLOCK_IO_PPI  EFI_PEI_RECOVERY_BLOCK_IO_PPI;

+

+///

+/// All blocks on the recovery device are addressed with a 64-bit Logical Block Address (LBA)

+///

+typedef UINT64  EFI_PEI_LBA;

+

+///

+/// EFI_PEI_BLOCK_DEVICE_TYPE

+///

+typedef enum {

+  LegacyFloppy  = 0,   ///< The recovery device is a floppy. 

+  IdeCDROM      = 1,   ///< The recovery device is an IDE CD-ROM

+  IdeLS120      = 2,   ///< The recovery device is an IDE LS-120

+  UsbMassStorage= 3,   ///< The recovery device is a USB Mass Storage device

+  MaxDeviceType

+} EFI_PEI_BLOCK_DEVICE_TYPE;

+

+///

+/// Inconsistent with specification here: 

+/// PEI_BLOCK_IO_MEDIA has been changed to EFI_PEI_BLOCK_IO_MEDIA.

+/// Inconsistency exists in UEFI Platform Initialization Specification 1.2 

+/// Volume 1: Pre-EFI Initalization Core Interface, where all referrences to 

+/// this structure name are with the "EFI_" prefix, except for the definition 

+/// which is without "EFI_".  So the name of PEI_BLOCK_IO_MEDIA is taken as the 

+/// exception, and EFI_PEI_BLOCK_IO_MEDIA is used to comply with most part of 

+/// the specification.

+///

+typedef struct {

+  ///

+  /// The type of media device being referenced by DeviceIndex. 

+  ///

+  EFI_PEI_BLOCK_DEVICE_TYPE  DeviceType;

+  ///

+  /// A flag that indicates if media is present. This flag is always set for 

+  /// nonremovable media devices.

+  ///

+  BOOLEAN                    MediaPresent;

+  ///

+  /// The last logical block that the device supports.

+  ///

+  UINTN                      LastBlock;

+  ///

+  /// The size of a logical block in bytes.

+  ///

+  UINTN                      BlockSize;

+} EFI_PEI_BLOCK_IO_MEDIA;

+

+/**

+  Gets the count of block I/O devices that one specific block driver detects.

+

+  This function is used for getting the count of block I/O devices that one 

+  specific block driver detects.  To the PEI ATAPI driver, it returns the number

+  of all the detected ATAPI devices it detects during the enumeration process. 

+  To the PEI legacy floppy driver, it returns the number of all the legacy 

+  devices it finds during its enumeration process. If no device is detected, 

+  then the function will return zero.  

+  

+  @param[in]  PeiServices          General-purpose services that are available 

+                                   to every PEIM.

+  @param[in]  This                 Indicates the EFI_PEI_RECOVERY_BLOCK_IO_PPI 

+                                   instance.

+  @param[out] NumberBlockDevices   The number of block I/O devices discovered.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_PEI_GET_NUMBER_BLOCK_DEVICES)(

+  IN  EFI_PEI_SERVICES               **PeiServices,

+  IN  EFI_PEI_RECOVERY_BLOCK_IO_PPI  *This,

+  OUT UINTN                          *NumberBlockDevices

+  );

+

+/**

+  Gets a block device's media information.

+

+  This function will provide the caller with the specified block device's media 

+  information. If the media changes, calling this function will update the media 

+  information accordingly.

+

+  @param[in]  PeiServices   General-purpose services that are available to every

+                            PEIM

+  @param[in]  This          Indicates the EFI_PEI_RECOVERY_BLOCK_IO_PPI instance.

+  @param[in]  DeviceIndex   Specifies the block device to which the function wants 

+                            to talk. Because the driver that implements Block I/O 

+                            PPIs will manage multiple block devices, the PPIs that 

+                            want to talk to a single device must specify the 

+                            device index that was assigned during the enumeration

+                            process. This index is a number from one to 

+                            NumberBlockDevices.

+  @param[out] MediaInfo     The media information of the specified block media.  

+                            The caller is responsible for the ownership of this 

+                            data structure.

+

+  @par Note: 

+      The MediaInfo structure describes an enumeration of possible block device 

+      types.  This enumeration exists because no device paths are actually passed 

+      across interfaces that describe the type or class of hardware that is publishing 

+      the block I/O interface. This enumeration will allow for policy decisions

+      in the Recovery PEIM, such as "Try to recover from legacy floppy first, 

+      LS-120 second, CD-ROM third." If there are multiple partitions abstracted 

+      by a given device type, they should be reported in ascending order; this 

+      order also applies to nested partitions, such as legacy MBR, where the 

+      outermost partitions would have precedence in the reporting order. The 

+      same logic applies to systems such as IDE that have precedence relationships 

+      like "Master/Slave" or "Primary/Secondary"; the master device should be 

+      reported first, the slave second.

+  

+  @retval EFI_SUCCESS        Media information about the specified block device 

+                             was obtained successfully.

+  @retval EFI_DEVICE_ERROR   Cannot get the media information due to a hardware 

+                             error.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_PEI_GET_DEVICE_MEDIA_INFORMATION)(

+  IN  EFI_PEI_SERVICES               **PeiServices,

+  IN  EFI_PEI_RECOVERY_BLOCK_IO_PPI  *This,

+  IN  UINTN                          DeviceIndex,

+  OUT EFI_PEI_BLOCK_IO_MEDIA         *MediaInfo

+  );

+

+/**

+  Reads the requested number of blocks from the specified block device.

+

+  The function reads the requested number of blocks from the device. All the 

+  blocks are read, or an error is returned. If there is no media in the device,

+  the function returns EFI_NO_MEDIA.

+

+  @param[in]  PeiServices   General-purpose services that are available to 

+                            every PEIM.

+  @param[in]  This          Indicates the EFI_PEI_RECOVERY_BLOCK_IO_PPI instance.

+  @param[in]  DeviceIndex   Specifies the block device to which the function wants 

+                            to talk. Because the driver that implements Block I/O 

+                            PPIs will manage multiple block devices, the PPIs that 

+                            want to talk to a single device must specify the device 

+                            index that was assigned during the enumeration process. 

+                            This index is a number from one to NumberBlockDevices.

+  @param[in]  StartLBA      The starting logical block address (LBA) to read from

+                            on the device

+  @param[in]  BufferSize    The size of the Buffer in bytes. This number must be

+                            a multiple of the intrinsic block size of the device.

+  @param[out] Buffer        A pointer to the destination buffer for the data.

+                            The caller is responsible for the ownership of the 

+                            buffer.

+                         

+  @retval EFI_SUCCESS             The data was read correctly from the device.

+  @retval EFI_DEVICE_ERROR        The device reported an error while attempting 

+                                  to perform the read operation.

+  @retval EFI_INVALID_PARAMETER   The read request contains LBAs that are not 

+                                  valid, or the buffer is not properly aligned.

+  @retval EFI_NO_MEDIA            There is no media in the device.

+  @retval EFI_BAD_BUFFER_SIZE     The BufferSize parameter is not a multiple of

+                                  the intrinsic block size of the device.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_PEI_READ_BLOCKS)(

+  IN  EFI_PEI_SERVICES               **PeiServices,

+  IN  EFI_PEI_RECOVERY_BLOCK_IO_PPI  *This,

+  IN  UINTN                          DeviceIndex,

+  IN  EFI_PEI_LBA                    StartLBA,

+  IN  UINTN                          BufferSize,

+  OUT VOID                           *Buffer

+  );

+

+///

+///  EFI_PEI_RECOVERY_BLOCK_IO_PPI provides the services that are required

+///  to access a block I/O device during PEI recovery boot mode.

+///

+struct _EFI_PEI_RECOVERY_BLOCK_IO_PPI {

+  ///

+  /// Gets the number of block I/O devices that the specific block driver manages.

+  ///

+  EFI_PEI_GET_NUMBER_BLOCK_DEVICES      GetNumberOfBlockDevices;

+  

+  ///

+  /// Gets the specified media information.

+  ///

+  EFI_PEI_GET_DEVICE_MEDIA_INFORMATION  GetBlockDeviceMediaInfo;

+  

+  ///

+  /// Reads the requested number of blocks from the specified block device.

+  ///

+  EFI_PEI_READ_BLOCKS                   ReadBlocks;

+};

+

+extern EFI_GUID gEfiPeiVirtualBlockIoPpiGuid;

+

+#endif

diff --git a/MdePkg/Include/Ppi/DeviceRecoveryModule.h b/MdePkg/Include/Ppi/DeviceRecoveryModule.h
new file mode 100644
index 0000000000..708f47a6a0
--- /dev/null
+++ b/MdePkg/Include/Ppi/DeviceRecoveryModule.h
@@ -0,0 +1,144 @@
+/** @file

+  This file declares the Device Recovery Module PPI.

+

+  The interface of this PPI does the following:

+    - Reports the number of recovery DXE capsules that exist on the associated device(s)

+    - Finds the requested firmware binary capsule

+    - Loads that capsule into memory

+

+  A device can be either a group of devices, such as a block device, or an individual device.

+  The module determines the internal search order, with capsule number 1 as the highest load

+  priority and number N as the lowest priority.

+

+  Copyright (c) 2007 - 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 PPI is defined in UEFI Platform Initialization Specification 1.2 Volume 1: 

+  Pre-EFI Initalization Core Interface

+

+**/

+

+#ifndef _PEI_DEVICE_RECOVERY_MODULE_PPI_H_

+#define _PEI_DEVICE_RECOVERY_MODULE_PPI_H_

+

+#define EFI_PEI_DEVICE_RECOVERY_MODULE_PPI_GUID \

+  { \

+    0x0DE2CE25, 0x446A, 0x45a7, {0xBF, 0xC9, 0x37, 0xDA, 0x26, 0x34, 0x4B, 0x37 } \

+  }

+

+typedef struct _EFI_PEI_DEVICE_RECOVERY_MODULE_PPI EFI_PEI_DEVICE_RECOVERY_MODULE_PPI;

+

+/**

+  Returns the number of DXE capsules residing on the device.

+

+  This function searches for DXE capsules from the associated device and returns

+  the number and maximum size in bytes of the capsules discovered. Entry 1 is 

+  assumed to be the highest load priority and entry N is assumed to be the lowest 

+  priority.

+

+  @param[in]  PeiServices              General-purpose services that are available 

+                                       to every PEIM

+  @param[in]  This                     Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI

+                                       instance.

+  @param[out] NumberRecoveryCapsules   Pointer to a caller-allocated UINTN. On 

+                                       output, *NumberRecoveryCapsules contains 

+                                       the number of recovery capsule images 

+                                       available for retrieval from this PEIM 

+                                       instance.

+

+  @retval EFI_SUCCESS        One or more capsules were discovered.

+  @retval EFI_DEVICE_ERROR   A device error occurred.

+  @retval EFI_NOT_FOUND      A recovery DXE capsule cannot be found.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_PEI_DEVICE_GET_NUMBER_RECOVERY_CAPSULE)(

+  IN  EFI_PEI_SERVICES                    **PeiServices,

+  IN  EFI_PEI_DEVICE_RECOVERY_MODULE_PPI  *This,

+  OUT UINTN                               *NumberRecoveryCapsules

+  );

+

+/**

+  Returns the size and type of the requested recovery capsule.

+

+  This function gets the size and type of the capsule specified by CapsuleInstance.

+

+  @param[in]  PeiServices       General-purpose services that are available to every PEIM

+  @param[in]  This              Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI 

+                                instance.

+  @param[in]  CapsuleInstance   Specifies for which capsule instance to retrieve 

+                                the information.  This parameter must be between 

+                                one and the value returned by GetNumberRecoveryCapsules() 

+                                in NumberRecoveryCapsules.

+  @param[out] Size              A pointer to a caller-allocated UINTN in which 

+                                the size of the requested recovery module is 

+                                returned.

+  @param[out] CapsuleType       A pointer to a caller-allocated EFI_GUID in which 

+                                the type of the requested recovery capsule is 

+                                returned.  The semantic meaning of the value 

+                                returned is defined by the implementation.

+

+  @retval EFI_SUCCESS        One or more capsules were discovered.

+  @retval EFI_DEVICE_ERROR   A device error occurred.

+  @retval EFI_NOT_FOUND      A recovery DXE capsule cannot be found.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_PEI_DEVICE_GET_RECOVERY_CAPSULE_INFO)(

+  IN  EFI_PEI_SERVICES                    **PeiServices,

+  IN  EFI_PEI_DEVICE_RECOVERY_MODULE_PPI  *This,

+  IN  UINTN                               CapsuleInstance,

+  OUT UINTN                               *Size,

+  OUT EFI_GUID                            *CapsuleType

+  );

+

+/**

+  Loads a DXE capsule from some media into memory.

+

+  This function, by whatever mechanism, retrieves a DXE capsule from some device

+  and loads it into memory. Note that the published interface is device neutral.

+

+  @param[in,out] PeiServices       General-purpose services that are available 

+                                   to every PEIM

+  @param[in]     This              Indicates the EFI_PEI_DEVICE_RECOVERY_MODULE_PPI

+                                   instance.

+  @param[in]     CapsuleInstance   Specifies which capsule instance to retrieve.

+  @param[out]    Buffer            Specifies a caller-allocated buffer in which 

+                                   the requested recovery capsule will be returned.

+

+  @retval EFI_SUCCESS        The capsule was loaded correctly.

+  @retval EFI_DEVICE_ERROR   A device error occurred.

+  @retval EFI_NOT_FOUND      A requested recovery DXE capsule cannot be found.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_PEI_DEVICE_LOAD_RECOVERY_CAPSULE)(

+  IN OUT EFI_PEI_SERVICES                    **PeiServices,

+  IN     EFI_PEI_DEVICE_RECOVERY_MODULE_PPI  *This,

+  IN     UINTN                               CapsuleInstance,

+  OUT    VOID                                *Buffer

+  );

+

+///

+/// Presents a standard interface to EFI_PEI_DEVICE_RECOVERY_MODULE_PPI,

+/// regardless of the underlying device(s).

+///

+struct _EFI_PEI_DEVICE_RECOVERY_MODULE_PPI {

+  EFI_PEI_DEVICE_GET_NUMBER_RECOVERY_CAPSULE  GetNumberRecoveryCapsules;    ///< Returns the number of DXE capsules residing on the device.

+  EFI_PEI_DEVICE_GET_RECOVERY_CAPSULE_INFO    GetRecoveryCapsuleInfo;       ///< Returns the size and type of the requested recovery capsule.

+  EFI_PEI_DEVICE_LOAD_RECOVERY_CAPSULE        LoadRecoveryCapsule;          ///< Loads a DXE capsule from some media into memory.

+};

+

+extern EFI_GUID gEfiPeiDeviceRecoveryModulePpiGuid;

+

+#endif  /* _PEI_DEVICE_RECOVERY_MODULE_PPI_H_ */

diff --git a/MdePkg/Include/Ppi/RecoveryModule.h b/MdePkg/Include/Ppi/RecoveryModule.h
new file mode 100644
index 0000000000..55ed9c926e
--- /dev/null
+++ b/MdePkg/Include/Ppi/RecoveryModule.h
@@ -0,0 +1,91 @@
+/** @file

+  This file declares Recovery Module PPI.  This PPI is used to find and load the

+  recovery files.

+

+  A module that produces this PPI has many roles and is responsible for the following:

+    -# Calling the driver recovery PPI EFI_PEI_DEVICE_RECOVERY_MODULE_PPI.

+       GetNumberRecoveryCapsules() to determine if one or more DXE recovery 

+       entities exist.

+    -# If no capsules exist, then performing appropriate error handling.

+    -# Allocating a buffer of MaxRecoveryCapsuleSize as determined by

+       EFI_PEI_DEVICE_RECOVERY_MODULE_PPI.GetNumberRecoveryCapsules() or

+       larger.

+    -# Determining the policy in which DXE recovery capsules are loaded.

+    -# Calling the driver recovery PPI EFI_PEI_DEVICE_RECOVERY_MODULE_PPI.

+       LoadRecoveryCapsule() for capsule number x.

+    -# If the load failed, performing appropriate error handling.

+    -# Performing security checks for a loaded DXE recovery capsule.

+    -# If the security checks failed, then logging the failure in a data HOB.

+    -# If the security checks failed, then determining the next 

+       EFI_PEI_DEVICE_RECOVERY_MODULE_PPI.LoadRecoveryCapsule()capsule number; 

+       otherwise, go to step 11.

+    -# If more DXE recovery capsules exist, then go to step 5; otherwise, perform 

+       error handling.

+    -# Decomposing the capsule loaded by EFI_PEI_DEVICE_RECOVERY_MODULE_PPI.

+       LoadRecoveryCapsule() into its components. It is assumed that the path 

+       parameters are redundant for recovery and Setup parameters are either 

+       redundant or canned.

+    -# Invalidating all HOB entries for updateable firmware volume entries. 

+       This invalidation prevents possible errant drivers from being executed.

+    -# Updating the HOB table with the recovery DXE firmware volume information 

+       generated from the capsule decomposition.

+    -# Returning to the PEI Dispatcher.  

+  

+  Copyright (c) 2007 - 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 PPI is defined in UEFI Platform Initialization Specification 1.2 Volume 1: 

+  Pre-EFI Initalization Core Interface

+

+**/

+

+#ifndef __PEI_RECOVERY_MODULE_PPI_H__

+#define __PEI_RECOVERY_MODULE_PPI_H__

+

+///

+///  Inconsistent with specification here: 

+///  GUID marco name has been changed to the consistent PPI GUID macro name.

+///

+#define EFI_PEI_RECOVERY_MODULE_PPI_GUID \

+  { \

+    0xFB6D9542, 0x612D, 0x4f45, {0x87, 0x2F, 0x5C, 0xFF, 0x52, 0xE9, 0x3D, 0xCF } \

+  }

+

+typedef struct _EFI_PEI_RECOVERY_MODULE_PPI EFI_PEI_RECOVERY_MODULE_PPI;

+

+/**

+  Loads a DXE capsule from some media into memory and updates the HOB table

+  with the DXE firmware volume information.

+

+  @param  PeiServices   General-purpose services that are available to every PEIM.

+  @param  This          Indicates the EFI_PEI_RECOVERY_MODULE_PPI instance.

+

+  @retval EFI_SUCCESS        The capsule was loaded correctly.

+  @retval EFI_DEVICE_ERROR   A device error occurred.

+  @retval EFI_NOT_FOUND      A recovery DXE capsule cannot be found.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_PEI_LOAD_RECOVERY_CAPSULE)(

+  IN EFI_PEI_SERVICES             **PeiServices,

+  IN EFI_PEI_RECOVERY_MODULE_PPI  *This

+  );

+

+///

+///  Finds and loads the recovery files.

+///

+struct _EFI_PEI_RECOVERY_MODULE_PPI {

+  EFI_PEI_LOAD_RECOVERY_CAPSULE LoadRecoveryCapsule;  ///< Loads a DXE binary capsule into memory.

+};

+

+extern EFI_GUID gEfiPeiRecoveryModulePpiGuid;

+

+#endif

diff --git a/MdePkg/Include/Ppi/S3Resume.h b/MdePkg/Include/Ppi/S3Resume.h
new file mode 100644
index 0000000000..d333d6fcc0
--- /dev/null
+++ b/MdePkg/Include/Ppi/S3Resume.h
@@ -0,0 +1,92 @@
+/** @file

+  This PPI produces functions to interpret and execute the PI boot script table.

+  

+  This PPI is published by a PEIM and provides for the restoration of the platform's

+  configuration when resuming from the ACPI S3 power state. The ability to execute 

+  the boot script may depend on the availability of other PPIs. For example, if 

+  the boot script includes an SMBus command, this PEIM looks for the relevant PPI 

+  that is able to execute that command.  

+  

+  Copyright (c) 2007 - 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 PPI is defined in UEFI Platform Initialization Specification 1.2 Volume 5: 

+  Standards

+

+**/

+

+#ifndef __PEI_S3_RESUME_PPI_H__

+#define __PEI_S3_RESUME_PPI_H__

+

+///

+/// Global ID for EFI_PEI_S3_RESUME_PPI

+///

+#define EFI_PEI_S3_RESUME_PPI_GUID \

+  { \

+    0x4426CCB2, 0xE684, 0x4a8a, {0xAE, 0x40, 0x20, 0xD4, 0xB0, 0x25, 0xB7, 0x10 } \

+  }

+

+///

+/// Forward declaration for EFI_PEI_S3_RESUME_PPI

+///

+typedef struct _EFI_PEI_S3_RESUME_PPI  EFI_PEI_S3_RESUME_PPI;

+

+/**

+  Restores the platform to its preboot configuration for an S3 resume and

+  jumps to the OS waking vector.

+

+  This function will restore the platform to its pre-boot configuration that was 

+  pre-stored in the boot script table and transfer control to OS waking vector.

+  Upon invocation, this function is responsible for locating the following 

+  information before jumping to OS waking vector:

+    - ACPI tables

+    - boot script table

+    - any other information that it needs

+    

+  The S3RestoreConfig() function then executes the pre-stored boot script table 

+  and transitions the platform to the pre-boot state. The boot script is recorded 

+  during regular boot using the EFI_S3_SAVE_STATE_PROTOCOL.Write() and

+  EFI_S3_SMM_SAVE_STATE_PROTOCOL.Write() functions.  Finally, this function 

+  transfers control to the OS waking vector. If the OS supports only a real-mode 

+  waking vector, this function will switch from flat mode to real mode before 

+  jumping to the waking vector.  If all platform pre-boot configurations are 

+  successfully restored and all other necessary information is ready, this 

+  function will never return and instead will directly jump to the OS waking 

+  vector. If this function returns, it indicates that the attempt to resume 

+  from the ACPI S3 sleep state failed.  

+  

+  @param[in] PeiServices   Pointer to the PEI Services Table

+

+  @retval EFI_ABORTED     Execution of the S3 resume boot script table failed.

+  @retval EFI_NOT_FOUND   Some necessary information that is used for the S3 

+                          resume boot path could not be located.

+

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_PEI_S3_RESUME_PPI_RESTORE_CONFIG)(

+  IN EFI_PEI_SERVICES  **PeiServices

+  );

+

+/**

+  EFI_PEI_S3_RESUME_PPI accomplishes the firmware S3 resume boot

+  path and transfers control to OS.

+**/

+struct _EFI_PEI_S3_RESUME_PPI {

+  ///

+  /// Restores the platform to its preboot configuration for an S3 resume and

+  /// jumps to the OS waking vector.

+  ///

+  EFI_PEI_S3_RESUME_PPI_RESTORE_CONFIG  S3RestoreConfig;

+};

+

+extern EFI_GUID gEfiPeiS3ResumePpiGuid;

+

+#endif