#include "introtypes.h"
#include "bddisasm.h"

Data Structures
struct	_INS_CACHE_INV_ENTRY

struct	_INS_CACHE_ENTRY

struct	_INS_CACHE_LINE

struct	_INS_CACHE

Macros
#define	IC_ANY_VAS 0

Typedefs
typedef struct _INS_CACHE_INV_ENTRY	INS_CACHE_INV_ENTRY

typedef struct _INS_CACHE_INV_ENTRY *	PINS_CACHE_INV_ENTRY

typedef struct _INS_CACHE_ENTRY	INS_CACHE_ENTRY

typedef struct _INS_CACHE_ENTRY *	PINS_CACHE_ENTRY

typedef struct _INS_CACHE_LINE	INS_CACHE_LINE

typedef struct _INS_CACHE_LINE *	PINS_CACHE_LINE

typedef struct _INS_CACHE	INS_CACHE

typedef struct _INS_CACHE *	PINS_CACHE

Functions
INTSTATUS	IntIcLookupInstruction (PINS_CACHE Cache, PINSTRUX Instrux, QWORD Gva, QWORD Cr3)
	Lookup an instruction inside the cache. More...

INTSTATUS	IntIcFlush (PINS_CACHE Cache)
	Flush the entire instruction cache. More...

INTSTATUS	IntIcFlushAddress (PINS_CACHE Cache, QWORD Gva, QWORD Cr3)
	Flush entries cached from a given address. More...

INTSTATUS	IntIcFlushGvaPage (PINS_CACHE Cache, QWORD Gva, QWORD Cr3, BOOLEAN Spill)
	Flush all entries cached from a given guest virtual page. More...

INTSTATUS	IntIcFlushGpaPage (PINS_CACHE Cache, QWORD Gpa)
	Flush all entries cached from a given guest physical page. More...

INTSTATUS	IntIcFlushVaSpace (PINS_CACHE Cache, QWORD Cr3)
	Flush an entire virtual address space. More...

INTSTATUS	IntIcAddInstruction (PINS_CACHE Cache, PINSTRUX Instruction, QWORD Gva, QWORD Cr3, BOOLEAN Global)
	Adds an instruction to the cache. More...

INTSTATUS	IntIcCreate (INS_CACHE **Cache, DWORD LinesCount, DWORD EntriesCount, DWORD InvCount)
	Create anew instruction cache. More...

INTSTATUS	IntIcDestroy (PINS_CACHE *Cache)
	Destroy an instruction cache. More...

void	IntIcDumpIcache (void)
	Dumps the entire contents of the implicit, per guest, instruction cache. More...

Macro Definition Documentation

◆ IC_ANY_VAS

#define IC_ANY_VAS 0

Constant used to indicate that a cache operation should be applied to every virtual address space. Instructions cached inside kernel space must use this value instead of an actual Cr3 value.

Definition at line 86 of file icache.h.

Referenced by IntIcFlushAddress(), IntIcFlushGvaPage(), IntIcFlushVaSpace(), IntIcLookupInstructionInternal(), IntLixAgentActivatePendingAgent(), IntMtblDisable(), IntMtblPatchInstruction(), IntMtblRemoveEntry(), IntPtiDeleteInstruction(), IntPtiMonitorAllPtWriteCandidates(), IntSwapgsDisable(), IntSwapgsStartMitigation(), and IntWinAgentActivatePendingAgent().

Typedef Documentation

◆ INS_CACHE

typedef struct _INS_CACHE INS_CACHE

The instruction cache structure.

◆ INS_CACHE_ENTRY

typedef struct _INS_CACHE_ENTRY INS_CACHE_ENTRY

Describes one cached instruction.

◆ INS_CACHE_INV_ENTRY

typedef struct _INS_CACHE_INV_ENTRY INS_CACHE_INV_ENTRY

Describes one invalidation entry. Invalidation entries are created for each guest page that contains cached instructions. If multiple instructions are cached within the same guest page, a single such invalidation entry is created, and the reference count is incremented accordingly. Whenever a write or a remapping takes place for a page that contains cached instructions, this structure will be used to locate all cached instructions, in order to invalidate them.

◆ INS_CACHE_LINE

typedef struct _INS_CACHE_LINE INS_CACHE_LINE

One cache line containing multiple entries.

◆ PINS_CACHE

typedef struct _INS_CACHE * PINS_CACHE

◆ PINS_CACHE_ENTRY

typedef struct _INS_CACHE_ENTRY * PINS_CACHE_ENTRY

◆ PINS_CACHE_INV_ENTRY

typedef struct _INS_CACHE_INV_ENTRY * PINS_CACHE_INV_ENTRY

◆ PINS_CACHE_LINE

typedef struct _INS_CACHE_LINE * PINS_CACHE_LINE

Function Documentation

◆ IntIcAddInstruction()

INTSTATUS IntIcAddInstruction	(	PINS_CACHE	Cache,
		PINSTRUX	Instruction,
		QWORD	Gva,
		QWORD	Cr3,
		BOOLEAN	Global
	)

Adds an instruction to the cache.

Will add the given instruction to the decoded instruction cache. If an invalid entry is found, the instruction will be added there. If not, a random entry will be selected for eviction. The instruction address Gva is used as a tag, and the address space Cr3 is used to indicate the process the instruction belongs to. If the instruction is in kernel, Cr3 must be IC_ANY_VAS and Global must be true, otherwise the instruction may be evicted from the cache even if the page it lies in is still valid. This function will automatically create the invalidation entries for this instruction, or reference an already existing invalidation entry, if instructions from this page have already been cached.

Parameters

[in]	Cache	The instruction cache.
[in]	Instruction	The decoded instruction to be added inside the cache.
[in]	Gva	Instruction address.
[in]	Cr3	Address space. Must be IC_ANY_VAS for kernel instructions.
[in]	Global	True if the instruction is global (shared among multiple address spaces).

Return values

INT_STATUS_SUCCESS On success.

Definition at line 952 of file icache.c.

Referenced by IntDecDecodeInstructionAtRipWithCache().

◆ IntIcCreate()

INTSTATUS IntIcCreate	(	INS_CACHE **	Cache,
		DWORD	LinesCount,
		DWORD	EntriesCount,
		DWORD	InvCount
	)

Create anew instruction cache.

Will create a new instruction cache. The layout will be given by LinesCount and EntriesCount, thus creating LinesCount x EntriesCount total entries inside the cache. InvCount give the number of entries for the invalidation structures, which are used to invalidate all instruction belonging to the same page.

Parameters

[in,out]	Cache	An address to a pointer that will contain the instruction cache address.
[in]	LinesCount	Number of lines.
[in]	EntriesCount	Number of entries per line.
[in]	InvCount	Number of lines for invalidation entries.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_INSUFFICIENT_RESOURCES	If a memory allocation fails.

Definition at line 1086 of file icache.c.

Referenced by IntGuestInit().

◆ IntIcDestroy()

INTSTATUS IntIcDestroy ( PINS_CACHE * Cache )

Destroy an instruction cache.

Frees an instruction cache previously created using IntIcCreate.

Parameters

[in,out] Cache The previously created instruction cache.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_NOT_INITIALIZED_HINT	If the provided cache was not allocated.

Definition at line 1211 of file icache.c.

Referenced by IntGuestUninit().

◆ IntIcDumpIcache()

void IntIcDumpIcache ( void )

Dumps the entire contents of the implicit, per guest, instruction cache.

Definition at line 55 of file icache.c.

◆ IntIcFlush()

INTSTATUS IntIcFlush ( PINS_CACHE Cache )

Flush the entire instruction cache.

Will invalidate the contents of the given instruction cache. This is done by marking every cached entry as invalid.

Parameters

[in] Cache The instruction cache.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_INVALID_PARAMETER	If an invalid parameter is supplied.

Definition at line 537 of file icache.c.

Referenced by IntIcCreate(), and IntVirtMemSafeWrite().

◆ IntIcFlushAddress()

INTSTATUS IntIcFlushAddress	(	PINS_CACHE	Cache,
		QWORD	Gva,
		QWORD	Cr3
	)

Flush entries cached from a given address.

Will invalidate the entry tagged with Gva. If no entry with the given tag exists, it will return INT_STATUS_NOT_FOUND. This function will invalidate cached entries for a single address, not for an entire page. The function will invalidate only entries inside the provided address space given by Cr3, but it will always invalidate Global entries. If Cr3 == IC_ANY_VAS, entries in all address spaces will be invalidated. NOTE: After an entry is invalidated, it will no longer be used in any ways. It may be replaced by other entries that must be cached, if no other slots are available.

Parameters

[in]	Cache	The instruction cache.
[in]	Gva	The address to be invalidated.
[in]	Cr3	The target virtual address space. If Cr3 == IC_ANY_VAS, entries in all address spaces will be invalidated.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_NOT_FOUND	If no instruction is cached with the tag Gva.

Definition at line 597 of file icache.c.

Referenced by IntLixAgentActivatePendingAgent(), IntMtblDisable(), IntMtblPatchInstruction(), IntMtblRemoveEntry(), IntPtiDeleteInstruction(), IntPtiMonitorAllPtWriteCandidates(), IntSwapgsDisable(), IntSwapgsStartMitigation(), and IntWinAgentActivatePendingAgent().

◆ IntIcFlushGpaPage()

INTSTATUS IntIcFlushGpaPage	(	PINS_CACHE	Cache,
		QWORD	Gpa
	)

Flush all entries cached from a given guest physical page.

Will invalidate all entries cached inside the provided physical page. Low 12 bits inside Gpa are ignored. NOTE: After an entry is invalidated, it will no longer be used in any ways. It may be replaced by other entries that must be cached, if no other slots are available.

Parameters

[in]	Cache	The instruction cache.
[in]	Gpa	The physical page to be invalidated.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_NOT_FOUND	If no instruction is cached with the tag Gva.

Definition at line 734 of file icache.c.

◆ IntIcFlushGvaPage()

INTSTATUS IntIcFlushGvaPage	(	PINS_CACHE	Cache,
		QWORD	Gva,
		QWORD	Cr3,
		BOOLEAN	Spill
	)

Flush all entries cached from a given guest virtual page.

Will invalidate all the instructions cached inside the provided virtual page. Low 12 bits inside Gva are ignored. If Spill is TRUE, it will only invalidate the last instruction in the page, if it spills inside the next page. NOTE: After an entry is invalidated, it will no longer be used in any ways. It may be replaced by other entries that must be cached, if no other slots are available.

Parameters

[in]	Cache	The instruction cache.
[in]	Gva	The page that must be invalidated.
[in]	Cr3	The target virtual address space. If Cr3 == IC_ANY_VAS, all address spaces will be flushed.
[in]	Spill	If true, only the last instruction in the page will be invalidated, if it spills in the next page.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_NOT_FOUND	If no instruction is cached with the tag Gva.

Definition at line 664 of file icache.c.

Referenced by IntIcSwapHandler(), and IntIcWriteHandler().

◆ IntIcFlushVaSpace()

INTSTATUS IntIcFlushVaSpace	(	PINS_CACHE	Cache,
		QWORD	Cr3
	)

Flush an entire virtual address space.

Flushes all the instruction cached inside the provided virtual address space Cr3. If Cr3 == IC_ANY_VAS, instructions in every virtual address space will be flushed.

Parameters

[in]	Cache	The instruction cache.
[in]	Cr3	The target virtual address space. If Cr3 == IC_ANY_VAS, all address spaces will be flushed.

Return values

INT_STATUS_SUCCESS On success.

Definition at line 797 of file icache.c.

Referenced by IntLixTaskDeactivateExploitProtection(), IntLixTaskDestroy(), and IntWinProcChangeProtectionFlags().

◆ IntIcLookupInstruction()

INTSTATUS IntIcLookupInstruction	(	PINS_CACHE	Cache,
		PINSTRUX	Instrux,
		QWORD	Gva,
		QWORD	Cr3
	)

Lookup an instruction inside the cache.

Will check the instruction cache to see if it contains a decoded instruction which is tagged with Gva. If so, it will copy the decoded instruction inside the buffer pointed by Instrux. Otherwise, it will return INT_STATUS_NOT_FOUND. Note that this is a wrapper over IntIcLookupInstructionInternal, and this function is publicly exposed to the callers.

Parameters

[in]	Cache	The instruction cache.
[out]	Instrux	Will contain, upon successful return, the decoded instruction.
[in]	Gva	The Gva that contains the instruction.
[in]	Cr3	The virtual address space that contains the instruction.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_NOT_FOUND	If no instruction is cached with the given Gva.

Definition at line 495 of file icache.c.

Referenced by IntDecDecodeInstructionAtRipWithCache().

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ IC_ANY_VAS

Typedef Documentation

◆ INS_CACHE

◆ INS_CACHE_ENTRY

◆ INS_CACHE_INV_ENTRY

◆ INS_CACHE_LINE

◆ PINS_CACHE

◆ PINS_CACHE_ENTRY

◆ PINS_CACHE_INV_ENTRY

◆ PINS_CACHE_LINE

Function Documentation

◆ IntIcAddInstruction()

◆ IntIcCreate()

◆ IntIcDestroy()

◆ IntIcDumpIcache()

◆ IntIcFlush()

◆ IntIcFlushAddress()

◆ IntIcFlushGpaPage()

◆ IntIcFlushGvaPage()

◆ IntIcFlushVaSpace()

◆ IntIcLookupInstruction()