From 938e182117505d0e42759ba85b15599bd7844ec7 Mon Sep 17 00:00:00 2001 From: klu2 Date: Tue, 18 Aug 2009 07:07:02 +0000 Subject: [PATCH] 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 --- MdePkg/Include/Protocol/S3SaveState.h | 210 ++++++++++++++++++++++++++ MdePkg/MdePkg.dec | 9 +- 2 files changed, 216 insertions(+), 3 deletions(-) create mode 100644 MdePkg/Include/Protocol/S3SaveState.h 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__ diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index 9e1034ed2a..de51c66d31 100644 --- a/MdePkg/MdePkg.dec +++ b/MdePkg/MdePkg.dec @@ -544,6 +544,12 @@ # Include/Protocol/DiskInfo.h gEfiDiskInfoProtocolGuid = { 0xD432A67F, 0x14DC, 0x484B, { 0xB3, 0xBB, 0x3F, 0x02, 0x91, 0x84, 0x93, 0x27 }} + ## Include/Protocol/Smbios.h + gEfiSmbiosProtocolGuid = {0x3583ff6, 0xcb36, 0x4940, {0x94, 0x7e, 0xb9, 0xb3, 0x9f, 0x4a, 0xfa, 0xf7}} + + ## Include/Protocol/S3SaveState.h + gEfiS3SaveStateProtocolGuid = {0xe857caf6, 0xc046, 0x45dc, {0xbe, 0x3f, 0xee, 0x7, 0x65, 0xfb, 0xa8, 0x87}} + # # Protocols defined in UEFI2.1/UEFI2.0/EFI1.1 # @@ -806,9 +812,6 @@ ## Include/Protocol/HiiPackageList.h gEfiHiiPackageListProtocolGuid = { 0x6a1ee763, 0xd47a, 0x43b4, {0xaa, 0xbe, 0xef, 0x1d, 0xe2, 0xab, 0x56, 0xfc}} - ## Include/Protocol/Smbios.h - gEfiSmbiosProtocolGuid = {0x3583ff6, 0xcb36, 0x4940, {0x94, 0x7e, 0xb9, 0xb3, 0x9f, 0x4a, 0xfa, 0xf7}} - [PcdsFeatureFlag] ## If TRUE, the component name protocol will not be installed. gEfiMdePkgTokenSpaceGuid.PcdComponentNameDisable|FALSE|BOOLEAN|0x0000000d