OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3Base.c

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