2 S3 support for QEMU fw_cfg
4 This library class enables driver modules (a) to query whether S3 support was
5 enabled on the QEMU command line, (b) to produce fw_cfg DMA operations that
6 are to be replayed at S3 resume time.
8 Copyright (C) 2017, Red Hat, Inc.
10 This program and the accompanying materials are licensed and made available
11 under the terms and conditions of the BSD License which accompanies this
12 distribution. The full text of the license may be found at
13 http://opensource.org/licenses/bsd-license.php
15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
16 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19 #ifndef __FW_CFG_S3_LIB__
20 #define __FW_CFG_S3_LIB__
25 Determine if S3 support is explicitly enabled.
27 @retval TRUE If S3 support is explicitly enabled. Other functions in this
28 library may be called (subject to their individual
31 FALSE Otherwise. This includes unavailability of the firmware
32 configuration interface. No other function in this library
43 Prototype for the callback function that the client module provides.
45 In the callback function, the client module calls the
46 QemuFwCfgS3ScriptWriteBytes(), QemuFwCfgS3ScriptReadBytes(),
47 QemuFwCfgS3ScriptSkipBytes(), and QemuFwCfgS3ScriptCheckValue() functions.
48 Those functions produce ACPI S3 Boot Script opcodes that will perform fw_cfg
49 DMA operations, and will check any desired values that were read, during S3
52 The callback function is invoked when the production of ACPI S3 Boot Script
53 opcodes becomes possible. This may occur directly on the call stack of
54 QemuFwCfgS3CallWhenBootScriptReady() (see below), or after
55 QemuFwCfgS3CallWhenBootScriptReady() has successfully returned.
57 The callback function must not return if it fails -- in the general case,
58 there is noone to propagate any errors to. Therefore, on error, an error
59 message should be logged, and CpuDeadLoop() must be called.
61 @param[in,out] Context Carries information from the client module
62 itself (i.e., from the invocation of
63 QemuFwCfgS3CallWhenBootScriptReady()) to the
66 If Context points to dynamically allocated
67 storage, then the callback function must
70 @param[in,out] ScratchBuffer Points to reserved memory, allocated by
71 QemuFwCfgS3CallWhenBootScriptReady()
74 ScratchBuffer is typed and sized by the client
76 QemuFwCfgS3CallWhenBootScriptReady(). The
77 client module defines a union type of
78 structures for ScratchBuffer such that the
79 union can hold client data for any desired
80 fw_cfg DMA read and write operations, and value
83 The callback function casts ScratchBuffer to
84 the union type described above. It passes union
85 member sizes as NumberOfBytes to
86 QemuFwCfgS3ScriptReadBytes() and
87 QemuFwCfgS3ScriptWriteBytes(). It passes field
88 addresses and sizes in structures in the union
89 as ScratchData and ValueSize to
90 QemuFwCfgS3ScriptCheckValue().
92 ScratchBuffer is aligned at 8 bytes.
95 VOID (EFIAPI FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION
) (
96 IN OUT VOID
*Context
, OPTIONAL
97 IN OUT VOID
*ScratchBuffer
102 Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for
103 when the production of ACPI S3 Boot Script opcodes becomes possible.
105 Take ownership of the client-provided Context, and pass it to the callback
106 function, when the latter is invoked.
108 Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon
109 that the client will produce in the callback function.
111 @param[in] Callback FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke
112 when the production of ACPI S3 Boot Script
113 opcodes becomes possible. Callback() may be
114 called immediately from
115 QemuFwCfgS3CallWhenBootScriptReady().
117 @param[in,out] Context Client-provided data structure for the
118 Callback() callback function to consume.
120 If Context points to dynamically allocated
121 memory, then Callback() must release it.
123 If Context points to dynamically allocated
125 QemuFwCfgS3CallWhenBootScriptReady() returns
126 successfully, then the caller of
127 QemuFwCfgS3CallWhenBootScriptReady() must
128 neither dereference nor even evaluate Context
129 any longer, as ownership of the referenced area
130 has been transferred to Callback().
132 @param[in] ScratchBufferSize The size of the scratch buffer that will hold,
133 in reserved memory, all client data read,
134 written, and checked by the ACPI S3 Boot Script
135 opcodes produced by Callback().
137 @retval RETURN_UNSUPPORTED The library instance does not support this
140 @retval RETURN_NOT_FOUND The fw_cfg DMA interface to QEMU is
143 @retval RETURN_BAD_BUFFER_SIZE ScratchBufferSize is too large.
145 @retval RETURN_OUT_OF_RESOURCES Memory allocation failed.
147 @retval RETURN_SUCCESS Callback() has been installed, and the
148 ownership of Context has been transferred.
149 Reserved memory has been allocated for the
152 A successful invocation of
153 QemuFwCfgS3CallWhenBootScriptReady() cannot
156 @return Error codes from underlying functions.
160 QemuFwCfgS3CallWhenBootScriptReady (
161 IN FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION
*Callback
,
162 IN OUT VOID
*Context
, OPTIONAL
163 IN UINTN ScratchBufferSize
168 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
169 and transfer data to it.
171 The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore
172 NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write
173 them to fw_cfg using DMA.
175 If the operation fails during S3 resume, the boot script will hang.
177 This function may only be called from the client module's
178 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
179 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
181 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
182 item to write, expressed as INT32. If
183 FirmwareConfigItem is -1, no selection is
184 made, the write will occur to the currently
185 selected item, at its currently selected
186 offset. Otherwise, the specified item will be
187 selected, and the write will occur at offset
190 @param[in] NumberOfBytes Size of the data to restore in ScratchBuffer,
191 and to write from ScratchBuffer, during S3
192 resume. NumberOfBytes must not exceed
193 ScratchBufferSize, which was passed to
194 QemuFwCfgS3CallWhenBootScriptReady().
196 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
197 Boot Script successfully. There is no way
200 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
202 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
205 @return Error codes from underlying functions.
209 QemuFwCfgS3ScriptWriteBytes (
210 IN INT32 FirmwareConfigItem
,
211 IN UINTN NumberOfBytes
216 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
217 and transfer data from it.
219 The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes
220 bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved
223 If the operation fails during S3 resume, the boot script will hang.
225 This function may only be called from the client module's
226 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
227 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
229 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
230 item to read, expressed as INT32. If
231 FirmwareConfigItem is -1, no selection is
232 made, the read will occur from the currently
233 selected item, from its currently selected
234 offset. Otherwise, the specified item will be
235 selected, and the read will occur from offset
238 @param[in] NumberOfBytes Size of the data to read during S3 resume.
239 NumberOfBytes must not exceed
240 ScratchBufferSize, which was passed to
241 QemuFwCfgS3CallWhenBootScriptReady().
243 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
244 Boot Script successfully. There is no way
247 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
249 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
252 @return Error codes from underlying functions.
256 QemuFwCfgS3ScriptReadBytes (
257 IN INT32 FirmwareConfigItem
,
258 IN UINTN NumberOfBytes
263 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
264 and increase its offset.
266 If the operation fails during S3 resume, the boot script will hang.
268 This function may only be called from the client module's
269 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
270 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
272 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
273 item to advance the offset of, expressed as
274 INT32. If FirmwareConfigItem is -1, no
275 selection is made, and the offset for the
276 currently selected item is increased.
277 Otherwise, the specified item will be
278 selected, and the offset increment will occur
281 @param[in] NumberOfBytes The number of bytes to skip in the subject
284 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
285 Boot Script successfully. There is no way
288 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
290 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is too large.
292 @return Error codes from underlying functions.
296 QemuFwCfgS3ScriptSkipBytes (
297 IN INT32 FirmwareConfigItem
,
298 IN UINTN NumberOfBytes
303 Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.
305 If the check fails during S3 resume, the boot script will hang.
307 This function may only be called from the client module's
308 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
309 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
311 @param[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field
312 in ScratchBuffer that should be checked. The caller
313 is responsible for populating the field during S3
314 resume, by calling QemuFwCfgS3ScriptReadBytes() ahead
315 of QemuFwCfgS3ScriptCheckValue().
317 ScratchData must point into ScratchBuffer, which was
318 allocated, and passed to Callback(), by
319 QemuFwCfgS3CallWhenBootScriptReady().
321 ScratchData must be aligned at ValueSize bytes.
323 @param[in] ValueSize One of 1, 2, 4 or 8, specifying the size of the field
326 @param[in] ValueMask The value read from ScratchData is binarily AND-ed
327 with ValueMask, and the result is compared against
328 Value. If the masked data equals Value, the check
329 passes, and the boot script can proceed. Otherwise,
330 the check fails, and the boot script hangs.
332 @param[in] Value Refer to ValueMask.
334 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
335 Boot Script successfully. There is no way
338 @retval RETURN_INVALID_PARAMETER ValueSize is invalid.
340 @retval RETURN_INVALID_PARAMETER ValueMask or Value cannot be represented in
343 @retval RETURN_INVALID_PARAMETER ScratchData is not aligned at ValueSize
346 @retval RETURN_BAD_BUFFER_SIZE The ValueSize bytes at ScratchData aren't
347 wholly contained in the ScratchBufferSize
348 bytes at ScratchBuffer.
350 @return Error codes from underlying functions.
354 QemuFwCfgS3ScriptCheckValue (
355 IN VOID
*ScratchData
,