HyperDbgHyperTrace.h File Reference

Headers relating exported functions from hypertrace (tracing) module. More...

Go to the source code of this file.

Macros
#define	IMPORT_EXPORT_HYPERTRACE   __declspec(dllimport)

Functions
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTraceInitCallback (HYPERTRACE_CALLBACKS *HyperTraceCallbacks, BOOLEAN RunningOnHypervisorEnvironment)
	Initialize the hypertrace module callbacks.
IMPORT_EXPORT_HYPERTRACE VOID	HyperTraceUninit ()
	Uninitialize the hypertrace module.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTraceLbrIsSupported (UINT32 *Capacity, BOOLEAN *IsArchLbr)
	Check if LBR is supported on the current CPU and get its capacity.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTraceLbrCheck ()
	Check if LBR is supported and enabled on the current core.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTraceLbrRestore ()
	Restore (re-enable) LBR collection on the current core with previous filter options.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTraceLbrRestoreByFilter (UINT64 FilterOptions)
	Restore (re-enable) LBR collection on the current core with the specified filter options.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTraceLbrSave (HYPERTRACE_LBR_OPERATION_PACKETS *HyperTraceOperationRequest)
	Save LBR tracing for HyperTrace.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTraceLbrPrint (HYPERTRACE_LBR_OPERATION_PACKETS *HyperTraceOperationRequest)
	Print LBR tracing for HyperTrace.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTraceLbrFlush (HYPERTRACE_LBR_OPERATION_PACKETS *HyperTraceOperationRequest)
	Flush LBR tracing for HyperTrace.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTraceLbrQueryStateOfLbrSaveAndLoadVmExitAndEntryControls (UINT32 CoreId)
	Query the state of LBR save and load VM exit and entry controls.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTraceLbrPerformDump (HYPERTRACE_LBR_DUMP_PACKETS *LbrDumpRequest)
	Perform actions related to HyperTrace LBR dumping.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTraceLbrPerformOperation (HYPERTRACE_LBR_OPERATION_PACKETS *LbrOperationRequest)
	Perform actions related to HyperTrace LBR operations.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTracePtEnable (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Enable PT tracing for HyperTrace.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTracePtDisable (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Disable PT tracing for HyperTrace.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTracePtPause (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Pause PT tracing on every core. Buffers stay allocated and the per-CPU CTL is preserved, so HyperTracePtResume can restart the trace exactly where it stopped.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTracePtResume (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Resume PT tracing on every core after a prior HyperTracePtPause.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTracePtSize (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Snapshot the current PT output position on every core and write the per-CPU byte counts into HyperTraceOperationRequest->BytesPerCpu. The returned counts are the decode window — bytes [0, BytesPerCpu[i]) in CPU i's user mapping currently hold valid trace data.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTracePtDump (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Dump PT trace state for HyperTrace.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTracePtFlush (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Flush PT trace state on all cores (free buffers).
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTracePtFilter (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Apply a new PT trace configuration (TraceUser / TraceKernel / TargetCr3 / BufferSize / NumAddrRanges + AddrRanges) on all cores.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTracePtPerformOperation (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Perform actions related to HyperTrace PT.
IMPORT_EXPORT_HYPERTRACE BOOLEAN	HyperTracePtMmap (HYPERTRACE_PT_MMAP_PACKETS *Req)
	Map every per-CPU PT main output + overflow buffer into the calling user-mode process. See HYPERTRACE_PT_MMAP_PACKETS for the full lifetime / single-process contract.

Detailed Description

Headers relating exported functions from hypertrace (tracing) module.

Author

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

Version

0.18

Date

2026-02-08

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

IMPORT_EXPORT_HYPERTRACE

#define IMPORT_EXPORT_HYPERTRACE   __declspec(dllimport)

Function Documentation

HyperTraceInitCallback()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTraceInitCallback	(	HYPERTRACE_CALLBACKS *	HyperTraceCallbacks,
		BOOLEAN	RunningOnHypervisorEnvironment )

Initialize the hypertrace module callbacks.

This only for callback initialization, not for LBR, PT, etc. initialization

Parameters

HyperTraceCallbacks	Pointer to the HyperTrace callbacks structure to be registered
RunningOnHypervisorEnvironment	Whether the initialization is being done for hypervisor environment or not, it can be used to skip some of the initialization steps if it is not for hypervisor environment and behave differently based on that

Returns

BOOLEAN

{
    UINT32 ProcessorsCount = 0;
 
    //
    // Check if any of the required callbacks are NULL
    //
    for (UINT32 i = 0; i < sizeof(HYPERTRACE_CALLBACKS) / sizeof(UINT64); i++)
    {
        if (((PVOID *)HyperTraceCallbacks)[i] == NULL)
        {
            //
            // The callback has null entry, so we cannot proceed
            //
            return FALSE;
        }
    }
 
    //
    // Save the callbacks
    //
    PlatformWriteMemory(&g_Callbacks, HyperTraceCallbacks, sizeof(HYPERTRACE_CALLBACKS));
 
    //
    // Query the number of processors in the system to initialize the global LBR state list accordingly
    //
    ProcessorsCount = PlatformCpuGetActiveProcessorCount();
 
    //
    // Initialize the global LBR state list to hold LBR states for each core
    //
    g_LbrStateList = (LBR_STACK_ENTRY *)PlatformMemAllocateZeroedNonPagedPool(sizeof(LBR_STACK_ENTRY) * ProcessorsCount);
 
    //
    // Initialize the global PT per-CPU state list. Each entry starts in
    // PT_STATE_DISABLED with no buffers allocated; PtStart() will lazily
    // allocate ToPA / output / overflow buffers on first use per core.
    //
    g_PtStateList = (PT_PER_CPU *)PlatformMemAllocateZeroedNonPagedPool(sizeof(PT_PER_CPU) * ProcessorsCount);
 
    if (g_PtStateList != NULL)
    {
        UINT32 i;
        for (i = 0; i < ProcessorsCount; i++)
        {
            PtEngineInitDefaultConfig(&g_PtStateList[i].Config);
            g_PtStateList[i].State = PT_STATE_DISABLED;
        }
    }
 
    //
    // Set the flag to indicate whether the initialization is being done for hypervisor environment or not
    //
    g_RunningOnHypervisorEnvironment = RunningOnHypervisorEnvironment;
 
    //
    // It is initialized, but LBR is disabled at this stage
    //
    g_LastBranchRecordEnabled = FALSE;
 
    //
    // It is initialized, but Processor Trace is disabled at this stage
    //
    g_ProcessorTraceEnabled = FALSE;
 
    //
    // Enable callbacks and set the initialized flag
    //
    g_HyperTraceCallbacksInitialized = TRUE;
 
    return TRUE;
}

HyperTraceLbrCheck()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTraceLbrCheck

(

)

Check if LBR is supported and enabled on the current core.

Returns

BOOLEAN

{
    //
    // Only check LBR once it is already initialized
    //
    if (!g_LastBranchRecordEnabled)
    {
        return FALSE;
    }
 
    return LbrCheck();
}

HyperTraceLbrFlush()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTraceLbrFlush

(

HYPERTRACE_LBR_OPERATION_PACKETS *

HyperTraceOperationRequest

)

Flush LBR tracing for HyperTrace.

Parameters

HyperTraceOperationRequest

Returns

BOOLEAN

{
    //
    // Check if LBR is already disabled or not
    //
    if (!g_LastBranchRecordEnabled)
    {
        HyperTraceLbrSetKernelStatus(HyperTraceOperationRequest, DEBUGGER_ERROR_LBR_ALREADY_DISABLED);
        return FALSE;
    }
 
    //
    // Disabling LBR
    //
    g_LastBranchRecordEnabled = FALSE;
 
    //
    // Broadcast flushing LBR on all cores
    //
    BroadcastFlushLbrOnAllCores();
 
    //
    // Set successful status
    //
    HyperTraceLbrSetKernelStatus(HyperTraceOperationRequest, DEBUGGER_OPERATION_WAS_SUCCESSFUL);
 
    return TRUE;
}

HyperTraceLbrIsSupported()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTraceLbrIsSupported	(	UINT32 *	Capacity,
		BOOLEAN *	IsArchLbr )

Check if LBR is supported on the current CPU and get its capacity.

Parameters

Capacity	Pointer to a variable to receive the LBR capacity (number of entries)
IsArchLbr	Pointer to a variable to receive whether the supported LBR is architectural LBR or not (legacy LBR)

Returns

BOOLEAN

{
    //
    // Check for ARCHITECTURAL LBR support first, if not supported then check for LEGACY LBR support
    //
    if (!LbrCheckAndReadArchitecturalLbrDetails())
    {
        //
        // If the CPU does not support architectural LBR, we can check for legacy LBR support as a fallback
        //
        if (!LbrCheckAndReadLegacyLbrDetails())
        {
            return FALSE;
        }
    }
 
    //
    // Set capacity when the pointer is valid
    //
    if (Capacity != NULL)
    {
        *Capacity = (UINT32)g_LbrCapacity;
    }
 
    //
    // Set IsArchLbr when the pointer is valid
    //
    if (IsArchLbr != NULL)
    {
        *IsArchLbr = g_ArchBasedLastBranchRecord;
    }
 
    return TRUE;
}

HyperTraceLbrPerformDump()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTraceLbrPerformDump

(

HYPERTRACE_LBR_DUMP_PACKETS *

LbrDumpRequest

)

Perform actions related to HyperTrace LBR dumping.

Parameters

LbrDumpRequest

Returns

BOOLEAN

{
    ULONG ProcessorsCount;
 
    //
    // Check if LBR is enabled or not before dumping
    //
    if (!g_LastBranchRecordEnabled)
    {
        HyperTraceLbrDumpSetKernelStatus(LbrDumpRequest, DEBUGGER_ERROR_LBR_ALREADY_DISABLED);
        return FALSE;
    }
 
    //
    // Get the number of processors in the system to validate the requested core id for dumping
    //
    ProcessorsCount = KeQueryActiveProcessorCount(0);
 
    //
    // Check if core id is valid
    //
    if (LbrDumpRequest->CoreId >= ProcessorsCount)
    {
        HyperTraceLbrDumpSetKernelStatus(LbrDumpRequest, DEBUGGER_ERROR_INVALID_CORE_ID);
        return FALSE;
    }
 
    //
    // Check if next core is valid in the case of dumping all cores
    //
    if (LbrDumpRequest->CoreId == ProcessorsCount - 1)
    {
        LbrDumpRequest->NextCoreIsValid = FALSE;
    }
    else
    {
        LbrDumpRequest->NextCoreIsValid = TRUE;
    }
 
    //
    // Set ARCH or LEGACY LBR flag in the dump request structure based on the type of LBR supported by the CPU
    //
    LbrDumpRequest->ArchBasedLBR = g_ArchBasedLastBranchRecord;
 
    //
    // Set the current LBR capacity in the dump request structure based on the type of LBR supported by the CPU
    //
    LbrDumpRequest->CurrentLbrCapacity = (UINT8)g_LbrCapacity;
 
    //
    // Copy the LBR stack entries of the requested core into the dump request structure to be sent back to usermode
    //
    RtlCopyMemory(&LbrDumpRequest->LbrStack, &g_LbrStateList[LbrDumpRequest->CoreId], sizeof(LBR_STACK_ENTRY));
 
    //
    // Set successful status
    //
    HyperTraceLbrDumpSetKernelStatus(LbrDumpRequest, DEBUGGER_OPERATION_WAS_SUCCESSFUL);
 
    return TRUE;
}

HyperTraceLbrPerformOperation()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTraceLbrPerformOperation

(

HYPERTRACE_LBR_OPERATION_PACKETS *

LbrOperationRequest

)

Perform actions related to HyperTrace LBR operations.

Parameters

LbrOperationRequest

Returns

BOOLEAN

{
    BOOLEAN Status = TRUE;
 
    //
    // Check if the hypertrace module is initialized before performing any operation
    //
    if (!g_HyperTraceCallbacksInitialized)
    {
        HyperTraceLbrSetKernelStatus(LbrOperationRequest, DEBUGGER_ERROR_HYPERTRACE_NOT_INITIALIZED);
        return FALSE;
    }
 
    //
    // Perform the requested operation
    //
    switch (LbrOperationRequest->LbrOperationType)
    {
    case HYPERTRACE_LBR_OPERATION_REQUEST_TYPE_ENABLE:
 
        // LogInfo("HyperTrace: Enabling LBR tracing...\n");
 
        HyperTraceLbrEnable(LbrOperationRequest);
 
        break;
 
    case HYPERTRACE_LBR_OPERATION_REQUEST_TYPE_DISABLE:
 
        // LogInfo("HyperTrace: Disabling LBR tracing...\n");
 
        HyperTraceLbrDisable(LbrOperationRequest);
 
        break;
 
    case HYPERTRACE_LBR_OPERATION_REQUEST_TYPE_FLUSH:
 
        // LogInfo("HyperTrace: Flushing LBR tracing...\n");
 
        HyperTraceLbrFlush(LbrOperationRequest);
 
        break;
 
    case HYPERTRACE_LBR_OPERATION_REQUEST_TYPE_FILTER:
 
        // LogInfo("HyperTrace: Updating LBR filter options...\n");
 
        HyperTraceLbrUpdateFilterOptions(LbrOperationRequest);
 
        break;
 
    default:
 
        Status = FALSE;
        HyperTraceLbrSetKernelStatus(LbrOperationRequest, DEBUGGER_ERROR_INVALID_HYPERTRACE_OPERATION_TYPE);
 
        break;
    }
 
    return Status;
}

HyperTraceLbrPrint()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTraceLbrPrint

(

HYPERTRACE_LBR_OPERATION_PACKETS *

HyperTraceOperationRequest

)

Print LBR tracing for HyperTrace.

Parameters

HyperTraceOperationRequest

Returns

BOOLEAN

{
    //
    // Check if LBR is already disabled or not
    //
    if (!g_LastBranchRecordEnabled)
    {
        HyperTraceLbrSetKernelStatus(HyperTraceOperationRequest, DEBUGGER_ERROR_LBR_ALREADY_DISABLED);
        return FALSE;
    }
 
    // LogInfo("Dumping LBR Buffer...\n");
 
    //
    // Save the LBR state
    //
    LbrSave();
 
    //
    // This will print the collected LBR branches to the log
    //
    LbrPrint();
 
    //
    // The operation was successful
    //
    HyperTraceLbrSetKernelStatus(HyperTraceOperationRequest, DEBUGGER_OPERATION_WAS_SUCCESSFUL);
 
    return TRUE;
}

HyperTraceLbrQueryStateOfLbrSaveAndLoadVmExitAndEntryControls()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTraceLbrQueryStateOfLbrSaveAndLoadVmExitAndEntryControls

(

UINT32

CoreId

)

Query the state of LBR save and load VM exit and entry controls.

Parameters

CoreId

The index of the processor core to query

Returns

BOOLEAN

{
    UNREFERENCED_PARAMETER(CoreId); // Right now there is no core specifc controls for LBR
 
    return g_LastBranchRecordEnabled;
}

HyperTraceLbrRestore()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTraceLbrRestore

(

)

Restore (re-enable) LBR collection on the current core with previous filter options.

Returns

BOOLEAN

{
    return HyperTraceLbrRestoreByFilter(g_LbrFilterOptions);
}

HyperTraceLbrRestoreByFilter()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTraceLbrRestoreByFilter

(

UINT64

FilterOptions

)

Restore (re-enable) LBR collection on the current core with the specified filter options.

Parameters

FilterOptions

A bitmask of filter options to apply to the LBR branches

Returns

BOOLEAN

{
    //
    // Only restore (re-enable) LBR once it is already initialized
    //
    if (!g_LastBranchRecordEnabled)
    {
        return FALSE;
    }
 
    return LbrStart(FilterOptions);
}

HyperTraceLbrSave()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTraceLbrSave

(

HYPERTRACE_LBR_OPERATION_PACKETS *

HyperTraceOperationRequest

)

Save LBR tracing for HyperTrace.

Parameters

HyperTraceOperationRequest

Returns

BOOLEAN

{
    //
    // Check if LBR is already disabled or not
    //
    if (!g_LastBranchRecordEnabled)
    {
        HyperTraceLbrSetKernelStatus(HyperTraceOperationRequest, DEBUGGER_ERROR_LBR_ALREADY_DISABLED);
        return FALSE;
    }
 
    // LogInfo("Saving LBR Buffer...\n");
 
    //
    // Save the LBR state
    //
    LbrSave();
 
    //
    // The operation was successful
    //
    HyperTraceLbrSetKernelStatus(HyperTraceOperationRequest, DEBUGGER_OPERATION_WAS_SUCCESSFUL);
 
    return TRUE;
}

HyperTracePtDisable()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTracePtDisable

(

HYPERTRACE_PT_OPERATION_PACKETS *

PtOperationRequest

)

Disable PT tracing for HyperTrace.

Parameters

PtOperationRequest

Pointer to the HyperTrace PT operation request packet

Returns

BOOLEAN

{
    //
    // Check if PT is already disabled or not
    //
    if (!g_ProcessorTraceEnabled)
    {
        if (PtOperationRequest != NULL)
        {
            PtOperationRequest->KernelStatus = DEBUGGER_ERROR_PT_ALREADY_DISABLED;
        }
 
        return FALSE;
    }
 
    //
    // Disabling PT
    //
    g_ProcessorTraceEnabled = FALSE;
 
    //
    // Broadcast disabling PT on all cores (DPC stops tracing per-core)
    //
    BroadcastDisablePtOnAllCores();
 
    //
    // Free per-CPU buffers at PASSIVE_LEVEL after the broadcast has stopped
    // tracing on every core.
    //
    PtFreeAllCpuBuffers();
 
    //
    // Set successful status
    //
    if (PtOperationRequest != NULL)
    {
        PtOperationRequest->KernelStatus = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
    }
 
    return TRUE;
}

HyperTracePtDump()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTracePtDump

(

HYPERTRACE_PT_OPERATION_PACKETS *

HyperTraceOperationRequest

)

Dump PT trace state for HyperTrace.

Parameters

HyperTraceOperationRequest

Returns

BOOLEAN

{
    if (!g_ProcessorTraceEnabled)
    {
        if (HyperTraceOperationRequest != NULL)
        {
            HyperTraceOperationRequest->KernelStatus = DEBUGGER_ERROR_PT_ALREADY_DISABLED;
        }
        return FALSE;
    }
 
    LogInfo("Dumping PT trace summary...\n");
 
    BroadcastDumpPtOnAllCores();
 
    if (HyperTraceOperationRequest != NULL)
    {
        HyperTraceOperationRequest->KernelStatus = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
    }
 
    return TRUE;
}

HyperTracePtEnable()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTracePtEnable

(

HYPERTRACE_PT_OPERATION_PACKETS *

PtOperationRequest

)

Enable PT tracing for HyperTrace.

Parameters

PtOperationRequest

Pointer to the HyperTrace PT operation request packet

Returns

BOOLEAN

{
    //
    // Check if PT is already enabled or not
    //
    if (g_ProcessorTraceEnabled)
    {
        PtOperationRequest->KernelStatus = DEBUGGER_ERROR_PT_ALREADY_ENABLED;
        return FALSE;
    }
 
    //
    // Check PT support on CPU
    //
    if (!PtCheck())
    {
        PtOperationRequest->KernelStatus = DEBUGGER_ERROR_PT_NOT_SUPPORTED;
        return FALSE;
    }
 
    //
    // Allocate per-CPU ToPA / output / overflow buffers at PASSIVE_LEVEL
    // (the contiguous-memory allocator cannot run from a DPC).
    // PtAllocateAllCpuBuffers reads Cpu->Config.BufferSize, which was set
    // either at module init (default 2MB) or by a prior !pt filter — so
    // any pre-enable filter settings are preserved here.
    //
    if (!PtAllocateAllCpuBuffers())
    {
        //
        // Roll back any partial allocations so we don't leak on next try.
        //
        PtFreeAllCpuBuffers();
        PtOperationRequest->KernelStatus = DEBUGGER_ERROR_PT_NOT_SUPPORTED;
        return FALSE;
    }
 
    //
    // Broadcast enabling PT on all cores
    //
    BroadcastEnablePtOnAllCores();
 
    //
    // Set the flag to indicate that PT tracing is enabled
    //
    g_ProcessorTraceEnabled = TRUE;
 
    //
    // Set successful status
    //
    PtOperationRequest->KernelStatus = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
 
    return TRUE;
}

HyperTracePtFilter()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTracePtFilter

(

HYPERTRACE_PT_OPERATION_PACKETS *

Req

)

Apply a new PT trace configuration (TraceUser / TraceKernel / TargetCr3 / BufferSize / NumAddrRanges + AddrRanges) on all cores.

Mirrors HyperTraceLbrUpdateFilterOptions / LbrFilter:

• If PT is currently enabled, stop tracing on all cores, free and reallocate buffers (because BufferSize may have changed), push the new config into every per-CPU slot, and resume tracing on all cores.
• If PT is currently disabled, only update the per-CPU config so that the next !pt enable picks it up.

Must be called at IRQL == PASSIVE_LEVEL because of the contiguous-memory allocator.

{
    PT_FILTER_OPTIONS FilterOptions = {0};
    BOOLEAN           WasEnabled    = g_ProcessorTraceEnabled;
    BOOLEAN           BufferChanged = FALSE;
    UINT64            ExistingSize  = 0;
    UINT32            Copy;
 
    //
    // Translate the user-mode packet into PT_FILTER_OPTIONS — the narrow
    // surface PtFilter operates on. Default to user+kernel when the
    // caller specified neither (matches LBR's empty-filter behaviour).
    //
    if (Req->TraceUser || Req->TraceKernel)
    {
        FilterOptions.TraceUser   = (Req->TraceUser != 0) ? TRUE : FALSE;
        FilterOptions.TraceKernel = (Req->TraceKernel != 0) ? TRUE : FALSE;
    }
    else
    {
        FilterOptions.TraceUser   = TRUE;
        FilterOptions.TraceKernel = TRUE;
    }
    FilterOptions.TargetCr3     = Req->TargetCr3;
    FilterOptions.BufferSize    = Req->BufferSize;
    FilterOptions.NumAddrRanges = Req->NumAddrRanges;
    if (FilterOptions.NumAddrRanges > PT_MAX_ADDR_RANGES)
        FilterOptions.NumAddrRanges = PT_MAX_ADDR_RANGES;
    for (Copy = 0; Copy < FilterOptions.NumAddrRanges; Copy++)
    {
        FilterOptions.AddrRanges[Copy] = Req->AddrRanges[Copy];
    }
 
    //
    // Decide between fast (filter-only) and slow (buffer-resize) paths.
    //
    if (g_PtStateList != NULL)
    {
        ExistingSize = g_PtStateList[0].Config.BufferSize;
    }
    if (FilterOptions.BufferSize != 0 && FilterOptions.BufferSize != ExistingSize)
    {
        BufferChanged = TRUE;
    }
 
    if (!WasEnabled || BufferChanged)
    {
        //
        // Slow path — PT is off and/or BufferSize changed. We have to
        // free + reallocate per-CPU buffers at PASSIVE_LEVEL, so we
        // can't go through DPC for the config seeding either.
        //
        PT_TRACE_CONFIG Cfg;
 
        if (WasEnabled)
        {
            BroadcastFlushPtOnAllCores();
            PtFreeAllCpuBuffers();
        }
 
        //
        // Build a full PT_TRACE_CONFIG (defaults + the user-tunable
        // fields from the request) and seed it on every CPU so the next
        // PtAllocateAllCpuBuffers picks up the right BufferSize and
        // PtEngineStart programs the right RTIT_CTL bits.
        //
        HyperTracePtBuildConfig(Req, &Cfg);
        HyperTracePtSeedConfigOnAllCpus(&Cfg);
 
        if (WasEnabled)
        {
            if (!PtAllocateAllCpuBuffers())
            {
                PtFreeAllCpuBuffers();
                g_ProcessorTraceEnabled = FALSE;
                if (Req != NULL)
                {
                    Req->KernelStatus = DEBUGGER_ERROR_PT_NOT_SUPPORTED;
                }
                return FALSE;
            }
 
            BroadcastEnablePtOnAllCores();
        }
    }
    else
    {
        //
        // Fast filter-only path: PT is running and BufferSize is
        // unchanged. Force FilterOptions.BufferSize=0 so PtFilter on each core
        // keeps the buffer that's already allocated, then broadcast.
        //
        FilterOptions.BufferSize = 0;
        BroadcastFilterPtOnAllCores(&FilterOptions);
    }
 
    if (Req != NULL)
    {
        Req->KernelStatus = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
    }
 
    return TRUE;
}

HyperTracePtFlush()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTracePtFlush

(

HYPERTRACE_PT_OPERATION_PACKETS *

HyperTraceOperationRequest

)

Flush PT trace state on all cores (free buffers).

Parameters

HyperTraceOperationRequest

Returns

BOOLEAN

{
    if (!g_ProcessorTraceEnabled)
    {
        if (HyperTraceOperationRequest != NULL)
        {
            HyperTraceOperationRequest->KernelStatus = DEBUGGER_ERROR_PT_ALREADY_DISABLED;
        }
        return FALSE;
    }
 
    //
    // Stop tracing on all cores via DPC (so MSRs are quiesced)
    //
    BroadcastFlushPtOnAllCores();
 
    //
    // Then free contiguous buffers at PASSIVE_LEVEL
    //
    PtFreeAllCpuBuffers();
 
    //
    // Reallocate buffers so subsequent !pt save / !pt dump / !pt enable
    // continue to work — Flush in LBR keeps tracing alive, so we mirror
    // that by leaving PT primed for the next !pt enable.
    //
    if (!PtAllocateAllCpuBuffers())
    {
        PtFreeAllCpuBuffers();
        if (HyperTraceOperationRequest != NULL)
        {
            HyperTraceOperationRequest->KernelStatus = DEBUGGER_ERROR_PT_NOT_SUPPORTED;
        }
        g_ProcessorTraceEnabled = FALSE;
        return FALSE;
    }
 
    //
    // Resume tracing on all cores
    //
    BroadcastEnablePtOnAllCores();
 
    if (HyperTraceOperationRequest != NULL)
    {
        HyperTraceOperationRequest->KernelStatus = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
    }
 
    return TRUE;
}

HyperTracePtMmap()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTracePtMmap

(

HYPERTRACE_PT_MMAP_PACKETS *

Req

)

Map every per-CPU PT main output + overflow buffer into the calling user-mode process. See HYPERTRACE_PT_MMAP_PACKETS for the full lifetime / single-process contract.

{
    if (Req == NULL)
        return FALSE;
 
    Req->NumCpus = 0;
 
    if (!g_HyperTraceCallbacksInitialized)
    {
        Req->KernelStatus = DEBUGGER_ERROR_HYPERTRACE_NOT_INITIALIZED;
        return FALSE;
    }
 
    if (!g_ProcessorTraceEnabled)
    {
        Req->KernelStatus = DEBUGGER_ERROR_PT_ALREADY_DISABLED;
        return FALSE;
    }
 
    if (PtMmapAllCpuBuffersToUser(Req->Cpus, PT_MAX_CPUS_FOR_MMAP, &Req->NumCpus) != 0)
    {
        Req->KernelStatus = DEBUGGER_ERROR_PT_NOT_SUPPORTED;
        return FALSE;
    }
 
    Req->KernelStatus = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
    return TRUE;
}

HyperTracePtPause()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTracePtPause

(

HYPERTRACE_PT_OPERATION_PACKETS *

HyperTraceOperationRequest

)

Pause PT tracing on every core. Buffers stay allocated and the per-CPU CTL is preserved, so HyperTracePtResume can restart the trace exactly where it stopped.

Parameters

HyperTraceOperationRequest

Returns

BOOLEAN

{
    if (!g_ProcessorTraceEnabled)
    {
        if (HyperTraceOperationRequest != NULL)
        {
            HyperTraceOperationRequest->KernelStatus = DEBUGGER_ERROR_PT_ALREADY_DISABLED;
        }
        return FALSE;
    }
 
    BroadcastPausePtOnAllCores();
 
    if (HyperTraceOperationRequest != NULL)
    {
        HyperTraceOperationRequest->KernelStatus = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
    }
 
    return TRUE;
}

HyperTracePtPerformOperation()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTracePtPerformOperation

(

HYPERTRACE_PT_OPERATION_PACKETS *

PtOperationRequest

)

Perform actions related to HyperTrace PT.

Parameters

PtOperationRequest

Returns

BOOLEAN

{
    BOOLEAN Status = TRUE;
 
    //
    // Check if the hypertrace module is initialized before performing any operation
    //
    if (!g_HyperTraceCallbacksInitialized)
    {
        PtOperationRequest->KernelStatus = DEBUGGER_ERROR_HYPERTRACE_NOT_INITIALIZED;
        return FALSE;
    }
 
    //
    // Perform the requested operation
    //
    switch (PtOperationRequest->PtOperationType)
    {
    case HYPERTRACE_PT_OPERATION_REQUEST_TYPE_ENABLE:
 
        LogInfo("HyperTrace: Enabling PT tracing...\n");
 
        HyperTracePtEnable(PtOperationRequest);
 
        break;
 
    case HYPERTRACE_PT_OPERATION_REQUEST_TYPE_DISABLE:
 
        LogInfo("HyperTrace: Disabling PT tracing...\n");
 
        HyperTracePtDisable(PtOperationRequest);
 
        break;
 
    case HYPERTRACE_PT_OPERATION_REQUEST_TYPE_PAUSE:
 
        LogInfo("HyperTrace: Pausing PT tracing...\n");
 
        HyperTracePtPause(PtOperationRequest);
 
        break;
 
    case HYPERTRACE_PT_OPERATION_REQUEST_TYPE_RESUME:
 
        LogInfo("HyperTrace: Resuming PT tracing...\n");
 
        HyperTracePtResume(PtOperationRequest);
 
        break;
 
    case HYPERTRACE_PT_OPERATION_REQUEST_TYPE_SIZE:
 
        LogInfo("HyperTrace: Snapshotting PT buffer sizes...\n");
 
        HyperTracePtSize(PtOperationRequest);
 
        break;
 
    case HYPERTRACE_PT_OPERATION_REQUEST_TYPE_DUMP:
 
        LogInfo("HyperTrace: Showing PT tracing...\n");
 
        HyperTracePtDump(PtOperationRequest);
 
        break;
 
    case HYPERTRACE_PT_OPERATION_REQUEST_TYPE_FLUSH:
 
        LogInfo("HyperTrace: Flushing PT tracing...\n");
 
        HyperTracePtFlush(PtOperationRequest);
 
        break;
 
    case HYPERTRACE_PT_OPERATION_REQUEST_TYPE_FILTER:
 
        LogInfo("HyperTrace: Updating PT filter / config...\n");
 
        HyperTracePtFilter(PtOperationRequest);
 
        break;
 
    default:
        Status                           = FALSE;
        PtOperationRequest->KernelStatus = DEBUGGER_ERROR_INVALID_HYPERTRACE_OPERATION_TYPE;
        break;
    }
 
    return Status;
}

HyperTracePtResume()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTracePtResume

(

HYPERTRACE_PT_OPERATION_PACKETS *

HyperTraceOperationRequest

)

Resume PT tracing on every core after a prior HyperTracePtPause.

Parameters

HyperTraceOperationRequest

Returns

BOOLEAN

{
    if (!g_ProcessorTraceEnabled)
    {
        if (HyperTraceOperationRequest != NULL)
        {
            HyperTraceOperationRequest->KernelStatus = DEBUGGER_ERROR_PT_ALREADY_DISABLED;
        }
        return FALSE;
    }
 
    BroadcastResumePtOnAllCores();
 
    if (HyperTraceOperationRequest != NULL)
    {
        HyperTraceOperationRequest->KernelStatus = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
    }
 
    return TRUE;
}

HyperTracePtSize()

IMPORT_EXPORT_HYPERTRACE BOOLEAN HyperTracePtSize

(

HYPERTRACE_PT_OPERATION_PACKETS *

HyperTraceOperationRequest

)

Snapshot the current PT output position on every core and write the per-CPU byte counts into HyperTraceOperationRequest->BytesPerCpu. The returned counts are the decode window — bytes [0, BytesPerCpu[i]) in CPU i's user mapping currently hold valid trace data.

Parameters

HyperTraceOperationRequest

Returns

BOOLEAN

{
    UINT32 ProcessorsCount;
 
    if (!g_ProcessorTraceEnabled)
    {
        if (HyperTraceOperationRequest != NULL)
        {
            HyperTraceOperationRequest->KernelStatus = DEBUGGER_ERROR_PT_ALREADY_DISABLED;
        }
        return FALSE;
    }
 
    if (HyperTraceOperationRequest == NULL)
        return FALSE;
 
    ProcessorsCount = KeQueryActiveProcessorCount(0);
    if (ProcessorsCount > PT_MAX_CPUS_FOR_MMAP)
        ProcessorsCount = PT_MAX_CPUS_FOR_MMAP;
 
    RtlZeroMemory(HyperTraceOperationRequest->BytesPerCpu,
                  sizeof(HyperTraceOperationRequest->BytesPerCpu));
 
    BroadcastSizePtOnAllCores(HyperTraceOperationRequest->BytesPerCpu);
 
    HyperTraceOperationRequest->NumCpus      = ProcessorsCount;
    HyperTraceOperationRequest->KernelStatus = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
    return TRUE;
}

HyperTraceUninit()

IMPORT_EXPORT_HYPERTRACE VOID HyperTraceUninit

(

)

Uninitialize the hypertrace module.

Returns

VOID

{
    //
    // Check if the callbacks are initialized, if not, we don't need to handle anymore
    //
    if (!g_HyperTraceCallbacksInitialized)
    {
        return;
    }
 
    //
    // Disable LBR tracing if it is still enabled
    //
    if (g_LastBranchRecordEnabled)
    {
        HyperTraceLbrDisable(NULL);
    }
 
    //
    // Unallocate the global LBR state list if it is allocated
    //
    if (g_LbrStateList != NULL)
    {
        PlatformMemFreePool(g_LbrStateList);
        g_LbrStateList = NULL;
    }
 
    //
    // Disable Processor Trace if it is still enabled
    //
    if (g_ProcessorTraceEnabled)
    {
        HyperTracePtDisable(NULL);
    }
 
    //
    // Free PT buffers (if any) and the per-CPU state list
    //
    if (g_PtStateList != NULL)
    {
        UINT32 ProcessorsCountLocal = KeQueryActiveProcessorCount(0);
        UINT32 i;
 
        for (i = 0; i < ProcessorsCountLocal; i++)
        {
            PtEngineFreeBuffers(&g_PtStateList[i]);
        }
 
        PlatformMemFreePool(g_PtStateList);
        g_PtStateList = NULL;
    }
 
    //
    // Reset the environment flag to default value
    //
    g_RunningOnHypervisorEnvironment = FALSE;
 
    //
    // Set callbacks to not initialized
    //
    g_HyperTraceCallbacksInitialized = FALSE;
}