Files
psxrecomp/tools
Matthew Stanley 0c4dd2db85 docs(tcp): generate the command index; fix six wrong entries
TCP_COMMANDS.md instructed contributors to "update this file" on every new
handler. It described 47 commands while the two debug servers registered 292
between them (279 native + 61 Beetle, overlapping) -- 15% coverage. A
hand-maintained inventory that size does not stay correct, and a stale
reference is worse than none because people trust it.

New tools/gen_tcp_commands.py parses the s_commands[] (native) and CMDS[]
(Beetle) tables and regenerates a complete index between AUTOGEN markers,
marking which commands the curated prose already covers. The hand-written
"Command inventory" table is untouched -- it carries parameters and context
worth keeping. `--check` exits non-zero when the block drifts, so this can gate
CI; verified it fails on a simulated added handler and passes once regenerated.

Corrections to the curated table, each verified against the code first:

  write_ram       params are `addr`,`val` -- not `addr`,`hex` -- and it writes
                  exactly one byte per call (handle_write_ram)
  screenshot      writes a PNG (psx_screenshot.png), not a 24-bit BMP
                  (debug_server.c:7666,7856)
  wtrace_range    ring holds 262144 entries (WRITE_TRACE_CAP, 1<<18), not 1024
                  -- the documented figure was 256x too small
  sljit_async     row removed; the command is not registered anywhere (the
                  sljit tier was removed 2026-07-15)
  pause/continue/step/run_to_frame
                  documented as working. All four are registered but
                  unconditionally return an error (debug_server.c:7324-7342);
                  they were deliberately removed in favour of ring-buffer
                  queries. Marked REMOVED with the replacement each error
                  message names.

Also corrected the header: it presented DuckStation (port 4371) as one of the
two live servers, though DuckStation was retired as the oracle on 2026-05-05
and has no .gitmodules entry, while the page's own CLI examples already used
Beetle on 4380. The live pair is now Native 4370 / Beetle 4380, with a note
that the inventory's "D" column is historical, and the "add a handler" checklist
now points at beetle_debug_server.c and the generator instead of DuckStation.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-27 11:49:31 -07:00
..