nx_gdbstub.nx

nx_gdbstub.nx -- GDB REMOTE SERIAL PROTOCOL stub over the sovereign RV64 emulator (rv64im_min_sim). THE RUNG: /compare/nishios NO1 "GDB remote-serial stub", watch symbol gdbstub_serve (ver 0.1 N0, ranked #1 2026-08-23). Its accept rule is an EXTERNAL ORACLE: a STOCK gdb attaches to a guest running on our emulator, breaks at an address our own decoder resolved, steps, reads a register whose value an independent sim run derived, and detaches leaving the guest running -- plus the negative control that a breakpoint at a never-executed address does NOT stop. That oracle lives in nx_gdbstub_gate (gdb-multiarch in batch mode); this file is the stub it attaches to. WHAT IT SPEAKS (GDB Remote Serial Protocol, the subset a stock gdb needs for a bare-metal target): framing $<payload>#<2-hex checksum>, '+'/'-' acks until QStartNoAckMode, 0x03 = interrupt qSupported PacketSize + QStartNoAckMode + qXfer:features:read (we SERVE target.xml, so gdb never has to guess the register file: riscv:rv64, x0..x31 + pc, 64-bit) ? g G p P m M Z0 z0 s c D k vKill H T qC qAttached qfThreadInfo qsThreadInfo stop replies: S05 (trap: breakpoint or single-step), S02 (interrupted by 0x03), W<code> (guest halted through the finisher / exit ecall), X04 (illegal instruction) everything else answers the empty packet, which is the protocol's "unsupported" and makes gdb fall back (X -> M, vCont -> s/c) rather than fail. WHAT IT DELIBERATELY DOES NOT DO: - memory packets (m/M) touch RAM ONLY (mem_base..mem_base+mem_size): a debugger read of device MMIO would run the device model's side effects (a UART read clears state), and a debugger must not change what it observes. Device windows answer E14. Addresses are translated through the sim's own nx_rv64im_xlate, so in S/U-mode under Sv39 gdb sees the guest's virtual space, same as the guest does; a walk fault answers E14 and the fault flag is cleared, never left for the guest. (Documented imprecision: the sim's xlate sets the PTE A bit on a successful walk, so an S/U-mode 'm' read can set A on a page the guest had not yet touched.) - no RLE in replies, no binary X writes, no threads beyond the one hart (qC/H answer thread 1). SIZES ARE DERIVED, NOT PICKED: GDB_G_HEX = (NX_RV64IM_RF_N_REGS + 1 pc) * (NX_RV64IM_RF_WIDTH / 4) hex chars = the 'g' reply GDB_PACKETSIZE (advertised) = GDB_G_HEX: gdb bounds every m/M/qXfer chunk by this, so a reply never exceeds the 'g' reply and a request payload never exceeds it either. GDB_BUF = 2*GDB_PACKETSIZE + framing: payload bound + command prefix (shorter than a payload by construction) + '$' '#' and two checksum chars. breakpoints = a BITMAP over RAM, one bit per halfword (the RVC granularity), sized from sim.mem_size -- no breakpoint cap to guess, O(1) test in the hot step loop. GDB_POLL_STEPS = the step count between interrupt polls while continuing, = one millisecond at the 20 MIPS interpreted rate nishios.plan publishes, so Ctrl-C latency is bounded to ~1 ms without a syscall per step.