gdb-debugging - SKILL.md Agent Skill

name: gdb-debugging description: Guide for debugging Nanvix guests using GDB remote debugging over the microvm machine type. Use this when asked about attaching GDB, setting breakpoints, or stepping through kernel code.

GDB Debugging Nanvix

Use this skill when the user asks about debugging the Nanvix kernel or guest applications using GDB. Refer to doc/gdb.md for the user-facing documentation.

Prerequisites

Nanvix built in standalone mode (DEPLOYMENT_MODE=standalone). The standalone feature automatically enables the gdb Cargo feature in nanvixd and nanvix-bench. At the crate level, the gdb feature requires microvm (enforced via feature dependency).
A GDB client with x86_64 target support (gdb-multiarch or x86_64-elf-gdb).

Build

./z build -- all DEPLOYMENT_MODE=standalone

Launch

Through nanvixd (preferred):

RUST_LOG=info ./bin/nanvixd.elf -gdb-port 1234 -- ./bin/hello-rust-nostd.elf

Through uservm directly:

RUST_LOG=info ./bin/uservm.elf \
    -kernel ./bin/kernel.elf \
    -initrd ./bin/hello-rust-nostd.elf \
    -standalone -gdb-port 1234

The guest halts at its first instruction until a GDB client connects.

Connect

gdb-multiarch ./bin/kernel.elf
(gdb) target remote :1234
(gdb) break _start
(gdb) continue

A ready-to-use .gdbinit exists at the repository root and is loaded automatically when GDB is launched from the project directory.

GDB Command Reference

Operation	Command	Notes
Read registers	`info registers`	All GPRs, RIP, RFLAGS, segments
Write registers	`set $rax = 0x42`	Any general-purpose register
Read memory	`x/16xb 0x1000`	Guest physical memory
Write memory	`set {int}0x1000 = 1`	Guest physical memory
Software breakpoint	`break *0x1000`	INT3-based
Remove breakpoint	`delete 1`	Restores original instruction byte
Single step	`stepi`	One instruction
Continue	`continue`	Resume until next event
Backtrace	`bt`	Requires symbols
Disassemble	`disas`	At current RIP

Common Workflows

Kernel crash

(gdb) continue
# ... guest crashes ...
(gdb) bt
(gdb) info registers
(gdb) x/10i $rip

Stepping through boot

(gdb) stepi
(gdb) info registers

Breaking on a function

(gdb) break kmain
(gdb) continue

Troubleshooting

Problem	Cause / Fix
GDB cannot connect	Port in use (`ss -tlnp \| grep 1234`), or VM not started
	with `-gdb-port`.
"Remote connection closed"	Guest exited before GDB connected. Check VM stderr.
Breakpoints not hit	Address mismatch — kernel uses identity mapping
	(GVA == GPA). Verify symbol file: `file ./bin/kernel.elf`.
Memory access returns zeros	Address outside guest memory region
	(`config::kernel::MEMORY_SIZE`).

Limitations

Linux only. GDB debugging requires the microvm machine type with KVM, which is not available on Windows. The WHP backend does not expose a GDB server.
Standalone mode only. -gdb-port requires DEPLOYMENT_MODE=standalone.
Physical addresses only. The kernel uses identity mapping (GVA == GPA).
No hardware breakpoints. Only software breakpoints (INT3).
Single vCPU. Single-threaded debugging model.
Ctrl+C latency. The break-in signal is processed at the next vCPU exit (e.g., port I/O), not asynchronously during pure guest computation. In practice this is near-instant because the Nanvix guest performs frequent I/O.

Architecture Notes

GDB server uses the gdbstub crate (v0.7), feature-gated behind gdb.
Server runs synchronously in the vCPU thread (KVM register ioctls are thread-specific).
Software breakpoints patch guest memory with INT3 (0xCC); KVM delivers VcpuExit::Debug.
The gdb feature is enabled by the standalone feature in nanvixd and nanvix-bench. At the crate level, gdb requires microvm (enforced via feature dependency). The -gdb-port flag is validated at runtime to require -standalone mode.