Kd.h File Reference

Header for routines related to kernel mode debugging. More...

Go to the source code of this file.

Classes
struct	_DEBUGGEE_REQUEST_TO_CHANGE_PROCESS
	request to change the process More...
struct	_DEBUGGEE_REQUEST_TO_CHANGE_THREAD
	request to change the thread More...
struct	_DEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT
	request to pause and halt the system More...
struct	_HARDWARE_DEBUG_REGISTER_DETAILS
	store the details of a hardware debug register to ignore any trigger for other threads More...

Typedefs
typedef struct _DEBUGGEE_REQUEST_TO_CHANGE_PROCESS	DEBUGGEE_REQUEST_TO_CHANGE_PROCESS
	request to change the process
typedef struct _DEBUGGEE_REQUEST_TO_CHANGE_PROCESS *	PDEBUGGEE_REQUEST_TO_CHANGE_PROCESS
typedef struct _DEBUGGEE_REQUEST_TO_CHANGE_THREAD	DEBUGGEE_REQUEST_TO_CHANGE_THREAD
	request to change the thread
typedef struct _DEBUGGEE_REQUEST_TO_CHANGE_THREAD *	PDEBUGGEE_REQUEST_TO_CHANGE_THREAD
typedef struct _DEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT	DEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT
	request to pause and halt the system
typedef struct _DEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT *	PDEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT
typedef struct _HARDWARE_DEBUG_REGISTER_DETAILS	HARDWARE_DEBUG_REGISTER_DETAILS
	store the details of a hardware debug register to ignore any trigger for other threads
typedef struct _HARDWARE_DEBUG_REGISTER_DETAILS *	PHARDWARE_DEBUG_REGISTER_DETAILS

Functions
VOID	KdHaltSystem (PDEBUGGER_PAUSE_PACKET_RECEIVED PausePacket)
	Halt the system.
VOID	KdHandleDebugEventsWhenKernelDebuggerIsAttached (PROCESSOR_DEBUGGING_STATE *DbgState, BOOLEAN TrapSetByDebugger)
	Handles debug events when kernel-debugger is attached.
VOID	KdManageSystemHaltOnVmxRoot (PROCESSOR_DEBUGGING_STATE *DbgState, PDEBUGGER_TRIGGERED_EVENT_DETAILS EventDetails)
	manage system halt on vmx-root mode
BOOLEAN	KdCheckAndHandleNmiCallback (_In_ UINT32 CoreId)
VOID	KdHandleNmi (_Inout_ PROCESSOR_DEBUGGING_STATE *DbgState)
VOID	KdInitializeKernelDebugger ()
	initialize kernel debugger
VOID	KdUninitializeKernelDebugger ()
	uninitialize kernel debugger
VOID	KdInitializeInstantEventPools ()
	Initialize the required pools for instant events.
VOID	KdSendFormatsFunctionResult (UINT64 Value)
	Notify user-mode to unload the debuggee and close the connections.
VOID	KdSendCommandFinishedSignal (UINT32 CoreId)
	Notify debugger that the execution of command finished.
VOID	KdHandleBreakpointAndDebugBreakpointsCallback (_In_ UINT32 CoreId, _In_ DEBUGGEE_PAUSING_REASON Reason, PDEBUGGER_TRIGGERED_EVENT_DETAILS EventDetails)
VOID	KdHandleBreakpointAndDebugBreakpoints (_Inout_ PROCESSOR_DEBUGGING_STATE *DbgState, _In_ DEBUGGEE_PAUSING_REASON Reason, PDEBUGGER_TRIGGERED_EVENT_DETAILS EventDetails)
VOID	KdHandleRegisteredMtfCallback (_In_ UINT32 CoreId)
VOID	KdHandleHaltsWhenNmiReceivedFromVmxRoot (_Inout_ PROCESSOR_DEBUGGING_STATE *DbgState)
BOOLEAN	KdCheckImmediateMessagingMechanism (UINT32 OperationCode)
	Checks whether the immediate messaging mechism is needed or not.
BOOLEAN	KdResponsePacketToDebugger (_In_ _Strict_type_match_ DEBUGGER_REMOTE_PACKET_TYPE PacketType, _In_ _Strict_type_match_ DEBUGGER_REMOTE_PACKET_REQUESTED_ACTION Response, _In_reads_bytes_opt_(OptionalBufferLength) CHAR *OptionalBuffer, _In_ UINT32 OptionalBufferLength)
BOOLEAN	KdLoggingResponsePacketToDebugger (_In_reads_bytes_(OptionalBufferLength) CHAR *OptionalBuffer, _In_ UINT32 OptionalBufferLength, _In_ UINT32 OperationCode)
BOOLEAN	KdCheckGuestOperatingModeChanges (UINT16 PreviousCsSelector, UINT16 CurrentCsSelector)
	Check if the execution mode (kernel-mode to user-mode or user-mode to kernel-mode) changed.
BOOLEAN	KdIsGuestOnUsermode32Bit ()
	determines if the guest was in 32-bit user-mode or 64-bit (long mode)
VOID	KdHandleNmiBroadcastDebugBreaks (UINT32 CoreId, BOOLEAN IsOnVmxNmiHandler)
	Handle broadcast NMIs for halting cores in vmx-root mode.
VOID	KdUnlockTheHaltedCore (PROCESSOR_DEBUGGING_STATE *DbgState)
	unlock the target core
BOOLEAN	KdCheckTheHaltedCore (PROCESSOR_DEBUGGING_STATE *DbgState)
	check the lock state of the target core
BOOLEAN	KdQueryDebuggerQueryThreadOrProcessTracingDetailsByCoreId (UINT32 CoreId, DEBUGGER_THREAD_PROCESS_TRACING TracingType)
	Query for process/thread interception status.

Variables
volatile LONG	DebuggerResponseLock
	Vmx-root lock for sending response of debugger.
volatile LONG	DebuggerHandleBreakpointLock
	Vmx-root lock for handling breaks to debugger.

Detailed Description

Header for routines related to kernel mode debugging.

Author

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

Version

0.1

Date

2020-12-20

Copyright

This project is released under the GNU Public License v3.

Typedef Documentation

DEBUGGEE_REQUEST_TO_CHANGE_PROCESS

typedef struct _DEBUGGEE_REQUEST_TO_CHANGE_PROCESS DEBUGGEE_REQUEST_TO_CHANGE_PROCESS

request to change the process

DEBUGGEE_REQUEST_TO_CHANGE_THREAD

typedef struct _DEBUGGEE_REQUEST_TO_CHANGE_THREAD DEBUGGEE_REQUEST_TO_CHANGE_THREAD

request to change the thread

DEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT

typedef struct _DEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT DEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT

request to pause and halt the system

HARDWARE_DEBUG_REGISTER_DETAILS

typedef struct _HARDWARE_DEBUG_REGISTER_DETAILS HARDWARE_DEBUG_REGISTER_DETAILS

store the details of a hardware debug register to ignore any trigger for other threads

PDEBUGGEE_REQUEST_TO_CHANGE_PROCESS

typedef struct _DEBUGGEE_REQUEST_TO_CHANGE_PROCESS * PDEBUGGEE_REQUEST_TO_CHANGE_PROCESS

PDEBUGGEE_REQUEST_TO_CHANGE_THREAD

typedef struct _DEBUGGEE_REQUEST_TO_CHANGE_THREAD * PDEBUGGEE_REQUEST_TO_CHANGE_THREAD

PDEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT

typedef struct _DEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT * PDEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT

PHARDWARE_DEBUG_REGISTER_DETAILS

typedef struct _HARDWARE_DEBUG_REGISTER_DETAILS * PHARDWARE_DEBUG_REGISTER_DETAILS

Function Documentation

KdCheckAndHandleNmiCallback()

BOOLEAN KdCheckAndHandleNmiCallback

(

_In_ UINT32

CoreId

)

KdCheckGuestOperatingModeChanges()

BOOLEAN KdCheckGuestOperatingModeChanges	(	UINT16	PreviousCsSelector,
		UINT16	CurrentCsSelector )

Check if the execution mode (kernel-mode to user-mode or user-mode to kernel-mode) changed.

Parameters

PreviousCsSelector
CurrentCsSelector

Returns

BOOLEAN

{
    PreviousCsSelector = PreviousCsSelector & ~3;
    CurrentCsSelector  = CurrentCsSelector & ~3;
 
    //
    // Check if the execution modes are the same or not
    //
    if (PreviousCsSelector == CurrentCsSelector)
    {
        //
        // Execution modes are not changed
        //
        return FALSE;
    }
 
    if ((PreviousCsSelector == KGDT64_R3_CODE || PreviousCsSelector == KGDT64_R3_CMCODE) && CurrentCsSelector == KGDT64_R0_CODE)
    {
        //
        // User-mode -> Kernel-mode
        //
        LogInfo("User-mode -> Kernel-mode\n");
    }
    else if ((CurrentCsSelector == KGDT64_R3_CODE || CurrentCsSelector == KGDT64_R3_CMCODE) && PreviousCsSelector == KGDT64_R0_CODE)
    {
        //
        // Kernel-mode to user-mode
        //
        LogInfo("Kernel-mode -> User-mode\n");
    }
    else if (CurrentCsSelector == KGDT64_R3_CODE && PreviousCsSelector == KGDT64_R3_CMCODE)
    {
        //
        // A heaven's gate (User-mode 32-bit code -> User-mode 64-bit code)
        //
        LogInfo("32-bit User-mode -> 64-bit User-mode (Heaven's gate)\n");
    }
    else if (PreviousCsSelector == KGDT64_R3_CODE && CurrentCsSelector == KGDT64_R3_CMCODE)
    {
        //
        // A heaven's gate (User-mode 64-bit code -> User-mode 32-bit code)
        //
        LogInfo("64-bit User-mode -> 32-bit User-mode (Return from Heaven's gate)\n");
    }
    else
    {
        LogError("Err, unknown changes in cs selector during the instrumentation step-in\n");
    }
 
    //
    // Execution modes are changed
    //
    return TRUE;
}

KdCheckImmediateMessagingMechanism()

BOOLEAN KdCheckImmediateMessagingMechanism

(

UINT32

OperationCode

)

Checks whether the immediate messaging mechism is needed or not.

Parameters

OperationCode

Returns

BOOLEAN

{
    return (g_KernelDebuggerState && !(OperationCode & OPERATION_MANDATORY_DEBUGGEE_BIT));
}

KdCheckTheHaltedCore()

BOOLEAN KdCheckTheHaltedCore

(

PROCESSOR_DEBUGGING_STATE *

DbgState

)

check the lock state of the target core

Parameters

DbgState

The state of the debugger on the target core

Returns

BOOLEAN

{
    return SpinlockCheckLock(&DbgState->Lock);
}

KdHaltSystem()

VOID KdHaltSystem

(

PDEBUGGER_PAUSE_PACKET_RECEIVED

PausePacket

)

Halt the system.

Parameters

PausePacket

Returns

VOID

{
    //
    // Broadcast to halt everything
    // Instead of broadcasting we will just send one vmcall and
    // from that point, we halt all the other cores by NMIs, this
    // way we are sure that we get all the other cores at the middle
    // of their execution codes and not on HyperDbg routines
    //
    // KdBroadcastHaltOnAllCores();
    //
 
    //
    // vm-exit and halt current core
    //
    VmFuncVmxVmcall(DEBUGGER_VMCALL_VM_EXIT_HALT_SYSTEM, 0, 0, 0);
 
    //
    // Set the status
    //
    PausePacket->Result = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
}

KdHandleBreakpointAndDebugBreakpoints()

VOID KdHandleBreakpointAndDebugBreakpoints	(	_Inout_ PROCESSOR_DEBUGGING_STATE *	DbgState,
		_In_ DEBUGGEE_PAUSING_REASON	Reason,
		PDEBUGGER_TRIGGERED_EVENT_DETAILS	EventDetails )

KdHandleBreakpointAndDebugBreakpointsCallback()

VOID KdHandleBreakpointAndDebugBreakpointsCallback	(	_In_ UINT32	CoreId,
		_In_ DEBUGGEE_PAUSING_REASON	Reason,
		PDEBUGGER_TRIGGERED_EVENT_DETAILS	EventDetails )

KdHandleDebugEventsWhenKernelDebuggerIsAttached()

VOID KdHandleDebugEventsWhenKernelDebuggerIsAttached	(	PROCESSOR_DEBUGGING_STATE *	DbgState,
		BOOLEAN	TrapSetByDebugger )

Handles debug events when kernel-debugger is attached.

Parameters

DbgState	The state of the debugger on the current core
TrapSetByDebugger	Shows whether a trap set by debugger or not

Returns

VOID

{
    DEBUGGER_TRIGGERED_EVENT_DETAILS TargetContext    = {0};
    BOOLEAN                          IgnoreDebugEvent = FALSE;
    UINT64                           LastVmexitRip    = VmFuncGetLastVmexitRip(DbgState->CoreId);
 
    //
    // It's a breakpoint and should be handled by the kernel debugger
    //
    TargetContext.Context = (PVOID)LastVmexitRip;
 
    if (TrapSetByDebugger)
    {
        //
        // *** Handle a regular trap flag (most of the times as a result of stepping) set by the debugger ***
        //
 
        //
        // Check and handle if there is a software defined breakpoint
        //
        if (!BreakpointCheckAndHandleDebuggerDefinedBreakpoints(DbgState,
                                                                LastVmexitRip,
                                                                DEBUGGEE_PAUSING_REASON_DEBUGGEE_STEPPED,
                                                                FALSE))
        {
            if (g_HardwareDebugRegisterDetailsForStepOver.Address != (UINT64)NULL)
            {
                //
                // Check if it's caused by a step-over hardware debug breakpoint or not
                //
                if (LastVmexitRip == g_HardwareDebugRegisterDetailsForStepOver.Address)
                {
                    if (g_HardwareDebugRegisterDetailsForStepOver.ProcessId == HANDLE_TO_UINT32(PsGetCurrentProcessId()) &&
                        g_HardwareDebugRegisterDetailsForStepOver.ThreadId == HANDLE_TO_UINT32(PsGetCurrentThreadId()))
                    {
                        //
                        // It's a step caused by a debug register breakpoint step-over
                        //
                        RtlZeroMemory(&g_HardwareDebugRegisterDetailsForStepOver, sizeof(HARDWARE_DEBUG_REGISTER_DETAILS));
                    }
                    else
                    {
                        //
                        // Should be ignored because it's a hardware debug register that is
                        // likely triggered by other thread
                        //
                        IgnoreDebugEvent = TRUE;
 
                        //
                        // Also, we should re-apply the hardware debug breakpoint on this thread
                        //
                        SetDebugRegisters(DEBUGGER_DEBUG_REGISTER_FOR_STEP_OVER,
                                          BREAK_ON_INSTRUCTION_FETCH,
                                          FALSE,
                                          g_HardwareDebugRegisterDetailsForStepOver.Address);
                    }
                }
            }
 
            if (!IgnoreDebugEvent)
            {
                //
                // Handle a regular step
                //
                KdHandleBreakpointAndDebugBreakpoints(DbgState,
                                                      DEBUGGEE_PAUSING_REASON_DEBUGGEE_STEPPED,
                                                      &TargetContext);
            }
        }
    }
    else
    {
        //
        // It's a regular debug break event
        //
        KdHandleBreakpointAndDebugBreakpoints(DbgState,
                                              DEBUGGEE_PAUSING_REASON_DEBUGGEE_HARDWARE_DEBUG_REGISTER_HIT,
                                              &TargetContext);
    }
}

KdHandleHaltsWhenNmiReceivedFromVmxRoot()

VOID KdHandleHaltsWhenNmiReceivedFromVmxRoot

(

_Inout_ PROCESSOR_DEBUGGING_STATE *

DbgState

)

KdHandleNmi()

VOID KdHandleNmi

(

_Inout_ PROCESSOR_DEBUGGING_STATE *

DbgState

)

KdHandleNmiBroadcastDebugBreaks()

VOID KdHandleNmiBroadcastDebugBreaks	(	UINT32	CoreId,
		BOOLEAN	IsOnVmxNmiHandler )

Handle broadcast NMIs for halting cores in vmx-root mode.

Parameters

CoreId
IsOnVmxNmiHandler

Returns

VOID

{
    //
    // Get the current debugging state
    //
    PROCESSOR_DEBUGGING_STATE * DbgState = &g_DbgState[CoreId];
 
    //
    // We use it as a global flag (for both vmx-root and vmx non-root), because
    // generally it doesn't have any use case in vmx-root (IsOnVmxNmiHandler == FALSE)
    // but in some cases, we might set the MTF but another vm-exit receives before
    // MTF and in that place if it tries to trigger and event, then the MTF is not
    // handled and the core is not locked properly, just waits to get the handle
    // of the "DebuggerHandleBreakpointLock", so we check this flag there
    //
    DbgState->NmiState.WaitingToBeLocked = TRUE;
 
    if (IsOnVmxNmiHandler)
    {
        //
        // Indicate that it's called from NMI handle, and it relates to
        // halting the debuggee
        //
        DbgState->NmiState.NmiCalledInVmxRootRelatedToHaltDebuggee = TRUE;
 
        //
        // If the core was in the middle of spinning on the spinlock
        // of getting the debug lock, this mechanism is not needed,
        // but if the core is not spinning there or the core is processing
        // a random vm-exit, then we inject an immediate vm-exit after vm-entry
        // or inject a DPC
        // this is used for two reasons.
        //
        //      1. first, we will get the registers (context) to halt the core
        //      2. second, it guarantees that if the NMI arrives within any
        //         instruction in vmx-root mode, then we injected an immediate
        //         vm-exit and we won't miss any cpu cycle in the guest
        //
        // KdFireDpc(KdHaltCoreInTheCaseOfHaltedFromNmiInVmxRoot, NULL);
        VmFuncSetMonitorTrapFlag(TRUE);
    }
    else
    {
        //
        // Handle core break
        //
        KdHandleNmi(DbgState);
    }
}

KdHandleRegisteredMtfCallback()

VOID KdHandleRegisteredMtfCallback

(

_In_ UINT32

CoreId

)

KdInitializeInstantEventPools()

VOID KdInitializeInstantEventPools

(

)

Initialize the required pools for instant events.

Returns

VOID

{
    //
    // Request pages to be allocated for regular instant events
    //
    PoolManagerRequestAllocation(REGULAR_INSTANT_EVENT_CONDITIONAL_BUFFER, MAXIMUM_REGULAR_INSTANT_EVENTS, INSTANT_REGULAR_EVENT_BUFFER);
 
    //
    // Request pages to be allocated for regular instant events's actions
    //
    PoolManagerRequestAllocation(REGULAR_INSTANT_EVENT_ACTION_BUFFER, MAXIMUM_REGULAR_INSTANT_EVENTS, INSTANT_REGULAR_EVENT_ACTION_BUFFER);
 
#if MAXIMUM_BIG_INSTANT_EVENTS >= 1
 
    //
    // Request pages to be allocated for big instant events
    //
    PoolManagerRequestAllocation(BIG_INSTANT_EVENT_CONDITIONAL_BUFFER, MAXIMUM_BIG_INSTANT_EVENTS, INSTANT_BIG_EVENT_BUFFER);
 
    //
    // Request pages to be allocated for big instant events's actions
    //
    PoolManagerRequestAllocation(BIG_INSTANT_EVENT_ACTION_BUFFER, MAXIMUM_BIG_INSTANT_EVENTS, INSTANT_BIG_EVENT_ACTION_BUFFER);
 
#endif // MAXIMUM_BIG_INSTANT_EVENTS
 
    //
    // Pre-allocate pools for possible EPT hooks
    // Because there are possible init EPT hook structures, we only allocate the
    //  maximum number of regular instant event subtracted from the initial pages
    //
    ConfigureEptHookReservePreallocatedPoolsForEptHooks(MAXIMUM_REGULAR_INSTANT_EVENTS - MAXIMUM_NUMBER_OF_INITIAL_PREALLOCATED_EPT_HOOKS);
 
    if (!PoolManagerCheckAndPerformAllocationAndDeallocation())
    {
        LogWarning("Warning, cannot allocate the pre-allocated pools for EPT hooks");
 
        //
        // BTW, won't fail the starting phase because of this
        //
    }
}

KdInitializeKernelDebugger()

VOID KdInitializeKernelDebugger

(

)

initialize kernel debugger

this function should be called on vmx non-root

Returns

VOID

{
    //
    // Allocate DPC routine
    //
    // for (size_t i = 0; i < CoreCount; i++)
    // {
    //     g_DbgState[i].KdDpcObject = PlatformMemAllocateNonPagedPool(sizeof(KDPC));
    //
    //     if (g_DbgState[i].KdDpcObject == NULL)
    //     {
    //         LogError("Err, allocating dpc holder for debuggee");
    //         return;
    //     }
    // }
 
    //
    // Request pages for breakpoint detail
    //
    PoolManagerRequestAllocation(sizeof(DEBUGGEE_BP_DESCRIPTOR),
                                 MAXIMUM_BREAKPOINTS_WITHOUT_CONTINUE,
                                 BREAKPOINT_DEFINITION_STRUCTURE);
 
    //
    // Enable vm-exit on Hardware debug exceptions and breakpoints
    // so, intercept #DBs and #BP by changing exception bitmap (one core)
    //
    BroadcastEnableDbAndBpExitingAllCores();
 
    //
    // Reset pause break requests
    //
    RtlZeroMemory(&g_IgnoreBreaksToDebugger, sizeof(DEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT));
 
    //
    // Initialize list of breakpoints and breakpoint id
    //
    g_MaximumBreakpointId = 0;
    InitializeListHead(&g_BreakpointsListHead);
 
    //
    // Initial the needed pools for instant events
    //
    KdInitializeInstantEventPools();
 
    //
    // Indicate that the kernel debugger is active
    //
    g_KernelDebuggerState = TRUE;
}

KdIsGuestOnUsermode32Bit()

BOOLEAN KdIsGuestOnUsermode32Bit

(

)

determines if the guest was in 32-bit user-mode or 64-bit (long mode)

this function should be called from vmx-root

Returns

BOOLEAN

{
    //
    // Only 16 bit is needed however, vmwrite might write on other bits
    // and corrupt other variables, that's why we get 64bit
    //
    UINT64 CsSel = (UINT64)NULL;
 
    //
    // Read guest's cs selector
    //
    CsSel = VmFuncGetCsSelector();
 
    if (CsSel == KGDT64_R0_CODE)
    {
        //
        // 64-bit kernel-mode
        //
        return FALSE;
    }
    else if ((CsSel & ~3) == KGDT64_R3_CODE)
    {
        //
        // 64-bit user-mode
        //
        return FALSE;
    }
    else if ((CsSel & ~3) == KGDT64_R3_CMCODE)
    {
        //
        // 32-bit user-mode
        //
        return TRUE;
    }
    else
    {
        LogError("Err, unknown value for cs, cannot determine wow64 mode");
    }
 
    //
    // By default, 64-bit
    //
    return FALSE;
}

KdLoggingResponsePacketToDebugger()

BOOLEAN KdLoggingResponsePacketToDebugger	(	_In_reads_bytes_(OptionalBufferLength) CHAR *	OptionalBuffer,
		_In_ UINT32	OptionalBufferLength,
		_In_ UINT32	OperationCode )

KdManageSystemHaltOnVmxRoot()

VOID KdManageSystemHaltOnVmxRoot	(	PROCESSOR_DEBUGGING_STATE *	DbgState,
		PDEBUGGER_TRIGGERED_EVENT_DETAILS	EventDetails )

manage system halt on vmx-root mode

This function should only be called from KdHandleBreakpointAndDebugBreakpoints

Parameters

DbgState	The state of the debugger on the current core
EventDetails
MainCore	the core that triggered the event

Returns

VOID

{
    DEBUGGEE_KD_PAUSED_PACKET PausePacket;
    ULONG                     ExitInstructionLength = 0;
    RFLAGS                    Rflags                = {0};
    UINT64                    LastVmexitRip         = 0;
 
    //
    // Perform Pre-halt tasks
    //
    KdApplyTasksPreHaltCore(DbgState);
 
StartAgain:
 
    //
    // We check for receiving buffer (unhalting) only on the
    // first core and not on every cores
    //
    if (DbgState->MainDebuggingCore)
    {
        //
        // *** Current Operating Core  ***
        //
        RtlZeroMemory(&PausePacket, sizeof(DEBUGGEE_KD_PAUSED_PACKET));
 
        //
        // Get the last RIP for vm-exit handler
        //
        LastVmexitRip = VmFuncGetRip();
 
        //
        // Set the halt reason
        //
        PausePacket.PausingReason = g_DebuggeeHaltReason;
 
        //
        // Set the current core
        //
        PausePacket.CurrentCore = DbgState->CoreId;
 
        //
        // Set the RIP and mode of execution
        //
        PausePacket.Rip                    = LastVmexitRip;
        PausePacket.IsProcessorOn32BitMode = KdIsGuestOnUsermode32Bit();
 
        //
        // Set disassembly state
        //
        PausePacket.IgnoreDisassembling    = DbgState->IgnoreDisasmInNextPacket;
        DbgState->IgnoreDisasmInNextPacket = FALSE;
 
        //
        // Set rflags for finding the results of conditional jumps
        //
        Rflags.AsUInt      = VmFuncGetRflags();
        PausePacket.Rflags = Rflags.AsUInt;
 
        //
        // Set the event tag (if it's an event)
        //
        if (EventDetails != NULL)
        {
            PausePacket.EventTag          = EventDetails->Tag;
            PausePacket.EventCallingStage = EventDetails->Stage;
        }
 
        //
        // Read the instruction len hint
        //
        if (DbgState->InstructionLengthHint != 0)
        {
            ExitInstructionLength = DbgState->InstructionLengthHint;
        }
        else
        {
            //
            // Reading instruction length (VMCS_VMEXIT_INSTRUCTION_LENGTH) won't work for anything that is not instruction exiting,
            // so we won't use it anymore
            //
 
            //
            // Set the length to notify debuggee
            //
            ExitInstructionLength = CheckAddressMaximumInstructionLength((PVOID)LastVmexitRip);
        }
 
        //
        // Set the reading length of bytes (for instruction disassembling)
        //
        PausePacket.ReadInstructionLen = (UINT16)ExitInstructionLength;
 
        //
        // Find the current instruction
        //
        MemoryMapperReadMemorySafeOnTargetProcess(LastVmexitRip,
                                                  &PausePacket.InstructionBytesOnRip,
                                                  ExitInstructionLength);
 
        //
        // Send the pause packet, along with RIP and an indication
        // to pause to the debugger
        //
        KdResponsePacketToDebugger(DEBUGGER_REMOTE_PACKET_TYPE_DEBUGGEE_TO_DEBUGGER,
                                   DEBUGGER_REMOTE_PACKET_REQUESTED_ACTION_DEBUGGEE_PAUSED_AND_CURRENT_INSTRUCTION,
                                   (CHAR *)&PausePacket,
                                   sizeof(DEBUGGEE_KD_PAUSED_PACKET));
 
        //
        // Perform Commands from the debugger
        //
        KdDispatchAndPerformCommandsFromDebugger(DbgState);
 
        //
        // Check if it's a change core event or not, otherwise finish the execution
        // and continue debuggee
        //
        if (!DbgState->MainDebuggingCore)
        {
            //
            // It's a core switch, start again
            //
            goto StartAgain;
        }
    }
    else
    {
        //
        // All cores except operating core
        //
 
        //
        // Lock and unlock the lock so all core can get the lock
        // and continue their normal execution
        //
        DbgState->NmiState.WaitingToBeLocked = FALSE;
 
        ScopedSpinlock(
            DbgState->Lock,
 
            //
            // Check if it's a change core event or not
            //
            if (DbgState->MainDebuggingCore) {
                //
                // It's a core change event
                //
                g_DebuggeeHaltReason = DEBUGGEE_PAUSING_REASON_DEBUGGEE_CORE_SWITCHED;
 
                goto StartAgain;
            }
 
        );
 
        //
        // Check if any task needs to be executed on this core or not
        //
        if (DbgState->HaltedCoreTask.PerformHaltedTask)
        {
            //
            // Indicate that the halted core is no longer needed to execute a task
            // as the current task is executed once
            //
            DbgState->HaltedCoreTask.PerformHaltedTask = FALSE;
 
            //
            // Perform the target task
            //
            HaltedCorePerformTargetTask(DbgState,
                                        DbgState->HaltedCoreTask.TargetTask,
                                        DbgState->HaltedCoreTask.Context);
 
            //
            // Check if the core needs to be locked again
            //
            if (DbgState->HaltedCoreTask.LockAgainAfterTask)
            {
                //
                // Lock again
                //
                SpinlockLock(&DbgState->Lock);
 
                goto StartAgain;
            }
        }
    }
 
    //
    // Apply the basic task for the core before continue
    //
    KdApplyTasksPostContinueCore(DbgState);
}

KdQueryDebuggerQueryThreadOrProcessTracingDetailsByCoreId()

BOOLEAN KdQueryDebuggerQueryThreadOrProcessTracingDetailsByCoreId	(	UINT32	CoreId,
		DEBUGGER_THREAD_PROCESS_TRACING	TracingType )

Query for process/thread interception status.

Parameters

CoreId
TracingType

Returns

BOOLEAN whether it's activated or not

{
    BOOLEAN                     Result   = FALSE;
    PROCESSOR_DEBUGGING_STATE * DbgState = &g_DbgState[CoreId];
 
    switch (TracingType)
    {
    case DEBUGGER_THREAD_PROCESS_TRACING_INTERCEPT_CLOCK_INTERRUPTS_FOR_THREAD_CHANGE:
 
        Result = DbgState->ThreadOrProcessTracingDetails.InterceptClockInterruptsForThreadChange;
 
        break;
 
    case DEBUGGER_THREAD_PROCESS_TRACING_INTERCEPT_CLOCK_INTERRUPTS_FOR_PROCESS_CHANGE:
 
        Result = DbgState->ThreadOrProcessTracingDetails.InterceptClockInterruptsForProcessChange;
 
        break;
 
    case DEBUGGER_THREAD_PROCESS_TRACING_INTERCEPT_CLOCK_DEBUG_REGISTER_INTERCEPTION:
 
        Result = DbgState->ThreadOrProcessTracingDetails.DebugRegisterInterceptionState;
 
        break;
 
    case DEBUGGER_THREAD_PROCESS_TRACING_INTERCEPT_CLOCK_WAITING_FOR_MOV_CR3_VM_EXITS:
 
        Result = DbgState->ThreadOrProcessTracingDetails.IsWatingForMovCr3VmExits;
 
        break;
 
    default:
 
        LogError("Err, debugger encountered an unknown query type for querying process or thread interception details");
 
        break;
    }
 
    return Result;
}

KdResponsePacketToDebugger()

BOOLEAN KdResponsePacketToDebugger	(	_In_ _Strict_type_match_ DEBUGGER_REMOTE_PACKET_TYPE	PacketType,
		_In_ _Strict_type_match_ DEBUGGER_REMOTE_PACKET_REQUESTED_ACTION	Response,
		_In_reads_bytes_opt_(OptionalBufferLength) CHAR *	OptionalBuffer,
		_In_ UINT32	OptionalBufferLength )

KdSendCommandFinishedSignal()

VOID KdSendCommandFinishedSignal

(

UINT32

CoreId

)

Notify debugger that the execution of command finished.

Parameters

CoreId

Returns

VOID

{
    //
    // Halt other cores again
    //
    KdHandleBreakpointAndDebugBreakpointsCallback(CoreId,
                                                  DEBUGGEE_PAUSING_REASON_DEBUGGEE_COMMAND_EXECUTION_FINISHED,
                                                  NULL);
}

KdSendFormatsFunctionResult()

VOID KdSendFormatsFunctionResult

(

UINT64

Value

)

Notify user-mode to unload the debuggee and close the connections.

Parameters

Value

Returns

VOID

{
    DEBUGGEE_FORMATS_PACKET FormatsPacket = {0};
 
    FormatsPacket.Result = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
    FormatsPacket.Value  = Value;
 
    //
    // Kernel debugger is active, we should send the bytes over serial
    //
    KdResponsePacketToDebugger(
        DEBUGGER_REMOTE_PACKET_TYPE_DEBUGGEE_TO_DEBUGGER,
        DEBUGGER_REMOTE_PACKET_REQUESTED_ACTION_DEBUGGEE_RESULT_OF_FORMATS,
        (CHAR *)&FormatsPacket,
        sizeof(DEBUGGEE_FORMATS_PACKET));
}

KdUninitializeKernelDebugger()

VOID KdUninitializeKernelDebugger

(

)

uninitialize kernel debugger

this function should be called on vmx non-root

Returns

VOID

{
    ULONG ProcessorsCount;
 
    if (g_KernelDebuggerState)
    {
        ProcessorsCount = KeQueryActiveProcessorCount(0);
 
        //
        // Indicate that the kernel debugger is not active
        //
        g_KernelDebuggerState = FALSE;
 
        //
        // Reset pause break requests
        //
        RtlZeroMemory(&g_IgnoreBreaksToDebugger, sizeof(DEBUGGEE_REQUEST_TO_IGNORE_BREAKS_UNTIL_AN_EVENT));
 
        //
        // Remove all active breakpoints
        //
        BreakpointRemoveAllBreakpoints();
 
        //
        // Disable vm-exit on Hardware debug exceptions and breakpoints
        // so, not intercept #DBs and #BP by changing exception bitmap (one core)
        //
        BroadcastDisableDbAndBpExitingAllCores();
    }
}

KdUnlockTheHaltedCore()

VOID KdUnlockTheHaltedCore

(

PROCESSOR_DEBUGGING_STATE *

DbgState

)

unlock the target core

Parameters

DbgState

The state of the debugger on the target core

Returns

VOID

{
    SpinlockUnlock(&DbgState->Lock);
}

Variable Documentation

DebuggerHandleBreakpointLock

volatile LONG DebuggerHandleBreakpointLock

Vmx-root lock for handling breaks to debugger.

DebuggerResponseLock

volatile LONG DebuggerResponseLock

Vmx-root lock for sending response of debugger.