PtApi.c File Reference

Tracing routines for HyperTrace module (Intel Processor Trace). More...

#include "pch.h"

Functions
BOOLEAN	HyperTracePtEnable (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Enable PT tracing for HyperTrace.
BOOLEAN	HyperTracePtDisable (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Disable PT tracing for 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.
BOOLEAN	HyperTracePtResume (HYPERTRACE_PT_OPERATION_PACKETS *HyperTraceOperationRequest)
	Resume PT tracing on every core after a prior HyperTracePtPause.
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.
BOOLEAN	HyperTracePtDump (HYPERTRACE_PT_OPERATION_PACKETS *HyperTraceOperationRequest)
	Dump PT trace state for HyperTrace.
BOOLEAN	HyperTracePtFlush (HYPERTRACE_PT_OPERATION_PACKETS *HyperTraceOperationRequest)
	Flush PT trace state on all cores (free buffers).
BOOLEAN	HyperTracePtFilter (HYPERTRACE_PT_OPERATION_PACKETS *Req)
	Apply a new PT trace configuration (TraceUser / TraceKernel / TargetCr3 / BufferSize / NumAddrRanges + AddrRanges) on all cores.
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.
BOOLEAN	HyperTracePtPerformOperation (HYPERTRACE_PT_OPERATION_PACKETS *PtOperationRequest)
	Perform actions related to HyperTrace PT.

Detailed Description

Tracing routines for HyperTrace module (Intel Processor Trace).

Author

Masoud Rahimi Jafari (Masoo.nosp@m.drah.nosp@m.imy13.nosp@m.79@g.nosp@m.mail..nosp@m.com)

Version

0.19

Date

2026-04-29

Copyright

This project is released under the GNU Public License v3.

Function Documentation

HyperTracePtDisable()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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;
}