OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3Pei.c

   1 /** @file
   2   Limited functionality QemuFwCfgS3Lib instance, for PEI phase modules.
   3
   4   QemuFwCfgS3Enabled() queries S3 enablement via fw_cfg. Other library APIs
   5   will report lack of support.
   6
   7   Copyright (C) 2017, Red Hat, Inc.
   8
   9   This program and the accompanying materials are licensed and made available
  10   under the terms and conditions of the BSD License which accompanies this
  11   distribution. The full text of the license may be found at
  12   http://opensource.org/licenses/bsd-license.php
  13
  14   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
  15   WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  16 **/
  17
  18 #include <Library/QemuFwCfgS3Lib.h>
  19
  20 /**
  21   Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for
  22   when the production of ACPI S3 Boot Script opcodes becomes possible.
  23
  24   Take ownership of the client-provided Context, and pass it to the callback
  25   function, when the latter is invoked.
  26
  27   Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon
  28   that the client will produce in the callback function.
  29
  30   @param[in] Callback           FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke
  31                                 when the production of ACPI S3 Boot Script
  32                                 opcodes becomes possible. Callback() may be
  33                                 called immediately from
  34                                 QemuFwCfgS3CallWhenBootScriptReady().
  35
  36   @param[in,out] Context        Client-provided data structure for the
  37                                 Callback() callback function to consume.
  38
  39                                 If Context points to dynamically allocated
  40                                 memory, then Callback() must release it.
  41
  42                                 If Context points to dynamically allocated
  43                                 memory, and
  44                                 QemuFwCfgS3CallWhenBootScriptReady() returns
  45                                 successfully, then the caller of
  46                                 QemuFwCfgS3CallWhenBootScriptReady() must
  47                                 neither dereference nor even evaluate Context
  48                                 any longer, as ownership of the referenced area
  49                                 has been transferred to Callback().
  50
  51   @param[in] ScratchBufferSize  The size of the scratch buffer that will hold,
  52                                 in reserved memory, all client data read,
  53                                 written, and checked by the ACPI S3 Boot Script
  54                                 opcodes produced by Callback().
  55
  56   @retval RETURN_UNSUPPORTED       The library instance does not support this
  57                                    function.
  58
  59   @retval RETURN_NOT_FOUND         The fw_cfg DMA interface to QEMU is
  60                                    unavailable.
  61
  62   @retval RETURN_BAD_BUFFER_SIZE   ScratchBufferSize is too large.
  63
  64   @retval RETURN_OUT_OF_RESOURCES  Memory allocation failed.
  65
  66   @retval RETURN_SUCCESS           Callback() has been installed, and the
  67                                    ownership of Context has been transferred.
  68                                    Reserved memory has been allocated for the
  69                                    scratch buffer.
  70
  71                                    A successful invocation of
  72                                    QemuFwCfgS3CallWhenBootScriptReady() cannot
  73                                    be rolled back.
  74
  75   @return                          Error codes from underlying functions.
  76 **/
  77 RETURN_STATUS
  78 EFIAPI
  79 QemuFwCfgS3CallWhenBootScriptReady (
  80   IN     FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION *Callback,
  81   IN OUT VOID                                 *Context,          OPTIONAL
  82   IN     UINTN                                ScratchBufferSize
  83   )
  84 {
  85   return RETURN_UNSUPPORTED;
  86 }