#include <Uefi.h>
#include <Library/PeCoffExtraActionLib.h>
#include <Protocol/EmuIoThunk.h>
#include <Protocol/DevicePath.h>

Data Structures
struct	EMU_VENDOR_DEVICE_PATH_NODE

struct	EMU_THUNK_DEVICE_PATH

struct	_EMU_THUNK_PROTOCOL

Macros
#define	EMU_THUNK_PROTOCOL_GUID { 0x5CF32E0B, 0x8EDF, 0x2E44, { 0x9C, 0xDA, 0x93, 0x20, 0x5E, 0x99, 0xEC, 0x1C } }

Typedefs
typedef struct _EMU_THUNK_PROTOCOL	EMU_THUNK_PROTOCOL

typedef UINTN(EFIAPI *	EMU_WRITE_STD_ERROR) (IN UINT8 *Buffer, IN UINTN NumberOfBytes)

typedef EFI_STATUS(EFIAPI *	EMU_CONFIG_STD_IN) (VOID)

typedef UINTN(EFIAPI *	EMU_WRITE_STD_OUT) (IN UINT8 *Buffer, IN UINTN NumberOfBytes)

typedef UINTN(EFIAPI *	EMU_READ_STD_IN) (OUT UINT8 *Buffer, IN UINTN NumberOfBytes)

typedef BOOLEAN(EFIAPI *	EMU_POLL_STD_IN) (VOID)

typedef VOID (EFIAPI	EMU_OS_MALLOC) (IN UINTN Size)

typedef VOID (EFIAPI	EMU_OS_VMALLOC) (IN UINTN Size)

typedef BOOLEAN(EFIAPI *	EMU_OS_FREE) (IN VOID *Ptr)

typedef EFI_STATUS(EFIAPI *	EMU_PE_COFF_GET_ENTRY_POINT) (IN VOID Pe32Data, IN OUT VOID *EntryPoint)

typedef VOID(EFIAPI *	EMU_PE_COFF_RELOCATE_EXTRA_ACTION) (IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext)

typedef VOID(EFIAPI *	EMU_PE_COFF_UNLOAD_EXTRA_ACTION) (IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext)

typedef VOID(EFIAPI *	EMU_ENABLE_INERRUPTS) (VOID)

typedef VOID(EFIAPI *	EMU_DISABLE_INERRUPTS) (VOID)

typedef UINT64(EFIAPI *	EMU_QUERY_PERFORMANCE_FREQENCY) (VOID)

typedef UINT64(EFIAPI *	EMU_QUERY_PERFORMANCE_COUNTER) (VOID)

typedef VOID(EFIAPI *	EMU_SLEEP) (IN UINT64 Nanoseconds)

typedef VOID(EFIAPI *	EMU_CPU_SLEEP) (VOID)

typedef VOID(EFIAPI *	EMU_EXIT) (IN UINTN Status)

typedef VOID(EFIAPI *	EMU_GET_TIME) (OUT EFI_TIME Time, OUT EFI_TIME_CAPABILITIES Capabilities OPTIONAL)

typedef EFI_STATUS(EFIAPI *	EMU_SET_TIME) (IN EFI_TIME *Time)

typedef VOID(EFIAPI *	EMU_SET_TIMER) (IN UINT64 PeriodMs, IN EMU_SET_TIMER_CALLBACK CallBack)

typedef EFI_STATUS(EFIAPI *	EMU_GET_NEXT_PROTOCOL) (IN BOOLEAN EmuBusDriver, OUT EMU_IO_THUNK_PROTOCOL **Instance OPTIONAL)

Functions
typedef	VOID (EFIAPI EMU_SET_TIMER_CALLBACK)(IN UINT64 DeltaMs)

Variables
EFI_GUID	gEmuThunkProtocolGuid

Detailed Description

Emulator Thunk to abstract OS services from pure EFI code

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

Definition in file EmuThunk.h.

Macro Definition Documentation

◆ EMU_THUNK_PROTOCOL_GUID

#define EMU_THUNK_PROTOCOL_GUID { 0x5CF32E0B, 0x8EDF, 0x2E44, { 0x9C, 0xDA, 0x93, 0x20, 0x5E, 0x99, 0xEC, 0x1C } }

Definition at line 14 of file EmuThunk.h.

Typedef Documentation

◆ EMU_CONFIG_STD_IN

typedef EFI_STATUS(EFIAPI * EMU_CONFIG_STD_IN) (VOID)

Definition at line 45 of file EmuThunk.h.

◆ EMU_CPU_SLEEP

typedef VOID(EFIAPI * EMU_CPU_SLEEP) (VOID)

Definition at line 138 of file EmuThunk.h.

◆ EMU_DISABLE_INERRUPTS

typedef VOID(EFIAPI * EMU_DISABLE_INERRUPTS) (VOID)

Definition at line 114 of file EmuThunk.h.

◆ EMU_ENABLE_INERRUPTS

typedef VOID(EFIAPI * EMU_ENABLE_INERRUPTS) (VOID)

Definition at line 108 of file EmuThunk.h.

◆ EMU_EXIT

typedef VOID(EFIAPI * EMU_EXIT) (IN UINTN Status)

Definition at line 144 of file EmuThunk.h.

◆ EMU_GET_NEXT_PROTOCOL

typedef EFI_STATUS(EFIAPI * EMU_GET_NEXT_PROTOCOL) (IN BOOLEAN EmuBusDriver, OUT EMU_IO_THUNK_PROTOCOL **Instance OPTIONAL)

Enumerates the current set of protocol instances that abstract OS services from EFI.

A given protocol can have multiple instances. Usually a protocol is configured via a single PCD string. The data associated for each instance is seperated via a ! in the string. EMU_IO_THUNK_PROTOCOL_CLOSE.ConfigString will contain the information in the PCD string up to the next !. Thus each instance has a unique ConfigString.

Parameters

EmuBusDriver	TRUE means only return protocol instances that need to be produced by the EmuBusDriver. FALSE means return all possible protocols
Instance	On input the protocol to search for, or NULL to start a search of all the supported protocol instances.
NextProtocol	On output it represents the next value to be passed into Protocol.
Interface	A pointer to the EMU_IO_THUNK_PROTOCOL_CLOSE interface.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_NOT_FOUND	The next protocol instance was not found.
EFI_INVALID_PARAMETER	Instance is NULL.

Definition at line 196 of file EmuThunk.h.

◆ EMU_GET_TIME

typedef VOID(EFIAPI * EMU_GET_TIME) (OUT EFI_TIME *Time, OUT EFI_TIME_CAPABILITIES *Capabilities OPTIONAL)

Definition at line 150 of file EmuThunk.h.

◆ EMU_OS_FREE

typedef BOOLEAN(EFIAPI * EMU_OS_FREE) (IN VOID *Ptr)

Definition at line 83 of file EmuThunk.h.

◆ EMU_OS_MALLOC

typedef VOID *(EFIAPI * EMU_OS_MALLOC) (IN UINTN Size)

Definition at line 71 of file EmuThunk.h.

◆ EMU_OS_VMALLOC

typedef VOID *(EFIAPI * EMU_OS_VMALLOC) (IN UINTN Size)

Definition at line 77 of file EmuThunk.h.

◆ EMU_PE_COFF_GET_ENTRY_POINT

typedef EFI_STATUS(EFIAPI * EMU_PE_COFF_GET_ENTRY_POINT) (IN VOID *Pe32Data, IN OUT VOID **EntryPoint)

Definition at line 89 of file EmuThunk.h.

◆ EMU_PE_COFF_RELOCATE_EXTRA_ACTION

typedef VOID(EFIAPI * EMU_PE_COFF_RELOCATE_EXTRA_ACTION) (IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext)

Definition at line 96 of file EmuThunk.h.

◆ EMU_PE_COFF_UNLOAD_EXTRA_ACTION

typedef VOID(EFIAPI * EMU_PE_COFF_UNLOAD_EXTRA_ACTION) (IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext)

Definition at line 102 of file EmuThunk.h.

◆ EMU_POLL_STD_IN

typedef BOOLEAN(EFIAPI * EMU_POLL_STD_IN) (VOID)

Definition at line 65 of file EmuThunk.h.

◆ EMU_QUERY_PERFORMANCE_COUNTER

typedef UINT64(EFIAPI * EMU_QUERY_PERFORMANCE_COUNTER) (VOID)

Definition at line 126 of file EmuThunk.h.

◆ EMU_QUERY_PERFORMANCE_FREQENCY

typedef UINT64(EFIAPI * EMU_QUERY_PERFORMANCE_FREQENCY) (VOID)

Definition at line 120 of file EmuThunk.h.

◆ EMU_READ_STD_IN

typedef UINTN(EFIAPI * EMU_READ_STD_IN) (OUT UINT8 *Buffer, IN UINTN NumberOfBytes)

Definition at line 58 of file EmuThunk.h.

◆ EMU_SET_TIME

typedef EFI_STATUS(EFIAPI * EMU_SET_TIME) (IN EFI_TIME *Time)

Definition at line 157 of file EmuThunk.h.

◆ EMU_SET_TIMER

typedef VOID(EFIAPI * EMU_SET_TIMER) (IN UINT64 PeriodMs, IN EMU_SET_TIMER_CALLBACK CallBack)

Definition at line 169 of file EmuThunk.h.

◆ EMU_SLEEP

typedef VOID(EFIAPI * EMU_SLEEP) (IN UINT64 Nanoseconds)

Definition at line 132 of file EmuThunk.h.

◆ EMU_THUNK_PROTOCOL

typedef struct _EMU_THUNK_PROTOCOL EMU_THUNK_PROTOCOL

Definition at line 35 of file EmuThunk.h.

◆ EMU_WRITE_STD_ERROR

typedef UINTN(EFIAPI * EMU_WRITE_STD_ERROR) (IN UINT8 *Buffer, IN UINTN NumberOfBytes)

Definition at line 38 of file EmuThunk.h.

◆ EMU_WRITE_STD_OUT

typedef UINTN(EFIAPI * EMU_WRITE_STD_OUT) (IN UINT8 *Buffer, IN UINTN NumberOfBytes)

Definition at line 51 of file EmuThunk.h.

Function Documentation

◆ VOID()

typedef VOID ( EFIAPI AP_RESET )

Writes bytes from a buffer to firmware configuration

Parameters

[in]	Size	Size in bytes to write
[in]	Buffer	Buffer to transfer data from (OPTIONAL if Size is 0)

Skips bytes in firmware configuration

Parameters

[in] Size Size in bytes to skip

Prototype for the callback function that the client module provides.

In the callback function, the client module calls the QemuFwCfgS3ScriptWriteBytes(), QemuFwCfgS3ScriptReadBytes(), QemuFwCfgS3ScriptSkipBytes(), and QemuFwCfgS3ScriptCheckValue() functions. Those functions produce ACPI S3 Boot Script opcodes that will perform fw_cfg DMA operations, and will check any desired values that were read, during S3 resume.

The callback function is invoked when the production of ACPI S3 Boot Script opcodes becomes possible. This may occur directly on the call stack of QemuFwCfgS3CallWhenBootScriptReady() (see below), or after QemuFwCfgS3CallWhenBootScriptReady() has successfully returned.

The callback function must not return if it fails – in the general case, there is noone to propagate any errors to. Therefore, on error, an error message should be logged, and CpuDeadLoop() must be called.

Parameters

[in,out] Context Carries information from the client module itself (i.e., from the invocation of QemuFwCfgS3CallWhenBootScriptReady()) to the callback function.

If Context points to dynamically allocated storage, then the callback function must release it.

Parameters

[in,out] ScratchBuffer Points to reserved memory, allocated by QemuFwCfgS3CallWhenBootScriptReady() internally.

ScratchBuffer is typed and sized by the client module when it calls QemuFwCfgS3CallWhenBootScriptReady(). The client module defines a union type of structures for ScratchBuffer such that the union can hold client data for any desired fw_cfg DMA read and write operations, and value checking.

The callback function casts ScratchBuffer to the union type described above. It passes union member sizes as NumberOfBytes to QemuFwCfgS3ScriptReadBytes() and QemuFwCfgS3ScriptWriteBytes(). It passes field addresses and sizes in structures in the union as ScratchData and ValueSize to QemuFwCfgS3ScriptCheckValue().

ScratchBuffer is aligned at 8 bytes.

Reads firmware configuration bytes into a buffer

Parameters

[in]	Size	Size in bytes to read
[in]	Buffer	Buffer to store data into (OPTIONAL if Size is 0)

Writes bytes from a buffer to firmware configuration

Parameters

[in]	Size	Size in bytes to write
[in]	Buffer	Buffer to transfer data from (OPTIONAL if Size is 0)

Skips bytes in firmware configuration

Parameters

[in] Size Size in bytes to skip

Assembly code to move an AP from long mode to real mode.

Move an AP from long mode to real mode in preparation to invoking the reset vector. This is used for SEV-ES guests where a hypervisor is not allowed to set the CS and RIP to point to the reset vector.

Parameters

[in]	BufferStart	The reset vector target.
[in]	Code16	16-bit protected mode code segment value.
[in]	Code32	32-bit protected mode code segment value.
[in]	StackStart	The start of a stack to be used for transitioning from long mode to real mode.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ EMU_THUNK_PROTOCOL_GUID

Typedef Documentation

◆ EMU_CONFIG_STD_IN

◆ EMU_CPU_SLEEP

◆ EMU_DISABLE_INERRUPTS

◆ EMU_ENABLE_INERRUPTS

◆ EMU_EXIT

◆ EMU_GET_NEXT_PROTOCOL

◆ EMU_GET_TIME

◆ EMU_OS_FREE

◆ EMU_OS_MALLOC

◆ EMU_OS_VMALLOC

◆ EMU_PE_COFF_GET_ENTRY_POINT

◆ EMU_PE_COFF_RELOCATE_EXTRA_ACTION

◆ EMU_PE_COFF_UNLOAD_EXTRA_ACTION

◆ EMU_POLL_STD_IN

◆ EMU_QUERY_PERFORMANCE_COUNTER

◆ EMU_QUERY_PERFORMANCE_FREQENCY

◆ EMU_READ_STD_IN

◆ EMU_SET_TIME

◆ EMU_SET_TIMER

◆ EMU_SLEEP

◆ EMU_THUNK_PROTOCOL

◆ EMU_WRITE_STD_ERROR

◆ EMU_WRITE_STD_OUT

Function Documentation

◆ VOID()