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 <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>
Reviewed-by: Jordan Justen <jordan.l.justen@intel.com>

diff --git a/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf b/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf
index ba24a0b9d434bd5e9d3d5cf91f7cd01cc2233772..837fd70db6e55b29f40b9f69e18d61eeb719f3e2 100644 (file)
--- a/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf
+++ b/OvmfPkg/Library/QemuFwCfgS3Lib/BaseQemuFwCfgS3LibNull.inf
@@ -33,7 +33,11 @@
 \r
 [Sources]\r
   QemuFwCfgS3Base.c\r
+  QemuFwCfgS3BasePei.c\r
 \r
 [Packages]\r
   MdePkg/MdePkg.dec\r
   OvmfPkg/OvmfPkg.dec\r
+\r
+[LibraryClasses]\r
+  DebugLib\r

diff --git a/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3Base.c b/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3Base.c
index bed9bf3dfb57dbe5f94d12a7c44b0df30f5d8f43..7b71305d1267484a7f6555217c046900a64bbf3c 100644 (file)
--- 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.\r
 **/\r
 \r
+#include <Library/DebugLib.h>\r
 #include <Library/QemuFwCfgS3Lib.h>\r
 \r
 /**\r
@@ -37,3 +38,73 @@ QemuFwCfgS3Enabled (
 {\r
   return FALSE;\r
 }\r
+\r
+\r
+/**\r
+  Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for\r
+  when the production of ACPI S3 Boot Script opcodes becomes possible.\r
+\r
+  Take ownership of the client-provided Context, and pass it to the callback\r
+  function, when the latter is invoked.\r
+\r
+  Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon\r
+  that the client will produce in the callback function.\r
+\r
+  @param[in] Callback           FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke\r
+                                when the production of ACPI S3 Boot Script\r
+                                opcodes becomes possible. Callback() may be\r
+                                called immediately from\r
+                                QemuFwCfgS3CallWhenBootScriptReady().\r
+\r
+  @param[in,out] Context        Client-provided data structure for the\r
+                                Callback() callback function to consume.\r
+\r
+                                If Context points to dynamically allocated\r
+                                memory, then Callback() must release it.\r
+\r
+                                If Context points to dynamically allocated\r
+                                memory, and\r
+                                QemuFwCfgS3CallWhenBootScriptReady() returns\r
+                                successfully, then the caller of\r
+                                QemuFwCfgS3CallWhenBootScriptReady() must\r
+                                neither dereference nor even evaluate Context\r
+                                any longer, as ownership of the referenced area\r
+                                has been transferred to Callback().\r
+\r
+  @param[in] ScratchBufferSize  The size of the scratch buffer that will hold,\r
+                                in reserved memory, all client data read,\r
+                                written, and checked by the ACPI S3 Boot Script\r
+                                opcodes produced by Callback().\r
+\r
+  @retval RETURN_UNSUPPORTED       The library instance does not support this\r
+                                   function.\r
+\r
+  @retval RETURN_NOT_FOUND         The fw_cfg DMA interface to QEMU is\r
+                                   unavailable.\r
+\r
+  @retval RETURN_BAD_BUFFER_SIZE   ScratchBufferSize is too large.\r
+\r
+  @retval RETURN_OUT_OF_RESOURCES  Memory allocation failed.\r
+\r
+  @retval RETURN_SUCCESS           Callback() has been installed, and the\r
+                                   ownership of Context has been transferred.\r
+                                   Reserved memory has been allocated for the\r
+                                   scratch buffer.\r
+\r
+                                   A successful invocation of\r
+                                   QemuFwCfgS3CallWhenBootScriptReady() cannot\r
+                                   be rolled back.\r
+\r
+  @return                          Error codes from underlying functions.\r
+**/\r
+EFIAPI\r
+RETURN_STATUS\r
+QemuFwCfgS3CallWhenBootScriptReady (\r
+  IN     FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION *Callback,\r
+  IN OUT VOID                                 *Context,          OPTIONAL\r
+  IN     UINTN                                ScratchBufferSize\r
+  )\r
+{\r
+  ASSERT (FALSE);\r
+  return RETURN_UNSUPPORTED;\r
+}\r

diff --git a/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3BasePei.c b/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3BasePei.c
new file mode 100644 (file)
index 0000000..674929e
--- /dev/null
+++ b/OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3BasePei.c
@@ -0,0 +1,227 @@
+/** @file\r
+  Shared code for the Base Null and PEI fw_cfg instances of the QemuFwCfgS3Lib\r
+  class.\r
+\r
+  Copyright (C) 2017, Red Hat, Inc.\r
+\r
+  This program and the accompanying materials are licensed and made available\r
+  under the terms and conditions of the BSD License which accompanies this\r
+  distribution. The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT\r
+  WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+**/\r
+\r
+#include <Library/DebugLib.h>\r
+#include <Library/QemuFwCfgS3Lib.h>\r
+\r
+/**\r
+  Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
+  and transfer data to it.\r
+\r
+  The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore\r
+  NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write\r
+  them to fw_cfg using DMA.\r
+\r
+  If the operation fails during S3 resume, the boot script will hang.\r
+\r
+  This function may only be called from the client module's\r
+  FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
+  QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
+\r
+  @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config\r
+                                 item to write, expressed as INT32. If\r
+                                 FirmwareConfigItem is -1, no selection is\r
+                                 made, the write will occur to the currently\r
+                                 selected item, at its currently selected\r
+                                 offset. Otherwise, the specified item will be\r
+                                 selected, and the write will occur at offset\r
+                                 0.\r
+\r
+  @param[in] NumberOfBytes       Size of the data to restore in ScratchBuffer,\r
+                                 and to write from ScratchBuffer, during S3\r
+                                 resume. NumberOfBytes must not exceed\r
+                                 ScratchBufferSize, which was passed to\r
+                                 QemuFwCfgS3CallWhenBootScriptReady().\r
+\r
+  @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3\r
+                                    Boot Script successfully. There is no way\r
+                                    to undo this action.\r
+\r
+  @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.\r
+\r
+  @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is larger than\r
+                                    ScratchBufferSize.\r
+\r
+  @return                           Error codes from underlying functions.\r
+**/\r
+EFIAPI\r
+RETURN_STATUS\r
+QemuFwCfgS3ScriptWriteBytes (\r
+  IN INT32 FirmwareConfigItem,\r
+  IN UINTN NumberOfBytes\r
+  )\r
+{\r
+  ASSERT (FALSE);\r
+  return RETURN_UNSUPPORTED;\r
+}\r
+\r
+\r
+/**\r
+  Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
+  and transfer data from it.\r
+\r
+  The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes\r
+  bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved\r
+  memory.\r
+\r
+  If the operation fails during S3 resume, the boot script will hang.\r
+\r
+  This function may only be called from the client module's\r
+  FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
+  QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
+\r
+  @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config\r
+                                 item to read, expressed as INT32. If\r
+                                 FirmwareConfigItem is -1, no selection is\r
+                                 made, the read will occur from the currently\r
+                                 selected item, from its currently selected\r
+                                 offset. Otherwise, the specified item will be\r
+                                 selected, and the read will occur from offset\r
+                                 0.\r
+\r
+  @param[in] NumberOfBytes       Size of the data to read during S3 resume.\r
+                                 NumberOfBytes must not exceed\r
+                                 ScratchBufferSize, which was passed to\r
+                                 QemuFwCfgS3CallWhenBootScriptReady().\r
+\r
+  @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3\r
+                                    Boot Script successfully. There is no way\r
+                                    to undo this action.\r
+\r
+  @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.\r
+\r
+  @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is larger than\r
+                                    ScratchBufferSize.\r
+\r
+  @return                           Error codes from underlying functions.\r
+**/\r
+EFIAPI\r
+RETURN_STATUS\r
+QemuFwCfgS3ScriptReadBytes (\r
+  IN INT32 FirmwareConfigItem,\r
+  IN UINTN NumberOfBytes\r
+  )\r
+{\r
+  ASSERT (FALSE);\r
+  return RETURN_UNSUPPORTED;\r
+}\r
+\r
+\r
+/**\r
+  Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
+  and increase its offset.\r
+\r
+  If the operation fails during S3 resume, the boot script will hang.\r
+\r
+  This function may only be called from the client module's\r
+  FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
+  QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
+\r
+  @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config\r
+                                 item to advance the offset of, expressed as\r
+                                 INT32. If FirmwareConfigItem is -1, no\r
+                                 selection is made, and the offset for the\r
+                                 currently selected item is increased.\r
+                                 Otherwise, the specified item will be\r
+                                 selected, and the offset increment will occur\r
+                                 from offset 0.\r
+\r
+  @param[in] NumberOfBytes       The number of bytes to skip in the subject\r
+                                 fw_cfg item.\r
+\r
+  @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3\r
+                                    Boot Script successfully. There is no way\r
+                                    to undo this action.\r
+\r
+  @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.\r
+\r
+  @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is too large.\r
+\r
+  @return                           Error codes from underlying functions.\r
+**/\r
+EFIAPI\r
+RETURN_STATUS\r
+QemuFwCfgS3ScriptSkipBytes (\r
+  IN INT32 FirmwareConfigItem,\r
+  IN UINTN NumberOfBytes\r
+  )\r
+{\r
+  ASSERT (FALSE);\r
+  return RETURN_UNSUPPORTED;\r
+}\r
+\r
+\r
+/**\r
+  Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.\r
+\r
+  If the check fails during S3 resume, the boot script will hang.\r
+\r
+  This function may only be called from the client module's\r
+  FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
+  QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
+\r
+  @param[in] ScratchData  Pointer to the UINT8, UINT16, UINT32 or UINT64 field\r
+                          in ScratchBuffer that should be checked. The caller\r
+                          is responsible for populating the field during S3\r
+                          resume, by calling QemuFwCfgS3ScriptReadBytes() ahead\r
+                          of QemuFwCfgS3ScriptCheckValue().\r
+\r
+                          ScratchData must point into ScratchBuffer, which was\r
+                          allocated, and passed to Callback(), by\r
+                          QemuFwCfgS3CallWhenBootScriptReady().\r
+\r
+                          ScratchData must be aligned at ValueSize bytes.\r
+\r
+  @param[in] ValueSize    One of 1, 2, 4 or 8, specifying the size of the field\r
+                          to check.\r
+\r
+  @param[in] ValueMask    The value read from ScratchData is binarily AND-ed\r
+                          with ValueMask, and the result is compared against\r
+                          Value. If the masked data equals Value, the check\r
+                          passes, and the boot script can proceed. Otherwise,\r
+                          the check fails, and the boot script hangs.\r
+\r
+  @param[in] Value        Refer to ValueMask.\r
+\r
+  @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3\r
+                                    Boot Script successfully. There is no way\r
+                                    to undo this action.\r
+\r
+  @retval RETURN_INVALID_PARAMETER  ValueSize is invalid.\r
+\r
+  @retval RETURN_INVALID_PARAMETER  ValueMask or Value cannot be represented in\r
+                                    ValueSize bytes.\r
+\r
+  @retval RETURN_INVALID_PARAMETER  ScratchData is not aligned at ValueSize\r
+                                    bytes.\r
+\r
+  @retval RETURN_BAD_BUFFER_SIZE    The ValueSize bytes at ScratchData aren't\r
+                                    wholly contained in the ScratchBufferSize\r
+                                    bytes at ScratchBuffer.\r
+\r
+  @return                           Error codes from underlying functions.\r
+**/\r
+EFIAPI\r
+RETURN_STATUS\r
+QemuFwCfgS3ScriptCheckValue (\r
+  IN VOID   *ScratchData,\r
+  IN UINT8  ValueSize,\r
+  IN UINT64 ValueMask,\r
+  IN UINT64 Value\r
+  )\r
+{\r
+  ASSERT (FALSE);\r
+  return RETURN_UNSUPPORTED;\r
+}\r