From 4256a312aef59ab4acb9bf4e0c3897a32bd172f8 Mon Sep 17 00:00:00 2001
From: Aiken Harris <harraiken91@gmail.com>
Date: Sun, 7 Jun 2026 02:04:27 +0200
Subject: [PATCH] Implement kernel debugger entry point

---
 sdk/xtdk/xtstatus.h           |  1 +
 xtoskrnl/includes/kd/debug.hh |  7 ++++
 xtoskrnl/kd/debug.cc          | 76 +++++++++++++++++++++++++++++++++++
 3 files changed, 84 insertions(+)

diff --git a/sdk/xtdk/xtstatus.h b/sdk/xtdk/xtstatus.h
index 0803ba2..2a5c6bd 100644
--- a/sdk/xtdk/xtstatus.h
+++ b/sdk/xtdk/xtstatus.h
@@ -48,6 +48,7 @@
 
 /* XT status code definitions */
 #define STATUS_SUCCESS                                                     ((XTSTATUS) 0x00000000L)
+#define STATUS_WAKE_SYSTEM_DEBUGGER                                        ((XTSTATUS) 0x80000007L)
 #define STATUS_END_OF_MEDIA                                                ((XTSTATUS) 0x8000001EL)
 #define STATUS_RESOURCE_LOCKED                                             ((XTSTATUS) 0xC0000000L)
 #define STATUS_UNSUCCESSFUL                                                ((XTSTATUS) 0xC0000001L)
diff --git a/xtoskrnl/includes/kd/debug.hh b/xtoskrnl/includes/kd/debug.hh
index a112c9d..535d208 100644
--- a/xtoskrnl/includes/kd/debug.hh
+++ b/xtoskrnl/includes/kd/debug.hh
@@ -25,6 +25,13 @@ namespace KD
 
         public:
             STATIC XTAPI BOOLEAN DebuggerActive(VOID);
+            STATIC XTAPI VOID EnterDebugger(IN PKTRAP_FRAME TrapFrame);
+            STATIC XTAPI KCONTINUE_STATUS SwitchCpu(VOID);
+
+        private:
+            STATIC XTAPI BOOLEAN ProcessCpuStateChange(IN PEXCEPTION_RECORD ExceptionRecord,
+                                                       IN OUT PCONTEXT Context,
+                                                       IN BOOLEAN SecondChanceException);
     };
 }
 
diff --git a/xtoskrnl/kd/debug.cc b/xtoskrnl/kd/debug.cc
index f79a816..507b0f2 100644
--- a/xtoskrnl/kd/debug.cc
+++ b/xtoskrnl/kd/debug.cc
@@ -22,3 +22,79 @@ KD::Debugger::DebuggerActive(VOID)
 {
     return Active;
 }
+
+/**
+ * Serves as the primary entry point for the interactive kernel debugger.
+ *
+ * @param TrapFrame
+ *        Supplies a pointer to the processor's trap frame captured at the moment the breakpoint or exception occurred.
+ *
+ * @return This routine does not return any value.
+ *
+ * @since XT 1.0
+ */
+XTAPI
+VOID
+KD::Debugger::EnterDebugger(IN PKTRAP_FRAME TrapFrame)
+{
+    /* Mark the debugger as active */
+    Active = TRUE;
+
+    /* Print debug message and enter an infinite loop */
+    DebugPrint(L"\n\n*** KDebugger Entered at RIP 0x%.16llX ***\n", TrapFrame->Rip);
+    for(;;);
+
+    /* Mark the debugger as inactive */
+    Active = FALSE;
+}
+
+/**
+ * Processes a processor state change and acts as the primary event loop for the debugger.
+ *
+ * @param ExceptionRecord
+ *        Supplies a pointer to the exception record that triggered the state change.
+ *
+ * @param Context
+ *        Supplies a pointer to the processor's context frame.
+ *
+ * @param SecondChance
+ *        Supplies a boolean value indicating whether this is a second-chance exception.
+ *
+ * @return This routine returns TRUE if the exception was handled by the debugger, or FALSE otherwise.
+ *
+ * @since XT 1.0
+ */
+XTAPI
+BOOLEAN
+KD::Debugger::ProcessCpuStateChange(IN PEXCEPTION_RECORD ExceptionRecord,
+                                    IN OUT PCONTEXT Context,
+                                    IN BOOLEAN SecondChance)
+{
+    return FALSE;
+}
+
+/**
+ * Transfers active control to a previously frozen processor.
+ *
+ * @return This routine returns a value indicating how execution should proceed after the debugging session concludes.
+ *
+ * @since XT 1.0
+ */
+XTAPI
+KCONTINUE_STATUS
+KD::Debugger::SwitchCpu(VOID)
+{
+    EXCEPTION_RECORD ExceptionRecord;
+    PKPROCESSOR_CONTROL_BLOCK Prcb;
+
+    /* Get processor control block */
+    Prcb = KE::Processor::GetCurrentProcessorControlBlock();
+
+    /* Construct an exception record */
+    ExceptionRecord.ExceptionAddress = (PVOID)&Prcb->ProcessorState.ContextFrame.Rip;
+    ExceptionRecord.ExceptionCode = STATUS_WAKE_SYSTEM_DEBUGGER;
+    ExceptionRecord.ExceptionRecord  = &ExceptionRecord;
+
+    /* Pass the synthetic exception and the processor context to the debugger */
+    return (KCONTINUE_STATUS)ProcessCpuStateChange(&ExceptionRecord, &Prcb->ProcessorState.ContextFrame, FALSE);
+}