rewrite comments into one, unified style

code/kernel/ke_debug.c

@@ -1,4 +1,5 @@
-// ke_debug.c - debugging utilities
+// Kernel debugging and bugcheck support. This file owns panic reporting, process fault reporting, and diagnostic queries.
+
 #include <stdarg.h>
 #include <stdint.h>
 #include <string.h>
@@ -31,6 +32,7 @@ static size_t   gDebugLogWrite;
 static size_t   gDebugLogUsed;
 static volatile long gDebugLogFlushing;
 
+// Implements the debug Log Append Locked operation.
 static void KiDebugLogAppendLocked(const char* text, size_t len) {
     if (!gDebugLogBuffer || gDebugLogSize == 0 || !text || len == 0)
         return;
@@ -53,6 +55,7 @@ static void KiDebugLogAppendLocked(const char* text, size_t len) {
         gDebugLogUsed += len;
 }
 
+// Implements the debug Console Write operation.
 static void KiDebugConsoleWrite(const char* text, size_t len) {
     if (!PrintChar || !text)
         return;
@@ -64,12 +67,14 @@ static volatile long gPanicInProgress = 0;
 static volatile uintptr_t gPanicOwnerToken = 0;
 static volatile long gPanicStoppedCpuCount = 0;
 
+// Implements the panic Secondary Halt operation.
 static _Noreturn void KiPanicSecondaryHalt(void) {
     _disable();
     _InterlockedIncrement(&gPanicStoppedCpuCount);
     for (;;) __halt();
 }
 
+// Implements the panic Current Token operation.
 static uintptr_t KiPanicCurrentToken(void) {
     THREAD* thread = KeGetCurrentThread();
     if (thread)
@@ -80,15 +85,18 @@ static uintptr_t KiPanicCurrentToken(void) {
     return 1u;
 }
 
+// Implements the panic Is Active operation.
 static int KiPanicIsActive(void) {
     return _InterlockedCompareExchange((volatile long*)&gPanicInProgress, 0, 0) != 0;
 }
 
+// Implements the panic Current Cpu Owns Report operation.
 static int KiPanicCurrentCpuOwnsReport(void) {
     uintptr_t token = KiPanicCurrentToken();
     return token != 0 && gPanicOwnerToken == token;
 }
 
+// Implements the begin Fatal Report operation.
 static void KiBeginFatalReport(void) {
     _disable();
     uintptr_t token = KiPanicCurrentToken();
@@ -114,11 +122,13 @@ __declspec(dllexport) int KeHandleNmiIpi(void) {
     return 0;
 }
 
+// Implements the kernel Put Char operation.
 void KiKernelPutChar(char c) {
     if (PrintChar)
         PrintChar(c, 0xCCCCCC, 0x012456);
 }
 
+// Initializes debug.
 void KeInitDebug(void (*PrintPtr)(char, uint32_t, uint32_t), uint32_t flags) {
     gDebugFlags = flags;
     gDebugEnabled = (flags & (KE_DEBUG_CONSOLE | KE_DEBUG_FILE_LOG)) != 0;
@@ -136,10 +146,12 @@ void KeInitDebug(void (*PrintPtr)(char, uint32_t, uint32_t), uint32_t flags) {
     }
 }
 
+// Returns debug Flags.
 uint32_t KeGetDebugFlags(void) {
     return gDebugFlags;
 }
 
+// Updates debug Console Writer.
 void KeSetDebugConsoleWriter(void (*PrintPtr)(char, uint32_t, uint32_t)) {
     if (!PrintPtr)
         return;
@@ -147,6 +159,7 @@ void KeSetDebugConsoleWriter(void (*PrintPtr)(char, uint32_t, uint32_t)) {
     printf_set_putchar(KiKernelPutChar);
 }
 
+// Implements the dbg Print operation.
 __declspec(dllexport) void DbgPrint(const char* fmt, ...) {
     if (!gDebugEnabled || !fmt) return;
 
@@ -179,6 +192,7 @@ __declspec(dllexport) void DbgPrint(const char* fmt, ...) {
     KeReleaseSpinlock(&gDebugPrintLock, flags);
 }
 
+// Flushes debug Log To File.
 __declspec(dllexport) KSTATUS KeFlushDebugLogToFile(SYS_STRING_VIEW path) {
     if (!gDebugLogBuffer || gDebugLogSize == 0 || !SysSvIsValid(path) || path.Length == 0)
         return STATUS_INVALID_PARAMETER;
@@ -228,7 +242,7 @@ __declspec(dllexport) KSTATUS KeFlushDebugLogToFile(SYS_STRING_VIEW path) {
     return (KSUCCESS(st) && totalWritten == used) ? STATUS_SUCCESS : st;
 }
 
-// KePanic
+// KePanic.
 __declspec(dllexport) _Noreturn void KePanic(int code, const char* fmt, ...) {
     KiBeginFatalReport();
 
@@ -276,13 +290,11 @@ __declspec(dllexport) void KePrintConsole(const char* buf, size_t len) {
         PrintChar(buf[i], 0xCCCCCC, 0x012456);
 }
 
-// ---------------------------------------------------------------------------
 // KeBugCheckProcess - user-mode fault handler
-//
+
 // Resolves the faulting RIP to a module name, prints a yellow crash banner,
 // kills the offending process, then exits the current thread so the scheduler
 // can continue running everything else.
-// ---------------------------------------------------------------------------
 
 // Return the short exception name for a CPU exception vector.
 // Keep this table complete for vectors 0..31 so faults never collapse into
@@ -326,6 +338,7 @@ static const char* KiFaultVectorName(int vector) {
     }
 }
 
+// Implements the fault Has Error Code operation.
 static int KiFaultHasErrorCode(int vector) {
     switch (vector) {
         case 8:   // #DF
@@ -374,10 +387,12 @@ static const char* KiResolveModuleEx(PROCESS* proc, uintptr_t addr,
     return "unknown";
 }
 
+// Implements the resolve Module operation.
 static const char* KiResolveModule(PROCESS* proc, uintptr_t addr) {
     return KiResolveModuleEx(proc, addr, (uintptr_t*)0, (size_t*)0);
 }
 
+// Prints address.
 static void KiPrintAddress(PROCESS* proc, const char* label, uintptr_t addr) {
     uintptr_t base = 0;
     size_t size = 0;
@@ -396,6 +411,7 @@ static void KiPrintAddress(PROCESS* proc, const char* label, uintptr_t addr) {
     }
 }
 
+// Implements the user Read U64 operation.
 static int KiUserReadU64(uintptr_t addr, uint64_t* out) {
     if (!out) return 0;
     if (!addr) return 0;
@@ -405,6 +421,7 @@ static int KiUserReadU64(uintptr_t addr, uint64_t* out) {
     return 1;
 }
 
+// Implements the user Read U8 operation.
 static int KiUserReadU8(uintptr_t addr, uint8_t* out) {
     if (!out) return 0;
     if (!addr) return 0;
@@ -414,6 +431,7 @@ static int KiUserReadU8(uintptr_t addr, uint8_t* out) {
     return 1;
 }
 
+// Dumps bytes.
 static void KiDumpBytes(PROCESS* proc, const char* label, uintptr_t center) {
     if (!center) {
         printf("%s: <null>\n", label);
@@ -438,6 +456,7 @@ static void KiDumpBytes(PROCESS* proc, const char* label, uintptr_t center) {
     }
 }
 
+// Implements the user Read I32 operation.
 static int KiUserReadI32(uintptr_t addr, int32_t* out) {
     if (!out) return 0;
     if (!addr) return 0;
@@ -447,6 +466,7 @@ static int KiUserReadI32(uintptr_t addr, int32_t* out) {
     return 1;
 }
 
+// Dumps indirect Call Slot.
 static void KiDumpIndirectCallSlot(PROCESS* proc, uintptr_t ret) {
     if (!ret) return;
 
@@ -461,12 +481,14 @@ static void KiDumpIndirectCallSlot(PROCESS* proc, uintptr_t ret) {
     if (KiUserReadU8(ret - 6, &b0) &&
         KiUserReadU8(ret - 5, &b1) &&
         b0 == 0xff && b1 == 0x15 &&
+        // Implements the user Read I32 operation.
         KiUserReadI32(ret - 4, &disp)) {
         insn = ret - 6;
     } else if (KiUserReadU8(ret - 7, &b0) &&
                KiUserReadU8(ret - 6, &b1) &&
                KiUserReadU8(ret - 5, &b2) &&
                b0 == 0x48 && b1 == 0xff && b2 == 0x15 &&
+               // Implements the user Read I32 operation.
                KiUserReadI32(ret - 4, &disp)) {
         insn = ret - 7;
     } else {
@@ -490,6 +512,7 @@ static void KiDumpIndirectCallSlot(PROCESS* proc, uintptr_t ret) {
     KiDumpBytes(proc, "Bytes near indirect slot", slot);
 }
 
+// Dumps modules.
 static void KiDumpModules(PROCESS* proc) {
     if (!proc) return;
 
@@ -513,6 +536,7 @@ static void KiDumpModules(PROCESS* proc) {
     }
 }
 
+// Dumps user Stack.
 static void KiDumpUserStack(PROCESS* proc, uintptr_t rsp) {
     printf("User stack @ %016llx:\n", (unsigned long long)rsp);
     if (!rsp) {
@@ -548,6 +572,7 @@ static void KiDumpUserStack(PROCESS* proc, uintptr_t rsp) {
     }
 }
 
+// Dumps fault Frame.
 static void KiDumpFaultFrame(PROCESS* proc, const KFAULT_FRAME* f) {
     if (!f) return;
 
@@ -586,6 +611,7 @@ static void KiDumpFaultFrame(PROCESS* proc, const KFAULT_FRAME* f) {
     KiDumpUserStack(proc, (uintptr_t)f->Rsp);
 }
 
+// Prints crash Char.
 static void KiPrintCrashChar(char c) {
     if (PrintChar)
         PrintChar(c, 0xFFAA00, 0x000000);   // amber - distinct from green debug / red panic
@@ -621,6 +647,7 @@ static void KiPrintCrashHeader(PROCESS* proc, int vector, uintptr_t rip,
                (unsigned long long)errCode);
 }
 
+// Implements the finish Faulted Process operation.
 static _Noreturn void KiFinishFaultedProcess(PROCESS* proc, THREAD* thread) {
     printf_set_putchar(KiKernelPutChar);
 
@@ -640,6 +667,7 @@ _Noreturn void KeBugCheckProcess(int vector, uintptr_t rip, uintptr_t errCode, u
     KiFinishFaultedProcess(proc, thread);
 }
 
+// Implements the fault Dispatch Frame operation.
 __declspec(dllexport) _Noreturn void KeFaultDispatchFrame(const KFAULT_FRAME* frame) {
     // Panic NMIs are broadcast to stop all other CPUs. Do not try to decode
     // the interrupted context on a secondary CPU once another CPU owns panic.
@@ -718,13 +746,11 @@ __declspec(dllexport) _Noreturn void KeFaultDispatchFrame(const KFAULT_FRAME* fr
     KiFinishFaultedProcess(proc, thread);
 }
 
-// ---------------------------------------------------------------------------
 // KeFaultDispatch - single C entry point for all three IDT fault stubs.
-//
+
 // The asm stubs (ke_syscall.asm) collect the CPU exception frame values and
 // call here. We check the CS RPL to decide: kernel fault → panic and halt,
 // user fault → KeBugCheckProcess (kill process, resume scheduler).
-// ---------------------------------------------------------------------------
 __declspec(dllexport) _Noreturn void KeFaultDispatch(int vector, uintptr_t rip,
                                                      uintptr_t errCode, uintptr_t cr2,
                                                      uintptr_t cs) {