Declares interfaces to utility functions. More...

#include "ia32_type.h"

Include dependency graph for util.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	PhysicalMemoryRun
	Represents ranges of addresses. More...

struct	PhysicalMemoryDescriptor
	Represents a physical memory ranges of the system. More...

Enumerations
enum	VmxStatus : unsigned __int8 { VmxStatus::kOk = 0, VmxStatus::kErrorWithStatus = 1, VmxStatus::kErrorWithoutStatus = 2 }
	Indicates a result of VMX-instructions. More...

enum	HypercallNumber : unsigned __int32 { HypercallNumber::kTerminateVmm, HypercallNumber::kPingVmm, HypercallNumber::kGetSharedProcessorData }
	Available command numbers for VMCALL. More...

Functions
constexpr VmxStatus	operator\|= (_In_ VmxStatus lhs, _In_ VmxStatus rhs)
	Provides \|= operator for VmxStatus. More...

NTSTATUS	UtilInitialization (_In_ PDRIVER_OBJECT driver_object)
	Makes the Util functions ready for use. More...

void	UtilTermination ()
	Frees all resources allocated for the sake of the Util functions. More...

void *	UtilPcToFileHeader (_In_ void *address)
	Returns a module base address of address. More...

const PhysicalMemoryDescriptor *	UtilGetPhysicalMemoryRanges ()
	Returns ranges of physical memory on the system. More...

NTSTATUS	UtilForEachProcessor (_In_ NTSTATUS(callback_routine)(void ), _In_opt_ void *context)
	Executes callback_routine on each processor. More...

NTSTATUS	UtilForEachProcessorDpc (_In_ PKDEFERRED_ROUTINE deferred_routine, _In_opt_ void *context)
	Queues deferred_routine on all processors. More...

NTSTATUS	UtilSleep (_In_ LONG millisecond)
	Suspends the execution of the current thread. More...

void *	UtilMemMem (_In_ const void search_base, _In_ SIZE_T search_size, _In_ const void pattern, _In_ SIZE_T pattern_size)
	Searches a byte pattern from a given address range. More...

void *	UtilGetSystemProcAddress (_In_ const wchar_t *proc_name)
	Get an address of an exported symbol by the kernel or HAL. More...

bool	UtilIsX86Pae ()
	Checks if the system is a PAE-enabled x86 system. More...

bool	UtilIsAccessibleAddress (_In_ void *address)
	Checks is the address is present on physical memory. More...

ULONG64	UtilPaFromVa (_In_ void *va)
	VA -> PA. More...

PFN_NUMBER	UtilPfnFromVa (_In_ void *va)
	VA -> PFN. More...

PFN_NUMBER	UtilPfnFromPa (_In_ ULONG64 pa)
	PA -> PFN. More...

void *	UtilVaFromPa (_In_ ULONG64 pa)
	PA -> VA. More...

ULONG64	UtilPaFromPfn (_In_ PFN_NUMBER pfn)
	PNF -> PA. More...

void *	UtilVaFromPfn (_In_ PFN_NUMBER pfn)
	PNF -> VA. More...

void *	UtilAllocateContiguousMemory (_In_ SIZE_T number_of_bytes)
	Allocates continuous physical memory. More...

void	UtilFreeContiguousMemory (_In_ void *base_address)
	Frees an address allocated by UtilAllocateContiguousMemory() More...

NTSTATUS	UtilVmCall (_In_ HypercallNumber hypercall_number, _In_opt_ void *context)
	Executes VMCALL. More...

void	UtilDumpGpRegisters (_In_ const AllRegisters *all_regs, _In_ ULONG_PTR stack_pointer)
	Debug prints registers. More...

ULONG_PTR	UtilVmRead (_In_ VmcsField field)
	Reads natural-width VMCS. More...

ULONG64	UtilVmRead64 (_In_ VmcsField field)
	Reads 64bit-width VMCS. More...

VmxStatus	UtilVmWrite (_In_ VmcsField field, _In_ ULONG_PTR field_value)
	Writes natural-width VMCS. More...

VmxStatus	UtilVmWrite64 (_In_ VmcsField field, _In_ ULONG64 field_value)
	Writes 64bit-width VMCS. More...

ULONG_PTR	UtilReadMsr (_In_ Msr msr)
	Reads natural-width MSR. More...

ULONG64	UtilReadMsr64 (_In_ Msr msr)
	Reads 64bit-width MSR. More...

void	UtilWriteMsr (_In_ Msr msr, _In_ ULONG_PTR value)
	Writes natural-width MSR. More...

void	UtilWriteMsr64 (_In_ Msr msr, _In_ ULONG64 value)
	Writes 64bit-width MSR. More...

VmxStatus	UtilInveptGlobal ()
	Executes the INVEPT instruction and invalidates EPT entry cache. More...

VmxStatus	UtilInvvpidIndividualAddress (_In_ USHORT vpid, _In_ void *address)
	Executes the INVVPID instruction (type 0) More...

VmxStatus	UtilInvvpidSingleContext (_In_ USHORT vpid)
	Executes the INVVPID instruction (type 1) More...

VmxStatus	UtilInvvpidAllContext ()
	Executes the INVVPID instruction (type 2) More...

VmxStatus	UtilInvvpidSingleContextExceptGlobal (_In_ USHORT vpid)
	Executes the INVVPID instruction (type 3) More...

void	UtilLoadPdptes (_In_ ULONG_PTR cr3_value)
	Loads the PDPTE registers from CR3 to VMCS. More...

NTSTATUS	UtilForceCopyMemory (_In_ void destination, _In_ const void source, _In_ SIZE_T length)
	Does RtlCopyMemory safely even if destination is a read only region. More...

template<typename T >
constexpr bool	UtilIsInBounds (_In_ const T &value, _In_ const T &min, _In_ const T &max)
	Tests if value is in between min and max. More...

Detailed Description

Declares interfaces to utility functions.

Definition in file util.h.

Enumeration Type Documentation

◆ HypercallNumber

enum HypercallNumber : unsigned __int32

strong

Available command numbers for VMCALL.

Enumerator
kTerminateVmm	Terminates VMM.
kPingVmm	Sends ping to the VMM.
kGetSharedProcessorData	Terminates VMM.

Definition at line 68 of file util.h.

◆ VmxStatus

enum VmxStatus : unsigned __int8

strong

Indicates a result of VMX-instructions.

This convention was taken from the VMX-intrinsic functions by Microsoft.

Enumerator
kOk	Operation succeeded.
kErrorWithStatus	Operation failed with extended status available.
kErrorWithoutStatus	Operation failed without status available.

Definition at line 55 of file util.h.

Function Documentation

◆ operator|=()

constexpr VmxStatus operator\|=	(	_In_ VmxStatus	lhs,
		_In_ VmxStatus	rhs
	)

Provides |= operator for VmxStatus.

Definition at line 62 of file util.h.

◆ UtilAllocateContiguousMemory()

void* UtilAllocateContiguousMemory ( _In_ SIZE_T number_of_bytes )

Allocates continuous physical memory.

Parameters

number_of_bytes A size to allocate

Returns: A base address of an allocated memory or nullptr

A returned value must be freed with UtilFreeContiguousMemory().

◆ UtilDumpGpRegisters()

void UtilDumpGpRegisters	(	_In_ const AllRegisters *	all_regs,
		_In_ ULONG_PTR	stack_pointer
	)

Debug prints registers.

Parameters

all_regs	Registers to print out
stack_pointer	A stack pointer before calling this function

◆ UtilForceCopyMemory()

NTSTATUS UtilForceCopyMemory	(	_In_ void *	destination,
		_In_ const void *	source,
		_In_ SIZE_T	length
	)

Does RtlCopyMemory safely even if destination is a read only region.

Parameters

destination	A destination address
source	A source address
length	A size to copy in bytes

Returns: STATUS_SUCCESS if successful

◆ UtilForEachProcessor()

NTSTATUS UtilForEachProcessor	(	_In_ NTSTATUS()(void )	callback_routine,
		_In_opt_ void *	context
	)

Executes callback_routine on each processor.

Parameters

callback_routine	A function to execute
context	An arbitrary parameter for callback_routine

Returns: STATUS_SUCCESS when returned STATUS_SUCCESS on all processors

◆ UtilForEachProcessorDpc()

NTSTATUS UtilForEachProcessorDpc	(	_In_ PKDEFERRED_ROUTINE	deferred_routine,
		_In_opt_ void *	context
	)

Queues deferred_routine on all processors.

Parameters

deferred_routine	A DPC routine to be queued
context	An arbitrary parameter for deferred_routine

Returns: STATUS_SUCCESS when DPC was queued to all processors

deferred_routine must free the pointer to a DPC structure like this: ExFreePoolWithTag(dpc, kHyperPlatformCommonPoolTag).

◆ UtilFreeContiguousMemory()

void UtilFreeContiguousMemory ( _In_ void * base_address )

Frees an address allocated by UtilAllocateContiguousMemory()

Parameters

base_address A return value of UtilAllocateContiguousMemory() to free

◆ UtilGetPhysicalMemoryRanges()

const PhysicalMemoryDescriptor* UtilGetPhysicalMemoryRanges ( )

Returns ranges of physical memory on the system.

Returns: Physical memory ranges; never fails

Definition at line 403 of file util.cpp.

Here is the caller graph for this function:

◆ UtilGetSystemProcAddress()

void* UtilGetSystemProcAddress ( _In_ const wchar_t * proc_name )

Get an address of an exported symbol by the kernel or HAL.

Parameters

proc_name A name of a symbol to locate an address

Returns: An address of the symbol or nullptr

◆ UtilInitialization()

NTSTATUS UtilInitialization ( _In_ PDRIVER_OBJECT driver_object )

Makes the Util functions ready for use.

Parameters

driver_object The current driver's driver object

Returns: STATUS_SUCCESS on success

◆ UtilInveptGlobal()

VmxStatus UtilInveptGlobal ( )

Executes the INVEPT instruction and invalidates EPT entry cache.

Returns: A result of the INVEPT instruction

Definition at line 787 of file util.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UtilInvvpidAllContext()

VmxStatus UtilInvvpidAllContext ( )

Executes the INVVPID instruction (type 2)

Returns: A result of the INVVPID instruction

Definition at line 812 of file util.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UtilInvvpidIndividualAddress()

VmxStatus UtilInvvpidIndividualAddress	(	_In_ USHORT	vpid,
		_In_ void *	address
	)

Executes the INVVPID instruction (type 0)

Returns: A result of the INVVPID instruction

◆ UtilInvvpidSingleContext()

VmxStatus UtilInvvpidSingleContext ( _In_ USHORT vpid )

Executes the INVVPID instruction (type 1)

Returns: A result of the INVVPID instruction

◆ UtilInvvpidSingleContextExceptGlobal()

VmxStatus UtilInvvpidSingleContextExceptGlobal ( _In_ USHORT vpid )

Executes the INVVPID instruction (type 3)

Returns: A result of the INVVPID instruction

◆ UtilIsAccessibleAddress()

bool UtilIsAccessibleAddress ( _In_ void * address )

Checks is the address is present on physical memory.

Parameters

address A virtual address to test

Returns: true if the address is present on physical memory

◆ UtilIsInBounds()

template<typename T >

constexpr bool UtilIsInBounds	(	_In_ const T &	value,
		_In_ const T &	min,
		_In_ const T &	max
	)

Tests if value is in between min and max.

Parameters

value	A value to test
min	A minimum acceptable value
max	A maximum acceptable value

Returns: true if value is in between min and max

Definition at line 300 of file util.h.

Here is the caller graph for this function:

◆ UtilIsX86Pae()

bool UtilIsX86Pae ( )

Checks if the system is a PAE-enabled x86 system.

Returns: true if the system is a PAE-enabled x86 system

Definition at line 512 of file util.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ UtilLoadPdptes()

void UtilLoadPdptes ( _In_ ULONG_PTR cr3_value )

Loads the PDPTE registers from CR3 to VMCS.

Parameters

cr3_value CR3 value to retrieve PDPTEs

◆ UtilMemMem()

void* UtilMemMem	(	_In_ const void *	search_base,
		_In_ SIZE_T	search_size,
		_In_ const void *	pattern,
		_In_ SIZE_T	pattern_size
	)

Searches a byte pattern from a given address range.

Parameters

search_base	An address to start search
search_size	A length to search in bytes
pattern	A byte pattern to search
pattern_size	A size of pattern

Returns: An address of the first occurrence of the patten if found, or nullptr

◆ UtilPaFromPfn()

ULONG64 UtilPaFromPfn ( _In_ PFN_NUMBER pfn )

PNF -> PA.

Parameters

pfn	A page frame number to get its physical address

Returns: A physical address of pfn

◆ UtilPaFromVa()

ULONG64 UtilPaFromVa ( _In_ void * va )

VA -> PA.

Parameters

va	A virtual address to get its physical address

Returns: A physical address of va, or nullptr

Warning: It cannot be used for a virtual address managed by a prototype PTE.

◆ UtilPcToFileHeader()

void* UtilPcToFileHeader ( _In_ void * address )

Returns a module base address of address.

Parameters

address An address to get a base address

Returns: A base address of a range address belongs to, or nullptr

◆ UtilPfnFromPa()

PFN_NUMBER UtilPfnFromPa ( _In_ ULONG64 pa )

PA -> PFN.

Parameters

pa	A physical address to get its page frame number

Returns: A page frame number of pa, or 0

◆ UtilPfnFromVa()

PFN_NUMBER UtilPfnFromVa ( _In_ void * va )

VA -> PFN.

Parameters

va	A virtual address to get its physical address

Returns: A page frame number of va, or 0

Warning: It cannot be used for a virtual address managed by a prototype PTE.

◆ UtilReadMsr()

ULONG_PTR UtilReadMsr ( _In_ Msr msr )

Reads natural-width MSR.

Parameters

msr	MSR to read

Returns: read value

◆ UtilReadMsr64()

ULONG64 UtilReadMsr64 ( _In_ Msr msr )

Reads 64bit-width MSR.

Parameters

msr	MSR to read

Returns: read value

◆ UtilSleep()

NTSTATUS UtilSleep ( _In_ LONG millisecond )

Suspends the execution of the current thread.

Parameters

millisecond Time to suspend in milliseconds

Returns: STATUS_SUCCESS on success

◆ UtilTermination()

void UtilTermination ( )

Frees all resources allocated for the sake of the Util functions.

Definition at line 170 of file util.cpp.

Here is the caller graph for this function:

◆ UtilVaFromPa()

void* UtilVaFromPa ( _In_ ULONG64 pa )

PA -> VA.

Parameters

pa	A physical address to get its virtual address

Returns: A virtual address pa, or 0

◆ UtilVaFromPfn()

void* UtilVaFromPfn ( _In_ PFN_NUMBER pfn )

PNF -> VA.

Parameters

pfn	A page frame number to get its virtual address

Returns: A virtual address of pfn

◆ UtilVmCall()

NTSTATUS UtilVmCall	(	_In_ HypercallNumber	hypercall_number,
		_In_opt_ void *	context
	)

Executes VMCALL.

Parameters

hypercall_number	A command number
context	An arbitrary parameter

Returns: STATUS_SUCCESS if VMXON instruction succeeded

◆ UtilVmRead()

ULONG_PTR UtilVmRead ( _In_ VmcsField field )

Reads natural-width VMCS.

Parameters

field VMCS-field to read

Returns: read value

◆ UtilVmRead64()

ULONG64 UtilVmRead64 ( _In_ VmcsField field )

Reads 64bit-width VMCS.

Parameters

field VMCS-field to read

Returns: read value

◆ UtilVmWrite()

VmxStatus UtilVmWrite	(	_In_ VmcsField	field,
		_In_ ULONG_PTR	field_value
	)

Writes natural-width VMCS.

Parameters

field	VMCS-field to write
field_value	A value to write

Returns: A result of the VMWRITE instruction

◆ UtilVmWrite64()

VmxStatus UtilVmWrite64	(	_In_ VmcsField	field,
		_In_ ULONG64	field_value
	)

Writes 64bit-width VMCS.

Parameters

field	VMCS-field to write
field_value	A value to write

Returns: A result of the VMWRITE instruction

◆ UtilWriteMsr()

void UtilWriteMsr	(	_In_ Msr	msr,
		_In_ ULONG_PTR	value
	)

Writes natural-width MSR.

Parameters

msr	MSR to write
value	A value to write

◆ UtilWriteMsr64()

void UtilWriteMsr64	(	_In_ Msr	msr,
		_In_ ULONG64	value
	)

Writes 64bit-width MSR.

Parameters

msr	MSR to write
value	A value to write

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ HypercallNumber

◆ VmxStatus

Function Documentation

◆ operator|=()

◆ UtilAllocateContiguousMemory()

◆ UtilDumpGpRegisters()

◆ UtilForceCopyMemory()

◆ UtilForEachProcessor()

◆ UtilForEachProcessorDpc()

◆ UtilFreeContiguousMemory()

◆ UtilGetPhysicalMemoryRanges()

◆ UtilGetSystemProcAddress()

◆ UtilInitialization()

◆ UtilInveptGlobal()

◆ UtilInvvpidAllContext()

◆ UtilInvvpidIndividualAddress()

◆ UtilInvvpidSingleContext()

◆ UtilInvvpidSingleContextExceptGlobal()

◆ UtilIsAccessibleAddress()

◆ UtilIsInBounds()

◆ UtilIsX86Pae()

◆ UtilLoadPdptes()

◆ UtilMemMem()

◆ UtilPaFromPfn()

◆ UtilPaFromVa()

◆ UtilPcToFileHeader()

◆ UtilPfnFromPa()

◆ UtilPfnFromVa()

◆ UtilReadMsr()

◆ UtilReadMsr64()

◆ UtilSleep()

◆ UtilTermination()

◆ UtilVaFromPa()

◆ UtilVaFromPfn()

◆ UtilVmCall()

◆ UtilVmRead()

◆ UtilVmRead64()

◆ UtilVmWrite()

◆ UtilVmWrite64()

◆ UtilWriteMsr()

◆ UtilWriteMsr64()