In the Base Null instance:
- QemuFwCfgS3Enabled() returns constant FALSE. This is unique to the Base
Null instance, and the function is already present in
"QemuFwCfgS3Base.c".
- The QemuFwCfgS3CallWhenBootScriptReady() function must never be called
(according to the documentation, given the above). This is also unique
to the Base Null instance, so implement the function in
"QemuFwCfgS3Base.c".
- Consequently, the QemuFwCfgS3ScriptWriteBytes(),
QemuFwCfgS3ScriptReadBytes(), QemuFwCfgS3ScriptSkipBytes(), and
QemuFwCfgS3ScriptCheckValue() functions must never be called either.
This behavior is not unique to the Base Null instance (it will be shared
with the PEI fw_cfg instance), so add these functions to
"QemuFwCfgS3BasePei.c".
Cc: Jordan Justen <jordan.l.justen@intel.com>
Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=394
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
---
Notes:
v2:
- rename QemuFwCfgS3TransferOwnership to
QemuFwCfgS3CallWhenBootScriptReady [Jordan]
- rename FW_CFG_BOOT_SCRIPT_APPEND_FUNCTION to
FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION [Jordan]
- rename "Append" to "Callback" [Laszlo]
- rename QemuFwCfgS3WriteBytes, QemuFwCfgS3ReadBytes,
QemuFwCfgS3SkipBytes, and QemuFwCfgS3CheckValue to
QemuFwCfgS3ScriptWriteBytes, QemuFwCfgS3ScriptReadBytes,
QemuFwCfgS3ScriptSkipBytes, and QemuFwCfgS3ScriptCheckValue,
respectively [Jordan]
OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf | 4 +
OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3Base.c | 71 ++++++
OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3BasePei.c | 227 ++++++++++++++++++++
3 files changed, 302 insertions(+)
diff --git a/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf b/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf
index ba24a0b9d434..837fd70db6e5 100644
--- a/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf
+++ b/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf
@@ -33,7 +33,11 @@ [Defines]
[Sources]
QemuFwCfgS3Base.c
+ QemuFwCfgS3BasePei.c
[Packages]
MdePkg/MdePkg.dec
OvmfPkg/OvmfPkg.dec
+
+[LibraryClasses]
+ DebugLib
diff --git a/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3Base.c b/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3Base.c
index bed9bf3dfb57..7b71305d1267 100644
--- a/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3Base.c
+++ b/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3Base.c
@@ -16,6 +16,7 @@
WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
+#include <Library/DebugLib.h>
#include <Library/QemuFwCfgS3Lib.h>
/**
@@ -37,3 +38,73 @@ QemuFwCfgS3Enabled (
{
return FALSE;
}
+
+
+/**
+ Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for
+ when the production of ACPI S3 Boot Script opcodes becomes possible.
+
+ Take ownership of the client-provided Context, and pass it to the callback
+ function, when the latter is invoked.
+
+ Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon
+ that the client will produce in the callback function.
+
+ @param[in] Callback FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke
+ when the production of ACPI S3 Boot Script
+ opcodes becomes possible. Callback() may be
+ called immediately from
+ QemuFwCfgS3CallWhenBootScriptReady().
+
+ @param[in,out] Context Client-provided data structure for the
+ Callback() callback function to consume.
+
+ If Context points to dynamically allocated
+ memory, then Callback() must release it.
+
+ If Context points to dynamically allocated
+ memory, and
+ QemuFwCfgS3CallWhenBootScriptReady() returns
+ successfully, then the caller of
+ QemuFwCfgS3CallWhenBootScriptReady() must
+ neither dereference nor even evaluate Context
+ any longer, as ownership of the referenced area
+ has been transferred to Callback().
+
+ @param[in] ScratchBufferSize The size of the scratch buffer that will hold,
+ in reserved memory, all client data read,
+ written, and checked by the ACPI S3 Boot Script
+ opcodes produced by Callback().
+
+ @retval RETURN_UNSUPPORTED The library instance does not support this
+ function.
+
+ @retval RETURN_NOT_FOUND The fw_cfg DMA interface to QEMU is
+ unavailable.
+
+ @retval RETURN_BAD_BUFFER_SIZE ScratchBufferSize is too large.
+
+ @retval RETURN_OUT_OF_RESOURCES Memory allocation failed.
+
+ @retval RETURN_SUCCESS Callback() has been installed, and the
+ ownership of Context has been transferred.
+ Reserved memory has been allocated for the
+ scratch buffer.
+
+ A successful invocation of
+ QemuFwCfgS3CallWhenBootScriptReady() cannot
+ be rolled back.
+
+ @return Error codes from underlying functions.
+**/
+EFIAPI
+RETURN_STATUS
+QemuFwCfgS3CallWhenBootScriptReady (
+ IN FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION *Callback,
+ IN OUT VOID *Context, OPTIONAL
+ IN UINTN ScratchBufferSize
+ )
+{
+ ASSERT (FALSE);
+ return RETURN_UNSUPPORTED;
+}
diff --git a/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3BasePei.c b/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3BasePei.c
new file mode 100644
index 000000000000..674929e9d500
--- /dev/null
+++ b/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3BasePei.c
@@ -0,0 +1,227 @@
+/** @file
+ Shared code for the Base Null and PEI fw_cfg instances of the QemuFwCfgS3Lib
+ class.
+
+ Copyright (C) 2017, Red Hat, Inc.
+
+ This program and the accompanying materials are licensed and made available
+ under the terms and conditions of the BSD License which accompanies this
+ distribution. The full text of the license may be found at
+ http://opensource.org/licenses/bsd-license.php
+
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
+ WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+**/
+
+#include <Library/DebugLib.h>
+#include <Library/QemuFwCfgS3Lib.h>
+
+/**
+ Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
+ and transfer data to it.
+
+ The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore
+ NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write
+ them to fw_cfg using DMA.
+
+ If the operation fails during S3 resume, the boot script will hang.
+
+ This function may only be called from the client module's
+ FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
+ QemuFwCfgS3CallWhenBootScriptReady() as Callback.
+
+ @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
+ item to write, expressed as INT32. If
+ FirmwareConfigItem is -1, no selection is
+ made, the write will occur to the currently
+ selected item, at its currently selected
+ offset. Otherwise, the specified item will be
+ selected, and the write will occur at offset
+ 0.
+
+ @param[in] NumberOfBytes Size of the data to restore in ScratchBuffer,
+ and to write from ScratchBuffer, during S3
+ resume. NumberOfBytes must not exceed
+ ScratchBufferSize, which was passed to
+ QemuFwCfgS3CallWhenBootScriptReady().
+
+ @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
+ Boot Script successfully. There is no way
+ to undo this action.
+
+ @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
+
+ @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
+ ScratchBufferSize.
+
+ @return Error codes from underlying functions.
+**/
+EFIAPI
+RETURN_STATUS
+QemuFwCfgS3ScriptWriteBytes (
+ IN INT32 FirmwareConfigItem,
+ IN UINTN NumberOfBytes
+ )
+{
+ ASSERT (FALSE);
+ return RETURN_UNSUPPORTED;
+}
+
+
+/**
+ Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
+ and transfer data from it.
+
+ The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes
+ bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved
+ memory.
+
+ If the operation fails during S3 resume, the boot script will hang.
+
+ This function may only be called from the client module's
+ FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
+ QemuFwCfgS3CallWhenBootScriptReady() as Callback.
+
+ @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
+ item to read, expressed as INT32. If
+ FirmwareConfigItem is -1, no selection is
+ made, the read will occur from the currently
+ selected item, from its currently selected
+ offset. Otherwise, the specified item will be
+ selected, and the read will occur from offset
+ 0.
+
+ @param[in] NumberOfBytes Size of the data to read during S3 resume.
+ NumberOfBytes must not exceed
+ ScratchBufferSize, which was passed to
+ QemuFwCfgS3CallWhenBootScriptReady().
+
+ @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
+ Boot Script successfully. There is no way
+ to undo this action.
+
+ @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
+
+ @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
+ ScratchBufferSize.
+
+ @return Error codes from underlying functions.
+**/
+EFIAPI
+RETURN_STATUS
+QemuFwCfgS3ScriptReadBytes (
+ IN INT32 FirmwareConfigItem,
+ IN UINTN NumberOfBytes
+ )
+{
+ ASSERT (FALSE);
+ return RETURN_UNSUPPORTED;
+}
+
+
+/**
+ Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
+ and increase its offset.
+
+ If the operation fails during S3 resume, the boot script will hang.
+
+ This function may only be called from the client module's
+ FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
+ QemuFwCfgS3CallWhenBootScriptReady() as Callback.
+
+ @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
+ item to advance the offset of, expressed as
+ INT32. If FirmwareConfigItem is -1, no
+ selection is made, and the offset for the
+ currently selected item is increased.
+ Otherwise, the specified item will be
+ selected, and the offset increment will occur
+ from offset 0.
+
+ @param[in] NumberOfBytes The number of bytes to skip in the subject
+ fw_cfg item.
+
+ @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
+ Boot Script successfully. There is no way
+ to undo this action.
+
+ @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
+
+ @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is too large.
+
+ @return Error codes from underlying functions.
+**/
+EFIAPI
+RETURN_STATUS
+QemuFwCfgS3ScriptSkipBytes (
+ IN INT32 FirmwareConfigItem,
+ IN UINTN NumberOfBytes
+ )
+{
+ ASSERT (FALSE);
+ return RETURN_UNSUPPORTED;
+}
+
+
+/**
+ Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.
+
+ If the check fails during S3 resume, the boot script will hang.
+
+ This function may only be called from the client module's
+ FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
+ QemuFwCfgS3CallWhenBootScriptReady() as Callback.
+
+ @param[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field
+ in ScratchBuffer that should be checked. The caller
+ is responsible for populating the field during S3
+ resume, by calling QemuFwCfgS3ScriptReadBytes() ahead
+ of QemuFwCfgS3ScriptCheckValue().
+
+ ScratchData must point into ScratchBuffer, which was
+ allocated, and passed to Callback(), by
+ QemuFwCfgS3CallWhenBootScriptReady().
+
+ ScratchData must be aligned at ValueSize bytes.
+
+ @param[in] ValueSize One of 1, 2, 4 or 8, specifying the size of the field
+ to check.
+
+ @param[in] ValueMask The value read from ScratchData is binarily AND-ed
+ with ValueMask, and the result is compared against
+ Value. If the masked data equals Value, the check
+ passes, and the boot script can proceed. Otherwise,
+ the check fails, and the boot script hangs.
+
+ @param[in] Value Refer to ValueMask.
+
+ @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
+ Boot Script successfully. There is no way
+ to undo this action.
+
+ @retval RETURN_INVALID_PARAMETER ValueSize is invalid.
+
+ @retval RETURN_INVALID_PARAMETER ValueMask or Value cannot be represented in
+ ValueSize bytes.
+
+ @retval RETURN_INVALID_PARAMETER ScratchData is not aligned at ValueSize
+ bytes.
+
+ @retval RETURN_BAD_BUFFER_SIZE The ValueSize bytes at ScratchData aren't
+ wholly contained in the ScratchBufferSize
+ bytes at ScratchBuffer.
+
+ @return Error codes from underlying functions.
+**/
+EFIAPI
+RETURN_STATUS
+QemuFwCfgS3ScriptCheckValue (
+ IN VOID *ScratchData,
+ IN UINT8 ValueSize,
+ IN UINT64 ValueMask,
+ IN UINT64 Value
+ )
+{
+ ASSERT (FALSE);
+ return RETURN_UNSUPPORTED;
+}
--
2.9.3
_______________________________________________
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel
© 2016 - 2024 Red Hat, Inc.