#ifndef __FW_CFG_S3_LIB__\r
#define __FW_CFG_S3_LIB__\r
\r
+#include <Base.h>\r
+\r
/**\r
Determine if S3 support is explicitly enabled.\r
\r
VOID\r
);\r
\r
+\r
+/**\r
+ Prototype for the callback function that the client module provides.\r
+\r
+ In the callback function, the client module calls the\r
+ QemuFwCfgS3ScriptWriteBytes(), QemuFwCfgS3ScriptReadBytes(),\r
+ QemuFwCfgS3ScriptSkipBytes(), and QemuFwCfgS3ScriptCheckValue() functions.\r
+ Those functions produce ACPI S3 Boot Script opcodes that will perform fw_cfg\r
+ DMA operations, and will check any desired values that were read, during S3\r
+ resume.\r
+\r
+ The callback function is invoked when the production of ACPI S3 Boot Script\r
+ opcodes becomes possible. This may occur directly on the call stack of\r
+ QemuFwCfgS3CallWhenBootScriptReady() (see below), or after\r
+ QemuFwCfgS3CallWhenBootScriptReady() has successfully returned.\r
+\r
+ The callback function must not return if it fails -- in the general case,\r
+ there is noone to propagate any errors to. Therefore, on error, an error\r
+ message should be logged, and CpuDeadLoop() must be called.\r
+\r
+ @param[in,out] Context Carries information from the client module\r
+ itself (i.e., from the invocation of\r
+ QemuFwCfgS3CallWhenBootScriptReady()) to the\r
+ callback function.\r
+\r
+ If Context points to dynamically allocated\r
+ storage, then the callback function must\r
+ release it.\r
+\r
+ @param[in,out] ScratchBuffer Points to reserved memory, allocated by\r
+ QemuFwCfgS3CallWhenBootScriptReady()\r
+ internally.\r
+\r
+ ScratchBuffer is typed and sized by the client\r
+ module when it calls\r
+ QemuFwCfgS3CallWhenBootScriptReady(). The\r
+ client module defines a union type of\r
+ structures for ScratchBuffer such that the\r
+ union can hold client data for any desired\r
+ fw_cfg DMA read and write operations, and value\r
+ checking.\r
+\r
+ The callback function casts ScratchBuffer to\r
+ the union type described above. It passes union\r
+ member sizes as NumberOfBytes to\r
+ QemuFwCfgS3ScriptReadBytes() and\r
+ QemuFwCfgS3ScriptWriteBytes(). It passes field\r
+ addresses and sizes in structures in the union\r
+ as ScratchData and ValueSize to\r
+ QemuFwCfgS3ScriptCheckValue().\r
+\r
+ ScratchBuffer is aligned at 8 bytes.\r
+**/\r
+typedef\r
+VOID (EFIAPI FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION) (\r
+ IN OUT VOID *Context, OPTIONAL\r
+ IN OUT VOID *ScratchBuffer\r
+ );\r
+\r
+\r
+/**\r
+ Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for\r
+ when the production of ACPI S3 Boot Script opcodes becomes possible.\r
+\r
+ Take ownership of the client-provided Context, and pass it to the callback\r
+ function, when the latter is invoked.\r
+\r
+ Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon\r
+ that the client will produce in the callback function.\r
+\r
+ @param[in] Callback FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke\r
+ when the production of ACPI S3 Boot Script\r
+ opcodes becomes possible. Callback() may be\r
+ called immediately from\r
+ QemuFwCfgS3CallWhenBootScriptReady().\r
+\r
+ @param[in,out] Context Client-provided data structure for the\r
+ Callback() callback function to consume.\r
+\r
+ If Context points to dynamically allocated\r
+ memory, then Callback() must release it.\r
+\r
+ If Context points to dynamically allocated\r
+ memory, and\r
+ QemuFwCfgS3CallWhenBootScriptReady() returns\r
+ successfully, then the caller of\r
+ QemuFwCfgS3CallWhenBootScriptReady() must\r
+ neither dereference nor even evaluate Context\r
+ any longer, as ownership of the referenced area\r
+ has been transferred to Callback().\r
+\r
+ @param[in] ScratchBufferSize The size of the scratch buffer that will hold,\r
+ in reserved memory, all client data read,\r
+ written, and checked by the ACPI S3 Boot Script\r
+ opcodes produced by Callback().\r
+\r
+ @retval RETURN_UNSUPPORTED The library instance does not support this\r
+ function.\r
+\r
+ @retval RETURN_NOT_FOUND The fw_cfg DMA interface to QEMU is\r
+ unavailable.\r
+\r
+ @retval RETURN_BAD_BUFFER_SIZE ScratchBufferSize is too large.\r
+\r
+ @retval RETURN_OUT_OF_RESOURCES Memory allocation failed.\r
+\r
+ @retval RETURN_SUCCESS Callback() has been installed, and the\r
+ ownership of Context has been transferred.\r
+ Reserved memory has been allocated for the\r
+ scratch buffer.\r
+\r
+ A successful invocation of\r
+ QemuFwCfgS3CallWhenBootScriptReady() cannot\r
+ be rolled back.\r
+\r
+ @return Error codes from underlying functions.\r
+**/\r
+EFIAPI\r
+RETURN_STATUS\r
+QemuFwCfgS3CallWhenBootScriptReady (\r
+ IN FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION *Callback,\r
+ IN OUT VOID *Context, OPTIONAL\r
+ IN UINTN ScratchBufferSize\r
+ );\r
+\r
+\r
+/**\r
+ Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
+ and transfer data to it.\r
+\r
+ The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore\r
+ NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write\r
+ them to fw_cfg using DMA.\r
+\r
+ If the operation fails during S3 resume, the boot script will hang.\r
+\r
+ This function may only be called from the client module's\r
+ FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
+ QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
+\r
+ @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
+ item to write, expressed as INT32. If\r
+ FirmwareConfigItem is -1, no selection is\r
+ made, the write will occur to the currently\r
+ selected item, at its currently selected\r
+ offset. Otherwise, the specified item will be\r
+ selected, and the write will occur at offset\r
+ 0.\r
+\r
+ @param[in] NumberOfBytes Size of the data to restore in ScratchBuffer,\r
+ and to write from ScratchBuffer, during S3\r
+ resume. NumberOfBytes must not exceed\r
+ ScratchBufferSize, which was passed to\r
+ QemuFwCfgS3CallWhenBootScriptReady().\r
+\r
+ @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
+ Boot Script successfully. There is no way\r
+ to undo this action.\r
+\r
+ @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
+\r
+ @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than\r
+ ScratchBufferSize.\r
+\r
+ @return Error codes from underlying functions.\r
+**/\r
+EFIAPI\r
+RETURN_STATUS\r
+QemuFwCfgS3ScriptWriteBytes (\r
+ IN INT32 FirmwareConfigItem,\r
+ IN UINTN NumberOfBytes\r
+ );\r
+\r
+\r
+/**\r
+ Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
+ and transfer data from it.\r
+\r
+ The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes\r
+ bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved\r
+ memory.\r
+\r
+ If the operation fails during S3 resume, the boot script will hang.\r
+\r
+ This function may only be called from the client module's\r
+ FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
+ QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
+\r
+ @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
+ item to read, expressed as INT32. If\r
+ FirmwareConfigItem is -1, no selection is\r
+ made, the read will occur from the currently\r
+ selected item, from its currently selected\r
+ offset. Otherwise, the specified item will be\r
+ selected, and the read will occur from offset\r
+ 0.\r
+\r
+ @param[in] NumberOfBytes Size of the data to read during S3 resume.\r
+ NumberOfBytes must not exceed\r
+ ScratchBufferSize, which was passed to\r
+ QemuFwCfgS3CallWhenBootScriptReady().\r
+\r
+ @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
+ Boot Script successfully. There is no way\r
+ to undo this action.\r
+\r
+ @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
+\r
+ @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than\r
+ ScratchBufferSize.\r
+\r
+ @return Error codes from underlying functions.\r
+**/\r
+EFIAPI\r
+RETURN_STATUS\r
+QemuFwCfgS3ScriptReadBytes (\r
+ IN INT32 FirmwareConfigItem,\r
+ IN UINTN NumberOfBytes\r
+ );\r
+\r
+\r
+/**\r
+ Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
+ and increase its offset.\r
+\r
+ If the operation fails during S3 resume, the boot script will hang.\r
+\r
+ This function may only be called from the client module's\r
+ FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
+ QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
+\r
+ @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
+ item to advance the offset of, expressed as\r
+ INT32. If FirmwareConfigItem is -1, no\r
+ selection is made, and the offset for the\r
+ currently selected item is increased.\r
+ Otherwise, the specified item will be\r
+ selected, and the offset increment will occur\r
+ from offset 0.\r
+\r
+ @param[in] NumberOfBytes The number of bytes to skip in the subject\r
+ fw_cfg item.\r
+\r
+ @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
+ Boot Script successfully. There is no way\r
+ to undo this action.\r
+\r
+ @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
+\r
+ @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is too large.\r
+\r
+ @return Error codes from underlying functions.\r
+**/\r
+EFIAPI\r
+RETURN_STATUS\r
+QemuFwCfgS3ScriptSkipBytes (\r
+ IN INT32 FirmwareConfigItem,\r
+ IN UINTN NumberOfBytes\r
+ );\r
+\r
+\r
+/**\r
+ Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.\r
+\r
+ If the check fails during S3 resume, the boot script will hang.\r
+\r
+ This function may only be called from the client module's\r
+ FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
+ QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
+\r
+ @param[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field\r
+ in ScratchBuffer that should be checked. The caller\r
+ is responsible for populating the field during S3\r
+ resume, by calling QemuFwCfgS3ScriptReadBytes() ahead\r
+ of QemuFwCfgS3ScriptCheckValue().\r
+\r
+ ScratchData must point into ScratchBuffer, which was\r
+ allocated, and passed to Callback(), by\r
+ QemuFwCfgS3CallWhenBootScriptReady().\r
+\r
+ ScratchData must be aligned at ValueSize bytes.\r
+\r
+ @param[in] ValueSize One of 1, 2, 4 or 8, specifying the size of the field\r
+ to check.\r
+\r
+ @param[in] ValueMask The value read from ScratchData is binarily AND-ed\r
+ with ValueMask, and the result is compared against\r
+ Value. If the masked data equals Value, the check\r
+ passes, and the boot script can proceed. Otherwise,\r
+ the check fails, and the boot script hangs.\r
+\r
+ @param[in] Value Refer to ValueMask.\r
+\r
+ @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
+ Boot Script successfully. There is no way\r
+ to undo this action.\r
+\r
+ @retval RETURN_INVALID_PARAMETER ValueSize is invalid.\r
+\r
+ @retval RETURN_INVALID_PARAMETER ValueMask or Value cannot be represented in\r
+ ValueSize bytes.\r
+\r
+ @retval RETURN_INVALID_PARAMETER ScratchData is not aligned at ValueSize\r
+ bytes.\r
+\r
+ @retval RETURN_BAD_BUFFER_SIZE The ValueSize bytes at ScratchData aren't\r
+ wholly contained in the ScratchBufferSize\r
+ bytes at ScratchBuffer.\r
+\r
+ @return Error codes from underlying functions.\r
+**/\r
+EFIAPI\r
+RETURN_STATUS\r
+QemuFwCfgS3ScriptCheckValue (\r
+ IN VOID *ScratchData,\r
+ IN UINT8 ValueSize,\r
+ IN UINT64 ValueMask,\r
+ IN UINT64 Value\r
+ );\r
+\r
#endif\r
projects / mirror_edk2.git / commitdiff