OvmfPkg/Library/QemuFwCfgS3Lib/QemuFwCfgS3BasePei.c

   1 /** @file
   2   Shared code for the Base Null and PEI fw_cfg instances of the QemuFwCfgS3Lib
   3   class.
   4
   5   Copyright (C) 2017, Red Hat, Inc.
   6
   7   This program and the accompanying materials are licensed and made available
   8   under the terms and conditions of the BSD License which accompanies this
   9   distribution. The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
  13   WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14 **/
  15
  16 #include <Library/DebugLib.h>
  17 #include <Library/QemuFwCfgS3Lib.h>
  18
  19 /**
  20   Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
  21   and transfer data to it.
  22
  23   The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore
  24   NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write
  25   them to fw_cfg using DMA.
  26
  27   If the operation fails during S3 resume, the boot script will hang.
  28
  29   This function may only be called from the client module's
  30   FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
  31   QemuFwCfgS3CallWhenBootScriptReady() as Callback.
  32
  33   @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config
  34                                  item to write, expressed as INT32. If
  35                                  FirmwareConfigItem is -1, no selection is
  36                                  made, the write will occur to the currently
  37                                  selected item, at its currently selected
  38                                  offset. Otherwise, the specified item will be
  39                                  selected, and the write will occur at offset
  40                                  0.
  41
  42   @param[in] NumberOfBytes       Size of the data to restore in ScratchBuffer,
  43                                  and to write from ScratchBuffer, during S3
  44                                  resume. NumberOfBytes must not exceed
  45                                  ScratchBufferSize, which was passed to
  46                                  QemuFwCfgS3CallWhenBootScriptReady().
  47
  48   @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3
  49                                     Boot Script successfully. There is no way
  50                                     to undo this action.
  51
  52   @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.
  53
  54   @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is larger than
  55                                     ScratchBufferSize.
  56
  57   @return                           Error codes from underlying functions.
  58 **/
  59 RETURN_STATUS
  60 EFIAPI
  61 QemuFwCfgS3ScriptWriteBytes (
  62   IN INT32 FirmwareConfigItem,
  63   IN UINTN NumberOfBytes
  64   )
  65 {
  66   ASSERT (FALSE);
  67   return RETURN_UNSUPPORTED;
  68 }
  69
  70
  71 /**
  72   Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
  73   and transfer data from it.
  74
  75   The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes
  76   bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved
  77   memory.
  78
  79   If the operation fails during S3 resume, the boot script will hang.
  80
  81   This function may only be called from the client module's
  82   FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
  83   QemuFwCfgS3CallWhenBootScriptReady() as Callback.
  84
  85   @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config
  86                                  item to read, expressed as INT32. If
  87                                  FirmwareConfigItem is -1, no selection is
  88                                  made, the read will occur from the currently
  89                                  selected item, from its currently selected
  90                                  offset. Otherwise, the specified item will be
  91                                  selected, and the read will occur from offset
  92                                  0.
  93
  94   @param[in] NumberOfBytes       Size of the data to read during S3 resume.
  95                                  NumberOfBytes must not exceed
  96                                  ScratchBufferSize, which was passed to
  97                                  QemuFwCfgS3CallWhenBootScriptReady().
  98
  99   @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3
 100                                     Boot Script successfully. There is no way
 101                                     to undo this action.
 102
 103   @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.
 104
 105   @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is larger than
 106                                     ScratchBufferSize.
 107
 108   @return                           Error codes from underlying functions.
 109 **/
 110 RETURN_STATUS
 111 EFIAPI
 112 QemuFwCfgS3ScriptReadBytes (
 113   IN INT32 FirmwareConfigItem,
 114   IN UINTN NumberOfBytes
 115   )
 116 {
 117   ASSERT (FALSE);
 118   return RETURN_UNSUPPORTED;
 119 }
 120
 121
 122 /**
 123   Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
 124   and increase its offset.
 125
 126   If the operation fails during S3 resume, the boot script will hang.
 127
 128   This function may only be called from the client module's
 129   FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
 130   QemuFwCfgS3CallWhenBootScriptReady() as Callback.
 131
 132   @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config
 133                                  item to advance the offset of, expressed as
 134                                  INT32. If FirmwareConfigItem is -1, no
 135                                  selection is made, and the offset for the
 136                                  currently selected item is increased.
 137                                  Otherwise, the specified item will be
 138                                  selected, and the offset increment will occur
 139                                  from offset 0.
 140
 141   @param[in] NumberOfBytes       The number of bytes to skip in the subject
 142                                  fw_cfg item.
 143
 144   @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3
 145                                     Boot Script successfully. There is no way
 146                                     to undo this action.
 147
 148   @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.
 149
 150   @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is too large.
 151
 152   @return                           Error codes from underlying functions.
 153 **/
 154 RETURN_STATUS
 155 EFIAPI
 156 QemuFwCfgS3ScriptSkipBytes (
 157   IN INT32 FirmwareConfigItem,
 158   IN UINTN NumberOfBytes
 159   )
 160 {
 161   ASSERT (FALSE);
 162   return RETURN_UNSUPPORTED;
 163 }
 164
 165
 166 /**
 167   Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.
 168
 169   If the check fails during S3 resume, the boot script will hang.
 170
 171   This function may only be called from the client module's
 172   FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
 173   QemuFwCfgS3CallWhenBootScriptReady() as Callback.
 174
 175   @param[in] ScratchData  Pointer to the UINT8, UINT16, UINT32 or UINT64 field
 176                           in ScratchBuffer that should be checked. The caller
 177                           is responsible for populating the field during S3
 178                           resume, by calling QemuFwCfgS3ScriptReadBytes() ahead
 179                           of QemuFwCfgS3ScriptCheckValue().
 180
 181                           ScratchData must point into ScratchBuffer, which was
 182                           allocated, and passed to Callback(), by
 183                           QemuFwCfgS3CallWhenBootScriptReady().
 184
 185                           ScratchData must be aligned at ValueSize bytes.
 186
 187   @param[in] ValueSize    One of 1, 2, 4 or 8, specifying the size of the field
 188                           to check.
 189
 190   @param[in] ValueMask    The value read from ScratchData is binarily AND-ed
 191                           with ValueMask, and the result is compared against
 192                           Value. If the masked data equals Value, the check
 193                           passes, and the boot script can proceed. Otherwise,
 194                           the check fails, and the boot script hangs.
 195
 196   @param[in] Value        Refer to ValueMask.
 197
 198   @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3
 199                                     Boot Script successfully. There is no way
 200                                     to undo this action.
 201
 202   @retval RETURN_INVALID_PARAMETER  ValueSize is invalid.
 203
 204   @retval RETURN_INVALID_PARAMETER  ValueMask or Value cannot be represented in
 205                                     ValueSize bytes.
 206
 207   @retval RETURN_INVALID_PARAMETER  ScratchData is not aligned at ValueSize
 208                                     bytes.
 209
 210   @retval RETURN_BAD_BUFFER_SIZE    The ValueSize bytes at ScratchData aren't
 211                                     wholly contained in the ScratchBufferSize
 212                                     bytes at ScratchBuffer.
 213
 214   @return                           Error codes from underlying functions.
 215 **/
 216 RETURN_STATUS
 217 EFIAPI
 218 QemuFwCfgS3ScriptCheckValue (
 219   IN VOID   *ScratchData,
 220   IN UINT8  ValueSize,
 221   IN UINT64 ValueMask,
 222   IN UINT64 Value
 223   )
 224 {
 225   ASSERT (FALSE);
 226   return RETURN_UNSUPPORTED;
 227 }