contrib: device-file connectivity + decode-or-refuse codecs (Cyclone IV E)

[labeth]

What this is

A contrib/devfile-connectivity/ directory adding a device-file-derived approach to Cyclone IV E bitstream RE, meant to complement this repo's existing fuzzing / CRAM-codec / FASM↔RBF toolkit. Instead of learning bits purely by fuzzing, it parses the Quartus device files (.ddb) and harvests the assembler's own resolved setting↔bit model (via the decompiled reader plus a gdb intercept of the emitter), then inverts that model into a decoder.

What's included (device-general, cycloneive1, EP4CE6 / EP4CE10)

• DYGR route-asm static connectivity parser — whole-device {src_node → dest_node : bits} routing table from ddb_cycloneive1_asm.ddb + the routing pool.
• Routing node lattices C4 / R4 / R24 / C16 + a node→class map.
• CFF / flat-offset → rbf serialization map (plus the log-space gdb sweep method that recovers it).
• Coordinate reconciliation — routing (X,Y) == LUT / IOE (X,Y), same origin.
• Compiler-model-extraction method — harvest the assembler's resolved ASMDB tables and invert them (an alternative to re-deriving the opaque enum-keyed format).
• LUT codec — validated 42/42 against this repo's own golden_rbf_modeH sweep.
• LE/LAB, PLL/M9K, IOE config codecs; a decode-or-refuse decoder + flat↔rbf helper.
• A per-item README.md with provenance, validation, and how each piece composes with bitstream.py / the route-synth / fasm2rbf stages.

How it's validated

Bit-exact round-trip plus held-out checks (leave-one-compile-out and separate independent compiles). The connectivity table reproduces live-trace oracle arcs and predicts held-out arcs bit-exact; the LUT codec matches golden_rbf_modeH 42/42.

Honest limitations — please read before relying on this

• Coverage is partial; this is not a complete solve. On a foreign EP4CE10 production bitstream it decodes routing + LUT masks + IO + partial config, but LUT-to-LUT interior logic connectivity is not recovered. There is a proven wall: the disambiguating per-mux fanout templates land in a serialization region we did not crack, and the routing select codewords are ambiguous without them (shared across ~4 source nodes). So you get a connected routing/interconnect graph, not a full logic netlist.
• Config-plane (aux/CFF) coverage is partial — the serialization map is solved, but only a small config surface is realized for a real design.
• decode-or-refuse by design. It refuses anything it can't reproduce bit-exact, so it never bluffs — but it leaves unrecovered bits explicitly unowned rather than guessing them. On the target used for validation, overall coverage was ~1/3 of programmed bits.
• Large materialized tables (~60–100 MB) are NOT committed — regenerate with the included build_connectivity.py (matches this repo's gitignore convention).
• Provenance: derived by parsing and instrumenting the Quartus device files and their decompiled reader (standard device-file RE). The validation target was a proprietary vendor bitstream; all target-specific names and local paths have been genericized out of this contribution.
• AI-assisted: this was produced with heavy automated assistance (Claude Code). Every claim above is backed by a bit-exact round-trip or held-out check in the deliverables; nothing is asserted that wasn't measured.

Happy to restructure, rename, or split this to fit the repo's conventions — treat it as a starting point, not a finished drop-in.

🤖 Generated with Claude Code

https://claude.ai/code/session_01M3kmuqhMGWmWivDarkD8Vj