From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 801BF8226D for ; Wed, 22 Feb 2017 17:48:32 -0800 (PST) Received: from int-mx11.intmail.prod.int.phx2.redhat.com (int-mx11.intmail.prod.int.phx2.redhat.com [10.5.11.24]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 1004F3A7690; Thu, 23 Feb 2017 01:48:33 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-116-134.phx2.redhat.com [10.3.116.134]) by int-mx11.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id v1N1mJFM012836; Wed, 22 Feb 2017 20:48:32 -0500 From: Laszlo Ersek To: edk2-devel-01 Cc: Jordan Justen Date: Thu, 23 Feb 2017 02:48:10 +0100 Message-Id: <20170223014814.10937-9-lersek@redhat.com> In-Reply-To: <20170223014814.10937-1-lersek@redhat.com> References: <20170223014814.10937-1-lersek@redhat.com> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.24 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.29]); Thu, 23 Feb 2017 01:48:33 +0000 (UTC) Subject: [PATCH 08/12] OvmfPkg/QemuFwCfgS3Lib: implement opcode APIs for Base Null instance X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 23 Feb 2017 01:48:32 -0000 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 QemuFwCfgS3TransferOwnership() 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 QemuFwCfgS3WriteBytes(), QemuFwCfgS3ReadBytes(), QemuFwCfgS3SkipBytes(), and QemuFwCfgS3CheckValue() 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 --- OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf | 4 + OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3Base.c | 70 ++++++ OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3BasePei.c | 227 ++++++++++++++++++++ 3 files changed, 301 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..834ac8e523c7 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,72 @@ QemuFwCfgS3Enabled ( { return FALSE; } + + +/** + Install the client module's FW_CFG_BOOT_SCRIPT_APPEND_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] Append FW_CFG_BOOT_SCRIPT_APPEND_FUNCTION to invoke + when the production of ACPI S3 Boot Script + opcodes becomes possible. Append() may be + called immediately from + QemuFwCfgS3TransferOwnership(). + + @param[in,out] Context Client-provided data structure for the Append() + callback function to consume. + + If Context points to dynamically allocated + memory, then Append() must release it. + + If Context points to dynamically allocated + memory, and QemuFwCfgS3TransferOwnership() + returns successfully, then the caller of + QemuFwCfgS3TransferOwnership() must neither + dereference nor even evaluate Context any + longer, as ownership of the referenced area has + been transferred to Append(). + + @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 Append(). + + @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 Append() has been installed, and the + ownership of Context has been transferred. + Reserved memory has been allocated for the + scratch buffer. + + A successful invocation of + QemuFwCfgS3TransferOwnership() cannot be + rolled back. + + @return Error codes from underlying functions. +**/ +EFIAPI +RETURN_STATUS +QemuFwCfgS3TransferOwnership ( + IN FW_CFG_BOOT_SCRIPT_APPEND_FUNCTION *Append, + 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..537678999c5f --- /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 QemuFwCfgS3WriteBytes() 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_APPEND_FUNCTION, which was passed to + QemuFwCfgS3TransferOwnership() as Append. + + @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 + QemuFwCfgS3TransferOwnership(). + + @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 +QemuFwCfgS3WriteBytes ( + 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 QemuFwCfgS3ReadBytes() 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_APPEND_FUNCTION, which was passed to + QemuFwCfgS3TransferOwnership() as Append. + + @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 + QemuFwCfgS3TransferOwnership(). + + @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 +QemuFwCfgS3ReadBytes ( + 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_APPEND_FUNCTION, which was passed to + QemuFwCfgS3TransferOwnership() as Append. + + @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 +QemuFwCfgS3SkipBytes ( + 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_APPEND_FUNCTION, which was passed to + QemuFwCfgS3TransferOwnership() as Append. + + @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 QemuFwCfgS3ReadBytes() ahead of + QemuFwCfgS3CheckValue(). + + ScratchData must point into ScratchBuffer, which was + allocated, and passed to Append(), by + QemuFwCfgS3TransferOwnership(). + + 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 +QemuFwCfgS3CheckValue ( + IN VOID *ScratchData, + IN UINT8 ValueSize, + IN UINT64 ValueMask, + IN UINT64 Value + ) +{ + ASSERT (FALSE); + return RETURN_UNSUPPORTED; +} -- 2.9.3