OvmfPkg/Include/Library/QemuFwCfgS3Lib.h

   1 /** @file
   2   S3 support for QEMU fw_cfg
   3
   4   This library class enables driver modules (a) to query whether S3 support was
   5   enabled on the QEMU command line, (b) to produce fw_cfg DMA operations that
   6   are to be replayed at S3 resume time.
   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 #ifndef __FW_CFG_S3_LIB__
  20 #define __FW_CFG_S3_LIB__
  21
  22 #include <Base.h>
  23
  24 /**
  25   Determine if S3 support is explicitly enabled.
  26
  27   @retval  TRUE   If S3 support is explicitly enabled. Other functions in this
  28                   library may be called (subject to their individual
  29                   restrictions).
  30
  31            FALSE  Otherwise. This includes unavailability of the firmware
  32                   configuration interface. No other function in this library
  33                   must be called.
  34 **/
  35 BOOLEAN
  36 EFIAPI
  37 QemuFwCfgS3Enabled (
  38   VOID
  39   );
  40
  41
  42 /**
  43   Prototype for the callback function that the client module provides.
  44
  45   In the callback function, the client module calls the
  46   QemuFwCfgS3ScriptWriteBytes(), QemuFwCfgS3ScriptReadBytes(),
  47   QemuFwCfgS3ScriptSkipBytes(), and QemuFwCfgS3ScriptCheckValue() functions.
  48   Those functions produce ACPI S3 Boot Script opcodes that will perform fw_cfg
  49   DMA operations, and will check any desired values that were read, during S3
  50   resume.
  51
  52   The callback function is invoked when the production of ACPI S3 Boot Script
  53   opcodes becomes possible. This may occur directly on the call stack of
  54   QemuFwCfgS3CallWhenBootScriptReady() (see below), or after
  55   QemuFwCfgS3CallWhenBootScriptReady() has successfully returned.
  56
  57   The callback function must not return if it fails -- in the general case,
  58   there is noone to propagate any errors to. Therefore, on error, an error
  59   message should be logged, and CpuDeadLoop() must be called.
  60
  61   @param[in,out] Context        Carries information from the client module
  62                                 itself (i.e., from the invocation of
  63                                 QemuFwCfgS3CallWhenBootScriptReady()) to the
  64                                 callback function.
  65
  66                                 If Context points to dynamically allocated
  67                                 storage, then the callback function must
  68                                 release it.
  69
  70   @param[in,out] ScratchBuffer  Points to reserved memory, allocated by
  71                                 QemuFwCfgS3CallWhenBootScriptReady()
  72                                 internally.
  73
  74                                 ScratchBuffer is typed and sized by the client
  75                                 module when it calls
  76                                 QemuFwCfgS3CallWhenBootScriptReady(). The
  77                                 client module defines a union type of
  78                                 structures for ScratchBuffer such that the
  79                                 union can hold client data for any desired
  80                                 fw_cfg DMA read and write operations, and value
  81                                 checking.
  82
  83                                 The callback function casts ScratchBuffer to
  84                                 the union type described above. It passes union
  85                                 member sizes as NumberOfBytes to
  86                                 QemuFwCfgS3ScriptReadBytes() and
  87                                 QemuFwCfgS3ScriptWriteBytes(). It passes field
  88                                 addresses and sizes in structures in the union
  89                                 as ScratchData and ValueSize to
  90                                 QemuFwCfgS3ScriptCheckValue().
  91
  92                                 ScratchBuffer is aligned at 8 bytes.
  93 **/
  94 typedef
  95 VOID (EFIAPI FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION) (
  96   IN OUT VOID *Context,      OPTIONAL
  97   IN OUT VOID *ScratchBuffer
  98   );
  99
 100
 101 /**
 102   Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for
 103   when the production of ACPI S3 Boot Script opcodes becomes possible.
 104
 105   Take ownership of the client-provided Context, and pass it to the callback
 106   function, when the latter is invoked.
 107
 108   Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon
 109   that the client will produce in the callback function.
 110
 111   @param[in] Callback           FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke
 112                                 when the production of ACPI S3 Boot Script
 113                                 opcodes becomes possible. Callback() may be
 114                                 called immediately from
 115                                 QemuFwCfgS3CallWhenBootScriptReady().
 116
 117   @param[in,out] Context        Client-provided data structure for the
 118                                 Callback() callback function to consume.
 119
 120                                 If Context points to dynamically allocated
 121                                 memory, then Callback() must release it.
 122
 123                                 If Context points to dynamically allocated
 124                                 memory, and
 125                                 QemuFwCfgS3CallWhenBootScriptReady() returns
 126                                 successfully, then the caller of
 127                                 QemuFwCfgS3CallWhenBootScriptReady() must
 128                                 neither dereference nor even evaluate Context
 129                                 any longer, as ownership of the referenced area
 130                                 has been transferred to Callback().
 131
 132   @param[in] ScratchBufferSize  The size of the scratch buffer that will hold,
 133                                 in reserved memory, all client data read,
 134                                 written, and checked by the ACPI S3 Boot Script
 135                                 opcodes produced by Callback().
 136
 137   @retval RETURN_UNSUPPORTED       The library instance does not support this
 138                                    function.
 139
 140   @retval RETURN_NOT_FOUND         The fw_cfg DMA interface to QEMU is
 141                                    unavailable.
 142
 143   @retval RETURN_BAD_BUFFER_SIZE   ScratchBufferSize is too large.
 144
 145   @retval RETURN_OUT_OF_RESOURCES  Memory allocation failed.
 146
 147   @retval RETURN_SUCCESS           Callback() has been installed, and the
 148                                    ownership of Context has been transferred.
 149                                    Reserved memory has been allocated for the
 150                                    scratch buffer.
 151
 152                                    A successful invocation of
 153                                    QemuFwCfgS3CallWhenBootScriptReady() cannot
 154                                    be rolled back.
 155
 156   @return                          Error codes from underlying functions.
 157 **/
 158 RETURN_STATUS
 159 EFIAPI
 160 QemuFwCfgS3CallWhenBootScriptReady (
 161   IN     FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION *Callback,
 162   IN OUT VOID                                 *Context,          OPTIONAL
 163   IN     UINTN                                ScratchBufferSize
 164   );
 165
 166
 167 /**
 168   Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
 169   and transfer data to it.
 170
 171   The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore
 172   NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write
 173   them to fw_cfg using DMA.
 174
 175   If the operation fails during S3 resume, the boot script will hang.
 176
 177   This function may only be called from the client module's
 178   FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
 179   QemuFwCfgS3CallWhenBootScriptReady() as Callback.
 180
 181   @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config
 182                                  item to write, expressed as INT32. If
 183                                  FirmwareConfigItem is -1, no selection is
 184                                  made, the write will occur to the currently
 185                                  selected item, at its currently selected
 186                                  offset. Otherwise, the specified item will be
 187                                  selected, and the write will occur at offset
 188                                  0.
 189
 190   @param[in] NumberOfBytes       Size of the data to restore in ScratchBuffer,
 191                                  and to write from ScratchBuffer, during S3
 192                                  resume. NumberOfBytes must not exceed
 193                                  ScratchBufferSize, which was passed to
 194                                  QemuFwCfgS3CallWhenBootScriptReady().
 195
 196   @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3
 197                                     Boot Script successfully. There is no way
 198                                     to undo this action.
 199
 200   @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.
 201
 202   @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is larger than
 203                                     ScratchBufferSize.
 204
 205   @return                           Error codes from underlying functions.
 206 **/
 207 RETURN_STATUS
 208 EFIAPI
 209 QemuFwCfgS3ScriptWriteBytes (
 210   IN INT32 FirmwareConfigItem,
 211   IN UINTN NumberOfBytes
 212   );
 213
 214
 215 /**
 216   Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
 217   and transfer data from it.
 218
 219   The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes
 220   bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved
 221   memory.
 222
 223   If the operation fails during S3 resume, the boot script will hang.
 224
 225   This function may only be called from the client module's
 226   FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
 227   QemuFwCfgS3CallWhenBootScriptReady() as Callback.
 228
 229   @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config
 230                                  item to read, expressed as INT32. If
 231                                  FirmwareConfigItem is -1, no selection is
 232                                  made, the read will occur from the currently
 233                                  selected item, from its currently selected
 234                                  offset. Otherwise, the specified item will be
 235                                  selected, and the read will occur from offset
 236                                  0.
 237
 238   @param[in] NumberOfBytes       Size of the data to read during S3 resume.
 239                                  NumberOfBytes must not exceed
 240                                  ScratchBufferSize, which was passed to
 241                                  QemuFwCfgS3CallWhenBootScriptReady().
 242
 243   @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3
 244                                     Boot Script successfully. There is no way
 245                                     to undo this action.
 246
 247   @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.
 248
 249   @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is larger than
 250                                     ScratchBufferSize.
 251
 252   @return                           Error codes from underlying functions.
 253 **/
 254 RETURN_STATUS
 255 EFIAPI
 256 QemuFwCfgS3ScriptReadBytes (
 257   IN INT32 FirmwareConfigItem,
 258   IN UINTN NumberOfBytes
 259   );
 260
 261
 262 /**
 263   Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
 264   and increase its offset.
 265
 266   If the operation fails during S3 resume, the boot script will hang.
 267
 268   This function may only be called from the client module's
 269   FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
 270   QemuFwCfgS3CallWhenBootScriptReady() as Callback.
 271
 272   @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config
 273                                  item to advance the offset of, expressed as
 274                                  INT32. If FirmwareConfigItem is -1, no
 275                                  selection is made, and the offset for the
 276                                  currently selected item is increased.
 277                                  Otherwise, the specified item will be
 278                                  selected, and the offset increment will occur
 279                                  from offset 0.
 280
 281   @param[in] NumberOfBytes       The number of bytes to skip in the subject
 282                                  fw_cfg item.
 283
 284   @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3
 285                                     Boot Script successfully. There is no way
 286                                     to undo this action.
 287
 288   @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.
 289
 290   @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is too large.
 291
 292   @return                           Error codes from underlying functions.
 293 **/
 294 RETURN_STATUS
 295 EFIAPI
 296 QemuFwCfgS3ScriptSkipBytes (
 297   IN INT32 FirmwareConfigItem,
 298   IN UINTN NumberOfBytes
 299   );
 300
 301
 302 /**
 303   Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.
 304
 305   If the check fails during S3 resume, the boot script will hang.
 306
 307   This function may only be called from the client module's
 308   FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
 309   QemuFwCfgS3CallWhenBootScriptReady() as Callback.
 310
 311   @param[in] ScratchData  Pointer to the UINT8, UINT16, UINT32 or UINT64 field
 312                           in ScratchBuffer that should be checked. The caller
 313                           is responsible for populating the field during S3
 314                           resume, by calling QemuFwCfgS3ScriptReadBytes() ahead
 315                           of QemuFwCfgS3ScriptCheckValue().
 316
 317                           ScratchData must point into ScratchBuffer, which was
 318                           allocated, and passed to Callback(), by
 319                           QemuFwCfgS3CallWhenBootScriptReady().
 320
 321                           ScratchData must be aligned at ValueSize bytes.
 322
 323   @param[in] ValueSize    One of 1, 2, 4 or 8, specifying the size of the field
 324                           to check.
 325
 326   @param[in] ValueMask    The value read from ScratchData is binarily AND-ed
 327                           with ValueMask, and the result is compared against
 328                           Value. If the masked data equals Value, the check
 329                           passes, and the boot script can proceed. Otherwise,
 330                           the check fails, and the boot script hangs.
 331
 332   @param[in] Value        Refer to ValueMask.
 333
 334   @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3
 335                                     Boot Script successfully. There is no way
 336                                     to undo this action.
 337
 338   @retval RETURN_INVALID_PARAMETER  ValueSize is invalid.
 339
 340   @retval RETURN_INVALID_PARAMETER  ValueMask or Value cannot be represented in
 341                                     ValueSize bytes.
 342
 343   @retval RETURN_INVALID_PARAMETER  ScratchData is not aligned at ValueSize
 344                                     bytes.
 345
 346   @retval RETURN_BAD_BUFFER_SIZE    The ValueSize bytes at ScratchData aren't
 347                                     wholly contained in the ScratchBufferSize
 348                                     bytes at ScratchBuffer.
 349
 350   @return                           Error codes from underlying functions.
 351 **/
 352 RETURN_STATUS
 353 EFIAPI
 354 QemuFwCfgS3ScriptCheckValue (
 355   IN VOID   *ScratchData,
 356   IN UINT8  ValueSize,
 357   IN UINT64 ValueMask,
 358   IN UINT64 Value
 359   );
 360
 361 #endif