#include "introtypes.h"

Data Structures
struct	_GPA_CACHE_ENTRY

struct	_GPA_CACHE_LINE

struct	_GPA_CACHE_VICTIM

struct	_GPA_CACHE

Typedefs
typedef struct _GPA_CACHE_ENTRY	GPA_CACHE_ENTRY

typedef struct _GPA_CACHE_ENTRY *	PGPA_CACHE_ENTRY

typedef struct _GPA_CACHE_LINE	GPA_CACHE_LINE

typedef struct _GPA_CACHE_LINE *	PGPA_CACHE_LINE

typedef struct _GPA_CACHE_VICTIM	GPA_CACHE_VICTIM

typedef struct _GPA_CACHE_VICTIM *	PGPA_CACHE_VICTIM

typedef struct _GPA_CACHE	GPA_CACHE

typedef struct _GPA_CACHE *	PGPA_CACHE

Functions
void	IntGpaCacheDump (PGPA_CACHE Cache)
	Dumps the entire contents of the GPA cache. More...

INTSTATUS	IntGpaCacheInit (PGPA_CACHE *Cache, DWORD LinesCount, DWORD EntriesCount)
	Initialize a GPA cache. More...

INTSTATUS	IntGpaCacheUnInit (PGPA_CACHE *Cache)
	Uninit a GPA cache. More...

INTSTATUS	IntGpaCacheRelease (PGPA_CACHE Cache, QWORD Gpa)
	Release a previously used cached entry. More...

INTSTATUS	IntGpaCacheFindAndAdd (PGPA_CACHE Cache, QWORD Gpa, void **Hva)
	Search for an entry in the GPA cache, and add it, if it wasn't found. More...

INTSTATUS	IntGpaCacheFetchAndAdd (PGPA_CACHE Cache, QWORD Gpa, DWORD Size, PBYTE Buffer)
	Fetch data from a cached entry, or add it to the cache, of not already present. More...

INTSTATUS	IntGpaCachePatchAndAdd (PGPA_CACHE Cache, QWORD Gpa, DWORD Size, PBYTE Buffer)
	Patch data in a cached entry, or add it to the cache, of not already present. More...

INTSTATUS	IntGpaCacheFlush (PGPA_CACHE Cache)
	Flush the entire GPA cache. More...

Typedef Documentation

◆ GPA_CACHE

typedef struct _GPA_CACHE GPA_CACHE

Describes a GPA cache. The layout consists of LinesCount lines x EntriesCount entries. One can think at it as being EntriesCount associative.

◆ GPA_CACHE_ENTRY

typedef struct _GPA_CACHE_ENTRY GPA_CACHE_ENTRY

Describes on GPA cache entry.

◆ GPA_CACHE_LINE

typedef struct _GPA_CACHE_LINE GPA_CACHE_LINE

Describes one GPA cache line. A line consists of multiple entries.

◆ GPA_CACHE_VICTIM

typedef struct _GPA_CACHE_VICTIM GPA_CACHE_VICTIM

Describes one victim cache entry. Entries are added to the victim cache if their UseCount is non-zero on eviction.

◆ PGPA_CACHE

typedef struct _GPA_CACHE * PGPA_CACHE

◆ PGPA_CACHE_ENTRY

typedef struct _GPA_CACHE_ENTRY * PGPA_CACHE_ENTRY

◆ PGPA_CACHE_LINE

typedef struct _GPA_CACHE_LINE * PGPA_CACHE_LINE

◆ PGPA_CACHE_VICTIM

typedef struct _GPA_CACHE_VICTIM * PGPA_CACHE_VICTIM

Function Documentation

◆ IntGpaCacheDump()

void IntGpaCacheDump ( PGPA_CACHE Cache )

Dumps the entire contents of the GPA cache.

Parameters

[in] Cache The GPA cache to dump.

Definition at line 65 of file gpacache.c.

Referenced by DbgDumpGpaCache().

◆ IntGpaCacheFetchAndAdd()

INTSTATUS IntGpaCacheFetchAndAdd	(	PGPA_CACHE	Cache,
		QWORD	Gpa,
		DWORD	Size,
		PBYTE	Buffer
	)

Fetch data from a cached entry, or add it to the cache, of not already present.

This function will search for the guest physical address Gpa inside the cache. If it is not present, it will be added to the cache. Afterwards, it will copy Size bytes from the given Gpa into the provided Buffer. Gpa doesn't have to be page aligned. This function assumes that Buffer is large enough to accommodate at least the required size.

Parameters

[in]	Cache	The GPA cache.
[in]	Gpa	The Gpa to be accessed.
[in]	Size	Number of bytes to copy from Gpa into Buffer.
[out]	Buffer	Will contain, upon successful return, Size bytes copied from Gpa.

Returns: INT_STATUS_SUCCESS On success.; INT_STATUS_INVALID_PARAMETER If an invalid parameter is supplied.; INT_STATUS_NOT_SUPPORTED If a page overrun is encountered (Gpa + Size points outside the page).

Definition at line 508 of file gpacache.c.

Referenced by IntHookPtsCreateEntry(), IntHookPtsHandleModification(), IntHookPtwEmulateWrite(), IntWinProcValidateSystemCr3(), IntWinSDFetchSecDescAddress(), IntWinSDReadSecDesc(), and IntWinTokenFetchTokenAddress().

◆ IntGpaCacheFindAndAdd()

INTSTATUS IntGpaCacheFindAndAdd	(	PGPA_CACHE	Cache,
		QWORD	Gpa,
		void **	Hva
	)

Search for an entry in the GPA cache, and add it, if it wasn't found.

Checks if the provided Gpa is inside the cache. If it is, it will return a pointer to an already mapped page pointing to the given Gpa. If it isn't, it will first add the entry to the cache, and then return a pointer to the mapped page. The pointer to the mapped page is reference-counted, meaning that once this function is called, the mapped Gpa will be locked (it will not be evicted from the cache and the returned pointer will not be unmapped). In order to properly release the mapped Gpa, IntGpaCacheRelease must be called on Gpa.

Parameters

[in]	Cache	The GPA cache.
[in]	Gpa	The guest physical address that must be returned from the cache.
[out]	Hva	A mapped page tat points to the provided Gpa.

Returns: INT_STATUS_SUCCESS On success.; INT_STATUS_INVALID_PARAMETER If an invalid parameter has been supplied.

Definition at line 451 of file gpacache.c.

Referenced by IntDecEmulatePTWrite(), IntDispatchVeAsEpt(), IntIntegrityCheckAll(), and IntMapGpaForTranslation().

◆ IntGpaCacheFlush()

INTSTATUS IntGpaCacheFlush ( PGPA_CACHE Cache )

Flush the entire GPA cache.

Flushes the entire GPA cache - unmaps & removes all the entries cached so far. Note that entries that are in use (GPAs for which IntGpaCacheFindAndAdd was called, without releasing them using IntGpaCacheRelease) will be moved inside the victim cache, and references to those pages will remain valid until the victim cache is flushed.

Parameters

[in] Cache The GPA cache.

Returns: INT_STATUS_SUCCESS On success.; INT_STATUS_INVALID_PARAMETER If an invalid parameter is supplied.

Definition at line 776 of file gpacache.c.

Referenced by IntFlushGpaCache().

◆ IntGpaCacheInit()

INTSTATUS IntGpaCacheInit	(	PGPA_CACHE *	Cache,
		DWORD	LinesCount,
		DWORD	EntriesCount
	)

Initialize a GPA cache.

Initializes a new GPA cache. The GPA cache will have a layout given by LinesCount and EntriesCount: it will be EntriesCount associative, with LinesCount lines, for a total of EntriesCount * LinesCount entries.

Parameters

[in,out]	Cache	Will contain, upon successful return, the allocated GPA cache.
[in]	LinesCount	The number of cache lines.
[in]	EntriesCount	The number of entries per cache line.

Returns: INT_STATUS_SUCCESS if the cache has been successfully created.; INT_STATUS_INSUFFICIENT_RESOURCES If memory could not be allocated.; INT_STATUS_INVALID_PARAMETER If an invalid parameter has been supplied.

Definition at line 115 of file gpacache.c.

Referenced by IntGuestInit().

◆ IntGpaCachePatchAndAdd()

INTSTATUS IntGpaCachePatchAndAdd	(	PGPA_CACHE	Cache,
		QWORD	Gpa,
		DWORD	Size,
		PBYTE	Buffer
	)

Patch data in a cached entry, or add it to the cache, of not already present.

This function will search for the guest physical address Gpa inside the cache. If it is not present, it will be added to the cache. Afterwards, it will copy Size bytes from the provided Buffer into the given Gpa. Gpa doesn't have to be page aligned. This function assumes that Buffer is large enough to accommodate at least the required size.

Parameters

[in]	Cache	The GPA cache.
[in]	Gpa	The Gpa to be accessed.
[in]	Size	Number of bytes to copy from Gpa into Buffer.
[in]	Buffer	Contains the data to be copied at Gpa.

Returns: INT_STATUS_SUCCESS On success.; INT_STATUS_INVALID_PARAMETER If an invalid parameter is supplied.; INT_STATUS_NOT_SUPPORTED If a page overrun is encountered (Gpa + Size points outside the page).

Definition at line 593 of file gpacache.c.

Referenced by IntDispatchVeAsEpt().

◆ IntGpaCacheRelease()

INTSTATUS IntGpaCacheRelease	(	PGPA_CACHE	Cache,
		QWORD	Gpa
	)

Release a previously used cached entry.

Releases a previously mapped Gpa. This function must be called once the pointer returned by IntGpaCacheFindAndAdd is no longer needed. Calling this function for Gpa values that were not previously mapped using IntGpaCacheFindAndAdd will lead to undefined behavior. Note that the Gpa may have been moved inside the victim cache, if space was needed inside that particular cache line for another entry. This, however, is transparent to the caller.

Parameters

[in]	Cache	The GPA cache.
[in]	Gpa	The Gpa previously mapped using IntGpaCacheFindAndAdd.

Returns: INT_STATUS_SUCCESS On success.; INT_STATUS_INVALID_PARAMETER If an invalid parameter is supplied.; INT_STATUS_NOT_FOUND If the provided Gpa is not found inside the cache.

Definition at line 678 of file gpacache.c.

Referenced by IntDecEmulatePTWrite(), IntDispatchVeAsEpt(), IntIntegrityCheckAll(), and IntUnmapGpaForTranslation().

◆ IntGpaCacheUnInit()

INTSTATUS IntGpaCacheUnInit ( PGPA_CACHE * Cache )

Uninit a GPA cache.

Frees a previously initialized GPA cache. All entries, including entries inside the victim cache, will be removed. This function should be called only during uninit, as it carries to risk of leaving dangling pointers, if all Gpa entries were not released before calling this function.

Parameters

[in,out] Cache The previously allocated GPA cache.

Returns: INT_STATUS_SUCCESS On success.; INT_STATUS_NOT_INITIALIZED_HINT If the provided Cache is not allocated (it is NULL).

Definition at line 209 of file gpacache.c.

Referenced by IntGuestUninit().

Data Structures

Typedefs

Functions

Typedef Documentation

◆ GPA_CACHE

◆ GPA_CACHE_ENTRY

◆ GPA_CACHE_LINE

◆ GPA_CACHE_VICTIM

◆ PGPA_CACHE

◆ PGPA_CACHE_ENTRY

◆ PGPA_CACHE_LINE

◆ PGPA_CACHE_VICTIM

Function Documentation

◆ IntGpaCacheDump()

◆ IntGpaCacheFetchAndAdd()

◆ IntGpaCacheFindAndAdd()

◆ IntGpaCacheFlush()

◆ IntGpaCacheInit()

◆ IntGpaCachePatchAndAdd()

◆ IntGpaCacheRelease()

◆ IntGpaCacheUnInit()