majiayu000 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 metadataSESSION_ID.log- GDB command logSESSION_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