testdata: the reference chain's frames as gold standards, with a check

[hansfbaier]

This adds what you asked for in #47 after the revert in #48 — the reference chain's frames as "gold standard", and a check that fpga-as matches them.

It does not re-apply #47, because main still carries it: the tip is e394738 and fpga/injected-features.cc is present, so #48's revert is not in effect.

What's here

fpga/xilinx/testdata/reference-parity/ — one directory per case with input.fasm and, where the reference assembles it, gold.frames (the frames fasm2frames produced, canonicalised to the frames that set a bit):

case	part	what it pins down
01 missing feature	xc7a35tfgg484-2	an undefined feature must fail with a message, not terminate the process
02 zynq7 required features	xc7z010clg400-1	the part's required_features.fasm must be emitted
03 PUDC_B pull-up	xc7a35tcsg324-1	the pull-up is injected only with --emit_pudc_b_pullup
04 83-bit value	xc7a35tfgg484-2	a value on a range wider than 64 bits resolves correctly
06 pseudo PIP on an aliased tile	xc7k325tffg900-2	looked up in the tile's own database, and a no-op rather than a crash

check.sh runs fpga-as on each input with the same database and compares the configuration bits (FPGA_AS=... check.sh). Measured:

• with the assembler at e394738 (main): 5 pass, 0 fail;
• with the assembler built from b234841 (before Reproduce the reference implementation's output #47): 5 fail — 01 aborts on the undefined feature, the other four exit non-zero or disagree.

The whole sweep, which is what set these cases: of the 21 demo-projects designs that carry a .fasm, the pre-fix build produced a different configuration for 19 and no bitstream for 2; the fixed build is frame-identical to the reference on all 20 the reference can assemble (the 21st hits a database gap the reference hits too).

The raw evidence — failed bitstreams, payload byte diffs between the two builds, all three stderr streams, and the one case that still disagrees with the reference — is here: https://gist.github.com/hansfbaier/20a7b7da75d2bf8fc28ad92936d620e2.

Two notes

• The database is not committed (hundreds of MB), so the check reads PRJXRAY_DB_DIR and reports skipped without it.
• It is a script, not a bazel test: Bazel 9 has no native sh_test and @rules_shell is not in this module graph. If you want it running in CI, either a workflow step with the toolchain devshell, or a rules_shell dependency — your call, and I will wire whichever you prefer. That also covers @hzeller's test/smoke-tests.sh idea, which would then be this check plus downloading the corpus at a pinned demo-projects revision.

[hansfbaier]

While this PR's CI ran I went through the four failures, and three of them are main's rather than this PR's. The workflow history is the clearest evidence:

when	commit on main	ci
11:36	Move the injected configuration out of assembler.cc (#47)	failure
11:47	Revert "Reproduce the reference implementation's output" (#48)	success
11:56	Move the injected configuration out of assembler.cc (again)	failure
12:23	ci: clang-tidy --fix	failure

So main has been red since 11:56, and the failures in my run are the same ones:

• fpga/injected-features.cc:139/142/147 — absl::StrFormat with a runtime format string. Newer absl marks that overload unavailable, so MacOsBuild fails to compile the file and ClangTidy reports it as an error. This one is Reproduce the reference implementation's output #47's, and c90290e in this PR fixes it (absl::Substitute with $0/$1): with and without --emit_pudc_b_pullup the frames are identical to the binary built from main, and the reference-parity check passes 5/5.
• fpga/xilinx/bitstream-reader.h:108/117 — gcc-13 cannot compare an iterator with the std::ranges::subrange that std::ranges::search returns (fails Test), and treefmt wants the file reflowed (fails NixCheck). That file's last change is 11f3fc3 (March 2025) and Reproduce the reference implementation's output #47 never touched it.

If you want, I will fix those two in a separate commit here — the bitstream-reader.h one is small (compare against the subrange's begin()), the other is running the repo's formatter over it — or leave them to a dedicated PR, since neither belongs to this one.

[hansfbaier]

CI is green on 4d75e90 — ClangTidy, MacOsBuild, Test and NixCheck all pass.

Since the PR grew well past the original "gold standard" ask, here is what it actually carries:

commit	what
9b8b9b8	fpga/xilinx/testdata/reference-parity/ — inputs, the reference's frames, and check.sh: 5 cases, 5 pass against this tree and 5 fail against the assembler built from b234841
d77cbc5	injected-features.cc: the PUDC_B templates go through absl::Substitute — the runtime format string was a hard error for MacOsBuild and clang-tidy
4977f56	bitstream-reader.h: compare against the subrange iterators the clang-tidy --fix rewrite (957dafc) requires
0aab4b2	run clang-format over assembler.cc, database.cc, database-parsers.cc, arch-xc7-configuration-packet_test.cc — treefmt rejected them
6968bf0	drop the unused <optional>, and make the PUDC_B template literals raw strings so bugprone-suspicious-missing-comma stops reading a split literal as a missing comma
4d75e90	drop the const that blocked the automatic move in assembler.cc, and include absl/types/optional.h in configuration.h

main (957dafc) is still red for the same reasons — merging this should turn it green. Nothing here re-applies #47; main already carries it, and the revert in #48 is not in effect.