Subrata Banik | 20fe24b | 2021-12-09 02:46:38 +0530 | [diff] [blame] | 1 | /** @file |
| 2 | S3 Save State Protocol as defined in PI 1.6(Errata A) Specification VOLUME 5 Standard. |
| 3 | |
| 4 | This protocol is used by DXE PI module to store or record various IO operations |
| 5 | to be replayed during an S3 resume. |
| 6 | This protocol is not required for all platforms. |
| 7 | |
| 8 | Copyright (c) 2009 - 2019, Intel Corporation. All rights reserved.<BR> |
| 9 | SPDX-License-Identifier: BSD-2-Clause-Patent |
| 10 | |
| 11 | @par Revision Reference: |
| 12 | This PPI is defined in UEFI Platform Initialization Specification 1.2 Volume 5: |
| 13 | Standards |
| 14 | |
| 15 | **/ |
| 16 | |
| 17 | #ifndef __S3_SAVE_STATE_H__ |
| 18 | #define __S3_SAVE_STATE_H__ |
| 19 | |
| 20 | #define EFI_S3_SAVE_STATE_PROTOCOL_GUID \ |
| 21 | { 0xe857caf6, 0xc046, 0x45dc, { 0xbe, 0x3f, 0xee, 0x7, 0x65, 0xfb, 0xa8, 0x87 }} |
| 22 | |
| 23 | |
| 24 | typedef VOID *EFI_S3_BOOT_SCRIPT_POSITION; |
| 25 | |
| 26 | typedef struct _EFI_S3_SAVE_STATE_PROTOCOL EFI_S3_SAVE_STATE_PROTOCOL; |
| 27 | |
| 28 | /** |
| 29 | Record operations that need to be replayed during an S3 resume. |
| 30 | |
| 31 | This function is used to store an OpCode to be replayed as part of the S3 resume boot path. It is |
| 32 | assumed this protocol has platform specific mechanism to store the OpCode set and replay them |
| 33 | during the S3 resume. |
| 34 | |
| 35 | @param[in] This A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance. |
| 36 | @param[in] OpCode The operation code (opcode) number. |
| 37 | @param[in] ... Argument list that is specific to each opcode. See the following subsections for the |
| 38 | definition of each opcode. |
| 39 | |
| 40 | @retval EFI_SUCCESS The operation succeeded. A record was added into the specified |
| 41 | script table. |
| 42 | @retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script is not supported. |
| 43 | @retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script. |
| 44 | **/ |
| 45 | typedef |
| 46 | EFI_STATUS |
| 47 | (EFIAPI *EFI_S3_SAVE_STATE_WRITE)( |
| 48 | IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This, |
| 49 | IN UINTN OpCode, |
| 50 | ... |
| 51 | ); |
| 52 | |
| 53 | /** |
| 54 | Record operations that need to be replayed during an S3 resume. |
| 55 | |
| 56 | This function is used to store an OpCode to be replayed as part of the S3 resume boot path. It is |
| 57 | assumed this protocol has platform specific mechanism to store the OpCode set and replay them |
| 58 | during the S3 resume. |
| 59 | The opcode is inserted before or after the specified position in the boot script table. If Position is |
| 60 | NULL then that position is after the last opcode in the table (BeforeOrAfter is TRUE) or before |
| 61 | the first opcode in the table (BeforeOrAfter is FALSE). The position which is pointed to by |
| 62 | Position upon return can be used for subsequent insertions. |
| 63 | |
| 64 | This function has a variable parameter list. The exact parameter list depends on the OpCode that is |
| 65 | passed into the function. If an unsupported OpCode or illegal parameter list is passed in, this |
| 66 | function returns EFI_INVALID_PARAMETER. |
| 67 | If there are not enough resources available for storing more scripts, this function returns |
| 68 | EFI_OUT_OF_RESOURCES. |
| 69 | OpCode values of 0x80 - 0xFE are reserved for implementation specific functions. |
| 70 | |
| 71 | @param[in] This A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance. |
| 72 | @param[in] BeforeOrAfter Specifies whether the opcode is stored before (TRUE) or after (FALSE) the position |
| 73 | in the boot script table specified by Position. If Position is NULL or points to |
| 74 | NULL then the new opcode is inserted at the beginning of the table (if TRUE) or end |
| 75 | of the table (if FALSE). |
| 76 | @param[in, out] Position On entry, specifies the position in the boot script table where the opcode will be |
| 77 | inserted, either before or after, depending on BeforeOrAfter. On exit, specifies |
| 78 | the position of the inserted opcode in the boot script table. |
| 79 | @param[in] OpCode The operation code (opcode) number. See "Related Definitions" in Write() for the |
| 80 | defined opcode types. |
| 81 | @param[in] ... Argument list that is specific to each opcode. See the following subsections for the |
| 82 | definition of each opcode. |
| 83 | |
| 84 | @retval EFI_SUCCESS The operation succeeded. An opcode was added into the script. |
| 85 | @retval EFI_INVALID_PARAMETER The Opcode is an invalid opcode value. |
| 86 | @retval EFI_INVALID_PARAMETER The Position is not a valid position in the boot script table. |
| 87 | @retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script table. |
| 88 | **/ |
| 89 | typedef |
| 90 | EFI_STATUS |
| 91 | (EFIAPI *EFI_S3_SAVE_STATE_INSERT)( |
| 92 | IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This, |
| 93 | IN BOOLEAN BeforeOrAfter, |
| 94 | IN OUT EFI_S3_BOOT_SCRIPT_POSITION *Position OPTIONAL, |
| 95 | IN UINTN OpCode, |
| 96 | ... |
| 97 | ); |
| 98 | |
| 99 | /** |
| 100 | Find a label within the boot script table and, if not present, optionally create it. |
| 101 | |
| 102 | If the label Label is already exists in the boot script table, then no new label is created, the |
| 103 | position of the Label is returned in *Position and EFI_SUCCESS is returned. |
| 104 | If the label Label does not already exist and CreateIfNotFound is TRUE, then it will be |
| 105 | created before or after the specified position and EFI_SUCCESS is returned. |
| 106 | If the label Label does not already exist and CreateIfNotFound is FALSE, then |
| 107 | EFI_NOT_FOUND is returned. |
| 108 | |
| 109 | @param[in] This A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance. |
| 110 | @param[in] BeforeOrAfter Specifies whether the label is stored before (TRUE) or after (FALSE) the position in |
| 111 | the boot script table specified by Position. If Position is NULL or points to |
| 112 | NULL then the new label is inserted at the beginning of the table (if TRUE) or end of |
| 113 | the table (if FALSE). |
| 114 | @param[in] CreateIfNotFound Specifies whether the label will be created if the label does not exists (TRUE) or not (FALSE). |
| 115 | @param[in, out] Position On entry, specifies the position in the boot script table where the label will be inserted, |
| 116 | either before or after, depending on BeforeOrAfter. On exit, specifies the position |
| 117 | of the inserted label in the boot script table. |
| 118 | @param[in] Label Points to the label which will be inserted in the boot script table. |
| 119 | |
| 120 | @retval EFI_SUCCESS The label already exists or was inserted. |
| 121 | @retval EFI_NOT_FOUND The label did not already exist and CreateifNotFound was FALSE. |
| 122 | @retval EFI_INVALID_PARAMETER The Label is NULL or points to an empty string. |
| 123 | @retval EFI_INVALID_PARAMETER The Position is not a valid position in the boot script table. |
| 124 | @retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script. |
| 125 | **/ |
| 126 | typedef |
| 127 | EFI_STATUS |
| 128 | (EFIAPI *EFI_S3_SAVE_STATE_LABEL)( |
| 129 | IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This, |
| 130 | IN BOOLEAN BeforeOrAfter, |
| 131 | IN BOOLEAN CreateIfNotFound, |
| 132 | IN OUT EFI_S3_BOOT_SCRIPT_POSITION *Position OPTIONAL, |
| 133 | IN CONST CHAR8 *Label |
| 134 | ); |
| 135 | |
| 136 | /** |
| 137 | Compare two positions in the boot script table and return their relative position. |
| 138 | |
| 139 | This function compares two positions in the boot script table and returns their relative positions. If |
| 140 | Position1 is before Position2, then -1 is returned. If Position1 is equal to Position2, |
| 141 | then 0 is returned. If Position1 is after Position2, then 1 is returned. |
| 142 | |
| 143 | @param[in] This A pointer to the EFI_S3_SAVE_STATE_PROTOCOL instance. |
| 144 | @param[in] Position1 The positions in the boot script table to compare. |
| 145 | @param[in] Position2 The positions in the boot script table to compare. |
| 146 | @param[out] RelativePosition On return, points to the result of the comparison. |
| 147 | |
| 148 | @retval EFI_SUCCESS The operation succeeded. |
| 149 | @retval EFI_INVALID_PARAMETER The Position1 or Position2 is not a valid position in the boot script table. |
| 150 | @retval EFI_INVALID_PARAMETER The RelativePosition is NULL. |
| 151 | **/ |
| 152 | typedef |
| 153 | EFI_STATUS |
| 154 | (EFIAPI *EFI_S3_SAVE_STATE_COMPARE)( |
| 155 | IN CONST EFI_S3_SAVE_STATE_PROTOCOL *This, |
| 156 | IN EFI_S3_BOOT_SCRIPT_POSITION Position1, |
| 157 | IN EFI_S3_BOOT_SCRIPT_POSITION Position2, |
| 158 | OUT UINTN *RelativePosition |
| 159 | ); |
| 160 | |
| 161 | struct _EFI_S3_SAVE_STATE_PROTOCOL { |
| 162 | EFI_S3_SAVE_STATE_WRITE Write; |
| 163 | EFI_S3_SAVE_STATE_INSERT Insert; |
| 164 | EFI_S3_SAVE_STATE_LABEL Label; |
| 165 | EFI_S3_SAVE_STATE_COMPARE Compare; |
| 166 | }; |
| 167 | |
| 168 | extern EFI_GUID gEfiS3SaveStateProtocolGuid; |
| 169 | |
| 170 | #endif // __S3_SAVE_STATE_H__ |