Add definition of S3 save state from PI 1.2 specification.

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

1 files changed, 210 insertions, 0 deletions

diff --git a/MdePkg/Include/Protocol/S3SaveState.h b/MdePkg/Include/Protocol/S3SaveState.h
new file mode 100644
index 0000000000..a535764292
--- /dev/null
+++ b/MdePkg/Include/Protocol/S3SaveState.h
@@ -0,0 +1,210 @@
+/** @file

+  S3 Save State Protocol as defined in PI1.2 Specification VOLUME 5 Standard.

+

+  This protocol is used by DXE PI module to store or record various IO operations 

+  to be replayed during an S3 resume.

+  This protocol is not required for all platforms.

+  

+  Copyright (c) 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.             

+

+**/

+

+#ifndef __S3_SAVE_STATE_H__

+#define __S3_SAVE_STATE_H__

+

+#define EFI_S3_SAVE_STATE_PROTOCOL_GUID \

+    { 0xe857caf6, 0xc046, 0x45dc, { 0xbe, 0x3f, 0xee, 0x7, 0x65, 0xfb, 0xa8, 0x87 }}

+

+//*******************************************

+// EFI Boot Script Opcode definitions

+//*******************************************

+#define EFI_BOOT_SCRIPT_IO_WRITE_OPCODE                 0x00

+#define EFI_BOOT_SCRIPT_IO_READ_WRITE_OPCODE            0x01

+#define EFI_BOOT_SCRIPT_MEM_WRITE_OPCODE                0x02

+#define EFI_BOOT_SCRIPT_MEM_READ_WRITE_OPCODE           0x03

+#define EFI_BOOT_SCRIPT_PCI_CONFIG_WRITE_OPCODE         0x04

+#define EFI_BOOT_SCRIPT_PCI_CONFIG_READ_WRITE_OPCODE    0x05

+#define EFI_BOOT_SCRIPT_SMBUS_EXECUTE_OPCODE            0x06

+#define EFI_BOOT_SCRIPT_STALL_OPCODE                    0x07

+#define EFI_BOOT_SCRIPT_DISPATCH_OPCODE                 0x08

+#define EFI_BOOT_SCRIPT_DISPATCH_2_OPCODE               0x09

+#define EFI_BOOT_SCRIPT_INFORMATION_OPCODE              0x0A

+#define EFI_BOOT_SCRIPT_PCI_CONFIG2_WRITE_OPCODE        0x0B

+#define EFI_BOOT_SCRIPT_PCI_CONFIG2_READ_WRITE_OPCODE   0x0C

+#define EFI_BOOT_SCRIPT_IO_POLL_OPCODE                  0x0D

+#define EFI_BOOT_SCRIPT_MEM_POLL_OPCODE                 0x0E

+#define EFI_BOOT_SCRIPT_PCI_CONFIG_POLL_OPCODE          0x0F

+#define EFI_BOOT_SCRIPT_PCI_CONFIG2_POLL_OPCODE         0x10

+

+//*******************************************

+// EFI_BOOT_SCRIPT_WIDTH

+//*******************************************

+typedef enum {

+  EfiBootScriptWidthUint8,

+  EfiBootScriptWidthUint16,

+  EfiBootScriptWidthUint32,

+  EfiBootScriptWidthUint64,

+  EfiBootScriptWidthFifoUint8,

+  EfiBootScriptWidthFifoUint16,

+  EfiBootScriptWidthFifoUint32,

+  EfiBootScriptWidthFifoUint64,

+  EfiBootScriptWidthFillUint8,

+  EfiBootScriptWidthFillUint16,

+  EfiBootScriptWidthFillUint32,

+  EfiBootScriptWidthFillUint64,

+  EfiBootScriptWidthMaximum

+} EFI_BOOT_SCRIPT_WIDTH;

+

+typedef VOID *EFI_S3_BOOT_SCRIPT_POSITION;

+

+typedef struct _EFI_S3_SAVE_STATE_PROTOCOL  EFI_S3_SAVE_STATE_PROTOCOL;

+

+/**

+  Record operations that need to be replayed during an S3 resume.

+  

+  This function is used to store an OpCode to be replayed as part of the S3 resume boot path. It is

+  assumed this protocol has platform specific mechanism to store the OpCode set and replay them

+  during the S3 resume.

+  

+  @param[in]    This    A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.

+  @param[in]    OpCode  The operation code (opcode) number.

+  @param[in]    ...     Argument list that is specific to each opcode. See the following subsections for the

+                        definition of each opcode.

+                        

+  @retval EFI_SUCCESS           The operation succeeded. A record was added into the specified

+                                script table.                    

+  @retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script is not supported.

+  @retval EFI_OUT_OF_RESOURCES  There is insufficient memory to store the boot script.                       

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_S3_SAVE_STATE_WRITE)(

+   IN CONST struct _EFI_S3_SAVE_STATE_PROTOCOL  *This,

+   IN       UINT16                              OpCode,

+   ...

+);

+

+/**

+  Record operations that need to be replayed during an S3 resume.

+  

+  This function is used to store an OpCode to be replayed as part of the S3 resume boot path. It is

+  assumed this protocol has platform specific mechanism to store the OpCode set and replay them

+  during the S3 resume.

+  The opcode is inserted before or after the specified position in the boot script table. If Position is

+  NULL then that position is after the last opcode in the table (BeforeOrAfter is TRUE) or before

+  the first opcode in the table (BeforeOrAfter is FALSE). The position which is pointed to by

+  Position upon return can be used for subsequent insertions.

+  

+  This function has a variable parameter list. The exact parameter list depends on the OpCode that is

+  passed into the function. If an unsupported OpCode or illegal parameter list is passed in, this

+  function returns EFI_INVALID_PARAMETER.

+  If there are not enough resources available for storing more scripts, this function returns

+  EFI_OUT_OF_RESOURCES.

+  OpCode values of 0x80 - 0xFE are reserved for implementation specific functions.

+  

+  @param[in]        This            A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.

+  @param[in]        BeforeOrAfter   Specifies whether the opcode is stored before (TRUE) or after (FALSE) the position

+                                    in the boot script table specified by Position. If Position is NULL or points to

+                                    NULL then the new opcode is inserted at the beginning of the table (if TRUE) or end

+                                    of the table (if FALSE).

+  @param[in, out]   Position        On entry, specifies the position in the boot script table where the opcode will be

+                                    inserted, either before or after, depending on BeforeOrAfter. On exit, specifies

+                                    the position of the inserted opcode in the boot script table.

+  @param[in]        OpCode          The operation code (opcode) number. See "Related Definitions" in Write() for the

+                                    defined opcode types.

+  @param[in]        ...             Argument list that is specific to each opcode. See the following subsections for the

+                                    definition of each opcode. 

+                                    

+  @retval EFI_SUCCESS               The operation succeeded. An opcode was added into the script.

+  @retval EFI_INVALID_PARAMETER     The Opcode is an invalid opcode value.

+  @retval EFI_INVALID_PARAMETER     The Position is not a valid position in the boot script table.

+  @retval EFI_OUT_OF_RESOURCES      There is insufficient memory to store the boot script table.                                                                       

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_S3_SAVE_STATE_INSERT)(

+   IN       struct _EFI_S3_SAVE_STATE_PROTOCOL  *This,

+   IN       BOOLEAN                             BeforeOrAfter,

+   IN OUT   EFI_S3_BOOT_SCRIPT_POSITION         *Position       OPTIONAL,

+   IN       UINT16                              OpCode,

+   ...

+);

+

+/**

+  Find a label within the boot script table and, if not present, optionally create it.

+  

+  If the label Label is already exists in the boot script table, then no new label is created, the

+  position of the Label is returned in *Position and EFI_SUCCESS is returned.

+  If the label Label does not already exist and CreateIfNotFound is TRUE, then it will be

+  created before or after the specified position and EFI_SUCCESS is returned.

+  If the label Label does not already exist and CreateIfNotFound is FALSE, then

+  EFI_NOT_FOUND is returned.

+  

+  @param[in]      This                A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.

+  @param[in]      BeforeOrAfter       Specifies whether the label is stored before (TRUE) or after (FALSE) the position in

+                                      the boot script table specified by Position. If Position is NULL or points to

+                                      NULL then the new label is inserted at the beginning of the table (if TRUE) or end of

+                                      the table (if FALSE).

+  @param[in]      CreateIfNotFound    Specifies whether the label will be created if the label does not exists (TRUE) or not (FALSE).

+  @param[in, out] Position            On entry, specifies the position in the boot script table where the label will be inserted,

+                                      either before or after, depending on BeforeOrAfter. On exit, specifies the position

+                                      of the inserted label in the boot script table.

+  @param[in]      Label               Points to the label which will be inserted in the boot script table.

+  

+  @retval    EFI_SUCCESS              The label already exists or was inserted.

+  @retval    EFI_NOT_FOUND            The label did not already exist and CreateifNotFound was FALSE.

+  @retval    EFI_INVALID_PARAMETER    The Opcode is an invalid opcode value.

+  @retval    EFI_INVALID_PARAMETER    The Position is not a valid position in the boot script table.

+  @retval    EFI_OUT_OF_RESOURCES     There is insufficient memory to store the boot script.

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_S3_SAVE_STATE_LABEL)(

+   IN     struct _EFI_S3_SAVE_STATE_PROTOCOL    *This,

+   IN     BOOLEAN                               BeforeOrAfter,

+   IN     BOOLEAN                               CreateIfNotFound,

+   IN OUT EFI_S3_BOOT_SCRIPT_POSITION           *Position OPTIONAL,

+   IN     CONST CHAR8                           *Label

+);

+

+/**

+  Compare two positions in the boot script table and return their relative position.

+  

+  This function compares two positions in the boot script table and returns their relative positions. If

+  Position1 is before Position2, then -1 is returned. If Position1 is equal to Position2,

+  then 0 is returned. If Position1 is after Position2, then 1 is returned.

+  

+  @param[in]    This                A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance.

+  @param[in]    Position1           The positions in the boot script table to compare.

+  @param[in]    Position2           The positions in the boot script table to compare.

+  @param[out]   RelativePosition    On return, points to the result of the comparison.

+  

+  @retval   EFI_SUCCESS             The label already exists or was inserted.

+  @retval   EFI_INVALID_PARAMETER   The Position1 or Position2 is not a valid position in the boot script table.

+**/

+typedef

+EFI_STATUS

+(EFIAPI *EFI_S3_SAVE_STATE_COMPARE)(

+   IN   struct _EFI_S3_SAVE_STATE_PROTOCOL  *This,

+   IN   EFI_S3_BOOT_SCRIPT_POSITION         Position1,

+   IN   EFI_S3_BOOT_SCRIPT_POSITION         Position2,

+   OUT  UINTN                               *RelativePosition

+);

+

+struct _EFI_S3_SAVE_STATE_PROTOCOL {

+  EFI_S3_SAVE_STATE_WRITE   Write;

+  EFI_S3_SAVE_STATE_INSERT  Insert;

+  EFI_S3_SAVE_STATE_LABEL   Label;

+  EFI_S3_SAVE_STATE_COMPARE Compare;

+};

+

+extern EFI_GUID gEfiS3SaveStateProtocolGuid;

+

+#endif // __S3_SAVE_STATE_H__