Ept.h File Reference

Contains the headers relating to EPT structures, MTRR and all basic Hooking structures. More...

Go to the source code of this file.

Classes
struct	_MTRR_RANGE_DESCRIPTOR
	MTRR Descriptor. More...
union	_IA32_MTRR_FIXED_RANGE_TYPE
	Fixed range MTRR. More...
struct	_EPT_STATE
	Main structure for saving the state of EPT among the project. More...
struct	_VMM_EPT_DYNAMIC_SPLIT
	Split 2MB granularity to 4 KB granularity. More...

Macros
#define	PAGE_ATTRIB_READ   0x2
	Page attributes for internal use.
#define	PAGE_ATTRIB_WRITE   0x4
#define	PAGE_ATTRIB_EXEC   0x8
#define	PAGE_ATTRIB_EXEC_HIDDEN_HOOK   0x10
#define	SIZE_2_MB   ((SIZE_T)(512 * PAGE_SIZE))
	Integer 2MB.
#define	SIZE_1_GB   ((SIZE_T)(512 * SIZE_2_MB))
	Integer 1GB.
#define	SIZE_512_GB   ((SIZE_T)(512 * SIZE_1_GB))
	Integer 512GB.
#define	ADDRMASK_EPT_PML1_OFFSET(_VAR_)
	Offset into the 1st paging structure (4096 byte).
#define	ADDRMASK_EPT_PML1_INDEX(_VAR_)
	Index of the 1st paging structure (4096 byte).
#define	ADDRMASK_EPT_PML2_INDEX(_VAR_)
	Index of the 2nd paging structure (2MB).
#define	ADDRMASK_EPT_PML3_INDEX(_VAR_)
	Index of the 3rd paging structure (1GB).
#define	ADDRMASK_EPT_PML4_INDEX(_VAR_)
	Index of the 4th paging structure (512GB).
#define	MAX_VARIABLE_RANGE_MTRRS   255
	Architecturally defined number of variable range MTRRs.
#define	NUM_FIXED_RANGE_MTRRS   ((1 + 2 + 8) * RTL_NUMBER_OF_FIELD(IA32_MTRR_FIXED_RANGE_TYPE, s.Types))
	Architecturally defined number of fixed range MTRRs. 1 register for 64k, 2 registers for 16k, 8 registers for 4k, and each register has 8 ranges as per "Fixed Range MTRRs" states.
#define	NUM_MTRR_ENTRIES   (MAX_VARIABLE_RANGE_MTRRS + NUM_FIXED_RANGE_MTRRS)
	Total number of MTRR descriptors to store.

Typedefs
typedef struct _MTRR_RANGE_DESCRIPTOR	MTRR_RANGE_DESCRIPTOR
	MTRR Descriptor.
typedef struct _MTRR_RANGE_DESCRIPTOR *	PMTRR_RANGE_DESCRIPTOR
typedef union _IA32_MTRR_FIXED_RANGE_TYPE	IA32_MTRR_FIXED_RANGE_TYPE
	Fixed range MTRR.
typedef struct _EPT_STATE	EPT_STATE
	Main structure for saving the state of EPT among the project.
typedef struct _EPT_STATE *	PEPT_STATE
typedef struct _VMM_EPT_DYNAMIC_SPLIT	VMM_EPT_DYNAMIC_SPLIT
	Split 2MB granularity to 4 KB granularity.
typedef struct _VMM_EPT_DYNAMIC_SPLIT *	PVMM_EPT_DYNAMIC_SPLIT

Functions
BOOLEAN	EptSetupPML2Entry (PVMM_EPT_PAGE_TABLE EptPageTable, PEPT_PML2_ENTRY NewEntry, SIZE_T PageFrameNumber)
	Set up PML2 Entries.
BOOLEAN	EptHandlePageHookExit (_Inout_ VIRTUAL_MACHINE_STATE *VCpu, _In_ VMX_EXIT_QUALIFICATION_EPT_VIOLATION ViolationQualification, _In_ UINT64 GuestPhysicalAddr)
BOOLEAN	EptCheckFeatures (VOID)
	Check for EPT Features.
BOOLEAN	EptBuildMtrrMap (VOID)
	Build MTRR Map.
PVMM_EPT_PAGE_TABLE	EptAllocateAndCreateIdentityPageTable (VOID)
	Allocates page maps and create identity page table.
BOOLEAN	EptSplitLargePage (PVMM_EPT_PAGE_TABLE EptPageTable, BOOLEAN UsePreAllocatedBuffer, SIZE_T PhysicalAddress)
	Convert large pages to 4KB pages.
PEPT_PML2_ENTRY	EptGetPml2Entry (PVMM_EPT_PAGE_TABLE EptPageTable, SIZE_T PhysicalAddress)
	Split 2MB (LargePage) into 4kb pages.
BOOLEAN	EptLogicalProcessorInitialize (VOID)
	Initialize EPT Table based on Processor Index.
BOOLEAN	EptHandleEptViolation (VIRTUAL_MACHINE_STATE *VCpu)
	Handle EPT Violation.
PEPT_PML1_ENTRY	EptGetPml1Entry (PVMM_EPT_PAGE_TABLE EptPageTable, SIZE_T PhysicalAddress)
	Get the PML1 Entry of a special address.
PVOID	EptGetPml1OrPml2Entry (PVMM_EPT_PAGE_TABLE EptPageTable, SIZE_T PhysicalAddress, BOOLEAN *IsLargePage)
	Get the PML1 entry for this physical address if the large page is available then large page of Pml2 is returned.
VOID	EptHandleMisconfiguration (VOID)
	Handle Ept Misconfigurations.
VOID	EptSetPML1AndInvalidateTLB (_Inout_ VIRTUAL_MACHINE_STATE *VCpu, _Out_ PEPT_PML1_ENTRY EntryAddress, _In_ EPT_PML1_ENTRY EntryValue, _In_ _Strict_type_match_ INVEPT_TYPE InvalidationType)
	This function set the specific PML1 entry in a spinlock protected area then invalidate the TLB , this function should be called from vmx root-mode.
BOOLEAN	EptCheckAndHandleBreakpoint (VIRTUAL_MACHINE_STATE *VCpu)
	Check if the breakpoint vm-exit relates to EPT hook or not.

Detailed Description

Contains the headers relating to EPT structures, MTRR and all basic Hooking structures.

Author

Sina Karvandi (sina@.nosp@m.hype.nosp@m.rdbg..nosp@m.org)

Version

0.1

Date

2020-04-11

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

ADDRMASK_EPT_PML1_INDEX

#define ADDRMASK_EPT_PML1_INDEX

(

_VAR_

)

Value:

(((_VAR_) & 0x1FF000ULL) >> 12)

Index of the 1st paging structure (4096 byte).

ADDRMASK_EPT_PML1_OFFSET

#define ADDRMASK_EPT_PML1_OFFSET

(

_VAR_

)

Value:

((_VAR_) & 0xFFFULL)

Offset into the 1st paging structure (4096 byte).

ADDRMASK_EPT_PML2_INDEX

#define ADDRMASK_EPT_PML2_INDEX

(

_VAR_

)

Value:

(((_VAR_) & 0x3FE00000ULL) >> 21)

Index of the 2nd paging structure (2MB).

ADDRMASK_EPT_PML3_INDEX

#define ADDRMASK_EPT_PML3_INDEX

(

_VAR_

)

Value:

(((_VAR_) & 0x7FC0000000ULL) >> 30)

Index of the 3rd paging structure (1GB).

ADDRMASK_EPT_PML4_INDEX

#define ADDRMASK_EPT_PML4_INDEX

(

_VAR_

)

Value:

(((_VAR_) & 0xFF8000000000ULL) >> 39)

Index of the 4th paging structure (512GB).

MAX_VARIABLE_RANGE_MTRRS

#define MAX_VARIABLE_RANGE_MTRRS   255

Architecturally defined number of variable range MTRRs.

NUM_FIXED_RANGE_MTRRS

#define NUM_FIXED_RANGE_MTRRS   ((1 + 2 + 8) * RTL_NUMBER_OF_FIELD(IA32_MTRR_FIXED_RANGE_TYPE, s.Types))

Architecturally defined number of fixed range MTRRs. 1 register for 64k, 2 registers for 16k, 8 registers for 4k, and each register has 8 ranges as per "Fixed Range MTRRs" states.

NUM_MTRR_ENTRIES

#define NUM_MTRR_ENTRIES   (MAX_VARIABLE_RANGE_MTRRS + NUM_FIXED_RANGE_MTRRS)

Total number of MTRR descriptors to store.

PAGE_ATTRIB_EXEC

#define PAGE_ATTRIB_EXEC   0x8

PAGE_ATTRIB_EXEC_HIDDEN_HOOK

#define PAGE_ATTRIB_EXEC_HIDDEN_HOOK   0x10

PAGE_ATTRIB_READ

#define PAGE_ATTRIB_READ   0x2

Page attributes for internal use.

PAGE_ATTRIB_WRITE

#define PAGE_ATTRIB_WRITE   0x4

SIZE_1_GB

#define SIZE_1_GB   ((SIZE_T)(512 * SIZE_2_MB))

Integer 1GB.

SIZE_2_MB

#define SIZE_2_MB   ((SIZE_T)(512 * PAGE_SIZE))

Integer 2MB.

SIZE_512_GB

#define SIZE_512_GB   ((SIZE_T)(512 * SIZE_1_GB))

Integer 512GB.

Typedef Documentation

EPT_STATE

typedef struct _EPT_STATE EPT_STATE

Main structure for saving the state of EPT among the project.

IA32_MTRR_FIXED_RANGE_TYPE

typedef union _IA32_MTRR_FIXED_RANGE_TYPE IA32_MTRR_FIXED_RANGE_TYPE

Fixed range MTRR.

MTRR_RANGE_DESCRIPTOR

typedef struct _MTRR_RANGE_DESCRIPTOR MTRR_RANGE_DESCRIPTOR

MTRR Descriptor.

PEPT_STATE

typedef struct _EPT_STATE * PEPT_STATE

PMTRR_RANGE_DESCRIPTOR

typedef struct _MTRR_RANGE_DESCRIPTOR * PMTRR_RANGE_DESCRIPTOR

PVMM_EPT_DYNAMIC_SPLIT

typedef struct _VMM_EPT_DYNAMIC_SPLIT * PVMM_EPT_DYNAMIC_SPLIT

VMM_EPT_DYNAMIC_SPLIT

typedef struct _VMM_EPT_DYNAMIC_SPLIT VMM_EPT_DYNAMIC_SPLIT

Split 2MB granularity to 4 KB granularity.

Function Documentation

EptAllocateAndCreateIdentityPageTable()

PVMM_EPT_PAGE_TABLE EptAllocateAndCreateIdentityPageTable

(

VOID

)

Allocates page maps and create identity page table.

Returns

PVMM_EPT_PAGE_TABLE identity map page-table

{
    PVMM_EPT_PAGE_TABLE PageTable;
    EPT_PML3_POINTER    PML3Template;
    EPT_PML3_ENTRY      PML3TemplateLarge;
    EPT_PML2_ENTRY      PML2EntryTemplate;
    SIZE_T              EntryGroupIndex;
    SIZE_T              EntryIndex;
 
    //
    // Allocate all paging structures as 4KB aligned pages
    //
 
    //
    // Allocate address anywhere in the OS's memory space and
    // zero out all entries to ensure all unused entries are marked Not Present
    //
    PageTable = PlatformMemAllocateContiguousZeroedMemory(sizeof(VMM_EPT_PAGE_TABLE));
 
    if (PageTable == NULL)
    {
        LogError("Err, failed to allocate memory for PageTable");
        return NULL;
    }
 
    //
    // Keep track of dynamic 2MB->4KB split metadata for this EPT table.
    //
    InitializeListHead(&PageTable->DynamicSplitList);
 
    //
    // Create the template for the first entry in the PML4
    //
    PageTable->PML4[0].ReadAccess    = 1;
    PageTable->PML4[0].WriteAccess   = 1;
    PageTable->PML4[0].ExecuteAccess = 1;
 
    //
    // Copy the template into each of the 512 PML4 entry slots
    //
    CpuStosQ((SIZE_T *)&PageTable->PML4[1], PageTable->PML4[0].AsUInt, VMM_EPT_PML4E_COUNT - 1);
 
    for (int i = 0; i < VMM_EPT_PML4E_COUNT; i++)
    {
        if (i == 0)
        {
            //
            // Mark the first 512GB PML4 entry as present, which allows us to manage up
            // to 512GB of discrete paging structures and also set other reserved bits
            //
            PageTable->PML4[0].PageFrameNumber = (SIZE_T)VirtualAddressToPhysicalAddress(&PageTable->PML3[0]) / PAGE_SIZE;
        }
        else
        {
            PageTable->PML4[i].PageFrameNumber = (SIZE_T)VirtualAddressToPhysicalAddress(&PageTable->PML3_RSVD[i - 1][0]) / PAGE_SIZE;
        }
    }
 
    //
    // Now mark each 1GB PML3 entry as RWX and map each to their PML2 entry
    //
 
    //
    // Ensure stack memory is cleared
    //
    PML3Template.AsUInt      = 0;
    PML3TemplateLarge.AsUInt = 0;
 
    //
    // Set up one 'template' RWX PML3 entry and copy it into each of the 512 PML3 entries
    // Using the same method as SimpleVisor for copying each entry using intrinsics
    //
    PML3Template.ReadAccess    = 1;
    PML3Template.WriteAccess   = 1;
    PML3Template.ExecuteAccess = 1;
 
    PML3TemplateLarge.LargePage     = 1;
    PML3TemplateLarge.ReadAccess    = 1;
    PML3TemplateLarge.WriteAccess   = 1;
    PML3TemplateLarge.ExecuteAccess = 1;
    PML3TemplateLarge.MemoryType    = MEMORY_TYPE_UNCACHEABLE;
 
    //
    // Copy the template into each of the 512 PML3 entry slots for the original entries
    //
    CpuStosQ((SIZE_T *)&PageTable->PML3[0], PML3Template.AsUInt, VMM_EPT_PML3E_COUNT);
 
    //
    // Copt the template into each of the 512 PML3 entry slots for the reserved entries
    //
    for (SIZE_T i = 0; i < VMM_EPT_PML4E_COUNT - 1; i++)
    {
        CpuStosQ((SIZE_T *)&PageTable->PML3_RSVD[i][0], PML3TemplateLarge.AsUInt, VMM_EPT_PML3E_COUNT);
    }
 
    //
    // For each of the 512 PML3 entries
    //
    for (EntryIndex = 0; EntryIndex < VMM_EPT_PML3E_COUNT; EntryIndex++)
    {
        //
        // Map the 1GB PML3 entry to 512 PML2 (2MB) entries to describe each large page
        // NOTE: We do *not* manage any PML1 (4096 byte) entries and do not allocate them
        //
        PageTable->PML3[EntryIndex].PageFrameNumber = (SIZE_T)VirtualAddressToPhysicalAddress(&PageTable->PML2[EntryIndex][0]) / PAGE_SIZE;
    }
 
    //
    // For each of the 512 PML3 reserved entries for reserved PML3 entries
    //
    for (SIZE_T i = 0; i < VMM_EPT_PML4E_COUNT - 1; i++)
    {
        for (SIZE_T j = 0; j < VMM_EPT_PML3E_COUNT; j++)
        {
            //
            // Map the 1GB PML3 reserved entry to 512 PML3 (1GB) entries to describe each large page
            // NOTE: We do *not* manage them since they are reserved for out of 512 GB MMIO ranges
            // The first 512GB is used for the main system memory and the rest is reserved for MMIO
            //
            PageTable->PML3_RSVD[i][j].PageFrameNumber = (SIZE_512_GB +                           // First 512GB is used for system memory
                                                          (i * SIZE_512_GB) + (j * SIZE_1_GB)) >> // MMIO ranges
                                                         30;                                      // Convert to page frame number
        }
    }
 
    //
    // Now we will set up the PML2 entries, which are 2MB large pages
    //
    PML2EntryTemplate.AsUInt = 0;
 
    //
    // All PML2 entries will be RWX and 'present'
    //
    PML2EntryTemplate.WriteAccess   = 1;
    PML2EntryTemplate.ReadAccess    = 1;
    PML2EntryTemplate.ExecuteAccess = 1;
 
    //
    // We are using 2MB large pages, so we must mark this 1 here
    //
    PML2EntryTemplate.LargePage = 1;
 
    //
    // For each collection of 512 PML2 entries (512 collections * 512 entries per collection),
    // mark it RWX using the same template above.
    // This marks the entries as "Present" regardless of if the actual system has memory at
    // this region or not. We will cause a fault in our EPT handler if the guest access a page
    // outside a usable range, despite the EPT frame being present here
    //
    CpuStosQ((SIZE_T *)&PageTable->PML2[0], PML2EntryTemplate.AsUInt, VMM_EPT_PML3E_COUNT * VMM_EPT_PML2E_COUNT);
 
    //
    // For each of the 512 collections of 512 2MB PML2 entries
    //
    for (EntryGroupIndex = 0; EntryGroupIndex < VMM_EPT_PML3E_COUNT; EntryGroupIndex++)
    {
        //
        // For each 2MB PML2 entry in the collection
        //
        for (EntryIndex = 0; EntryIndex < VMM_EPT_PML2E_COUNT; EntryIndex++)
        {
            //
            // Setup the memory type and frame number of the PML2 entry
            //
            EptSetupPML2Entry(PageTable, &PageTable->PML2[EntryGroupIndex][EntryIndex], (EntryGroupIndex * VMM_EPT_PML2E_COUNT) + EntryIndex);
        }
    }
 
    return PageTable;
}

EptBuildMtrrMap()

BOOLEAN EptBuildMtrrMap

(

VOID

)

Build MTRR Map.

Build MTRR Map of current physical addresses.

Returns

BOOLEAN

Build MTRR Map.

Returns

BOOLEAN

{
    IA32_MTRR_CAPABILITIES_REGISTER MTRRCap;
    IA32_MTRR_PHYSBASE_REGISTER     CurrentPhysBase;
    IA32_MTRR_PHYSMASK_REGISTER     CurrentPhysMask;
    IA32_MTRR_DEF_TYPE_REGISTER     MTRRDefType;
    PMTRR_RANGE_DESCRIPTOR          Descriptor;
    UINT32                          CurrentRegister;
    UINT32                          NumberOfBitsInMask;
 
    MTRRCap.AsUInt     = CpuReadMsr(IA32_MTRR_CAPABILITIES);
    MTRRDefType.AsUInt = CpuReadMsr(IA32_MTRR_DEF_TYPE);
 
    //
    // All MTRRs are disabled when clear, and the
    // UC memory type is applied to all of physical memory.
    //
    if (!MTRRDefType.MtrrEnable)
    {
        g_EptState->DefaultMemoryType = MEMORY_TYPE_UNCACHEABLE;
        return TRUE;
    }
 
    //
    // The IA32_MTRR_DEF_TYPE MSR (named MTRRdefType MSR for the P6 family processors) sets the default
    // properties of the regions of physical memory that are not encompassed by MTRRs
    //
    g_EptState->DefaultMemoryType = (UINT8)MTRRDefType.DefaultMemoryType;
 
    //
    // The fixed memory ranges are mapped with 11 fixed-range registers of 64 bits each. Each of these registers is
    // divided into 8-bit fields that are used to specify the memory type for each of the sub-ranges the register controls:
    //  - Register IA32_MTRR_FIX64K_00000 - Maps the 512-KByte address range from 0H to 7FFFFH. This range
    //  is divided into eight 64-KByte sub-ranges.
    //
    //  - Registers IA32_MTRR_FIX16K_80000 and IA32_MTRR_FIX16K_A0000 - Maps the two 128-KByte
    //  address ranges from 80000H to BFFFFH. This range is divided into sixteen 16-KByte sub-ranges, 8 ranges per
    //  register.
    //
    //  - Registers IA32_MTRR_FIX4K_C0000 through IA32_MTRR_FIX4K_F8000 - Maps eight 32-KByte
    //  address ranges from C0000H to FFFFFH. This range is divided into sixty-four 4-KByte sub-ranges, 8 ranges per
    //  register.
    //
    if (MTRRCap.FixedRangeSupported && MTRRDefType.FixedRangeMtrrEnable)
    {
        const UINT32               K64Base  = 0x0;
        const UINT32               K64Size  = 0x10000;
        IA32_MTRR_FIXED_RANGE_TYPE K64Types = {CpuReadMsr(IA32_MTRR_FIX64K_00000)};
        for (UINT32 i = 0; i < 8; i++)
        {
            Descriptor                      = &g_EptState->MemoryRanges[g_EptState->NumberOfEnabledMemoryRanges++];
            Descriptor->MemoryType          = K64Types.s.Types[i];
            Descriptor->PhysicalBaseAddress = K64Base + (K64Size * i);
            Descriptor->PhysicalEndAddress  = K64Base + (K64Size * i) + (K64Size - 1);
            Descriptor->FixedRange          = TRUE;
        }
 
        const UINT32 K16Base = 0x80000;
        const UINT32 K16Size = 0x4000;
        for (UINT32 i = 0; i < 2; i++)
        {
            IA32_MTRR_FIXED_RANGE_TYPE K16Types = {CpuReadMsr(IA32_MTRR_FIX16K_80000 + i)};
            for (UINT32 j = 0; j < 8; j++)
            {
                Descriptor                      = &g_EptState->MemoryRanges[g_EptState->NumberOfEnabledMemoryRanges++];
                Descriptor->MemoryType          = K16Types.s.Types[j];
                Descriptor->PhysicalBaseAddress = (K16Base + (i * K16Size * 8)) + (K16Size * j);
                Descriptor->PhysicalEndAddress  = (K16Base + (i * K16Size * 8)) + (K16Size * j) + (K16Size - 1);
                Descriptor->FixedRange          = TRUE;
            }
        }
 
        const UINT32 K4Base = 0xC0000;
        const UINT32 K4Size = 0x1000;
        for (UINT32 i = 0; i < 8; i++)
        {
            IA32_MTRR_FIXED_RANGE_TYPE K4Types = {CpuReadMsr(IA32_MTRR_FIX4K_C0000 + i)};
 
            for (UINT32 j = 0; j < 8; j++)
            {
                Descriptor                      = &g_EptState->MemoryRanges[g_EptState->NumberOfEnabledMemoryRanges++];
                Descriptor->MemoryType          = K4Types.s.Types[j];
                Descriptor->PhysicalBaseAddress = (K4Base + (i * K4Size * 8)) + (K4Size * j);
                Descriptor->PhysicalEndAddress  = (K4Base + (i * K4Size * 8)) + (K4Size * j) + (K4Size - 1);
                Descriptor->FixedRange          = TRUE;
            }
        }
    }
 
    for (CurrentRegister = 0; CurrentRegister < MTRRCap.VariableRangeCount; CurrentRegister++)
    {
        //
        // For each dynamic register pair
        //
        CurrentPhysBase.AsUInt = CpuReadMsr(IA32_MTRR_PHYSBASE0 + (CurrentRegister * 2));
        CurrentPhysMask.AsUInt = CpuReadMsr(IA32_MTRR_PHYSMASK0 + (CurrentRegister * 2));
 
        //
        // Is the range enabled?
        //
        if (CurrentPhysMask.Valid)
        {
            //
            // We only need to read these once because the ISA dictates that MTRRs are
            // to be synchronized between all processors during BIOS initialization.
            //
            Descriptor = &g_EptState->MemoryRanges[g_EptState->NumberOfEnabledMemoryRanges++];
 
            //
            // Calculate the base address in bytes
            //
            Descriptor->PhysicalBaseAddress = CurrentPhysBase.PageFrameNumber * PAGE_SIZE;
 
            //
            // Calculate the total size of the range
            // The lowest bit of the mask that is set to 1 specifies the size of the range
            //
            CpuBitScanForward64((ULONG *)&NumberOfBitsInMask, CurrentPhysMask.PageFrameNumber * PAGE_SIZE);
 
            //
            // Size of the range in bytes + Base Address
            //
            Descriptor->PhysicalEndAddress = Descriptor->PhysicalBaseAddress + ((1ULL << NumberOfBitsInMask) - 1ULL);
 
            //
            // Memory Type (cacheability attributes)
            //
            Descriptor->MemoryType = (UCHAR)CurrentPhysBase.Type;
 
            Descriptor->FixedRange = FALSE;
 
            LogDebugInfo("MTRR Range: Base=0x%llx End=0x%llx Type=0x%x", Descriptor->PhysicalBaseAddress, Descriptor->PhysicalEndAddress, Descriptor->MemoryType);
        }
    }
 
    LogDebugInfo("Total MTRR ranges committed: 0x%x", g_EptState->NumberOfEnabledMemoryRanges);
 
    return TRUE;
}

EptCheckAndHandleBreakpoint()

BOOLEAN EptCheckAndHandleBreakpoint

(

VIRTUAL_MACHINE_STATE *

VCpu

)

Check if the breakpoint vm-exit relates to EPT hook or not.

Parameters

VCpu	The virtual processor's state

Returns

BOOLEAN

{
    UINT64  GuestRip = 0;
    BOOLEAN IsHandledByEptHook;
 
    //
    // Reading guest's RIP
    //
    VmxVmread64P(VMCS_GUEST_RIP, &GuestRip);
 
    //
    // Don't increment rip by default
    //
    HvSuppressRipIncrement(VCpu);
 
    //
    // Check if it relates to !epthook or not
    //
    IsHandledByEptHook = EptCheckAndHandleEptHookBreakpoints(VCpu, GuestRip);
 
    return IsHandledByEptHook;
}

EptCheckFeatures()

BOOLEAN EptCheckFeatures

(

VOID

)

Check for EPT Features.

Check whether EPT features are present or not.

Returns

BOOLEAN

Check for EPT Features.

Returns

BOOLEAN Shows whether EPT is supported in this machine or not

{
    IA32_VMX_EPT_VPID_CAP_REGISTER VpidRegister;
    IA32_MTRR_DEF_TYPE_REGISTER    MTRRDefType;
    g_IsVpidSupported   = FALSE;
    VpidRegister.AsUInt = CpuReadMsr(IA32_VMX_EPT_VPID_CAP);
    MTRRDefType.AsUInt  = CpuReadMsr(IA32_MTRR_DEF_TYPE);
 
    if (!VpidRegister.PageWalkLength4 || !VpidRegister.MemoryTypeWriteBack || !VpidRegister.Pde2MbPages)
    {
        return FALSE;
    }
 
    if (!VpidRegister.AdvancedVmexitEptViolationsInformation)
    {
        LogDebugInfo("The processor doesn't report advanced VM-exit information for EPT violations");
    }
 
    if (VpidRegister.Invvpid &&
        VpidRegister.InvvpidAllContexts &&
        VpidRegister.InvvpidIndividualAddress &&
        VpidRegister.InvvpidSingleContext &&
        VpidRegister.InvvpidSingleContextRetainGlobals &&
        !g_IsTopLevelHypervisorHyperV)
    {
        g_IsVpidSupported = TRUE;
        LogDebugInfo("The processor supports VPID");
    }
 
    if (!VpidRegister.ExecuteOnlyPages)
    {
        g_CompatibilityCheck.ExecuteOnlySupport = FALSE;
        LogDebugInfo("The processor doesn't support execute-only pages, execute hooks won't work as they're on this feature in our design");
    }
    else
    {
        g_CompatibilityCheck.ExecuteOnlySupport = TRUE;
    }
 
    if (!MTRRDefType.MtrrEnable)
    {
        LogError("Err, MTRR dynamic ranges are not supported");
        return FALSE;
    }
 
    LogDebugInfo("All EPT features are present");
 
    return TRUE;
}

EptGetPml1Entry()

PEPT_PML1_ENTRY EptGetPml1Entry	(	PVMM_EPT_PAGE_TABLE	EptPageTable,
		SIZE_T	PhysicalAddress )

Get the PML1 Entry of a special address.

Get the PML1 entry for this physical address if the page is split.

Parameters

EptPageTable
PhysicalAddress

Returns

PEPT_PML1_ENTRY

Get the PML1 Entry of a special address.

Parameters

EptPageTable	The EPT Page Table
PhysicalAddress	Physical address that we want to get its PML1

Returns

PEPT_PML1_ENTRY Return NULL if the address is invalid or the page wasn't already split

{
    SIZE_T          Directory, DirectoryPointer, PML4Entry;
    PEPT_PML2_ENTRY PML2;
    PEPT_PML1_ENTRY PML1;
 
    Directory        = ADDRMASK_EPT_PML2_INDEX(PhysicalAddress);
    DirectoryPointer = ADDRMASK_EPT_PML3_INDEX(PhysicalAddress);
    PML4Entry        = ADDRMASK_EPT_PML4_INDEX(PhysicalAddress);
 
    //
    // Addresses above 512GB are invalid because it is > physical address bus width
    //
    if (PML4Entry > 0)
    {
        return NULL;
    }
 
    PML2 = &EptPageTable->PML2[DirectoryPointer][Directory];
 
    //
    // Check to ensure the page is split
    //
    if (PML2->LargePage)
    {
        return NULL;
    }
 
    //
    // Resolve the split PML1 VA that was recorded during EptSplitLargePage
    //
    PML1 = EptGetSplitPml1VaByPml2Entry(EptPageTable, PML2);
 
    if (!PML1)
    {
        return NULL;
    }
 
    //
    // Index into PML1 for that address
    //
    PML1 = &PML1[ADDRMASK_EPT_PML1_INDEX(PhysicalAddress)];
 
    return PML1;
}

EptGetPml1OrPml2Entry()

PVOID EptGetPml1OrPml2Entry	(	PVMM_EPT_PAGE_TABLE	EptPageTable,
		SIZE_T	PhysicalAddress,
		BOOLEAN *	IsLargePage )

Get the PML1 entry for this physical address if the large page is available then large page of Pml2 is returned.

Parameters

EptPageTable	The EPT Page Table
PhysicalAddress	Physical address that we want to get its PML1
IsLargePage	Shows whether it's a large page or not

Returns

PEPT_PML1_ENTRY Return PEPT_PML1_ENTRY or PEPT_PML2_ENTRY

Parameters

EptPageTable	The EPT Page Table
PhysicalAddress	Physical address that we want to get its PML1
IsLargePage	Shows whether it's a large page or not

Returns

PVOID Return PEPT_PML1_ENTRY or PEPT_PML2_ENTRY

{
    SIZE_T          Directory, DirectoryPointer, PML4Entry;
    PEPT_PML2_ENTRY PML2;
    PEPT_PML1_ENTRY PML1;
 
    Directory        = ADDRMASK_EPT_PML2_INDEX(PhysicalAddress);
    DirectoryPointer = ADDRMASK_EPT_PML3_INDEX(PhysicalAddress);
    PML4Entry        = ADDRMASK_EPT_PML4_INDEX(PhysicalAddress);
 
    //
    // Addresses above 512GB are invalid because it is > physical address bus width
    //
    if (PML4Entry > 0)
    {
        return NULL;
    }
 
    PML2 = &EptPageTable->PML2[DirectoryPointer][Directory];
 
    //
    // Check to ensure the page is split
    //
    if (PML2->LargePage)
    {
        *IsLargePage = TRUE;
        return PML2;
    }
 
    //
    // Resolve the split PML1 VA that was recorded during EptSplitLargePage
    //
    PML1 = EptGetSplitPml1VaByPml2Entry(EptPageTable, PML2);
 
    if (!PML1)
    {
        return NULL;
    }
 
    //
    // Index into PML1 for that address
    //
    PML1 = &PML1[ADDRMASK_EPT_PML1_INDEX(PhysicalAddress)];
 
    *IsLargePage = FALSE;
    return PML1;
}

EptGetPml2Entry()

PEPT_PML2_ENTRY EptGetPml2Entry	(	PVMM_EPT_PAGE_TABLE	EptPageTable,
		SIZE_T	PhysicalAddress )

Split 2MB (LargePage) into 4kb pages.

Get the PML2 entry for this physical address.

Parameters

EptPageTable	The EPT Page Table
PreAllocatedBuffer	The address of pre-allocated buffer
PhysicalAddress	Physical address of where we want to split

Returns

BOOLEAN Returns true if it was successful or false if there was an error

Split 2MB (LargePage) into 4kb pages.

Parameters

EptPageTable	The EPT Page Table
PhysicalAddress	Physical Address that we want to get its PML2

Returns

PEPT_PML2_ENTRY The PML2 Entry Structure

{
    SIZE_T          Directory, DirectoryPointer, PML4Entry;
    PEPT_PML2_ENTRY PML2;
 
    Directory        = ADDRMASK_EPT_PML2_INDEX(PhysicalAddress);
    DirectoryPointer = ADDRMASK_EPT_PML3_INDEX(PhysicalAddress);
    PML4Entry        = ADDRMASK_EPT_PML4_INDEX(PhysicalAddress);
 
    //
    // Addresses above 512GB are invalid because it is > physical address bus width
    //
    if (PML4Entry > 0)
    {
        return NULL;
    }
 
    PML2 = &EptPageTable->PML2[DirectoryPointer][Directory];
    return PML2;
}

EptHandleEptViolation()

BOOLEAN EptHandleEptViolation

(

VIRTUAL_MACHINE_STATE *

VCpu

)

Handle EPT Violation.

Handle VM exits for EPT violations.

Parameters

VCpu	The virtual processor's state

Returns

BOOLEAN

Handle EPT Violation.

Violations are thrown whenever an operation is performed on an EPT entry that does not provide permissions to access that page

Parameters

VCpu	The virtual processor's state

Returns

BOOLEAN Return true if the violation was handled by the page hook handler and false if it was not handled

{
    UINT64                               GuestPhysicalAddr;
    VMX_EXIT_QUALIFICATION_EPT_VIOLATION ViolationQualification = {.AsUInt = VCpu->ExitQualification};
 
    //
    // Reading guest physical address
    //
    VmxVmread64P(VMCS_GUEST_PHYSICAL_ADDRESS, &GuestPhysicalAddr);
 
    if (EptHandlePageHookExit(VCpu, ViolationQualification, GuestPhysicalAddr))
    {
        //
        // Handled by page hook code
        //
        return TRUE;
    }
    else if (ExecTrapHandleEptViolationVmexit(VCpu, &ViolationQualification))
    {
        return TRUE;
    }
    else if (VmmCallbackUnhandledEptViolation(VCpu->CoreId, (UINT64)ViolationQualification.AsUInt, GuestPhysicalAddr))
    {
        //
        // Check whether this violation is meaningful for the application or not
        //
        return TRUE;
    }
 
    LogError("Err, unexpected EPT violation at RIP: %llx", VCpu->LastVmexitRip);
    DbgBreakPoint();
    //
    // Redo the instruction that caused the exception
    //
    return FALSE;
}

EptHandleMisconfiguration()

VOID EptHandleMisconfiguration

(

VOID

)

Handle Ept Misconfigurations.

Handle vm-exits for EPT Misconfiguration.

Returns

VOID

Handle Ept Misconfigurations.

Parameters

GuestAddress

Returns

VOID

{
    UINT64 GuestPhysicalAddr = 0;
 
    VmxVmread64P(VMCS_GUEST_PHYSICAL_ADDRESS, &GuestPhysicalAddr);
 
    LogInfo("EPT Misconfiguration!");
 
    LogError("Err, a field in the EPT paging structure was invalid, faulting guest address : 0x%llx",
             GuestPhysicalAddr);
 
    //
    // We can't continue now.
    // EPT misconfiguration is a fatal exception that will probably crash the OS if we don't get out now
    //
}

EptHandlePageHookExit()

BOOLEAN EptHandlePageHookExit	(	_Inout_ VIRTUAL_MACHINE_STATE *	VCpu,
		_In_ VMX_EXIT_QUALIFICATION_EPT_VIOLATION	ViolationQualification,
		_In_ UINT64	GuestPhysicalAddr )

EptLogicalProcessorInitialize()

BOOLEAN EptLogicalProcessorInitialize

(

VOID

)

Initialize EPT Table based on Processor Index.

Initialize EPT for an individual logical processor.

Returns

BOOLEAN

Initialize EPT Table based on Processor Index.

Creates an identity mapped page table and sets up an EPTP to be applied to the VMCS later

Returns

BOOLEAN

{
    ULONG               ProcessorsCount;
    PVMM_EPT_PAGE_TABLE PageTable;
    EPT_POINTER         EPTP = {0};
 
    //
    // Get number of processors
    //
    ProcessorsCount = KeQueryActiveProcessorCount(0);
 
    for (SIZE_T i = 0; i < ProcessorsCount; i++)
    {
        //
        // Allocate the identity mapped page table
        //
        PageTable = EptAllocateAndCreateIdentityPageTable();
 
        if (!PageTable)
        {
            //
            // Try to deallocate previous pools (if any)
            //
            for (SIZE_T j = 0; j < ProcessorsCount; j++)
            {
                if (g_GuestState[j].EptPageTable != NULL)
                {
                    MmFreeContiguousMemory(g_GuestState[j].EptPageTable);
                    g_GuestState[j].EptPageTable = NULL;
                }
            }
 
            LogError("Err, unable to allocate memory for EPT");
            return FALSE;
        }
 
        //
        // Virtual address to the page table to keep track of it for later freeing
        //
        g_GuestState[i].EptPageTable = PageTable;
 
        //
        // Use default memory type
        //
        EPTP.MemoryType = g_EptState->DefaultMemoryType;
 
        //
        // We might utilize the 'access' and 'dirty' flag features in the dirty logging mechanism
        //
        EPTP.EnableAccessAndDirtyFlags = TRUE;
 
        //
        // Bits 5:3 (1 less than the EPT page-walk length) must be 3, indicating an EPT page-walk length of 4;
        // see Section 28.2.2
        //
        EPTP.PageWalkLength = 3;
 
        //
        // The physical page number of the page table we will be using
        //
        EPTP.PageFrameNumber = (SIZE_T)VirtualAddressToPhysicalAddress(&PageTable->PML4) / PAGE_SIZE;
 
        //
        // We will write the EPTP to the VMCS later
        //
        g_GuestState[i].EptPointer = EPTP;
    }
 
    return TRUE;
}

EptSetPML1AndInvalidateTLB()

VOID EptSetPML1AndInvalidateTLB	(	_Inout_ VIRTUAL_MACHINE_STATE *	VCpu,
		_Out_ PEPT_PML1_ENTRY	EntryAddress,
		_In_ EPT_PML1_ENTRY	EntryValue,
		_In_ _Strict_type_match_ INVEPT_TYPE	InvalidationType )

This function set the specific PML1 entry in a spinlock protected area then invalidate the TLB , this function should be called from vmx root-mode.

Parameters

EntryAddress
EntryValue
InvalidationType

Returns

VOID

EptSetupPML2Entry()

BOOLEAN EptSetupPML2Entry	(	PVMM_EPT_PAGE_TABLE	EptPageTable,
		PEPT_PML2_ENTRY	NewEntry,
		SIZE_T	PageFrameNumber )

Set up PML2 Entries.

Parameters

EptPageTable
NewEntry	The PML2 Entry
PageFrameNumber	PFN (Physical Address)

Returns

VOID

{
    //
    // Each of the 512 collections of 512 PML2 entries is setup here
    // This will, in total, identity map every physical address from 0x0
    // to physical address 0x8000000000 (512GB of memory)
    // ((EntryGroupIndex * VMM_EPT_PML2E_COUNT) + EntryIndex) * 2MB is
    // the actual physical address we're mapping
    //
    NewEntry->PageFrameNumber = PageFrameNumber;
 
    if (EptIsValidForLargePage(PageFrameNumber))
    {
        NewEntry->MemoryType = EptGetMemoryType(PageFrameNumber, TRUE);
 
        return TRUE;
    }
    else
    {
        //
        // Here we won't need to use pre-allocated buffers
        //
        return EptSplitLargePage(EptPageTable, FALSE, PageFrameNumber * SIZE_2_MB);
    }
}

EptSplitLargePage()

BOOLEAN EptSplitLargePage	(	PVMM_EPT_PAGE_TABLE	EptPageTable,
		BOOLEAN	UsePreAllocatedBuffer,
		SIZE_T	PhysicalAddress )

Convert large pages to 4KB pages.

Parameters

EptPageTable
UsePreAllocatedBuffer
PhysicalAddress

Returns

BOOLEAN

Parameters

EptPageTable	The EPT Page Table
UsePreAllocatedBuffer	Whether allocate a memory or use pre-allocated buffer
PhysicalAddress	Physical address of where we want to split

Returns

BOOLEAN Returns true if it was successful or false if there was an error

{
    PVMM_EPT_DYNAMIC_SPLIT NewSplit;
    EPT_PML1_ENTRY         EntryTemplate;
    SIZE_T                 EntryIndex;
    PEPT_PML2_ENTRY        TargetEntry;
    EPT_PML2_POINTER       NewPointer;
 
    //
    // Find the PML2 entry that's currently used
    //
    TargetEntry = EptGetPml2Entry(EptPageTable, PhysicalAddress);
 
    if (!TargetEntry)
    {
        LogError("Err, an invalid physical address passed");
        return FALSE;
    }
 
    //
    // If this large page is not marked a large page, that means it's a pointer already.
    // That page is therefore already split.
    //
    if (!TargetEntry->LargePage)
    {
        return TRUE;
    }
 
    //
    // Allocate the PML1 entries
    //
    if (UsePreAllocatedBuffer)
    {
        NewSplit = (PVMM_EPT_DYNAMIC_SPLIT)PoolManagerCallbackRequestPool(SPLIT_2MB_PAGING_TO_4KB_PAGE, TRUE, sizeof(VMM_EPT_DYNAMIC_SPLIT));
    }
    else
    {
        NewSplit = (PVMM_EPT_DYNAMIC_SPLIT)PlatformMemAllocateNonPagedPool(sizeof(VMM_EPT_DYNAMIC_SPLIT));
    }
 
    if (!NewSplit)
    {
        LogError("Err, failed to allocate dynamic split memory");
        return FALSE;
    }
    RtlZeroMemory(NewSplit, sizeof(VMM_EPT_DYNAMIC_SPLIT));
 
    //
    // Point back to the entry in the dynamic split for easy reference for which entry that
    // dynamic split is for
    //
    NewSplit->Fields.Entry = TargetEntry;
 
    //
    // Make a template for RWX
    //
    EntryTemplate.AsUInt        = 0;
    EntryTemplate.ReadAccess    = 1;
    EntryTemplate.WriteAccess   = 1;
    EntryTemplate.ExecuteAccess = 1;
 
    //
    // Set the UserModeExecute bit based on the global state of MBEC
    //
    if (g_ModeBasedExecutionControlState)
    {
        EntryTemplate.UserModeExecute = 1;
    }
    else
    {
        EntryTemplate.UserModeExecute = 0;
    }
 
    //
    // copy other bits from target entry
    //
    EntryTemplate.MemoryType = TargetEntry->MemoryType;
    EntryTemplate.IgnorePat  = TargetEntry->IgnorePat;
    EntryTemplate.SuppressVe = TargetEntry->SuppressVe;
 
    //
    // Copy the template into all the PML1 entries
    //
    CpuStosQ((SIZE_T *)&NewSplit->PML1[0], EntryTemplate.AsUInt, VMM_EPT_PML1E_COUNT);
 
    //
    // Set the page frame numbers for identity mapping
    //
    for (EntryIndex = 0; EntryIndex < VMM_EPT_PML1E_COUNT; EntryIndex++)
    {
        //
        // Convert the 2MB page frame number to the 4096 page entry number plus the offset into the frame
        //
        NewSplit->PML1[EntryIndex].PageFrameNumber = ((TargetEntry->PageFrameNumber * SIZE_2_MB) / PAGE_SIZE) + EntryIndex;
        NewSplit->PML1[EntryIndex].MemoryType      = EptGetMemoryType(NewSplit->PML1[EntryIndex].PageFrameNumber, FALSE);
    }
 
    //
    // Allocate a new pointer which will replace the 2MB entry with a pointer to 512 4096 byte entries
    //
    NewPointer.AsUInt        = 0;
    NewPointer.WriteAccess   = 1;
    NewPointer.ReadAccess    = 1;
    NewPointer.ExecuteAccess = 1;
 
    //
    // Set the UserModeExecute bit based on the global state of MBEC
    //
    if (g_ModeBasedExecutionControlState)
    {
        NewPointer.UserModeExecute = 1;
    }
    else
    {
        NewPointer.UserModeExecute = 0;
    }
 
    NewPointer.PageFrameNumber = (SIZE_T)VirtualAddressToPhysicalAddress(&NewSplit->PML1[0]) / PAGE_SIZE;
 
    //
    // Now, replace the entry in the page table with our new split pointer
    //
    RtlCopyMemory(TargetEntry, &NewPointer, sizeof(NewPointer));
 
    //
    // Track the split so we can directly resolve PML1 VA from PML2 entry
    // without any PA->VA reverse translation
    //
    InsertHeadList(&EptPageTable->DynamicSplitList, &(NewSplit->DynamicSplitList));
 
    return TRUE;
}