public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
From: Laszlo Ersek <lersek@redhat.com>
To: edk2-devel-01 <edk2-devel@ml01.01.org>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Subject: [PATCH 08/12] OvmfPkg/QemuFwCfgS3Lib: implement opcode APIs for Base Null instance
Date: Thu, 23 Feb 2017 02:48:10 +0100	[thread overview]
Message-ID: <20170223014814.10937-9-lersek@redhat.com> (raw)
In-Reply-To: <20170223014814.10937-1-lersek@redhat.com>

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 <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>
---
 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 <Library/DebugLib.h>
 #include <Library/QemuFwCfgS3Lib.h>
 
 /**
@@ -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 <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 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




  parent reply	other threads:[~2017-02-23  1:48 UTC|newest]

Thread overview: 32+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-02-23  1:48 [PATCH 00/12] ArmVirtPkg, OvmfPkg: factor out QemuFwCfgS3Lib Laszlo Ersek
2017-02-23  1:48 ` [PATCH 01/12] OvmfPkg: introduce QemuFwCfgS3Lib class Laszlo Ersek
2017-02-23  1:48 ` [PATCH 02/12] OvmfPkg/QemuFwCfgS3Lib: add initial Base Null library instance Laszlo Ersek
2017-02-23  1:48 ` [PATCH 03/12] OvmfPkg/QemuFwCfgS3Lib: add initial PEI and DXE fw_cfg library instances Laszlo Ersek
2017-02-23  1:48 ` [PATCH 04/12] ArmVirtPkg: resolve QemuFwCfgS3Lib Laszlo Ersek
2017-02-23 11:18   ` Ard Biesheuvel
2017-02-23  1:48 ` [PATCH 05/12] OvmfPkg: " Laszlo Ersek
2017-02-23  1:48 ` [PATCH 06/12] ArmVirtPkg, OvmfPkg: retire QemuFwCfgS3Enabled() from QemuFwCfgLib Laszlo Ersek
2017-02-23 11:18   ` Ard Biesheuvel
2017-02-23  1:48 ` [PATCH 07/12] OvmfPkg/QemuFwCfgS3Lib: add boot script opcode generation APIs to libclass Laszlo Ersek
2017-03-10  9:58   ` Jordan Justen
2017-03-10 19:14     ` Laszlo Ersek
2017-02-23  1:48 ` Laszlo Ersek [this message]
2017-02-23  1:48 ` [PATCH 09/12] OvmfPkg/QemuFwCfgS3Lib: implement opcode APIs for PEI fw_cfg instance Laszlo Ersek
2017-02-23  1:48 ` [PATCH 10/12] OvmfPkg/QemuFwCfgS3Lib: implement opcode APIs for DXE " Laszlo Ersek
2017-02-23  1:48 ` [PATCH 11/12] OvmfPkg/SmmControl2Dxe: save fw_cfg boot script with QemuFwCfgS3Lib Laszlo Ersek
2017-03-10 10:14   ` Jordan Justen
2017-03-10 19:36     ` Laszlo Ersek
2017-03-13 21:32       ` Jordan Justen
2017-03-13 22:12         ` Laszlo Ersek
2017-03-13 22:43           ` Jordan Justen
2017-03-14  1:58             ` Kinney, Michael D
2017-03-14 13:48               ` Laszlo Ersek
2017-03-14 20:38                 ` Laszlo Ersek
2017-02-23  1:48 ` [PATCH 12/12] OvmfPkg/AcpiPlatformDxe: " Laszlo Ersek
2017-02-23 16:59 ` [PATCH 00/12] ArmVirtPkg, OvmfPkg: factor out QemuFwCfgS3Lib Jordan Justen
2017-02-23 17:22   ` Laszlo Ersek
2017-03-06  9:19 ` Jordan Justen
2017-03-06 18:41   ` Laszlo Ersek
2017-03-10  9:55     ` Jordan Justen
2017-03-10 20:16       ` Laszlo Ersek
2017-03-11  3:17         ` Laszlo Ersek

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-list from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20170223014814.10937-9-lersek@redhat.com \
    --to=devel@edk2.groups.io \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox