Kernel Debugging System

Location: kernel/debug/
Type: Kernel Debugging (Assembly)
Status: ✅ Fully Implemented

Overview

The FreeWorld OS kernel debugging system provides comprehensive debugging capabilities including KDB (Kernel Debugger), stack traces, and panic handling.

Components

KDB (Kernel Debugger)

Interactive kernel debugger accessible via serial port:

  • Breakpoints: Up to 64 breakpoints with INT3 installation
  • Register Inspection: View and modify all CPU registers
  • Memory Inspection: Read and write memory at any address
  • Stack Inspection: View current stack contents
  • Single-Step Execution: Step through code instruction by instruction
  • Command Interface: Full command-line interface with help system

Stack Trace

Frame pointer-based stack walking:

  • Call Stack Display: Shows up to 64 frames
  • Frame Pointer Walking: Uses RBP chain to walk stack
  • Address Display: Shows return addresses in hex
  • Integration: Available from KDB and panic handler

Panic Handler

Comprehensive kernel panic handler:

  • Panic Information: Displays panic message, file, and line number
  • Register Dump: Complete CPU register state
  • Stack Trace: Automatic stack trace on panic
  • Memory Dump: Memory contents around fault address
  • System State: CPU ID, memory info, process info
  • Graceful Halt: Safe system halt after panic

Breakpoint Management

Advanced breakpoint system:

  • Breakpoint Installation: INT3 instruction installation
  • Original Byte Saving: Preserves original instruction
  • Breakpoint Restoration: Restores original byte on continue
  • Exception Integration: INT3 exceptions trigger KDB

KDB Commands

Command Alias Description
help h Show help message
break <addr> b <addr> Set breakpoint at address
continue c Continue execution
step s Single step execution
registers reg Show all registers
memory <addr> mem <addr> Inspect memory at address
stack - Show stack contents
backtrace bt Show call stack
quit q Exit debugger

Features

  • Interactive debugging via serial port
  • 64 breakpoints with automatic management
  • Register inspection and modification
  • Memory inspection and modification
  • Stack inspection
  • Single-step execution (Trap Flag)
  • Stack trace with frame pointer walking
  • Comprehensive panic handler
  • System state dumping
  • Exception integration (INT3 breakpoints)

Implementation

Total Lines of Code: ~1,835 lines

  • kernel/debug/kdb.asm (~900 lines) - KDB implementation
  • kernel/debug/stack_trace.asm (~150 lines) - Stack trace
  • kernel/debug/panic.asm (~250 lines) - Panic handler
  • kernel/debug/serial_debug.asm (~60 lines) - Serial I/O
  • kernel/debug/kdb_breakpoints.asm (~120 lines) - Breakpoint management

Integration

The debugging system is integrated with:

  • Kernel initialization sequence
  • Exception handler (INT3 breakpoints)
  • Panic handler (error handler integration)
  • Serial port (debugging interface)