Defines an interface that exposes various services to the introspection engine. More...

#include "intro_types.h"

Data Structures
struct	_UPPER_IFACE
	Interface that exposes basic services to the introspection engines. More...

Macros
#define	PRINTF_ATTRIBUTE __attribute__((format(printf, 3, 4)))

#define	UPPER_IFACE_VERSION_1 0x00010074

#define	UPPER_IFACE_VERSION_1_SIZE sizeof(UPPER_IFACE)

#define	UPPER_IFACE_VERSION_LATEST UPPER_IFACE_VERSION_1

#define	UPPER_IFACE_VERSION_LATEST_SIZE UPPER_IFACE_VERSION_1_SIZE

Typedefs
typedef INTSTATUS PRINTF_ATTRIBUTE(*	PFUNC_IntTracePrint) (const CHAR File, DWORD Line, const CHAR Format,...)
	Provides print-like trace functionality for introcore. More...

typedef INTSTATUS(*	PFUNC_IntSpinLockInit) (void **SpinLock, PCHAR Name)
	Initializes a spin lock. More...

typedef INTSTATUS(*	PFUNC_IntSpinLockUnInit) (void **SpinLock)
	Uninits a spin lock. More...

typedef INTSTATUS(*	PFUNC_IntSpinLockAcquire) (void *SpinLock)
	Exclusively acquires a spin lock. More...

typedef INTSTATUS(*	PFUNC_IntSpinLockRelease) (void *SpinLock)
	Release a spin lock previously acquired with UPPER_IFACE.SpinLockAcquire. More...

typedef INTSTATUS(*	PFUNC_IntRwSpinLockInit) (void **SpinLock, PCHAR Name)
	Initializes a rw-spin lock. More...

typedef INTSTATUS(*	PFUNC_IntRwSpinLockUnInit) (void **SpinLock)
	Uninits a rw-spin lock. More...

typedef INTSTATUS(*	PFUNC_IntRwSpinLockAcquireShared) (void *SpinLock)
	Acquires a spin rw-lock in shared mode. More...

typedef INTSTATUS(*	PFUNC_IntRwSpinLockAcquireExclusive) (void *SpinLock)
	Acquires a spin rw-lock in exclusive mode. More...

typedef INTSTATUS(*	PFUNC_IntRwSpinLockReleaseShared) (void *SpinLock)
	Release a spin rw-lock previously acquired in shared mode with UPPER_IFACE.RwSpinLockAcquireShared. More...

typedef INTSTATUS(*	PFUNC_IntRwSpinLockReleaseExclusive) (void *SpinLock)
	Release a spin rw-lock previously acquired in exclusive mode with UPPER_IFACE.RwSpinLockAcquireExclusive. More...

typedef INTSTATUS(*	PFUNC_IntQueryHeapSize) (size_t TotalHeapSize, size_t FreeHeapSize)
	Get the available free memory available to introcore. More...

typedef void(*	PFUNC_IntBugCheck) (void)
	Crashes the introspection engine. More...

typedef void(*	PFUNC_IntEnterDebugger) (void)
	Breaks into the debugger. More...

typedef INTSTATUS(*	PFUNC_HpAllocWithTagAndInfo) (void **Address, size_t Size, DWORD Tag)
	Allocates a block of memory. More...

typedef INTSTATUS(*	PFUNC_HpFreeWithTagAndInfo) (void **Address, DWORD Tag)
	Frees a memory block previously allocated with UPPER_IFACE.MemAllocWithTagAndInfo. More...

typedef struct _UPPER_IFACE	UPPER_IFACE
	Interface that exposes basic services to the introspection engines. More...

typedef struct _UPPER_IFACE *	PUPPER_IFACE

Detailed Description

Defines an interface that exposes various services to the introspection engine.

This must be fully implemented by an integrator. Unlike glueiface.h, this can be implemented without any support from the hypervisor.

Definition in file upperiface.h.

Macro Definition Documentation

◆ PRINTF_ATTRIBUTE

#define PRINTF_ATTRIBUTE __attribute__((format(printf, 3, 4)))

Definition at line 22 of file upperiface.h.

◆ UPPER_IFACE_VERSION_1

#define UPPER_IFACE_VERSION_1 0x00010074

Definition at line 288 of file upperiface.h.

◆ UPPER_IFACE_VERSION_1_SIZE

#define UPPER_IFACE_VERSION_1_SIZE sizeof(UPPER_IFACE)

Definition at line 289 of file upperiface.h.

◆ UPPER_IFACE_VERSION_LATEST

#define UPPER_IFACE_VERSION_LATEST UPPER_IFACE_VERSION_1

Definition at line 291 of file upperiface.h.

Referenced by IntGlueInit().

◆ UPPER_IFACE_VERSION_LATEST_SIZE

#define UPPER_IFACE_VERSION_LATEST_SIZE UPPER_IFACE_VERSION_1_SIZE

Definition at line 292 of file upperiface.h.

Referenced by IntGlueInit().

Typedef Documentation

◆ PFUNC_HpAllocWithTagAndInfo

typedef INTSTATUS(* PFUNC_HpAllocWithTagAndInfo) (void **Address, size_t Size, DWORD Tag)

Allocates a block of memory.

Parameters

[in]	Address	on success, will contain a pointer to the allocated memory region.
[in]	Size	The size of the block.
[in]	Tag	The tag of the allocation.

Returns: INT_SUCCESS if the allocation succeeded.; INT_STATUS_INSUFFICIENT_RESOURCES if there is not enough memory available.

Definition at line 230 of file upperiface.h.

◆ PFUNC_HpFreeWithTagAndInfo

typedef INTSTATUS(* PFUNC_HpFreeWithTagAndInfo) (void **Address, DWORD Tag)

Frees a memory block previously allocated with UPPER_IFACE.MemAllocWithTagAndInfo.

Parameters

[in]	Address	Pointer to the memory address of the allocated block. After the function returns it will be set to NULL.
[in]	Tag	The tag of the allocation. Must match the one provided by the UPPER_IFACE.MemFreeWithTagAndInfo call.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 247 of file upperiface.h.

◆ PFUNC_IntBugCheck

typedef void(* PFUNC_IntBugCheck) (void)

Crashes the introspection engine.

This API is used by introcore when an unrecoverable error is encountered. Integrators are free to handle this in the best possible way they can. It is recommended to uninit the introspection engine and to create a memory dump, if possible.

Definition at line 205 of file upperiface.h.

◆ PFUNC_IntEnterDebugger

typedef void(* PFUNC_IntEnterDebugger) (void)

Breaks into the debugger.

This API is used by introcore to enter a debugger, if one is available.

Definition at line 215 of file upperiface.h.

◆ PFUNC_IntQueryHeapSize

typedef INTSTATUS(* PFUNC_IntQueryHeapSize) (size_t *TotalHeapSize, size_t *FreeHeapSize)

Get the available free memory available to introcore.

This function is used by introcore to determine if certain operations can be attempted. In low memory conditions, certain operations will not be attempted.

Parameters

[out]	TotalHeapSize	The total size of the heap, in bytes.
[out]	FreeHeapSize	The size of the remaining free heap, in bytes.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 192 of file upperiface.h.

◆ PFUNC_IntRwSpinLockAcquireExclusive

typedef INTSTATUS(* PFUNC_IntRwSpinLockAcquireExclusive) (void *SpinLock)

Acquires a spin rw-lock in exclusive mode.

Parameters

[in] SpinLock The lock that must be acquired. This was previously initialized by a UPPER_IFACE.RwSpinLockInit call.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 152 of file upperiface.h.

◆ PFUNC_IntRwSpinLockAcquireShared

typedef INTSTATUS(* PFUNC_IntRwSpinLockAcquireShared) (void *SpinLock)

Acquires a spin rw-lock in shared mode.

Parameters

[in] SpinLock The lock that must be acquired. This was previously initialized by a UPPER_IFACE.RwSpinLockInit call.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 139 of file upperiface.h.

◆ PFUNC_IntRwSpinLockInit

typedef INTSTATUS(* PFUNC_IntRwSpinLockInit) (void **SpinLock, PCHAR Name)

Initializes a rw-spin lock.

Parameters

[out]	SpinLock	Pointer to an opaque void* value that will represent the spin lock.
[in]	Name	NULL-terminated string that contains the name of the spin lock.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 111 of file upperiface.h.

◆ PFUNC_IntRwSpinLockReleaseExclusive

typedef INTSTATUS(* PFUNC_IntRwSpinLockReleaseExclusive) (void *SpinLock)

Release a spin rw-lock previously acquired in exclusive mode with UPPER_IFACE.RwSpinLockAcquireExclusive.

Parameters

[in] SpinLock The lock that must be released.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 176 of file upperiface.h.

◆ PFUNC_IntRwSpinLockReleaseShared

typedef INTSTATUS(* PFUNC_IntRwSpinLockReleaseShared) (void *SpinLock)

Release a spin rw-lock previously acquired in shared mode with UPPER_IFACE.RwSpinLockAcquireShared.

Parameters

[in] SpinLock The lock that must be released.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 164 of file upperiface.h.

◆ PFUNC_IntRwSpinLockUnInit

typedef INTSTATUS(* PFUNC_IntRwSpinLockUnInit) (void **SpinLock)

Uninits a rw-spin lock.

Parameters

[in,out] SpinLock Pointer to an opaque void* value that will represent the spin lock. This was previously initialized by a UPPER_IFACE.RwSpinLockInit call. On success, SpinLock will be set to NULL.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 126 of file upperiface.h.

◆ PFUNC_IntSpinLockAcquire

typedef INTSTATUS(* PFUNC_IntSpinLockAcquire) (void *SpinLock)

Exclusively acquires a spin lock.

Parameters

[in] SpinLock The lock that must be acquired. This was previously initialized by a UPPER_IFACE.SpinLockInit call.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 86 of file upperiface.h.

◆ PFUNC_IntSpinLockInit

typedef INTSTATUS(* PFUNC_IntSpinLockInit) (void **SpinLock, PCHAR Name)

Initializes a spin lock.

Parameters

[out]	SpinLock	Pointer to an opaque void* value that will represent the spin lock.
[in]	Name	NULL-terminated string that contains the name of the spin lock.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 58 of file upperiface.h.

◆ PFUNC_IntSpinLockRelease

typedef INTSTATUS(* PFUNC_IntSpinLockRelease) (void *SpinLock)

Release a spin lock previously acquired with UPPER_IFACE.SpinLockAcquire.

Parameters

[in] SpinLock The lock that must be released.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 98 of file upperiface.h.

◆ PFUNC_IntSpinLockUnInit

typedef INTSTATUS(* PFUNC_IntSpinLockUnInit) (void **SpinLock)

Uninits a spin lock.

Parameters

[in,out] SpinLock Pointer to an opaque void* value that will represent the spin lock. This was previously initialized by a UPPER_IFACE.SpinLockInit call. On success, SpinLock will be set to NULL.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value.

Definition at line 73 of file upperiface.h.

◆ PFUNC_IntTracePrint

typedef INTSTATUS PRINTF_ATTRIBUTE(* PFUNC_IntTracePrint) (const CHAR *File, DWORD Line, const CHAR *Format,...)

Provides print-like trace functionality for introcore.

Parameters

[in]	File	NULL terminated string of the name of the file from which the message originates, can be NULL.
[in]	Line	The line at which the log originates. If File is NULL it should be ignored.
[in]	Format	printf-like format string.

Returns: INT_STATUS_SUCCESS on success, or an appropriate INTSTATUS error value

Definition at line 42 of file upperiface.h.

◆ PUPPER_IFACE

typedef struct _UPPER_IFACE * PUPPER_IFACE

◆ UPPER_IFACE

typedef struct _UPPER_IFACE UPPER_IFACE

Interface that exposes basic services to the introspection engines.

Before using any of the function pointers in the structure, it must be validated using the UPPER_IFACE.Version and UPPER_IFACE.Size fields in order to ensure that the introcore version used matches the one for which this header file was published.

Data Structures

Macros

Typedefs

Detailed Description

Macro Definition Documentation

◆ PRINTF_ATTRIBUTE

◆ UPPER_IFACE_VERSION_1

◆ UPPER_IFACE_VERSION_1_SIZE

◆ UPPER_IFACE_VERSION_LATEST

◆ UPPER_IFACE_VERSION_LATEST_SIZE

Typedef Documentation

◆ PFUNC_HpAllocWithTagAndInfo

◆ PFUNC_HpFreeWithTagAndInfo

◆ PFUNC_IntBugCheck

◆ PFUNC_IntEnterDebugger

◆ PFUNC_IntQueryHeapSize

◆ PFUNC_IntRwSpinLockAcquireExclusive

◆ PFUNC_IntRwSpinLockAcquireShared

◆ PFUNC_IntRwSpinLockInit

◆ PFUNC_IntRwSpinLockReleaseExclusive

◆ PFUNC_IntRwSpinLockReleaseShared

◆ PFUNC_IntRwSpinLockUnInit

◆ PFUNC_IntSpinLockAcquire

◆ PFUNC_IntSpinLockInit

◆ PFUNC_IntSpinLockRelease

◆ PFUNC_IntSpinLockUnInit

◆ PFUNC_IntTracePrint

◆ PUPPER_IFACE

◆ UPPER_IFACE