First file of the documentation cleanup. Comments 403 -> 83 lines (46% ->
12% of the module), total 1563 -> 1266, with the real documentation moved into
structured docstrings instead of inline prose.
What went:
* every account of how a bug was found, what it looked like on a console,
and which fix attempts were falsified -- all of that lives in CLAUDE.md
* every description of how Swiss or libogc is written internally; the file
now documents what the GATEWAY does and what a host observes, not how any
particular host is implemented. Zero occurrences of Swiss/libogc/gcif
remain, in comments, docstrings, helper names or test output
* the module docstring, which still described the GUESSED header format
(addr[12:6] plus a 2-bit length field) replaced long ago
What arrived:
* a register table giving each address its name AND its purpose, bit
meanings included (NCRA reset/ST0/ST1/SR, IR's RI/TI/RBFI, the page
pointers, which side owns RWP vs RRP)
* a command-register section, likewise
* named IR/IMR and NCRB bit constants instead of bare indices
* a class docstring grouping the ports into EXI stream / ethernet side /
register taps / events
* an FSM docstring listing all 13 states in visit order with what each one
is for, and the invariant that every data phase ends on ~cs_active
Structure: elaborate() is now a table of contents -- _make_fifos,
_make_registers, _register_taps, _interrupts, _read_mux, _transaction_fsm,
_spram_responses, _command_write, _ethernet_events -- with register storage,
transaction state and the FIFOs passed as three namespaces so each block's
inputs are visible. The register write decode is its own method rather than
80 lines nested inside a state.
Dead code removed: sp_req, byte_ctr, drain_ctr, SP_LIMIT and _DEVICE_ID were
all write-only or declaration-only.
Behaviour preserved, checked four ways: all 15 module tests pass, the full
module suite passes, bba_top passes at EXI_HALF=1/2/8, and the hardware is
materially identical -- flip-flops exactly equal (1177 SB_DFFE, 671 SB_CARRY),
RAM/IO/global buffers unchanged, ICESTORM_LC 4350 -> 4380 (+0.7%). That rise
is the read mux: its Switch cases are now in address order, which changes how
the mux tree maps. All cases are distinct constants so the decode is
semantically identical.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Roflin
b175cb0e77