[mirror_edk2.git] / IntelFsp2Pkg / Include / Ppi / Variable.h

/** @file\r
  EDKII PEI Variable PPI provides an implementation of variables\r
  intended for use as a means to store data in the PEI environment.\r
\r
  Copyright (c) 2022, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef EDKII_PEI_VARIABLE_PPI_H_\r
#define EDKII_PEI_VARIABLE_PPI_H_\r
\r
#define EDKII_PEI_VARIABLE_PPI_GUID \\r
  { \\r
    0xe7b2cd04, 0x4b14, 0x44c2, { 0xb7, 0x48, 0xce, 0xaf, 0x2b, 0x66, 0x4a, 0xb0 } \\r
  }\r
\r
typedef struct _EDKII_PEI_VARIABLE_PPI EDKII_PEI_VARIABLE_PPI;\r
\r
/**\r
  This service retrieves a variable's value using its name and GUID.\r
\r
  Read the specified variable from the UEFI variable store. If the Data\r
  buffer is too small to hold the contents of the variable,\r
  the error EFI_BUFFER_TOO_SMALL is returned and DataSize is set to the\r
  required buffer size to obtain the data.\r
\r
  @param[in]        This              A pointer to this instance of the EDKII_PEI_VARIABLE_PPI.\r
  @param[in]        VariableName      A pointer to a null-terminated string that is the variable's name.\r
  @param[in]        VariableGuid      A pointer to an EFI_GUID that is the variable's GUID. The combination of\r
                                      VariableGuid and VariableName must be unique.\r
  @param[out]       Attributes        If non-NULL, on return, points to the variable's attributes.\r
  @param[in, out]   DataSize          On entry, points to the size in bytes of the Data buffer.\r
                                      On return, points to the size of the data returned in Data.\r
  @param[out]       Data              Points to the buffer which will hold the returned variable value.\r
                                      May be NULL with a zero DataSize in order to determine the size of the\r
                                      buffer needed.\r
\r
  @retval EFI_SUCCESS                 The variable was read successfully.\r
  @retval EFI_NOT_FOUND               The variable was not found.\r
  @retval EFI_BUFFER_TOO_SMALL        The DataSize is too small for the resulting data.\r
                                      DataSize is updated with the size required for\r
                                      the specified variable.\r
  @retval EFI_INVALID_PARAMETER       VariableName, VariableGuid, DataSize or Data is NULL.\r
  @retval EFI_DEVICE_ERROR            The variable could not be retrieved because of a device error.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EDKII_PEI_GET_VARIABLE)(\r
  IN CONST  EDKII_PEI_VARIABLE_PPI    *This,\r
  IN CONST  CHAR16                    *VariableName,\r
  IN CONST  EFI_GUID                  *VariableGuid,\r
  OUT       UINT32                    *Attributes   OPTIONAL,\r
  IN OUT    UINTN                     *DataSize,\r
  OUT       VOID                      *Data         OPTIONAL\r
  );\r
\r
/**\r
  Return the next variable name and GUID.\r
\r
  This function is called multiple times to retrieve the VariableName\r
  and VariableGuid of all variables currently available in the system.\r
  On each call, the previous results are passed into the interface,\r
  and, on return, the interface returns the data for the next\r
  variable. To get started, VariableName should initially contain L"\0"\r
  and VariableNameSize should be sizeof(CHAR16). When the entire\r
  variable list has been returned, EFI_NOT_FOUND is returned.\r
\r
  @param[in]        This              A pointer to this instance of the EDKII_PEI_VARIABLE_PPI.\r
  @param[in, out]   VariableNameSize  On entry, points to the size of the buffer pointed to by VariableName.\r
                                      On return, the size of the variable name buffer.\r
  @param[in, out]   VariableName      On entry, a pointer to a null-terminated string that is the variable's name.\r
                                      On return, points to the next variable's null-terminated name string.\r
  @param[in, out]   VariableGuid      On entry, a pointer to an EFI_GUID that is the variable's GUID.\r
                                      On return, a pointer to the next variable's GUID.\r
\r
  @retval EFI_SUCCESS                 The next variable name was read successfully.\r
  @retval EFI_NOT_FOUND               All variables have been enumerated.\r
  @retval EFI_BUFFER_TOO_SMALL        The VariableNameSize is too small for the resulting\r
                                      data. VariableNameSize is updated with the size\r
                                      required for the specified variable.\r
  @retval EFI_INVALID_PARAMETER       VariableName, VariableGuid or\r
                                      VariableNameSize is NULL.\r
  @retval EFI_DEVICE_ERROR            The variable could not be retrieved because of a device error.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EDKII_PEI_GET_NEXT_VARIABLE_NAME)(\r
  IN CONST  EDKII_PEI_VARIABLE_PPI    *This,\r
  IN OUT    UINTN                     *VariableNameSize,\r
  IN OUT    CHAR16                    *VariableName,\r
  IN OUT    EFI_GUID                  *VariableGuid\r
  );\r
\r
/**\r
  Sets the value of a variable.\r
\r
  @param[in]        This              A pointer to this instance of the EDKII_PEI_VARIABLE_PPI.\r
  @param[in]        VariableName      A Null-terminated string that is the name of the vendor's variable.\r
                                      Each VariableName is unique for each VendorGuid. VariableName must\r
                                      contain 1 or more characters. If VariableName is an empty string,\r
                                      then EFI_INVALID_PARAMETER is returned.\r
  @param[in]        VendorGuid        A unique identifier for the vendor.\r
  @param[in]        Attributes        Attributes bitmask to set for the variable.\r
  @param[in]        DataSize          The size in bytes of the Data buffer. Unless the EFI_VARIABLE_APPEND_WRITE\r
                                      attribute is set, a size of zero causes the variable to be deleted. When the\r
                                      EFI_VARIABLE_APPEND_WRITE attribute is set, then a SetVariable() call with a\r
                                      DataSize of zero will not cause any change to the variable value.\r
  @param[in]        Data              The contents for the variable.\r
\r
  @retval EFI_SUCCESS                 The firmware has successfully stored the variable and its data as\r
                                      defined by the Attributes.\r
  @retval EFI_INVALID_PARAMETER       An invalid combination of attribute bits, name, and GUID was supplied, or the\r
                                      DataSize exceeds the maximum allowed.\r
  @retval EFI_INVALID_PARAMETER       VariableName is an empty string.\r
  @retval EFI_OUT_OF_RESOURCES        Not enough storage is available to hold the variable and its data.\r
  @retval EFI_DEVICE_ERROR            The variable could not be stored due to a hardware error.\r
  @retval EFI_WRITE_PROTECTED         The variable in question is read-only.\r
  @retval EFI_WRITE_PROTECTED         The variable in question cannot be deleted.\r
  @retval EFI_SECURITY_VIOLATION      The variable could not be written due to EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS,\r
                                      or EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS, or\r
                                      EFI_VARIABLE_ENHANCED_AUTHENTICATED_ACCESS being set. Writing to authenticated\r
                                      variables is not supported in the PEI environment. Updates to authenticated\r
                                      variables can be requested during PEI via the EFI_AUTHENTICATED_VARIABLE_HOB, but\r
                                      these updates won't be written to non-volatile storage until later in DXE.\r
                                      The EFI_AUTHENTICATED_VARIABLE_HOB is a HOB with the GUID\r
                                      gEfiAuthenticatedVariableGuid. This HOB contains a VARIABLE_STORE_HEADER followed\r
                                      by one or more UEFI variables, which are stored as DWORD aligned tuples of\r
                                      (VARIABLE_HEADER + CHAR16 VariableName + VariableData).\r
                                      See MdeModulePkg/Include/Guid/VariableFormat.h for these data structure\r
                                      definitions and MdeModulePkg/Universal/Variable/RuntimeDxe/VariableParsing.c for\r
                                      an example of how to parse these data structures.\r
  @retval EFI_NOT_FOUND               The variable trying to be updated or deleted was not found.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EDKII_PEI_SET_VARIABLE)(\r
  IN CONST  EDKII_PEI_VARIABLE_PPI    *This,\r
  IN        CHAR16                    *VariableName,\r
  IN        EFI_GUID                  *VendorGuid,\r
  IN        UINT32                    Attributes,\r
  IN        UINTN                     DataSize,\r
  IN        VOID                      *Data\r
  );\r
\r
/**\r
  Returns information about the UEFI variables.\r
\r
  @param[in]        This                          A pointer to this instance of the EDKII_PEI_VARIABLE_PPI.\r
  @param[in]        Attributes                    Attributes bitmask to specify the type of variables on\r
                                                  which to return information.\r
  @param[out]       MaximumVariableStorageSize    On output the maximum size of the storage space\r
                                                  available for the EFI variables associated with the\r
                                                  attributes specified.\r
  @param[out]       RemainingVariableStorageSize  Returns the remaining size of the storage space\r
                                                  available for the EFI variables associated with the\r
                                                  attributes specified.\r
  @param[out]       MaximumVariableSize           Returns the maximum size of the individual EFI\r
                                                  variables associated with the attributes specified.\r
\r
  @retval EFI_SUCCESS                             Valid answer returned.\r
  @retval EFI_INVALID_PARAMETER                   An invalid combination of attribute bits was supplied\r
  @retval EFI_UNSUPPORTED                         The attribute is not supported on this platform, and the\r
                                                  MaximumVariableStorageSize,\r
                                                  RemainingVariableStorageSize, MaximumVariableSize\r
                                                  are undefined.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EDKII_PEI_QUERY_VARIABLE_INFO)(\r
  IN CONST  EDKII_PEI_VARIABLE_PPI    *This,\r
  IN        UINT32                    Attributes,\r
  OUT       UINT64                    *MaximumVariableStorageSize,\r
  OUT       UINT64                    *RemainingVariableStorageSize,\r
  OUT       UINT64                    *MaximumVariableSize\r
  );\r
\r
///\r
/// PEI Variable PPI is intended for use as a means\r
/// to store data in the PEI environment.\r
///\r
struct _EDKII_PEI_VARIABLE_PPI {\r
  EDKII_PEI_GET_VARIABLE            GetVariable;\r
  EDKII_PEI_GET_NEXT_VARIABLE_NAME  GetNextVariableName;\r
  EDKII_PEI_SET_VARIABLE            SetVariable;\r
  EDKII_PEI_QUERY_VARIABLE_INFO     QueryVariableInfo;\r
};\r
\r
extern EFI_GUID  gEdkiiPeiVariablePpiGuid;\r
\r
#endif\r
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