From 33ead2dd14073ce747d1a623975fc55d9fe84640 Mon Sep 17 00:00:00 2001 From: Laszlo Ersek Date: Wed, 22 Feb 2017 10:34:48 +0100 Subject: OvmfPkg/QemuFwCfgS3Lib: implement opcode APIs for Base Null instance 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 Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=394 Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Laszlo Ersek Reviewed-by: Jordan Justen --- .../QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf | 4 + OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3Base.c | 71 +++++++ .../Library/QemuFwCfgS3Lib/QemuFwCfgS3BasePei.c | 227 +++++++++++++++++++++ 3 files changed, 302 insertions(+) create mode 100644 OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3BasePei.c (limited to 'OvmfPkg') diff --git a/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf b/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf index ba24a0b9d4..837fd70db6 100644 --- a/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf +++ b/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf @@ -33,7 +33,11 @@ [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 bed9bf3dfb..7b71305d12 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 #include /** @@ -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 0000000000..674929e9d5 --- /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 +#include + +/** + 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; +} -- cgit v1.2.3