589 -> 602 lines but 42% -> 13% comment-only: the prose shrank by two thirds
while the structure and the docstrings grew. The module docstring now carries
the usage, both timing targets, the per-seed build layout and every environment
variable in one place.
SIX of the comments here were not merely verbose, they were WRONG, and three of
them described hardware behaviour that had been replaced:
* MISO was described in three places as leaving on the FALLING edge with the
path having to fit a HALF period (18.5 ns). It has not worked that way
since the full-cycle-early launch: NEG_TRIGGER=0 keeps the IO register on
the RISING edge and the bit is launched one edge before the host samples
it, so the budget is a FULL period. The >12 ns warning text said the same
wrong thing to anyone who tripped it.
* The MISO clock-to-pad parse had no note saying it is EXPECTED to find
nothing. "IOB (none)" is the good case -- a number there means the output
has regressed into the fabric -- and only the summary printer said so.
* Two comments sat adjacent at the ranking site giving DIFFERENT rules: one
said rank by worst relative fmax margin, the next said rank by smallest
MISO delay. The code does MISO first and falls back to margin; the
docstring now says that once.
* "~22% LC utilisation" -- it is ~81%, which inverts the point being made
(routing dominates because the part is FULL, not because it is empty).
* "the final artefact in build/top.bin is the result of the last (or best)
seed" was contradicted 150 lines later by "There is no top-level
build/top.bin". The latter is true.
* A comment described `results` as 4-tuples; the code appends 5.
Structure: the 240-line __main__ is now main() over _udp_config,
_make_dut_factory, _build_seed, _parse_timing, _score, _run_sweep and
_print_summary. elaborate() delegates to _drive_miso and
_drive_status_panel. Each keeps the reasoning that belongs to it -- why a
fresh platform and a separate build dir per seed (both were real mis-scoring
bugs), why the post-route number is the last occurrence, why an unparseable
seed must never be ranked.
Cut: the pin-35/PLL history, which ends in a conclusion that is all that
matters now (ETH_INT is on pin 13 because the board is built that way); the
reverted router-options experiment, down to one line; and a duplicated
paragraph about the clock constraint, plus a duplicate `import os`.
VERIFIED EQUIVALENT, not just tested:
* Generated RTLIL is identical across all 30659 lines after stripping the
\src source-location attributes -- those 44 lines are the only diff, so
the hardware is provably unchanged.
* The ranking logic was differential-tested against the old algorithm
transcribed verbatim: 4000 randomised sweeps including unparseable seeds
and the best_miso/best_score interaction, 0 mismatches.
* A real build of seed 1 reports clk 27.62 / exi 59.47 MHz, matching the
pre-refactor sweep's seed 1 exactly.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Roflin
b5961d0731