Ronak Kanabar | 1ae366f | 2023-06-07 01:21:56 +0530 | [diff] [blame^] | 1 | /** @file |
| 2 | EDKII PEI Variable PPI provides an implementation of variables |
| 3 | intended for use as a means to store data in the PEI environment. |
| 4 | |
| 5 | Copyright (c) 2022, Intel Corporation. All rights reserved.<BR> |
| 6 | SPDX-License-Identifier: BSD-2-Clause-Patent |
| 7 | |
| 8 | **/ |
| 9 | |
| 10 | #ifndef EDKII_PEI_VARIABLE_PPI_H_ |
| 11 | #define EDKII_PEI_VARIABLE_PPI_H_ |
| 12 | |
| 13 | #define EDKII_PEI_VARIABLE_PPI_GUID \ |
| 14 | { \ |
| 15 | 0xe7b2cd04, 0x4b14, 0x44c2, { 0xb7, 0x48, 0xce, 0xaf, 0x2b, 0x66, 0x4a, 0xb0 } \ |
| 16 | } |
| 17 | |
| 18 | typedef struct _EDKII_PEI_VARIABLE_PPI EDKII_PEI_VARIABLE_PPI; |
| 19 | |
| 20 | /** |
| 21 | This service retrieves a variable's value using its name and GUID. |
| 22 | |
| 23 | Read the specified variable from the UEFI variable store. If the Data |
| 24 | buffer is too small to hold the contents of the variable, |
| 25 | the error EFI_BUFFER_TOO_SMALL is returned and DataSize is set to the |
| 26 | required buffer size to obtain the data. |
| 27 | |
| 28 | @param[in] This A pointer to this instance of the EDKII_PEI_VARIABLE_PPI. |
| 29 | @param[in] VariableName A pointer to a null-terminated string that is the variable's name. |
| 30 | @param[in] VariableGuid A pointer to an EFI_GUID that is the variable's GUID. The combination of |
| 31 | VariableGuid and VariableName must be unique. |
| 32 | @param[out] Attributes If non-NULL, on return, points to the variable's attributes. |
| 33 | @param[in, out] DataSize On entry, points to the size in bytes of the Data buffer. |
| 34 | On return, points to the size of the data returned in Data. |
| 35 | @param[out] Data Points to the buffer which will hold the returned variable value. |
| 36 | May be NULL with a zero DataSize in order to determine the size of the |
| 37 | buffer needed. |
| 38 | |
| 39 | @retval EFI_SUCCESS The variable was read successfully. |
| 40 | @retval EFI_NOT_FOUND The variable was not found. |
| 41 | @retval EFI_BUFFER_TOO_SMALL The DataSize is too small for the resulting data. |
| 42 | DataSize is updated with the size required for |
| 43 | the specified variable. |
| 44 | @retval EFI_INVALID_PARAMETER VariableName, VariableGuid, DataSize or Data is NULL. |
| 45 | @retval EFI_DEVICE_ERROR The variable could not be retrieved because of a device error. |
| 46 | |
| 47 | **/ |
| 48 | typedef |
| 49 | EFI_STATUS |
| 50 | (EFIAPI *EDKII_PEI_GET_VARIABLE)( |
| 51 | IN CONST EDKII_PEI_VARIABLE_PPI *This, |
| 52 | IN CONST CHAR16 *VariableName, |
| 53 | IN CONST EFI_GUID *VariableGuid, |
| 54 | OUT UINT32 *Attributes OPTIONAL, |
| 55 | IN OUT UINTN *DataSize, |
| 56 | OUT VOID *Data OPTIONAL |
| 57 | ); |
| 58 | |
| 59 | /** |
| 60 | Return the next variable name and GUID. |
| 61 | |
| 62 | This function is called multiple times to retrieve the VariableName |
| 63 | and VariableGuid of all variables currently available in the system. |
| 64 | On each call, the previous results are passed into the interface, |
| 65 | and, on return, the interface returns the data for the next |
| 66 | variable. To get started, VariableName should initially contain L"\0" |
| 67 | and VariableNameSize should be sizeof(CHAR16). When the entire |
| 68 | variable list has been returned, EFI_NOT_FOUND is returned. |
| 69 | |
| 70 | @param[in] This A pointer to this instance of the EDKII_PEI_VARIABLE_PPI. |
| 71 | @param[in, out] VariableNameSize On entry, points to the size of the buffer pointed to by VariableName. |
| 72 | On return, the size of the variable name buffer. |
| 73 | @param[in, out] VariableName On entry, a pointer to a null-terminated string that is the variable's name. |
| 74 | On return, points to the next variable's null-terminated name string. |
| 75 | @param[in, out] VariableGuid On entry, a pointer to an EFI_GUID that is the variable's GUID. |
| 76 | On return, a pointer to the next variable's GUID. |
| 77 | |
| 78 | @retval EFI_SUCCESS The next variable name was read successfully. |
| 79 | @retval EFI_NOT_FOUND All variables have been enumerated. |
| 80 | @retval EFI_BUFFER_TOO_SMALL The VariableNameSize is too small for the resulting |
| 81 | data. VariableNameSize is updated with the size |
| 82 | required for the specified variable. |
| 83 | @retval EFI_INVALID_PARAMETER VariableName, VariableGuid or |
| 84 | VariableNameSize is NULL. |
| 85 | @retval EFI_DEVICE_ERROR The variable could not be retrieved because of a device error. |
| 86 | |
| 87 | **/ |
| 88 | typedef |
| 89 | EFI_STATUS |
| 90 | (EFIAPI *EDKII_PEI_GET_NEXT_VARIABLE_NAME)( |
| 91 | IN CONST EDKII_PEI_VARIABLE_PPI *This, |
| 92 | IN OUT UINTN *VariableNameSize, |
| 93 | IN OUT CHAR16 *VariableName, |
| 94 | IN OUT EFI_GUID *VariableGuid |
| 95 | ); |
| 96 | |
| 97 | /** |
| 98 | Sets the value of a variable. |
| 99 | |
| 100 | @param[in] This A pointer to this instance of the EDKII_PEI_VARIABLE_PPI. |
| 101 | @param[in] VariableName A Null-terminated string that is the name of the vendor's variable. |
| 102 | Each VariableName is unique for each VendorGuid. VariableName must |
| 103 | contain 1 or more characters. If VariableName is an empty string, |
| 104 | then EFI_INVALID_PARAMETER is returned. |
| 105 | @param[in] VendorGuid A unique identifier for the vendor. |
| 106 | @param[in] Attributes Attributes bitmask to set for the variable. |
| 107 | @param[in] DataSize The size in bytes of the Data buffer. Unless the EFI_VARIABLE_APPEND_WRITE |
| 108 | attribute is set, a size of zero causes the variable to be deleted. When the |
| 109 | EFI_VARIABLE_APPEND_WRITE attribute is set, then a SetVariable() call with a |
| 110 | DataSize of zero will not cause any change to the variable value. |
| 111 | @param[in] Data The contents for the variable. |
| 112 | |
| 113 | @retval EFI_SUCCESS The firmware has successfully stored the variable and its data as |
| 114 | defined by the Attributes. |
| 115 | @retval EFI_INVALID_PARAMETER An invalid combination of attribute bits, name, and GUID was supplied, or the |
| 116 | DataSize exceeds the maximum allowed. |
| 117 | @retval EFI_INVALID_PARAMETER VariableName is an empty string. |
| 118 | @retval EFI_OUT_OF_RESOURCES Not enough storage is available to hold the variable and its data. |
| 119 | @retval EFI_DEVICE_ERROR The variable could not be stored due to a hardware error. |
| 120 | @retval EFI_WRITE_PROTECTED The variable in question is read-only. |
| 121 | @retval EFI_WRITE_PROTECTED The variable in question cannot be deleted. |
| 122 | @retval EFI_SECURITY_VIOLATION The variable could not be written due to EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS, |
| 123 | or EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS, or |
| 124 | EFI_VARIABLE_ENHANCED_AUTHENTICATED_ACCESS being set. Writing to authenticated |
| 125 | variables is not supported in the PEI environment. Updates to authenticated |
| 126 | variables can be requested during PEI via the EFI_AUTHENTICATED_VARIABLE_HOB, but |
| 127 | these updates won't be written to non-volatile storage until later in DXE. |
| 128 | The EFI_AUTHENTICATED_VARIABLE_HOB is a HOB with the GUID |
| 129 | gEfiAuthenticatedVariableGuid. This HOB contains a VARIABLE_STORE_HEADER followed |
| 130 | by one or more UEFI variables, which are stored as DWORD aligned tuples of |
| 131 | (VARIABLE_HEADER + CHAR16 VariableName + VariableData). |
| 132 | See MdeModulePkg/Include/Guid/VariableFormat.h for these data structure |
| 133 | definitions and MdeModulePkg/Universal/Variable/RuntimeDxe/VariableParsing.c for |
| 134 | an example of how to parse these data structures. |
| 135 | @retval EFI_NOT_FOUND The variable trying to be updated or deleted was not found. |
| 136 | |
| 137 | **/ |
| 138 | typedef |
| 139 | EFI_STATUS |
| 140 | (EFIAPI *EDKII_PEI_SET_VARIABLE)( |
| 141 | IN CONST EDKII_PEI_VARIABLE_PPI *This, |
| 142 | IN CHAR16 *VariableName, |
| 143 | IN EFI_GUID *VendorGuid, |
| 144 | IN UINT32 Attributes, |
| 145 | IN UINTN DataSize, |
| 146 | IN VOID *Data |
| 147 | ); |
| 148 | |
| 149 | /** |
| 150 | Returns information about the UEFI variables. |
| 151 | |
| 152 | @param[in] This A pointer to this instance of the EDKII_PEI_VARIABLE_PPI. |
| 153 | @param[in] Attributes Attributes bitmask to specify the type of variables on |
| 154 | which to return information. |
| 155 | @param[out] MaximumVariableStorageSize On output the maximum size of the storage space |
| 156 | available for the EFI variables associated with the |
| 157 | attributes specified. |
| 158 | @param[out] RemainingVariableStorageSize Returns the remaining size of the storage space |
| 159 | available for the EFI variables associated with the |
| 160 | attributes specified. |
| 161 | @param[out] MaximumVariableSize Returns the maximum size of the individual EFI |
| 162 | variables associated with the attributes specified. |
| 163 | |
| 164 | @retval EFI_SUCCESS Valid answer returned. |
| 165 | @retval EFI_INVALID_PARAMETER An invalid combination of attribute bits was supplied |
| 166 | @retval EFI_UNSUPPORTED The attribute is not supported on this platform, and the |
| 167 | MaximumVariableStorageSize, |
| 168 | RemainingVariableStorageSize, MaximumVariableSize |
| 169 | are undefined. |
| 170 | |
| 171 | **/ |
| 172 | typedef |
| 173 | EFI_STATUS |
| 174 | (EFIAPI *EDKII_PEI_QUERY_VARIABLE_INFO)( |
| 175 | IN CONST EDKII_PEI_VARIABLE_PPI *This, |
| 176 | IN UINT32 Attributes, |
| 177 | OUT UINT64 *MaximumVariableStorageSize, |
| 178 | OUT UINT64 *RemainingVariableStorageSize, |
| 179 | OUT UINT64 *MaximumVariableSize |
| 180 | ); |
| 181 | |
| 182 | /// |
| 183 | /// PEI Variable PPI is intended for use as a means |
| 184 | /// to store data in the PEI environment. |
| 185 | /// |
| 186 | struct _EDKII_PEI_VARIABLE_PPI { |
| 187 | EDKII_PEI_GET_VARIABLE GetVariable; |
| 188 | EDKII_PEI_GET_NEXT_VARIABLE_NAME GetNextVariableName; |
| 189 | EDKII_PEI_SET_VARIABLE SetVariable; |
| 190 | EDKII_PEI_QUERY_VARIABLE_INFO QueryVariableInfo; |
| 191 | }; |
| 192 | |
| 193 | extern EFI_GUID gEdkiiPeiVariablePpiGuid; |
| 194 | |
| 195 | #endif |