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 SPDX-License-Identifier: BSD-2-Clause-Patent
13 #ifndef __FW_CFG_S3_LIB__
14 #define __FW_CFG_S3_LIB__
19 Determine if S3 support is explicitly enabled.
21 @retval TRUE If S3 support is explicitly enabled. Other functions in this
22 library may be called (subject to their individual
25 FALSE Otherwise. This includes unavailability of the firmware
26 configuration interface. No other function in this library
36 Prototype for the callback function that the client module provides.
38 In the callback function, the client module calls the
39 QemuFwCfgS3ScriptWriteBytes(), QemuFwCfgS3ScriptReadBytes(),
40 QemuFwCfgS3ScriptSkipBytes(), and QemuFwCfgS3ScriptCheckValue() functions.
41 Those functions produce ACPI S3 Boot Script opcodes that will perform fw_cfg
42 DMA operations, and will check any desired values that were read, during S3
45 The callback function is invoked when the production of ACPI S3 Boot Script
46 opcodes becomes possible. This may occur directly on the call stack of
47 QemuFwCfgS3CallWhenBootScriptReady() (see below), or after
48 QemuFwCfgS3CallWhenBootScriptReady() has successfully returned.
50 The callback function must not return if it fails -- in the general case,
51 there is noone to propagate any errors to. Therefore, on error, an error
52 message should be logged, and CpuDeadLoop() must be called.
54 @param[in,out] Context Carries information from the client module
55 itself (i.e., from the invocation of
56 QemuFwCfgS3CallWhenBootScriptReady()) to the
59 If Context points to dynamically allocated
60 storage, then the callback function must
63 @param[in,out] ScratchBuffer Points to reserved memory, allocated by
64 QemuFwCfgS3CallWhenBootScriptReady()
67 ScratchBuffer is typed and sized by the client
69 QemuFwCfgS3CallWhenBootScriptReady(). The
70 client module defines a union type of
71 structures for ScratchBuffer such that the
72 union can hold client data for any desired
73 fw_cfg DMA read and write operations, and value
76 The callback function casts ScratchBuffer to
77 the union type described above. It passes union
78 member sizes as NumberOfBytes to
79 QemuFwCfgS3ScriptReadBytes() and
80 QemuFwCfgS3ScriptWriteBytes(). It passes field
81 addresses and sizes in structures in the union
82 as ScratchData and ValueSize to
83 QemuFwCfgS3ScriptCheckValue().
85 ScratchBuffer is aligned at 8 bytes.
88 VOID(EFIAPI FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION
)(
89 IN OUT VOID
*Context OPTIONAL
,
90 IN OUT VOID
*ScratchBuffer
94 Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for
95 when the production of ACPI S3 Boot Script opcodes becomes possible.
97 Take ownership of the client-provided Context, and pass it to the callback
98 function, when the latter is invoked.
100 Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon
101 that the client will produce in the callback function.
103 @param[in] Callback FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke
104 when the production of ACPI S3 Boot Script
105 opcodes becomes possible. Callback() may be
106 called immediately from
107 QemuFwCfgS3CallWhenBootScriptReady().
109 @param[in,out] Context Client-provided data structure for the
110 Callback() callback function to consume.
112 If Context points to dynamically allocated
113 memory, then Callback() must release it.
115 If Context points to dynamically allocated
117 QemuFwCfgS3CallWhenBootScriptReady() returns
118 successfully, then the caller of
119 QemuFwCfgS3CallWhenBootScriptReady() must
120 neither dereference nor even evaluate Context
121 any longer, as ownership of the referenced area
122 has been transferred to Callback().
124 @param[in] ScratchBufferSize The size of the scratch buffer that will hold,
125 in reserved memory, all client data read,
126 written, and checked by the ACPI S3 Boot Script
127 opcodes produced by Callback().
129 @retval RETURN_UNSUPPORTED The library instance does not support this
132 @retval RETURN_NOT_FOUND The fw_cfg DMA interface to QEMU is
135 @retval RETURN_BAD_BUFFER_SIZE ScratchBufferSize is too large.
137 @retval RETURN_OUT_OF_RESOURCES Memory allocation failed.
139 @retval RETURN_SUCCESS Callback() has been installed, and the
140 ownership of Context has been transferred.
141 Reserved memory has been allocated for the
144 A successful invocation of
145 QemuFwCfgS3CallWhenBootScriptReady() cannot
148 @return Error codes from underlying functions.
152 QemuFwCfgS3CallWhenBootScriptReady (
153 IN FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION
*Callback
,
154 IN OUT VOID
*Context OPTIONAL
,
155 IN UINTN ScratchBufferSize
159 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
160 and transfer data to it.
162 The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore
163 NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write
164 them to fw_cfg using DMA.
166 If the operation fails during S3 resume, the boot script will hang.
168 This function may only be called from the client module's
169 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
170 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
172 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
173 item to write, expressed as INT32. If
174 FirmwareConfigItem is -1, no selection is
175 made, the write will occur to the currently
176 selected item, at its currently selected
177 offset. Otherwise, the specified item will be
178 selected, and the write will occur at offset
181 @param[in] NumberOfBytes Size of the data to restore in ScratchBuffer,
182 and to write from ScratchBuffer, during S3
183 resume. NumberOfBytes must not exceed
184 ScratchBufferSize, which was passed to
185 QemuFwCfgS3CallWhenBootScriptReady().
187 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
188 Boot Script successfully. There is no way
191 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
193 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
196 @return Error codes from underlying functions.
200 QemuFwCfgS3ScriptWriteBytes (
201 IN INT32 FirmwareConfigItem
,
202 IN UINTN NumberOfBytes
206 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
207 and transfer data from it.
209 The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes
210 bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved
213 If the operation fails during S3 resume, the boot script will hang.
215 This function may only be called from the client module's
216 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
217 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
219 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
220 item to read, expressed as INT32. If
221 FirmwareConfigItem is -1, no selection is
222 made, the read will occur from the currently
223 selected item, from its currently selected
224 offset. Otherwise, the specified item will be
225 selected, and the read will occur from offset
228 @param[in] NumberOfBytes Size of the data to read during S3 resume.
229 NumberOfBytes must not exceed
230 ScratchBufferSize, which was passed to
231 QemuFwCfgS3CallWhenBootScriptReady().
233 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
234 Boot Script successfully. There is no way
237 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
239 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
242 @return Error codes from underlying functions.
246 QemuFwCfgS3ScriptReadBytes (
247 IN INT32 FirmwareConfigItem
,
248 IN UINTN NumberOfBytes
252 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
253 and increase its offset.
255 If the operation fails during S3 resume, the boot script will hang.
257 This function may only be called from the client module's
258 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
259 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
261 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
262 item to advance the offset of, expressed as
263 INT32. If FirmwareConfigItem is -1, no
264 selection is made, and the offset for the
265 currently selected item is increased.
266 Otherwise, the specified item will be
267 selected, and the offset increment will occur
270 @param[in] NumberOfBytes The number of bytes to skip in the subject
273 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
274 Boot Script successfully. There is no way
277 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
279 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is too large.
281 @return Error codes from underlying functions.
285 QemuFwCfgS3ScriptSkipBytes (
286 IN INT32 FirmwareConfigItem
,
287 IN UINTN NumberOfBytes
291 Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.
293 If the check fails during S3 resume, the boot script will hang.
295 This function may only be called from the client module's
296 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
297 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
299 @param[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field
300 in ScratchBuffer that should be checked. The caller
301 is responsible for populating the field during S3
302 resume, by calling QemuFwCfgS3ScriptReadBytes() ahead
303 of QemuFwCfgS3ScriptCheckValue().
305 ScratchData must point into ScratchBuffer, which was
306 allocated, and passed to Callback(), by
307 QemuFwCfgS3CallWhenBootScriptReady().
309 ScratchData must be aligned at ValueSize bytes.
311 @param[in] ValueSize One of 1, 2, 4 or 8, specifying the size of the field
314 @param[in] ValueMask The value read from ScratchData is binarily AND-ed
315 with ValueMask, and the result is compared against
316 Value. If the masked data equals Value, the check
317 passes, and the boot script can proceed. Otherwise,
318 the check fails, and the boot script hangs.
320 @param[in] Value Refer to ValueMask.
322 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
323 Boot Script successfully. There is no way
326 @retval RETURN_INVALID_PARAMETER ValueSize is invalid.
328 @retval RETURN_INVALID_PARAMETER ValueMask or Value cannot be represented in
331 @retval RETURN_INVALID_PARAMETER ScratchData is not aligned at ValueSize
334 @retval RETURN_BAD_BUFFER_SIZE The ValueSize bytes at ScratchData aren't
335 wholly contained in the ScratchBufferSize
336 bytes at ScratchBuffer.
338 @return Error codes from underlying functions.
342 QemuFwCfgS3ScriptCheckValue (
343 IN VOID
*ScratchData
,