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