VariablePolicy.h@ 105670

Last change on this file since 105670 was 105670, checked in by vboxsync, 7 months ago
Devices/EFI/FirmwareNew: Merge edk2-stable-202405 and make it build on aarch64, bugref:4643
Property svn:eol-style set to `native`
File size: 12.8 KB

Line
1	/** @file -- VariablePolicy.h
2
3	This protocol allows communication with Variable Policy Engine.
4
5	Copyright (c) Microsoft Corporation.
6	SPDX-License-Identifier: BSD-2-Clause-Patent
7	**/
8
9	#ifndef __EDKII_VARIABLE_POLICY_PROTOCOL__
10	#define __EDKII_VARIABLE_POLICY_PROTOCOL__
11
12	#define EDKII_VARIABLE_POLICY_PROTOCOL_REVISION 0x0000000000020000
13
14	/*
15	Rev 0x0000000000010000:
16	- Initial protocol definition
17
18	Rev 0x0000000000020000:
19	- Add GetVariablePolicyInfo() API
20	- Add GetLockOnVariableStateVariablePolicyInfo() API
21
22	*/
23
24	#define EDKII_VARIABLE_POLICY_PROTOCOL_GUID \
25	{ \
26	0x81D1675C, 0x86F6, 0x48DF, { 0xBD, 0x95, 0x9A, 0x6E, 0x4F, 0x09, 0x25, 0xC3 } \
27	}
28
29	#define VARIABLE_POLICY_ENTRY_REVISION 0x00010000
30
31	#pragma pack(push, 1)
32	typedef struct {
33	UINT32 Version;
34	UINT16 Size;
35	UINT16 OffsetToName;
36	EFI_GUID Namespace;
37	UINT32 MinSize;
38	UINT32 MaxSize;
39	UINT32 AttributesMustHave;
40	UINT32 AttributesCantHave;
41	UINT8 LockPolicyType;
42	UINT8 Padding[3];
43	// UINT8 LockPolicy[]; // Variable Length Field
44	// CHAR16 Name[] // Variable Length Field
45	} VARIABLE_POLICY_ENTRY;
46
47	#define VARIABLE_POLICY_NO_MIN_SIZE 0
48	#define VARIABLE_POLICY_NO_MAX_SIZE MAX_UINT32
49	#define VARIABLE_POLICY_NO_MUST_ATTR 0
50	#define VARIABLE_POLICY_NO_CANT_ATTR 0
51
52	#define VARIABLE_POLICY_TYPE_NO_LOCK 0
53	#define VARIABLE_POLICY_TYPE_LOCK_NOW 1
54	#define VARIABLE_POLICY_TYPE_LOCK_ON_CREATE 2
55	#define VARIABLE_POLICY_TYPE_LOCK_ON_VAR_STATE 3
56
57	typedef struct {
58	EFI_GUID Namespace;
59	UINT8 Value;
60	UINT8 Padding;
61	// CHAR16 Name[]; // Variable Length Field
62	} VARIABLE_LOCK_ON_VAR_STATE_POLICY;
63	#pragma pack(pop)
64
65	/**
66	This API function disables the variable policy enforcement. If it's
67	already been called once, will return EFI_ALREADY_STARTED.
68
69	@retval EFI_SUCCESS
70	@retval EFI_ALREADY_STARTED Has already been called once this boot.
71	@retval EFI_WRITE_PROTECTED Interface has been locked until reboot.
72	@retval EFI_WRITE_PROTECTED Interface option is disabled by platform PCD.
73
74	**/
75	typedef
76	EFI_STATUS
77	(EFIAPI *DISABLE_VARIABLE_POLICY)(
78	VOID
79	);
80
81	/**
82	This API function returns whether or not the policy engine is
83	currently being enforced.
84
85	@param[out] State Pointer to a return value for whether the policy enforcement
86	is currently enabled.
87
88	@retval EFI_SUCCESS
89	@retval Others An error has prevented this command from completing.
90
91	**/
92	typedef
93	EFI_STATUS
94	(EFIAPI *IS_VARIABLE_POLICY_ENABLED)(
95	OUT BOOLEAN *State
96	);
97
98	/**
99	This API function validates and registers a new policy with
100	the policy enforcement engine.
101
102	@param[in] NewPolicy Pointer to the incoming policy structure.
103
104	@retval EFI_SUCCESS
105	@retval EFI_INVALID_PARAMETER NewPolicy is NULL or is internally inconsistent.
106	@retval EFI_ALREADY_STARTED An identical matching policy already exists.
107	@retval EFI_WRITE_PROTECTED The interface has been locked until the next reboot.
108	@retval EFI_ABORTED A calculation error has prevented this function from completing.
109	@retval EFI_OUT_OF_RESOURCES Cannot grow the table to hold any more policies.
110
111	**/
112	typedef
113	EFI_STATUS
114	(EFIAPI *REGISTER_VARIABLE_POLICY)(
115	IN CONST VARIABLE_POLICY_ENTRY *PolicyEntry
116	);
117
118	/**
119	This API function will dump the entire contents of the variable policy table.
120
121	Similar to GetVariable, the first call can be made with a 0 size and it will return
122	the size of the buffer required to hold the entire table.
123
124	@param[out] Policy Pointer to the policy buffer. Can be NULL if Size is 0.
125	@param[in,out] Size On input, the size of the output buffer. On output, the size
126	of the data returned.
127
128	@retval EFI_SUCCESS Policy data is in the output buffer and Size has been updated.
129	@retval EFI_INVALID_PARAMETER Size is NULL, or Size is non-zero and Policy is NULL.
130	@retval EFI_BUFFER_TOO_SMALL Size is insufficient to hold policy. Size updated with required size.
131
132	**/
133	typedef
134	EFI_STATUS
135	(EFIAPI *DUMP_VARIABLE_POLICY)(
136	IN OUT UINT8 *Policy,
137	IN OUT UINT32 *Size
138	);
139
140	/**
141	This API function locks the interface so that no more policy updates
142	can be performed or changes made to the enforcement until the next boot.
143
144	@retval EFI_SUCCESS
145	@retval Others An error has prevented this command from completing.
146
147	**/
148	typedef
149	EFI_STATUS
150	(EFIAPI *LOCK_VARIABLE_POLICY)(
151	VOID
152	);
153
154	/**
155	This function will return variable policy information for a UEFI variable with a
156	registered variable policy.
157
158	@param[in] VariableName The name of the variable to use for the policy search.
159	@param[in] VendorGuid The vendor GUID of the variable to use for the policy search.
160	@param[in,out] VariablePolicyVariableNameBufferSize On input, the size, in bytes, of the VariablePolicyVariableName
161	buffer.
162
163	On output, the size, in bytes, needed to store the variable
164	policy variable name.
165
166	If testing for the VariablePolicyVariableName buffer size
167	needed, set this value to zero so EFI_BUFFER_TOO_SMALL is
168	guaranteed to be returned if the variable policy variable name
169	is found.
170	@param[out] VariablePolicy Pointer to a buffer where the policy entry will be written
171	if found.
172	@param[out] VariablePolicyVariableName Pointer to a buffer where the variable name used for the
173	variable policy will be written if a variable name is
174	registered.
175
176	If the variable policy is not associated with a variable name
177	(e.g. applied to variable vendor namespace) and this parameter
178	is given, this parameter will not be modified and
179	VariablePolicyVariableNameBufferSize will be set to zero to
180	indicate a name was not present.
181
182	If the pointer given is not NULL,
183	VariablePolicyVariableNameBufferSize must be non-NULL.
184
185	@retval EFI_SUCCESS A variable policy entry was found and returned successfully.
186	@retval EFI_BAD_BUFFER_SIZE An internal buffer size caused a calculation error.
187	@retval EFI_BUFFER_TOO_SMALL The VariablePolicyVariableName buffer value is too small for the size needed.
188	The buffer should now point to the size needed.
189	@retval EFI_NOT_READY Variable policy has not yet been initialized.
190	@retval EFI_INVALID_PARAMETER A required pointer argument passed is NULL. This will be returned if
191	VariablePolicyVariableName is non-NULL and VariablePolicyVariableNameBufferSize
192	is NULL.
193	@retval EFI_NOT_FOUND A variable policy was not found for the given UEFI variable name and vendor GUID.
194
195	**/
196	typedef
197	EFI_STATUS
198	(EFIAPI *GET_VARIABLE_POLICY_INFO)(
199	IN CONST CHAR16 *VariableName,
200	IN CONST EFI_GUID *VendorGuid,
201	IN OUT UINTN *VariablePolicyVariableNameBufferSize OPTIONAL,
202	OUT VARIABLE_POLICY_ENTRY *VariablePolicy,
203	OUT CHAR16 *VariablePolicyVariableName OPTIONAL
204	);
205
206	/**
207	This function will return the Lock on Variable State policy information for the policy
208	associated with the given UEFI variable.
209
210	@param[in] VariableName The name of the variable to use for the policy search.
211	@param[in] VendorGuid The vendor GUID of the variable to use for the policy
212	search.
213	@param[in,out] VariableLockPolicyVariableNameBufferSize On input, the size, in bytes, of the
214	VariableLockPolicyVariableName buffer.
215
216	On output, the size, in bytes, needed to store the variable
217	policy variable name.
218
219	If testing for the VariableLockPolicyVariableName buffer
220	size needed, set this value to zero so EFI_BUFFER_TOO_SMALL
221	is guaranteed to be returned if the variable policy variable
222	name is found.
223	@param[out] VariablePolicy Pointer to a buffer where the policy entry will be written
224	if found.
225	@param[out] VariableLockPolicyVariableName Pointer to a buffer where the variable name used for the
226	variable lock on variable state policy will be written if
227	a variable name is registered.
228
229	If the lock on variable policy is not associated with a
230	variable name (e.g. applied to variable vendor namespace)
231	and this parameter is given, this parameter will not be
232	modified and VariableLockPolicyVariableNameBufferSize will
233	be set to zero to indicate a name was not present.
234
235	If the pointer given is not NULL,
236	VariableLockPolicyVariableNameBufferSize must be non-NULL.
237
238	@retval EFI_SUCCESS A Lock on Variable State variable policy entry was found and returned
239	successfully.
240	@retval EFI_BAD_BUFFER_SIZE An internal buffer size caused a calculation error.
241	@retval EFI_BUFFER_TOO_SMALL The VariableLockPolicyVariableName buffer is too small for the size needed.
242	The buffer should now point to the size needed.
243	@retval EFI_NOT_READY Variable policy has not yet been initialized.
244	@retval EFI_INVALID_PARAMETER A required pointer argument passed is NULL. This will be returned if
245	VariableLockPolicyVariableName is non-NULL and
246	VariableLockPolicyVariableNameBufferSize is NULL.
247	@retval EFI_NOT_FOUND A Lock on Variable State variable policy was not found for the given UEFI
248	variable name and vendor GUID.
249
250	**/
251	typedef
252	EFI_STATUS
253	(EFIAPI *GET_LOCK_ON_VARIABLE_STATE_VARIABLE_POLICY_INFO)(
254	IN CONST CHAR16 *VariableName,
255	IN CONST EFI_GUID *VendorGuid,
256	IN OUT UINTN *VariableLockPolicyVariableNameBufferSize OPTIONAL,
257	OUT VARIABLE_LOCK_ON_VAR_STATE_POLICY *VariablePolicy,
258	OUT CHAR16 *VariableLockPolicyVariableName OPTIONAL
259	);
260
261	typedef struct {
262	UINT64 Revision;
263	DISABLE_VARIABLE_POLICY DisableVariablePolicy;
264	IS_VARIABLE_POLICY_ENABLED IsVariablePolicyEnabled;
265	REGISTER_VARIABLE_POLICY RegisterVariablePolicy;
266	DUMP_VARIABLE_POLICY DumpVariablePolicy;
267	LOCK_VARIABLE_POLICY LockVariablePolicy;
268	GET_VARIABLE_POLICY_INFO GetVariablePolicyInfo;
269	GET_LOCK_ON_VARIABLE_STATE_VARIABLE_POLICY_INFO GetLockOnVariableStateVariablePolicyInfo;
270	} _EDKII_VARIABLE_POLICY_PROTOCOL;
271
272	typedef _EDKII_VARIABLE_POLICY_PROTOCOL EDKII_VARIABLE_POLICY_PROTOCOL;
273
274	extern EFI_GUID gEdkiiVariablePolicyProtocolGuid;
275
276	#endif

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/MdeModulePkg/Include/Protocol/VariablePolicy.h@ 105670

Download in other formats: