DirtyLogging.h File Reference

Headers for dirty logging mechanism. More...

Go to the source code of this file.

Macros
#define	PML_ENTITY_NUM   512

Functions
BOOLEAN	DirtyLoggingInitialize ()
	Initialize the dirty logging mechanism.
BOOLEAN	DirtyLoggingEnable (VIRTUAL_MACHINE_STATE *VCpu)
	Enables the dirty logging mechanism in VMX-root mode.
VOID	DirtyLoggingDisable (VIRTUAL_MACHINE_STATE *VCpu)
	Disables the dirty logging mechanism in VMX-root mode.
VOID	DirtyLoggingUninitialize ()
	Initialize the dirty logging mechanism.
VOID	DirtyLoggingHandleVmexits (VIRTUAL_MACHINE_STATE *VCpu)
	Handling vm-exits of PML.

Detailed Description

Headers for dirty logging mechanism.

Author

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

Version

0.2

Date

2023-02-12

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

PML_ENTITY_NUM

#define PML_ENTITY_NUM   512

Function Documentation

DirtyLoggingDisable()

VOID DirtyLoggingDisable

(

VIRTUAL_MACHINE_STATE *

VCpu

)

Disables the dirty logging mechanism in VMX-root mode.

should be called in vmx-root mode

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    UNREFERENCED_PARAMETER(VCpu);
 
    //
    // Clear the address
    //
    VmxVmwrite64(VMCS_CTRL_PML_ADDRESS, NULL64_ZERO);
 
    //
    // Clear the PML index
    //
    VmxVmwrite64(VMCS_GUEST_PML_INDEX, 0x0);
 
    //
    // Disable PML Enable bit
    //
    HvSetPmlEnableFlag(FALSE);
}

DirtyLoggingEnable()

BOOLEAN DirtyLoggingEnable

(

VIRTUAL_MACHINE_STATE *

VCpu

)

Enables the dirty logging mechanism in VMX-root mode.

should be called in vmx-root mode

Parameters

VCpu	The virtual processor's state

Returns

BOOLEAN

{
    //
    // Check if PML Address buffer is empty or not
    //
    if (VCpu->PmlBufferAddress == NULL)
    {
        return FALSE;
    }
 
    //
    // Write the address of the buffer
    //
    UINT64 PmlPhysAddr = VirtualAddressToPhysicalAddress(VCpu->PmlBufferAddress);
 
    // LogInfo("PML Buffer Address = %llx", PmlPhysAddr);
 
    VmxVmwrite64(VMCS_CTRL_PML_ADDRESS, PmlPhysAddr);
 
    //
    // Clear the PML index
    //
    VmxVmwrite64(VMCS_GUEST_PML_INDEX, PML_ENTITY_NUM - 1);
 
    //
    // If the "enable PML" VM-execution control is 1 and bit 6 of EPT pointer (EPTP)
    //  is 1 (enabling accessed and dirty flags for EPT) then we can use this feature
    // by default we set this flag for EPTP so, we have to enable PML ENABLE Bit in the
    // secondary proc-based controls
    //
 
    //
    // Secondary processor-based VM-execution control 17 is defined as enable PML
    //
    HvSetPmlEnableFlag(TRUE);
 
    //
    // Initialization was successful
    //
    return TRUE;
}

DirtyLoggingHandleVmexits()

VOID DirtyLoggingHandleVmexits

(

VIRTUAL_MACHINE_STATE *

VCpu

)

Handling vm-exits of PML.

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    //
    // *** The guest-physical address of the access is written
    // to the page-modification log and the buffer is full ***
    //
 
    //
    // Test log
    //
    LogInfo("Dirty Logging VM-exit");
    // DirtyLoggingHandlePageModificationLog(VCpu);
 
    //
    // Flush the PML buffer
    //
    DirtyLoggingFlushPmlBuffer(VCpu);
 
    //
    // Do not increment RIP
    //
    HvSuppressRipIncrement(VCpu);
}

DirtyLoggingInitialize()

BOOLEAN DirtyLoggingInitialize

(

)

Initialize the dirty logging mechanism.

Returns

BOOLEAN

{
    ULONG ProcessorsCount;
 
    //
    // Query count of active processors
    //
    ProcessorsCount = KeQueryActiveProcessorCount(0);
 
    //
    // The explanations are copied from Intel whitepaper on PML:
    // Link : https://www.intel.com/content/dam/www/public/us/en/documents/white-papers/page-modification-logging-vmm-white-paper.pdf
    //
 
    //
    // When PML is active each write that sets a dirty flag for EPT also generates an entry in an in-memory log,
    // reporting the guest-physical address of the write (aligned to 4 KBytes)
    // When the log is full, a VM exit occurs, notifying the VMM. A VMM can monitor the number of pages modified
    //  by each thread by specifying an available set of log entries
    //
 
    //
    // Check for the support of PML
    //
    if (!g_CompatibilityCheck.PmlSupport)
    {
        LogWarning("err, dirty logging mechanism is not initialized as the processor doesn't support PML");
        return FALSE;
    }
 
    //
    // A new 64-bit VM-execution control field is defined called the PML address. This is
    // the 4 - KByte aligned physical address of the page - modification log.The page modification
    // log comprises 512 64 - bit entries
    //
    for (SIZE_T i = 0; i < ProcessorsCount; i++)
    {
        if (g_GuestState[i].PmlBufferAddress == NULL)
        {
            g_GuestState[i].PmlBufferAddress = PlatformMemAllocateNonPagedPool(PAGE_SIZE);
        }
 
        if (g_GuestState[i].PmlBufferAddress == NULL)
        {
            //
            // Allocation failed
            //
            for (SIZE_T j = 0; j < ProcessorsCount; j++)
            {
                if (g_GuestState[j].PmlBufferAddress != NULL)
                {
                    PlatformMemFreePool(g_GuestState[j].PmlBufferAddress);
                }
            }
 
            return FALSE;
        }
 
        //
        // Clear the log buffer
        //
        RtlZeroBytes(g_GuestState[i].PmlBufferAddress, PAGE_SIZE);
    }
 
    //
    // Broadcast VMCALL to adjust PML controls from vmx-root
    //
    BroadcastEnablePmlOnAllProcessors();
 
    //
    // Initialization was successful
    //
    return TRUE;
}

DirtyLoggingUninitialize()

VOID DirtyLoggingUninitialize

(

)

Initialize the dirty logging mechanism.

Returns

VOID

{
    ULONG ProcessorsCount;
 
    //
    // Query count of active processors
    //
    ProcessorsCount = KeQueryActiveProcessorCount(0);
 
    //
    // Broadcast VMCALL to disable PML controls from vmx-root
    //
    BroadcastDisablePmlOnAllProcessors();
 
    //
    // Free the allocated pool buffers
    //
    for (SIZE_T i = 0; i < ProcessorsCount; i++)
    {
        if (g_GuestState[i].PmlBufferAddress != NULL)
        {
            PlatformMemFreePool(g_GuestState[i].PmlBufferAddress);
        }
    }
}