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

gdb-chat

Install Skill

SKILL.md