OvmfPkg/MemEncryptSevLib: find pages of initial SMRAM save state map
[mirror_edk2.git] / OvmfPkg / Include / Library / QemuFwCfgS3Lib.h
CommitLineData
f70b071e
LE
1/** @file\r
2 S3 support for QEMU fw_cfg\r
3\r
4 This library class enables driver modules (a) to query whether S3 support was\r
5 enabled on the QEMU command line, (b) to produce fw_cfg DMA operations that\r
6 are to be replayed at S3 resume time.\r
7\r
8 Copyright (C) 2017, Red Hat, Inc.\r
9\r
10 This program and the accompanying materials are licensed and made available\r
11 under the terms and conditions of the BSD License which accompanies this\r
12 distribution. The full text of the license may be found at\r
13 http://opensource.org/licenses/bsd-license.php\r
14\r
15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT\r
16 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
17**/\r
18\r
19#ifndef __FW_CFG_S3_LIB__\r
20#define __FW_CFG_S3_LIB__\r
21\r
06a265b9
LE
22#include <Base.h>\r
23\r
f70b071e
LE
24/**\r
25 Determine if S3 support is explicitly enabled.\r
26\r
27 @retval TRUE If S3 support is explicitly enabled. Other functions in this\r
28 library may be called (subject to their individual\r
29 restrictions).\r
30\r
31 FALSE Otherwise. This includes unavailability of the firmware\r
32 configuration interface. No other function in this library\r
33 must be called.\r
34**/\r
35BOOLEAN\r
36EFIAPI\r
37QemuFwCfgS3Enabled (\r
38 VOID\r
39 );\r
40\r
06a265b9
LE
41\r
42/**\r
43 Prototype for the callback function that the client module provides.\r
44\r
45 In the callback function, the client module calls the\r
46 QemuFwCfgS3ScriptWriteBytes(), QemuFwCfgS3ScriptReadBytes(),\r
47 QemuFwCfgS3ScriptSkipBytes(), and QemuFwCfgS3ScriptCheckValue() functions.\r
48 Those functions produce ACPI S3 Boot Script opcodes that will perform fw_cfg\r
49 DMA operations, and will check any desired values that were read, during S3\r
50 resume.\r
51\r
52 The callback function is invoked when the production of ACPI S3 Boot Script\r
53 opcodes becomes possible. This may occur directly on the call stack of\r
54 QemuFwCfgS3CallWhenBootScriptReady() (see below), or after\r
55 QemuFwCfgS3CallWhenBootScriptReady() has successfully returned.\r
56\r
57 The callback function must not return if it fails -- in the general case,\r
58 there is noone to propagate any errors to. Therefore, on error, an error\r
59 message should be logged, and CpuDeadLoop() must be called.\r
60\r
61 @param[in,out] Context Carries information from the client module\r
62 itself (i.e., from the invocation of\r
63 QemuFwCfgS3CallWhenBootScriptReady()) to the\r
64 callback function.\r
65\r
66 If Context points to dynamically allocated\r
67 storage, then the callback function must\r
68 release it.\r
69\r
70 @param[in,out] ScratchBuffer Points to reserved memory, allocated by\r
71 QemuFwCfgS3CallWhenBootScriptReady()\r
72 internally.\r
73\r
74 ScratchBuffer is typed and sized by the client\r
75 module when it calls\r
76 QemuFwCfgS3CallWhenBootScriptReady(). The\r
77 client module defines a union type of\r
78 structures for ScratchBuffer such that the\r
79 union can hold client data for any desired\r
80 fw_cfg DMA read and write operations, and value\r
81 checking.\r
82\r
83 The callback function casts ScratchBuffer to\r
84 the union type described above. It passes union\r
85 member sizes as NumberOfBytes to\r
86 QemuFwCfgS3ScriptReadBytes() and\r
87 QemuFwCfgS3ScriptWriteBytes(). It passes field\r
88 addresses and sizes in structures in the union\r
89 as ScratchData and ValueSize to\r
90 QemuFwCfgS3ScriptCheckValue().\r
91\r
92 ScratchBuffer is aligned at 8 bytes.\r
93**/\r
94typedef\r
95VOID (EFIAPI FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION) (\r
96 IN OUT VOID *Context, OPTIONAL\r
97 IN OUT VOID *ScratchBuffer\r
98 );\r
99\r
100\r
101/**\r
102 Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for\r
103 when the production of ACPI S3 Boot Script opcodes becomes possible.\r
104\r
105 Take ownership of the client-provided Context, and pass it to the callback\r
106 function, when the latter is invoked.\r
107\r
108 Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon\r
109 that the client will produce in the callback function.\r
110\r
111 @param[in] Callback FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke\r
112 when the production of ACPI S3 Boot Script\r
113 opcodes becomes possible. Callback() may be\r
114 called immediately from\r
115 QemuFwCfgS3CallWhenBootScriptReady().\r
116\r
117 @param[in,out] Context Client-provided data structure for the\r
118 Callback() callback function to consume.\r
119\r
120 If Context points to dynamically allocated\r
121 memory, then Callback() must release it.\r
122\r
123 If Context points to dynamically allocated\r
124 memory, and\r
125 QemuFwCfgS3CallWhenBootScriptReady() returns\r
126 successfully, then the caller of\r
127 QemuFwCfgS3CallWhenBootScriptReady() must\r
128 neither dereference nor even evaluate Context\r
129 any longer, as ownership of the referenced area\r
130 has been transferred to Callback().\r
131\r
132 @param[in] ScratchBufferSize The size of the scratch buffer that will hold,\r
133 in reserved memory, all client data read,\r
134 written, and checked by the ACPI S3 Boot Script\r
135 opcodes produced by Callback().\r
136\r
137 @retval RETURN_UNSUPPORTED The library instance does not support this\r
138 function.\r
139\r
140 @retval RETURN_NOT_FOUND The fw_cfg DMA interface to QEMU is\r
141 unavailable.\r
142\r
143 @retval RETURN_BAD_BUFFER_SIZE ScratchBufferSize is too large.\r
144\r
145 @retval RETURN_OUT_OF_RESOURCES Memory allocation failed.\r
146\r
147 @retval RETURN_SUCCESS Callback() has been installed, and the\r
148 ownership of Context has been transferred.\r
149 Reserved memory has been allocated for the\r
150 scratch buffer.\r
151\r
152 A successful invocation of\r
153 QemuFwCfgS3CallWhenBootScriptReady() cannot\r
154 be rolled back.\r
155\r
156 @return Error codes from underlying functions.\r
157**/\r
06a265b9 158RETURN_STATUS\r
08bed3fb 159EFIAPI\r
06a265b9
LE
160QemuFwCfgS3CallWhenBootScriptReady (\r
161 IN FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION *Callback,\r
162 IN OUT VOID *Context, OPTIONAL\r
163 IN UINTN ScratchBufferSize\r
164 );\r
165\r
166\r
167/**\r
168 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
169 and transfer data to it.\r
170\r
171 The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore\r
172 NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write\r
173 them to fw_cfg using DMA.\r
174\r
175 If the operation fails during S3 resume, the boot script will hang.\r
176\r
177 This function may only be called from the client module's\r
178 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
179 QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
180\r
181 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
182 item to write, expressed as INT32. If\r
183 FirmwareConfigItem is -1, no selection is\r
184 made, the write will occur to the currently\r
185 selected item, at its currently selected\r
186 offset. Otherwise, the specified item will be\r
187 selected, and the write will occur at offset\r
188 0.\r
189\r
190 @param[in] NumberOfBytes Size of the data to restore in ScratchBuffer,\r
191 and to write from ScratchBuffer, during S3\r
192 resume. NumberOfBytes must not exceed\r
193 ScratchBufferSize, which was passed to\r
194 QemuFwCfgS3CallWhenBootScriptReady().\r
195\r
196 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
197 Boot Script successfully. There is no way\r
198 to undo this action.\r
199\r
200 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
201\r
202 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than\r
203 ScratchBufferSize.\r
204\r
205 @return Error codes from underlying functions.\r
206**/\r
06a265b9 207RETURN_STATUS\r
08bed3fb 208EFIAPI\r
06a265b9
LE
209QemuFwCfgS3ScriptWriteBytes (\r
210 IN INT32 FirmwareConfigItem,\r
211 IN UINTN NumberOfBytes\r
212 );\r
213\r
214\r
215/**\r
216 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
217 and transfer data from it.\r
218\r
219 The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes\r
220 bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved\r
221 memory.\r
222\r
223 If the operation fails during S3 resume, the boot script will hang.\r
224\r
225 This function may only be called from the client module's\r
226 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
227 QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
228\r
229 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
230 item to read, expressed as INT32. If\r
231 FirmwareConfigItem is -1, no selection is\r
232 made, the read will occur from the currently\r
233 selected item, from its currently selected\r
234 offset. Otherwise, the specified item will be\r
235 selected, and the read will occur from offset\r
236 0.\r
237\r
238 @param[in] NumberOfBytes Size of the data to read during S3 resume.\r
239 NumberOfBytes must not exceed\r
240 ScratchBufferSize, which was passed to\r
241 QemuFwCfgS3CallWhenBootScriptReady().\r
242\r
243 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
244 Boot Script successfully. There is no way\r
245 to undo this action.\r
246\r
247 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
248\r
249 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than\r
250 ScratchBufferSize.\r
251\r
252 @return Error codes from underlying functions.\r
253**/\r
06a265b9 254RETURN_STATUS\r
08bed3fb 255EFIAPI\r
06a265b9
LE
256QemuFwCfgS3ScriptReadBytes (\r
257 IN INT32 FirmwareConfigItem,\r
258 IN UINTN NumberOfBytes\r
259 );\r
260\r
261\r
262/**\r
263 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
264 and increase its offset.\r
265\r
266 If the operation fails during S3 resume, the boot script will hang.\r
267\r
268 This function may only be called from the client module's\r
269 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
270 QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
271\r
272 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
273 item to advance the offset of, expressed as\r
274 INT32. If FirmwareConfigItem is -1, no\r
275 selection is made, and the offset for the\r
276 currently selected item is increased.\r
277 Otherwise, the specified item will be\r
278 selected, and the offset increment will occur\r
279 from offset 0.\r
280\r
281 @param[in] NumberOfBytes The number of bytes to skip in the subject\r
282 fw_cfg item.\r
283\r
284 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
285 Boot Script successfully. There is no way\r
286 to undo this action.\r
287\r
288 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
289\r
290 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is too large.\r
291\r
292 @return Error codes from underlying functions.\r
293**/\r
06a265b9 294RETURN_STATUS\r
08bed3fb 295EFIAPI\r
06a265b9
LE
296QemuFwCfgS3ScriptSkipBytes (\r
297 IN INT32 FirmwareConfigItem,\r
298 IN UINTN NumberOfBytes\r
299 );\r
300\r
301\r
302/**\r
303 Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.\r
304\r
305 If the check fails during S3 resume, the boot script will hang.\r
306\r
307 This function may only be called from the client module's\r
308 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
309 QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
310\r
311 @param[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field\r
312 in ScratchBuffer that should be checked. The caller\r
313 is responsible for populating the field during S3\r
314 resume, by calling QemuFwCfgS3ScriptReadBytes() ahead\r
315 of QemuFwCfgS3ScriptCheckValue().\r
316\r
317 ScratchData must point into ScratchBuffer, which was\r
318 allocated, and passed to Callback(), by\r
319 QemuFwCfgS3CallWhenBootScriptReady().\r
320\r
321 ScratchData must be aligned at ValueSize bytes.\r
322\r
323 @param[in] ValueSize One of 1, 2, 4 or 8, specifying the size of the field\r
324 to check.\r
325\r
326 @param[in] ValueMask The value read from ScratchData is binarily AND-ed\r
327 with ValueMask, and the result is compared against\r
328 Value. If the masked data equals Value, the check\r
329 passes, and the boot script can proceed. Otherwise,\r
330 the check fails, and the boot script hangs.\r
331\r
332 @param[in] Value Refer to ValueMask.\r
333\r
334 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
335 Boot Script successfully. There is no way\r
336 to undo this action.\r
337\r
338 @retval RETURN_INVALID_PARAMETER ValueSize is invalid.\r
339\r
340 @retval RETURN_INVALID_PARAMETER ValueMask or Value cannot be represented in\r
341 ValueSize bytes.\r
342\r
343 @retval RETURN_INVALID_PARAMETER ScratchData is not aligned at ValueSize\r
344 bytes.\r
345\r
346 @retval RETURN_BAD_BUFFER_SIZE The ValueSize bytes at ScratchData aren't\r
347 wholly contained in the ScratchBufferSize\r
348 bytes at ScratchBuffer.\r
349\r
350 @return Error codes from underlying functions.\r
351**/\r
06a265b9 352RETURN_STATUS\r
08bed3fb 353EFIAPI\r
06a265b9
LE
354QemuFwCfgS3ScriptCheckValue (\r
355 IN VOID *ScratchData,\r
356 IN UINT8 ValueSize,\r
357 IN UINT64 ValueMask,\r
358 IN UINT64 Value\r
359 );\r
360\r
f70b071e 361#endif\r