name: gdb-chat description: Conversational GDB debugging for Breenix kernel. Use for interactive debugging sessions - set breakpoints, inspect registers, examine memory, step through code, investigate crashes.

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