gdb-chat

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

Command	Description
continue / c	Continue execution
step / s	Step one source line
stepi / si	Step one instruction
next / n	Step over function calls
nexti / ni	Step over one instruction
finish	Run until function returns

Breakpoints

Command	Description
break LOCATION	Set breakpoint (function, file:line, *address)
hbreak LOCATION	Hardware breakpoint (works before paging)
tbreak LOCATION	Temporary breakpoint (deletes after hit)
watch EXPR	Break when memory is written
rwatch EXPR	Break when memory is read
info breakpoints	List all breakpoints
delete N	Delete breakpoint N

Registers

Command	Description
info registers	Show general-purpose registers
print/x $REG	Show specific register (e.g., $rip, $rax)
print/x $cr2	Page fault address
print/x $cr3	Current page table
show-segments	Show segment registers (custom)
show-control	Show control registers (custom)

Memory

Command	Description
x/Nxg ADDR	Examine N 8-byte values at ADDR
x/Nxw ADDR	Examine N 4-byte values
x/Ni ADDR	Disassemble N instructions
x/s ADDR	Show string at ADDR
disassemble	Disassemble current function
disassemble FUNC	Disassemble specific function

Stack & Frames

Command	Description
backtrace / bt	Show call stack
backtrace full	Show stack with locals
frame N	Select frame N
info locals	Show local variables
info args	Show function arguments

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