nanvix/gdb-debugging

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.