2 Shared code for the Base Null and PEI fw_cfg instances of the QemuFwCfgS3Lib
5 Copyright (C) 2017, Red Hat, Inc.
7 SPDX-License-Identifier: BSD-2-Clause-Patent
10 #include <Library/DebugLib.h>
11 #include <Library/QemuFwCfgS3Lib.h>
14 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
15 and transfer data to it.
17 The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore
18 NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write
19 them to fw_cfg using DMA.
21 If the operation fails during S3 resume, the boot script will hang.
23 This function may only be called from the client module's
24 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
25 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
27 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
28 item to write, expressed as INT32. If
29 FirmwareConfigItem is -1, no selection is
30 made, the write will occur to the currently
31 selected item, at its currently selected
32 offset. Otherwise, the specified item will be
33 selected, and the write will occur at offset
36 @param[in] NumberOfBytes Size of the data to restore in ScratchBuffer,
37 and to write from ScratchBuffer, during S3
38 resume. NumberOfBytes must not exceed
39 ScratchBufferSize, which was passed to
40 QemuFwCfgS3CallWhenBootScriptReady().
42 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
43 Boot Script successfully. There is no way
46 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
48 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
51 @return Error codes from underlying functions.
55 QemuFwCfgS3ScriptWriteBytes (
56 IN INT32 FirmwareConfigItem
,
57 IN UINTN NumberOfBytes
61 return RETURN_UNSUPPORTED
;
65 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
66 and transfer data from it.
68 The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes
69 bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved
72 If the operation fails during S3 resume, the boot script will hang.
74 This function may only be called from the client module's
75 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
76 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
78 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
79 item to read, expressed as INT32. If
80 FirmwareConfigItem is -1, no selection is
81 made, the read will occur from the currently
82 selected item, from its currently selected
83 offset. Otherwise, the specified item will be
84 selected, and the read will occur from offset
87 @param[in] NumberOfBytes Size of the data to read during S3 resume.
88 NumberOfBytes must not exceed
89 ScratchBufferSize, which was passed to
90 QemuFwCfgS3CallWhenBootScriptReady().
92 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
93 Boot Script successfully. There is no way
96 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
98 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
101 @return Error codes from underlying functions.
105 QemuFwCfgS3ScriptReadBytes (
106 IN INT32 FirmwareConfigItem
,
107 IN UINTN NumberOfBytes
111 return RETURN_UNSUPPORTED
;
115 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
116 and increase its offset.
118 If the operation fails during S3 resume, the boot script will hang.
120 This function may only be called from the client module's
121 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
122 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
124 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
125 item to advance the offset of, expressed as
126 INT32. If FirmwareConfigItem is -1, no
127 selection is made, and the offset for the
128 currently selected item is increased.
129 Otherwise, the specified item will be
130 selected, and the offset increment will occur
133 @param[in] NumberOfBytes The number of bytes to skip in the subject
136 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
137 Boot Script successfully. There is no way
140 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
142 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is too large.
144 @return Error codes from underlying functions.
148 QemuFwCfgS3ScriptSkipBytes (
149 IN INT32 FirmwareConfigItem
,
150 IN UINTN NumberOfBytes
154 return RETURN_UNSUPPORTED
;
158 Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.
160 If the check fails during S3 resume, the boot script will hang.
162 This function may only be called from the client module's
163 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
164 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
166 @param[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field
167 in ScratchBuffer that should be checked. The caller
168 is responsible for populating the field during S3
169 resume, by calling QemuFwCfgS3ScriptReadBytes() ahead
170 of QemuFwCfgS3ScriptCheckValue().
172 ScratchData must point into ScratchBuffer, which was
173 allocated, and passed to Callback(), by
174 QemuFwCfgS3CallWhenBootScriptReady().
176 ScratchData must be aligned at ValueSize bytes.
178 @param[in] ValueSize One of 1, 2, 4 or 8, specifying the size of the field
181 @param[in] ValueMask The value read from ScratchData is binarily AND-ed
182 with ValueMask, and the result is compared against
183 Value. If the masked data equals Value, the check
184 passes, and the boot script can proceed. Otherwise,
185 the check fails, and the boot script hangs.
187 @param[in] Value Refer to ValueMask.
189 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
190 Boot Script successfully. There is no way
193 @retval RETURN_INVALID_PARAMETER ValueSize is invalid.
195 @retval RETURN_INVALID_PARAMETER ValueMask or Value cannot be represented in
198 @retval RETURN_INVALID_PARAMETER ScratchData is not aligned at ValueSize
201 @retval RETURN_BAD_BUFFER_SIZE The ValueSize bytes at ScratchData aren't
202 wholly contained in the ScratchBufferSize
203 bytes at ScratchBuffer.
205 @return Error codes from underlying functions.
209 QemuFwCfgS3ScriptCheckValue (
210 IN VOID
*ScratchData
,
217 return RETURN_UNSUPPORTED
;