Lbr.h File Reference

Message logging and tracing implementation. More...

Go to the source code of this file.

Classes
union	_CPUID28_EAX
union	_CPUID28_EBX
union	_CPUID28_ECX
struct	_CPUID28_LEAFS
union	_IA32_LBR_CTL_REGISTER
	The structure to hold the IA32_LBR_CTL MSR, which is used to enable and configure the LBR feature. More...
struct	_CPU_LBR_MAP
	The structure to hold the mapping of CPU model to its LBR capacity. More...

Macros
#define	MSR_LEGACY_LBR_SELECT   0x000001C8
#define	MSR_LBR_TOS   0x000001C9
#define	MSR_LASTBRANCH_0_FROM_IP   0x00000680
#define	MSR_LASTBRANCH_0_TO_IP   0x000006C0
#define	MSR_LASTBRANCH_INFO_0   0x00000DC0
#define	LBR_SELECT_WITHOUT_FILTER   0x00000000
#define	IA32_LBR_0_FROM_IP   0x1500
#define	IA32_LBR_0_TO_IP   0x1600
#define	IA32_LBR_0_INFO   0x1200
#define	CPUID_ARCH_LAST_BRANCH_RECORD_INFORMATION   0x1c
#define	IA32_LBR_CTL   0x000014CE

Typedefs
typedef union _CPUID28_EAX	CPUID28_EAX
typedef union _CPUID28_EAX *	PCPUID28_EAX
typedef union _CPUID28_EBX	CPUID28_EBX
typedef union _CPUID28_EBX *	PCPUID28_EBX
typedef union _CPUID28_ECX	CPUID28_ECX
typedef union _CPUID28_ECX *	PCPUID28_ECX
typedef struct _CPUID28_LEAFS	CPUID28_LEAFS
typedef struct _CPUID28_LEAFS *	PCPUID28_LEAFS
typedef union _IA32_LBR_CTL_REGISTER	IA32_LBR_CTL_REGISTER
	The structure to hold the IA32_LBR_CTL MSR, which is used to enable and configure the LBR feature.
typedef union _IA32_LBR_CTL_REGISTER *	PIA32_LBR_CTL_REGISTER
typedef struct _CPU_LBR_MAP	CPU_LBR_MAP
	The structure to hold the mapping of CPU model to its LBR capacity.
typedef struct _CPU_LBR_MAP *	PCPU_LBR_MAP

Functions
BOOLEAN	LbrCheckAndReadLegacyLbrDetails ()
	Check if the current CPU supports LBR by examining the CPU family and model and looking up the corresponding LBR capacity.
BOOLEAN	LbrCheckAndReadArchitecturalLbrDetails ()
	Check if the current CPU supports architectural LBR.
BOOLEAN	LbrStart (UINT64 FilterOptions)
	Start collecting LBR branches.
BOOLEAN	LbrCheck ()
	Check if LBR is enabled or not.
VOID	LbrFilter (UINT64 FilterOptions)
	Filter LBR branches based on the provided options.
VOID	LbrStop ()
	Stop collecting LBR branches.
VOID	LbrFlush ()
	Flush LBR MSRs by disabling LBR and clearing all LBR entries.
VOID	LbrSave ()
	Save LBR branches.
VOID	LbrPrint ()
	Print collected LBR branches.

Variables
CPU_LBR_MAP	CPU_LBR_MAPS []
	The global variable to hold the mapping of CPU model to its LBR capacity.

Detailed Description

Message logging and tracing implementation.

Author

Hari Mishal (harim.nosp@m.isha.nosp@m.l6@gm.nosp@m.ail..nosp@m.com)

Modified from LIBIHT project (Thomasaon Zhao et al) with Windows style updates.

Version

0.18

Date

2025-12-02

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

CPUID_ARCH_LAST_BRANCH_RECORD_INFORMATION

#define CPUID_ARCH_LAST_BRANCH_RECORD_INFORMATION   0x1c

IA32_LBR_0_FROM_IP

#define IA32_LBR_0_FROM_IP   0x1500

IA32_LBR_0_INFO

#define IA32_LBR_0_INFO   0x1200

IA32_LBR_0_TO_IP

#define IA32_LBR_0_TO_IP   0x1600

IA32_LBR_CTL

#define IA32_LBR_CTL   0x000014CE

LBR_SELECT_WITHOUT_FILTER

#define LBR_SELECT_WITHOUT_FILTER   0x00000000

MSR_LASTBRANCH_0_FROM_IP

#define MSR_LASTBRANCH_0_FROM_IP   0x00000680

MSR_LASTBRANCH_0_TO_IP

#define MSR_LASTBRANCH_0_TO_IP   0x000006C0

MSR_LASTBRANCH_INFO_0

#define MSR_LASTBRANCH_INFO_0   0x00000DC0

MSR_LBR_TOS

#define MSR_LBR_TOS   0x000001C9

MSR_LEGACY_LBR_SELECT

#define MSR_LEGACY_LBR_SELECT   0x000001C8

Typedef Documentation

CPU_LBR_MAP

typedef struct _CPU_LBR_MAP CPU_LBR_MAP

The structure to hold the mapping of CPU model to its LBR capacity.

CPUID28_EAX

typedef union _CPUID28_EAX CPUID28_EAX

CPUID28_EBX

typedef union _CPUID28_EBX CPUID28_EBX

CPUID28_ECX

typedef union _CPUID28_ECX CPUID28_ECX

CPUID28_LEAFS

typedef struct _CPUID28_LEAFS CPUID28_LEAFS

IA32_LBR_CTL_REGISTER

typedef union _IA32_LBR_CTL_REGISTER IA32_LBR_CTL_REGISTER

The structure to hold the IA32_LBR_CTL MSR, which is used to enable and configure the LBR feature.

MSR Address: 0x14CEH (Hex) / 5326 (Dec)

PCPU_LBR_MAP

typedef struct _CPU_LBR_MAP * PCPU_LBR_MAP

PCPUID28_EAX

typedef union _CPUID28_EAX * PCPUID28_EAX

PCPUID28_EBX

typedef union _CPUID28_EBX * PCPUID28_EBX

PCPUID28_ECX

typedef union _CPUID28_ECX * PCPUID28_ECX

PCPUID28_LEAFS

typedef struct _CPUID28_LEAFS * PCPUID28_LEAFS

PIA32_LBR_CTL_REGISTER

typedef union _IA32_LBR_CTL_REGISTER * PIA32_LBR_CTL_REGISTER

Function Documentation

LbrCheck()

BOOLEAN LbrCheck

(

)

Check if LBR is enabled or not.

Returns

BOOLEAN

{
    BOOLEAN IsOnVmxRootMode = FALSE;
 
    if (g_RunningOnHypervisorEnvironment)
    {
        IsOnVmxRootMode = g_Callbacks.VmFuncVmxGetCurrentExecutionMode();
    }
 
    if (IsOnVmxRootMode)
    {
        return LbrCheckOnVmxRootMode();
    }
    else
    {
        return LbrCheckOnNativeOrVmxNonRootMode();
    }
}

LbrCheckAndReadArchitecturalLbrDetails()

BOOLEAN LbrCheckAndReadArchitecturalLbrDetails

(

)

Check if the current CPU supports architectural LBR.

Returns

BOOLEAN

{
    ULONG a, b, c, d;
 
    CPUID_EAX_07 Edx07 = {0};
 
    CPUID28_EAX Eax1c = {0};
    CPUID28_EBX Ebx1c = {0};
    CPUID28_ECX Ecx1c = {0};
 
    //
    // Check for Architectural LBR support
    //
    //
    xcpuidex(CPUID_STRUCTURED_EXTENDED_FEATURE_FLAGS, 0x00, &a, &b, &c, &d);
 
    Edx07.Edx.AsUInt = d;
 
    //
    // CPUID.07H.00H:EDX[19] == 1 means arch LBR is supported
    //
    if (Edx07.Edx.AsUInt & (1 << 19))
    {
        g_ArchBasedLastBranchRecord = TRUE;
    }
    else
    {
        //
        // Architectural LBR is not supported by the CPU
        //
        g_ArchBasedLastBranchRecord = FALSE;
 
        return FALSE;
    }
 
    //
    // Being here means the CPU supports architectural LBR, we can read the LBR capabilities from CPUID 0x1c leaf
    //
    xcpuidex(CPUID_ARCH_LAST_BRANCH_RECORD_INFORMATION, 0x00, &a, &b, &c, &d);
 
    //
    // Assign LBR leafs to structure for easier access
    //
    Eax1c.AsUInt = a;
    Ebx1c.AsUInt = b;
    Ecx1c.AsUInt = c;
 
    //
    // Store the CPUID.1CH leaf information in a global structure for later use
    //
    g_Cpuid28Leafs.Eax = Eax1c;
    g_Cpuid28Leafs.Ebx = Ebx1c;
    g_Cpuid28Leafs.Ecx = Ecx1c;
    g_Cpuid28Leafs.Edx = d;
 
    //
    // Read LBR capacity from CPUID.1CH.00H:EAX[7:0]
    // Based on Intel SDM: For each bit n set in this field, the IA32_LBR_DEPTH.DEPTH value 8 * (n + 1) is supported
    //
    if (Eax1c.LbrDepthMask)
    {
        //
        // Get the highest set bit in LbrDepthMask to determine the maximum supported LBR depth
        //
        ULONG HighestSetBit = 0;
        for (ULONG i = 0; i < 8; i++)
        {
            if (Eax1c.LbrDepthMask & (1 << i))
            {
                HighestSetBit = i;
            }
        }
        g_LbrCapacity = 8 * (HighestSetBit + 1);
    }
    else
    {
        //
        // If LbrDepthMask is 0, it means the CPU supports architectural LBR but does not specify the depth, we can assume a default value (e.g., 16 or 32) or treat it as unsupported
        //
        g_LbrCapacity = MAXIMUM_LBR_CAPACITY; // Assuming a default capacity of MAXIMUM_LBR_CAPACITY if not specified
    }
 
    return TRUE;
}

LbrCheckAndReadLegacyLbrDetails()

BOOLEAN LbrCheckAndReadLegacyLbrDetails

(

)

Check if the current CPU supports LBR by examining the CPU family and model and looking up the corresponding LBR capacity.

Returns

BOOLEAN

{
    ULONG     a, b, c, d;
    ULONG     Family, Model;
    ULONGLONG i;
 
    xcpuid(1, &a, &b, &c, &d);
 
    Family = ((a >> 8) & 0xF) + ((a >> 20) & 0xFF);
    Model  = ((a >> 4) & 0xF) | ((a >> 12) & 0xF0);
 
    for (i = 0; i < sizeof(CPU_LBR_MAPS) / sizeof(CPU_LBR_MAPS[0]); ++i)
    {
        if (Model == CPU_LBR_MAPS[i].Model)
        {
            g_LbrCapacity = CPU_LBR_MAPS[i].LbrCapacity;
            break;
        }
    }
 
    if (g_LbrCapacity == 0)
    {
        return FALSE;
    }
 
    return TRUE;
}

LbrFilter()

VOID LbrFilter

(

UINT64

FilterOptions

)

Filter LBR branches based on the provided options.

Parameters

FilterOptions

A bitmask of filter options to apply to the LBR branches

Returns

VOID

{
    // LogInfo("Updating LBR filter options: 0x%llx\n", FilterOptions);
 
    //
    // First, we flush the LBR to clear out any existing entries that may not meet the new filter criteria
    //
    LbrFlush();
 
    //
    // Then we apply the new filter options and re-enable LBR with the updated filter settings
    //
    LbrStart(FilterOptions);
}

LbrFlush()

VOID LbrFlush

(

)

Flush LBR MSRs by disabling LBR and clearing all LBR entries.

Returns

VOID

{
    // LogInfo("Flush LBR on cpu core: %d\n", KeGetCurrentProcessorNumberEx(NULL));
 
    //
    // Stop LBR collection and save any remaining entries
    //
    LbrStop();
 
    //
    // Reset the LBR control registers to zero:
    // - ARCH LBR: zeroes IA32_LBR_CTL entirely (clears filters and disables collection)
    // - Legacy LBR: zeroes MSR_LEGACY_LBR_SELECT (resets branch filter to capture-all)
    //
    LbrResetControlRegisters();
 
    //
    // Clear all remaining hardware state (TOS for legacy LBR, and all from/to MSR pairs)
    //
    LbrClearHardwareState();
}

LbrPrint()

VOID LbrPrint

(

)

Print collected LBR branches.

Returns

VOID

{
    ULONG             CurrentIdx;
    LBR_STACK_ENTRY * State;
    UINT32            CurrentCore                          = 0;
    CHAR              BrTypeName[LBR_BR_TYPE_NAME_MAX_LEN] = {0};
    UINT32            BrType                               = 0;
    //
    // Get the current core id
    //
    CurrentCore = KeGetCurrentProcessorNumberEx(NULL);
 
    //
    // Get the current processor LBR stack
    //
    State = &g_LbrStateList[CurrentCore];
 
    Log("LBR Chronological Trace on core : 0x%x\n\n", CurrentCore);
 
    for (ULONG i = 1; i <= g_LbrCapacity; i++)
    {
        if (g_ArchBasedLastBranchRecord)
        {
            //
            // In ARCH LBR, there is not TOS index and everything is in order
            //
            CurrentIdx = i - 1;
        }
        else
        {
            CurrentIdx = (ULONG)(State->Tos + i) % (ULONG)g_LbrCapacity;
        }
 
        if (State->BranchEntry[CurrentIdx].From == 0)
        {
            continue;
        }
 
        if (g_ArchBasedLastBranchRecord)
        {
            BrType = (UINT32)State->LastBranchInfo[CurrentIdx].BrType_OnlyArchLbr;
 
            //
            // Get the branch type name for better readability when printing
            //
            LbrGetArchBranchType(BrType, BrTypeName);
 
            //
            // Architectural LBR
            //
            Log("\t [%2u] Branch Mispredicted: %s, Branch type: %s, Cycle Count (Decimal): %04d (is valid? %s) - From: %016llx  To: %016llx\n",
                CurrentIdx,
                State->LastBranchInfo[CurrentIdx].Mispred ? "true " : "false",
                BrTypeName,
                State->LastBranchInfo[CurrentIdx].CycleCount,
                State->LastBranchInfo[CurrentIdx].CycCntValid_OnlyArchLbr ? "true " : "false",
                State->BranchEntry[CurrentIdx].From,
                State->BranchEntry[CurrentIdx].To);
        }
        else
        {
            //
            // Legacy LBR
            //
            Log("\t [%2u] Branch Mispredicted: %s, Cycle Count (Decimal): %04d - From: %016llx  To: %016llx\n",
                CurrentIdx,
                State->LastBranchInfo[CurrentIdx].Mispred ? "true " : "false",
                State->LastBranchInfo[CurrentIdx].CycleCount,
                State->BranchEntry[CurrentIdx].From,
                State->BranchEntry[CurrentIdx].To);
        }
    }
}

LbrSave()

VOID LbrSave

(

)

Save LBR branches.

Returns

VOID

{
    UINT64            LbrTos;
    LBR_STACK_ENTRY * State;
    UINT32            CurrentCore = 0;
 
    //
    // Get the current core id
    //
    CurrentCore = KeGetCurrentProcessorNumberEx(NULL);
 
    //
    // Get the current processor LBR stack
    //
    State = &g_LbrStateList[CurrentCore];
 
    //
    // Read and store the current TOS index to know where the most recent branch is stored
    // Note that there is no TOS index in ARCH LBR since everything is in order
    //
    if (!g_ArchBasedLastBranchRecord)
    {
        xrdmsr(MSR_LBR_TOS, &LbrTos);
        State->Tos = (UINT8)LbrTos;
    }
 
    //
    // Dump LBR entries into the current core's state structure
    //
    for (ULONG i = 0; i < (ULONG)g_LbrCapacity; i++)
    {
        if (g_ArchBasedLastBranchRecord)
        {
            xrdmsr(IA32_LBR_0_FROM_IP + i, &State->BranchEntry[i].From);
            xrdmsr(IA32_LBR_0_TO_IP + i, &State->BranchEntry[i].To);
            xrdmsr(IA32_LBR_0_INFO + i, &State->LastBranchInfo[i].AsUInt);
        }
        else
        {
            xrdmsr(MSR_LASTBRANCH_0_FROM_IP + i, &State->BranchEntry[i].From);
            xrdmsr(MSR_LASTBRANCH_0_TO_IP + i, &State->BranchEntry[i].To);
            xrdmsr(MSR_LASTBRANCH_INFO_0 + i, &State->LastBranchInfo[i].AsUInt);
        }
    }
}

LbrStart()

BOOLEAN LbrStart

(

UINT64

FilterOptions

)

Start collecting LBR branches.

Parameters

FilterOptions

A bitmask of filter options to apply to the LBR branches (e.g., filtering by branch type, privilege level, etc.)

Returns

BOOLEAN

{
    BOOLEAN               IsOnVmxRootMode;
    IA32_LBR_CTL_REGISTER Ia32LbrCtl = {0};
    ULONGLONG             DbgCtlMsr  = 0;
 
    if (g_LbrCapacity == 0)
    {
        LogInfo("Err, LBR aborting, CPU model not supported\n");
        return FALSE;
    }
 
    //
    // Adjust and set filter options
    //
    LbrAdjustFilterOptions(FilterOptions, &Ia32LbrCtl);
 
    //
    // Clear hardware state before enabling LBR
    //
    LbrClearHardwareState();
 
    if (g_RunningOnHypervisorEnvironment)
    {
        IsOnVmxRootMode = g_Callbacks.VmFuncVmxGetCurrentExecutionMode();
 
        //
        // DEBUGCTL is not involved in ARCH LBR - it has its own dedicated control register
        // So for ARCH LBR we skip reading the previous value and build the register from scratch (replacing it)
        //
        if (!g_ArchBasedLastBranchRecord)
        {
            if (IsOnVmxRootMode)
            {
                LbrGetValuesOnVmxRootMode(&DbgCtlMsr, &Ia32LbrCtl);
            }
            else
            {
                LbrGetValuesOnVmxNonRootMode(&DbgCtlMsr, &Ia32LbrCtl);
            }
        }
 
        //
        // Apply the appropriate bit to enable LBR based on whether it is architectural LBR or legacy LBR
        //
        if (g_ArchBasedLastBranchRecord)
        {
            LbrEnableArchBased(&Ia32LbrCtl);
        }
        else
        {
            LbrEnableLegacyBased(&DbgCtlMsr);
        }
 
        //
        // Write the updated LBR control register values back based on the current VMX execution mode
        //
        if (IsOnVmxRootMode)
        {
            LbrSetValuesOnVmxRootMode(DbgCtlMsr, Ia32LbrCtl);
        }
        else
        {
            LbrSetValuesOnVmxNonRootMode(DbgCtlMsr, Ia32LbrCtl);
        }
    }
    else
    {
        LbrStartOnNativeMode(Ia32LbrCtl);
    }
 
    return TRUE;
}

LbrStop()

VOID LbrStop

(

)

Stop collecting LBR branches.

Returns

VOID

{
    BOOLEAN               IsOnVmxRootMode;
    ULONGLONG             DbgCtlMsr  = NULL64_ZERO;
    IA32_LBR_CTL_REGISTER Ia32LbrCtl = {0};
 
    if (g_RunningOnHypervisorEnvironment)
    {
        IsOnVmxRootMode = g_Callbacks.VmFuncVmxGetCurrentExecutionMode();
 
        //
        // Read the current LBR control register values based on the current VMX execution mode
        //
        if (IsOnVmxRootMode)
        {
            LbrGetValuesOnVmxRootMode(&DbgCtlMsr, &Ia32LbrCtl);
        }
        else
        {
            LbrGetValuesOnVmxNonRootMode(&DbgCtlMsr, &Ia32LbrCtl);
        }
 
        //
        // Apply the appropriate bit to disable LBR based on whether it is architectural LBR or legacy LBR
        //
        if (g_ArchBasedLastBranchRecord)
        {
            LbrDisableArchBased(&Ia32LbrCtl);
        }
        else
        {
            LbrDisableLegacyBased(&DbgCtlMsr);
        }
 
        //
        // Write the updated LBR control register values back based on the current VMX execution mode
        //
        if (IsOnVmxRootMode)
        {
            LbrSetValuesOnVmxRootMode(DbgCtlMsr, Ia32LbrCtl);
        }
        else
        {
            LbrSetValuesOnVmxNonRootMode(DbgCtlMsr, Ia32LbrCtl);
        }
    }
    else
    {
        LbrStopOnNativeMode();
    }
}

Variable Documentation

CPU_LBR_MAPS

CPU_LBR_MAP CPU_LBR_MAPS[]

extern

The global variable to hold the mapping of CPU model to its LBR capacity.

                           {
    {0x5c, 32},
    {0x5f, 32},
    {0x4e, 32},
    {0x5e, 32},
    {0x8e, 32},
    {0x9e, 32},
    {0x55, 32},
    {0x66, 32},
    {0x7a, 32},
    {0x67, 32},
    {0x6a, 32},
    {0x6c, 32},
    {0x7d, 32},
    {0x7e, 32},
    {0x8c, 32},
    {0x8d, 32},
    {0xa5, 32},
    {0xa6, 32},
    {0xa7, 32},
    {0xa8, 32},
    {0x86, 32},
    {0x8a, 32},
    {0x96, 32},
    {0x9c, 32},
    {0x3d, 16},
    {0x47, 16},
    {0x4f, 16},
    {0x56, 16},
    {0x3c, 16},
    {0x45, 16},
    {0x46, 16},
    {0x3f, 16},
    {0x2a, 16},
    {0x2d, 16},
    {0x3a, 16},
    {0x3e, 16},
    {0x1a, 16},
    {0x1e, 16},
    {0x1f, 16},
    {0x2e, 16},
    {0x25, 16},
    {0x2c, 16},
    {0x2f, 16},
    {0x17, 4},
    {0x1d, 4},
    {0x0f, 4},
    {0x37, 8},
    {0x4a, 8},
    {0x4c, 8},
    {0x4d, 8},
    {0x5a, 8},
    {0x5d, 8},
    {0x1c, 8},
    {0x26, 8},
    {0x27, 8},
    {0x35, 8},
    {0x36, 8}};