gdb-chat

Breenix GDB Chat

Conversational GDB debugging interface for Breenix kernel development.

When to Use This Skill

Use this skill when you need interactive, stateful GDB debugging:

• Investigating crashes, page faults, or exceptions
• Stepping through syscall execution
• Examining register state at specific points
• Setting breakpoints and watchpoints
• Analyzing memory contents
• Tracing context switches

Quick Reference

# Start a debug session
breenix-gdb-chat/scripts/start_session.py

# Execute GDB commands
breenix-gdb-chat/scripts/gdb_cmd.py --session SESSION_ID --command "info registers"
breenix-gdb-chat/scripts/gdb_cmd.py --session SESSION_ID -c "break main" -c "continue"

# Stop session
breenix-gdb-chat/scripts/stop_session.py --session SESSION_ID

# List active sessions
breenix-gdb-chat/scripts/list_sessions.py

Workflow Example

Investigating a Page Fault

# 1. Start session
$ breenix-gdb-chat/scripts/start_session.py
{"session_id": "gdb_20251204_151030", "status": "connected"}

# 2. Set breakpoint
$ breenix-gdb-chat/scripts/gdb_cmd.py --session gdb_20251204_151030 \
    --command "break page_fault_handler"
{"success": true, "output": "Breakpoint 1 at 0xffffffff80003450"}

# 3. Continue to breakpoint
$ breenix-gdb-chat/scripts/gdb_cmd.py --session gdb_20251204_151030 \
    --command "continue"
{"success": true, "output": "Breakpoint 1, page_fault_handler()"}

# 4. Check faulting address (CR2)
$ breenix-gdb-chat/scripts/gdb_cmd.py --session gdb_20251204_151030 \
    --command "print/x \$cr2"
{"success": true, "output": "0x0000000000000008"}

# 5. Get backtrace
$ breenix-gdb-chat/scripts/gdb_cmd.py --session gdb_20251204_151030 \
    --command "backtrace"
{"success": true, "output": [{"function": "page_fault_handler", ...}]}

# 6. Check local variables
$ breenix-gdb-chat/scripts/gdb_cmd.py --session gdb_20251204_151030 \
    -c "frame 1" -c "info locals"

# 7. Stop session
$ breenix-gdb-chat/scripts/stop_session.py --session gdb_20251204_151030

Available Commands

Execution Control

Breakpoints

Registers

Memory

Stack & Frames

Kernel-Specific Tips

Page Fault Investigation

--command "print/x \$cr2"     # Faulting address
--command "print/x \$rip"     # Faulting instruction
--command "x/i \$rip"         # Show faulting instruction
--command "backtrace"         # Call stack

Syscall Debugging

--command "break rust_syscall_handler"
--command "continue"
--command "print/x \$rax"     # Syscall number
--command "print/x \$rdi"     # First argument
--command "step"              # Step into handler

Timer/Interrupt Analysis

--command "break timer_interrupt_handler"
--command "continue"
--command "info registers"    # See state at interrupt
--command "finish"            # Complete handler

Context Switch Tracing

--command "break check_need_resched_and_switch"
--command "continue"
--command "info locals"       # See scheduler state

Script Options

start_session.py

--mode uefi|bios    Boot mode (default: uefi)
--timeout SECONDS   Session timeout (default: 300)
--kernel PATH       Kernel binary path (auto-detected)
--debug             Print debug output

gdb_cmd.py

--session ID        Session ID (required)
--command CMD       GDB command (can specify multiple with -c)
--timeout SECONDS   Command timeout (default: 30)
--format json|text  Output format (default: json)

stop_session.py

--session ID        Session ID (required)
--force             Force kill without cleanup

list_sessions.py

--format json|text  Output format (default: json)
--cleanup           Remove dead sessions

Session State

Sessions are stored in /tmp/breenix_gdb_sessions/:

• SESSION_ID.json - Session metadata
• SESSION_ID.log - GDB command log
• SESSION_ID.qemu.log - QEMU output

Troubleshooting

Session not found

# List all sessions
breenix-gdb-chat/scripts/list_sessions.py

# Clean up dead sessions
breenix-gdb-chat/scripts/list_sessions.py --cleanup

# Start fresh session
breenix-gdb-chat/scripts/start_session.py

Command timeout

The target may be hung. Try:

# Force stop and restart
breenix-gdb-chat/scripts/stop_session.py --session ID --force
breenix-gdb-chat/scripts/start_session.py

Cannot connect to QEMU

Check QEMU started correctly:

cat /tmp/breenix_gdb_sessions/SESSION_ID.qemu.log