#include <Library/BaseLib.h>
#include <Library/DebugLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/QemuFwCfgLib.h>
#include <Library/QemuFwCfgS3Lib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Protocol/S3SaveState.h>

Macros
#define	RESERVED_MEM_ALIGNMENT 8

Functions
STATIC VOID EFIAPI	S3SaveStateInstalledNotify (IN EFI_EVENT Event, IN VOID *Context)

RETURN_STATUS EFIAPI	QemuFwCfgS3CallWhenBootScriptReady (IN FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION Callback, IN OUT VOID Context OPTIONAL, IN UINTN ScratchBufferSize)

RETURN_STATUS EFIAPI	QemuFwCfgS3ScriptWriteBytes (IN INT32 FirmwareConfigItem, IN UINTN NumberOfBytes)

RETURN_STATUS EFIAPI	QemuFwCfgS3ScriptReadBytes (IN INT32 FirmwareConfigItem, IN UINTN NumberOfBytes)

RETURN_STATUS EFIAPI	QemuFwCfgS3ScriptSkipBytes (IN INT32 FirmwareConfigItem, IN UINTN NumberOfBytes)

RETURN_STATUS EFIAPI	QemuFwCfgS3ScriptCheckValue (IN VOID *ScratchData, IN UINT8 ValueSize, IN UINT64 ValueMask, IN UINT64 Value)

Variables
STATIC EFI_EVENT	mS3SaveStateInstalledEvent

STATIC EFI_S3_SAVE_STATE_PROTOCOL *	mS3SaveState

STATIC FW_CFG_DMA_ACCESS *	mDmaAccess

STATIC VOID *	mScratchBuffer

STATIC UINTN	mScratchBufferSize

STATIC FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION *	mCallback

Detailed Description

Full functionality QemuFwCfgS3Lib instance, for DXE phase modules.

SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file QemuFwCfgS3Dxe.c.

Macro Definition Documentation

◆ RESERVED_MEM_ALIGNMENT

#define RESERVED_MEM_ALIGNMENT 8

Definition at line 32 of file QemuFwCfgS3Dxe.c.

Function Documentation

◆ QemuFwCfgS3CallWhenBootScriptReady()

RETURN_STATUS EFIAPI QemuFwCfgS3CallWhenBootScriptReady	(	IN FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION *	Callback,
		IN OUT VOID *Context	OPTIONAL,
		IN UINTN	ScratchBufferSize
	)

Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for when the production of ACPI S3 Boot Script opcodes becomes possible.

Take ownership of the client-provided Context, and pass it to the callback function, when the latter is invoked.

Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon that the client will produce in the callback function.

Parameters

[in]	Callback	FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke when the production of ACPI S3 Boot Script opcodes becomes possible. Callback() may be called immediately from QemuFwCfgS3CallWhenBootScriptReady().
[in,out]	Context	Client-provided data structure for the Callback() callback function to consume.

If Context points to dynamically allocated memory, then Callback() must release it.

If Context points to dynamically allocated memory, and QemuFwCfgS3CallWhenBootScriptReady() returns successfully, then the caller of QemuFwCfgS3CallWhenBootScriptReady() must neither dereference nor even evaluate Context any longer, as ownership of the referenced area has been transferred to Callback().

Parameters

[in] ScratchBufferSize The size of the scratch buffer that will hold, in reserved memory, all client data read, written, and checked by the ACPI S3 Boot Script opcodes produced by Callback().

Return values

RETURN_UNSUPPORTED	The library instance does not support this function.
RETURN_NOT_FOUND	The fw_cfg DMA interface to QEMU is unavailable.
RETURN_BAD_BUFFER_SIZE	ScratchBufferSize is too large.
RETURN_OUT_OF_RESOURCES	Memory allocation failed.
RETURN_SUCCESS	Callback() has been installed, and the ownership of Context has been transferred. Reserved memory has been allocated for the scratch buffer.

A successful invocation of QemuFwCfgS3CallWhenBootScriptReady() cannot be rolled back.

Returns: Error codes from underlying functions.

Definition at line 144 of file QemuFwCfgS3Dxe.c.

◆ QemuFwCfgS3ScriptCheckValue()

RETURN_STATUS EFIAPI QemuFwCfgS3ScriptCheckValue	(	IN VOID *	ScratchData,
		IN UINT8	ValueSize,
		IN UINT64	ValueMask,
		IN UINT64	Value
	)

Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.

If the check fails during S3 resume, the boot script will hang.

This function may only be called from the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to QemuFwCfgS3CallWhenBootScriptReady() as Callback.

Parameters

[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field in ScratchBuffer that should be checked. The caller is responsible for populating the field during S3 resume, by calling QemuFwCfgS3ScriptReadBytes() ahead of QemuFwCfgS3ScriptCheckValue().

ScratchData must point into ScratchBuffer, which was allocated, and passed to Callback(), by QemuFwCfgS3CallWhenBootScriptReady().

ScratchData must be aligned at ValueSize bytes.

Parameters

[in]	ValueSize	One of 1, 2, 4 or 8, specifying the size of the field to check.
[in]	ValueMask	The value read from ScratchData is binarily AND-ed with ValueMask, and the result is compared against Value. If the masked data equals Value, the check passes, and the boot script can proceed. Otherwise, the check fails, and the boot script hangs.
[in]	Value	Refer to ValueMask.

Return values

RETURN_SUCCESS	The opcodes were appended to the ACPI S3 Boot Script successfully. There is no way to undo this action.
RETURN_INVALID_PARAMETER	ValueSize is invalid.
RETURN_INVALID_PARAMETER	ValueMask or Value cannot be represented in ValueSize bytes.
RETURN_INVALID_PARAMETER	ScratchData is not aligned at ValueSize bytes.
RETURN_BAD_BUFFER_SIZE	The ValueSize bytes at ScratchData aren't wholly contained in the ScratchBufferSize bytes at ScratchBuffer.

Returns: Error codes from underlying functions.

Definition at line 809 of file QemuFwCfgS3Dxe.c.

◆ QemuFwCfgS3ScriptReadBytes()

RETURN_STATUS EFIAPI QemuFwCfgS3ScriptReadBytes	(	IN INT32	FirmwareConfigItem,
		IN UINTN	NumberOfBytes
	)

Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item, and transfer data from it.

The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved memory.

If the operation fails during S3 resume, the boot script will hang.

This function may only be called from the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to QemuFwCfgS3CallWhenBootScriptReady() as Callback.

Parameters

[in]	FirmwareConfigItem	The UINT16 selector key of the firmware config item to read, expressed as INT32. If FirmwareConfigItem is -1, no selection is made, the read will occur from the currently selected item, from its currently selected offset. Otherwise, the specified item will be selected, and the read will occur from offset 0.
[in]	NumberOfBytes	Size of the data to read during S3 resume. NumberOfBytes must not exceed ScratchBufferSize, which was passed to QemuFwCfgS3CallWhenBootScriptReady().

Return values

RETURN_SUCCESS	The opcodes were appended to the ACPI S3 Boot Script successfully. There is no way to undo this action.
RETURN_INVALID_PARAMETER	FirmwareConfigItem is invalid.
RETURN_BAD_BUFFER_SIZE	NumberOfBytes is larger than ScratchBufferSize.

Returns: Error codes from underlying functions.

Definition at line 489 of file QemuFwCfgS3Dxe.c.

◆ QemuFwCfgS3ScriptSkipBytes()

RETURN_STATUS EFIAPI QemuFwCfgS3ScriptSkipBytes	(	IN INT32	FirmwareConfigItem,
		IN UINTN	NumberOfBytes
	)

Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item, and increase its offset.

If the operation fails during S3 resume, the boot script will hang.

This function may only be called from the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to QemuFwCfgS3CallWhenBootScriptReady() as Callback.

Parameters

[in]	FirmwareConfigItem	The UINT16 selector key of the firmware config item to advance the offset of, expressed as INT32. If FirmwareConfigItem is -1, no selection is made, and the offset for the currently selected item is increased. Otherwise, the specified item will be selected, and the offset increment will occur from offset 0.
[in]	NumberOfBytes	The number of bytes to skip in the subject fw_cfg item.

Return values

RETURN_SUCCESS	The opcodes were appended to the ACPI S3 Boot Script successfully. There is no way to undo this action.
RETURN_INVALID_PARAMETER	FirmwareConfigItem is invalid.
RETURN_BAD_BUFFER_SIZE	NumberOfBytes is too large.

Returns: Error codes from underlying functions.

Definition at line 643 of file QemuFwCfgS3Dxe.c.

◆ QemuFwCfgS3ScriptWriteBytes()

RETURN_STATUS EFIAPI QemuFwCfgS3ScriptWriteBytes	(	IN INT32	FirmwareConfigItem,
		IN UINTN	NumberOfBytes
	)

Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item, and transfer data to it.

The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write them to fw_cfg using DMA.

If the operation fails during S3 resume, the boot script will hang.

This function may only be called from the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to QemuFwCfgS3CallWhenBootScriptReady() as Callback.

Parameters

[in]	FirmwareConfigItem	The UINT16 selector key of the firmware config item to write, expressed as INT32. If FirmwareConfigItem is -1, no selection is made, the write will occur to the currently selected item, at its currently selected offset. Otherwise, the specified item will be selected, and the write will occur at offset 0.
[in]	NumberOfBytes	Size of the data to restore in ScratchBuffer, and to write from ScratchBuffer, during S3 resume. NumberOfBytes must not exceed ScratchBufferSize, which was passed to QemuFwCfgS3CallWhenBootScriptReady().

Return values

RETURN_SUCCESS	The opcodes were appended to the ACPI S3 Boot Script successfully. There is no way to undo this action.
RETURN_INVALID_PARAMETER	FirmwareConfigItem is invalid.
RETURN_BAD_BUFFER_SIZE	NumberOfBytes is larger than ScratchBufferSize.

Returns: Error codes from underlying functions.

Definition at line 325 of file QemuFwCfgS3Dxe.c.

◆ S3SaveStateInstalledNotify()

STATIC VOID EFIAPI S3SaveStateInstalledNotify	(	IN EFI_EVENT	Event,
		IN VOID *	Context
	)

Event notification function for mS3SaveStateInstalledEvent.

Definition at line 50 of file QemuFwCfgS3Dxe.c.

Variable Documentation

◆ mCallback

STATIC FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION* mCallback

Definition at line 42 of file QemuFwCfgS3Dxe.c.

◆ mDmaAccess

STATIC FW_CFG_DMA_ACCESS* mDmaAccess

Definition at line 34 of file QemuFwCfgS3Dxe.c.

◆ mS3SaveState

STATIC EFI_S3_SAVE_STATE_PROTOCOL* mS3SaveState

Definition at line 25 of file QemuFwCfgS3Dxe.c.

◆ mS3SaveStateInstalledEvent

STATIC EFI_EVENT mS3SaveStateInstalledEvent

Definition at line 20 of file QemuFwCfgS3Dxe.c.

◆ mScratchBuffer

STATIC VOID* mScratchBuffer

Definition at line 35 of file QemuFwCfgS3Dxe.c.

◆ mScratchBufferSize

STATIC UINTN mScratchBufferSize

Definition at line 36 of file QemuFwCfgS3Dxe.c.

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ RESERVED_MEM_ALIGNMENT

Function Documentation

◆ QemuFwCfgS3CallWhenBootScriptReady()

◆ QemuFwCfgS3ScriptCheckValue()

◆ QemuFwCfgS3ScriptReadBytes()

◆ QemuFwCfgS3ScriptSkipBytes()

◆ QemuFwCfgS3ScriptWriteBytes()

◆ S3SaveStateInstalledNotify()

Variable Documentation

◆ mCallback

◆ mDmaAccess

◆ mS3SaveState

◆ mS3SaveStateInstalledEvent

◆ mScratchBuffer

◆ mScratchBufferSize