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