2 Shared code for the Base Null and PEI fw_cfg instances of the QemuFwCfgS3Lib
5 Copyright (C) 2017, Red Hat, Inc.
7 This program and the accompanying materials are licensed and made available
8 under the terms and conditions of the BSD License which accompanies this
9 distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
13 WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #include <Library/DebugLib.h>
17 #include <Library/QemuFwCfgS3Lib.h>
20 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
21 and transfer data to it.
23 The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore
24 NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write
25 them to fw_cfg using DMA.
27 If the operation fails during S3 resume, the boot script will hang.
29 This function may only be called from the client module's
30 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
31 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
33 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
34 item to write, expressed as INT32. If
35 FirmwareConfigItem is -1, no selection is
36 made, the write will occur to the currently
37 selected item, at its currently selected
38 offset. Otherwise, the specified item will be
39 selected, and the write will occur at offset
42 @param[in] NumberOfBytes Size of the data to restore in ScratchBuffer,
43 and to write from ScratchBuffer, during S3
44 resume. NumberOfBytes must not exceed
45 ScratchBufferSize, which was passed to
46 QemuFwCfgS3CallWhenBootScriptReady().
48 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
49 Boot Script successfully. There is no way
52 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
54 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
57 @return Error codes from underlying functions.
61 QemuFwCfgS3ScriptWriteBytes (
62 IN INT32 FirmwareConfigItem
,
63 IN UINTN NumberOfBytes
67 return RETURN_UNSUPPORTED
;
72 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
73 and transfer data from it.
75 The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes
76 bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved
79 If the operation fails during S3 resume, the boot script will hang.
81 This function may only be called from the client module's
82 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
83 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
85 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
86 item to read, expressed as INT32. If
87 FirmwareConfigItem is -1, no selection is
88 made, the read will occur from the currently
89 selected item, from its currently selected
90 offset. Otherwise, the specified item will be
91 selected, and the read will occur from offset
94 @param[in] NumberOfBytes Size of the data to read during S3 resume.
95 NumberOfBytes must not exceed
96 ScratchBufferSize, which was passed to
97 QemuFwCfgS3CallWhenBootScriptReady().
99 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
100 Boot Script successfully. There is no way
103 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
105 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
108 @return Error codes from underlying functions.
112 QemuFwCfgS3ScriptReadBytes (
113 IN INT32 FirmwareConfigItem
,
114 IN UINTN NumberOfBytes
118 return RETURN_UNSUPPORTED
;
123 Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
124 and increase its offset.
126 If the operation fails during S3 resume, the boot script will hang.
128 This function may only be called from the client module's
129 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
130 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
132 @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
133 item to advance the offset of, expressed as
134 INT32. If FirmwareConfigItem is -1, no
135 selection is made, and the offset for the
136 currently selected item is increased.
137 Otherwise, the specified item will be
138 selected, and the offset increment will occur
141 @param[in] NumberOfBytes The number of bytes to skip in the subject
144 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
145 Boot Script successfully. There is no way
148 @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
150 @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is too large.
152 @return Error codes from underlying functions.
156 QemuFwCfgS3ScriptSkipBytes (
157 IN INT32 FirmwareConfigItem
,
158 IN UINTN NumberOfBytes
162 return RETURN_UNSUPPORTED
;
167 Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.
169 If the check fails during S3 resume, the boot script will hang.
171 This function may only be called from the client module's
172 FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
173 QemuFwCfgS3CallWhenBootScriptReady() as Callback.
175 @param[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field
176 in ScratchBuffer that should be checked. The caller
177 is responsible for populating the field during S3
178 resume, by calling QemuFwCfgS3ScriptReadBytes() ahead
179 of QemuFwCfgS3ScriptCheckValue().
181 ScratchData must point into ScratchBuffer, which was
182 allocated, and passed to Callback(), by
183 QemuFwCfgS3CallWhenBootScriptReady().
185 ScratchData must be aligned at ValueSize bytes.
187 @param[in] ValueSize One of 1, 2, 4 or 8, specifying the size of the field
190 @param[in] ValueMask The value read from ScratchData is binarily AND-ed
191 with ValueMask, and the result is compared against
192 Value. If the masked data equals Value, the check
193 passes, and the boot script can proceed. Otherwise,
194 the check fails, and the boot script hangs.
196 @param[in] Value Refer to ValueMask.
198 @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
199 Boot Script successfully. There is no way
202 @retval RETURN_INVALID_PARAMETER ValueSize is invalid.
204 @retval RETURN_INVALID_PARAMETER ValueMask or Value cannot be represented in
207 @retval RETURN_INVALID_PARAMETER ScratchData is not aligned at ValueSize
210 @retval RETURN_BAD_BUFFER_SIZE The ValueSize bytes at ScratchData aren't
211 wholly contained in the ScratchBufferSize
212 bytes at ScratchBuffer.
214 @return Error codes from underlying functions.
218 QemuFwCfgS3ScriptCheckValue (
219 IN VOID
*ScratchData
,
226 return RETURN_UNSUPPORTED
;