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