Module gdb 

GDB-driven trace capture for anchor debugger --gdb.

Alternative to the register-tracing-file path. Each test thread’s VM blocks on a per-thread TCP port (sbpf’s built-in gdb stub, activated via the debugger feature on solana-sbpf). We drive the stub over the GDB Remote Serial Protocol, single-stepping each invocation while reading the full register set (including the pseudo-register at index 12 that the sbpf target exposes as InstructionCountRemaining — compute-unit remaining at each step).

Files are written into the same <profile_dir>/<test>/NNNN__txK.{regs, insns,program_id,cu} layout TestNameCallback produces, so the existing arena + TUI code consumes them unchanged. The only new artifact is .cu — 8 bytes per step, the VM’s cu_remaining value read via the gdb stub’s register 12.

CPI handling

Each CPI frame constructs its own EbpfVm, which reads VM_DEBUG_PORT and binds another listener on the same port (sbpf drops its listener after accept(), so re-entrance is fine). The client side has to notice that a step command on the outer connection is taking longer than expected, open a second TCP connection to the same port, and drive the inner session to completion — then the outer step reply arrives, stepping continues. This mirrors the actual sbpf/agave call stack: outer step → CPI syscall → inner VM exec → return → outer step reply.

Structs

GdbDriver

Owns the UDS listener at <profile_dir>/gdb.sock and the accept thread that spawns one driver thread per VM announcement. Drop signals stop, joins the accept thread, and removes the socket.

Constants

SOCKET_ENV

Env var the gdb driver and the test process use to rendezvous on the announce socket. Single source of truth — both the driver (std::env::set_var) and anchor-v2-testing (which reads it) must use this name.

Functions

run_gdb_mode

Loose-mode entry point. Stands up the driver, then runs cargo test with ANCHOR_GDB_SOCKET and --test-threads=1.

start_gdb_driver

Bind the UDS listener and spawn the accept thread. Caller is responsible for setting ANCHOR_GDB_SOCKET in the env of whatever test process consumes the socket.