T27.AI

Blog

The back half of openXC7, from a spec: FASM to frames to bitstream

2026-10-03 · 8 min read

[one design on one board, equivalence not a better bitstream; timings on one busy laptop, ratios are rough; the fpga-assembler speed figure is its README's, not ours] openXC7 turns FASM into a Xilinx 7-series bitstream with two prjxray tools, fasm2frames in Python and xc7frames2bit in C++. We rebuilt that half so every bit position, frame address and packet word comes from three t27 specs. Against the two tools it matches byte for byte on 22 of 22 FASM files and 16 of 16 frame files, and it is about 6 to 14 times faster on small real designs, about 85 times on a 121,587-line one, and up to about 200 times on synthetic test files. The comparison found a silent bit-wrap in fasm2frames (f4pga/prjxray#2574), a missing part check in xc7frames2bit (#2573), and a bug of our own on kintex7. On an AX7203 board (XC7A200T), a .bit written this way for a 121,587-line design was byte-identical to openXC7's, loaded into SRAM, and returned 403,200 of 403,200 tagged receipts.

openXC7 builds a Xilinx 7-series bitstream in two halves. The first half is yosys and nextpnr: Verilog in, FASM out. FASM is a text list of features such as CLBLM_R_X3Y0.SLICEM_X0.ALUT.INIT[63:0] = 64'h.... The second half turns that list into a bitstream. prjxray's fasm2frames (Python) looks up every feature's bits and writes configuration frames, and xc7frames2bit (C++) wraps the frames in configuration packets. We rewrote the second half so that every bit position, frame address and packet word comes from a t27 spec, and compared it byte for byte with the two tools it replaces.

What the specs hold

• packets.t27: the configuration packet stream. Headers, registers, commands, the CRC and the write sequence xc7frames2bit uses.
• far.t27: the frame address walk for xc7a35t, xc7a100t and xc7a200t, with the part picked by IDCODE.
• frames.t27: the frame ECC, and where a database bit lands in a frame. That covers the tile's word offset, the alias shift of a *_SING tile, a tile that starts below its frame, and what happens to a bit that falls outside.

The driver, bitwalk, is Rust. t27c gen-rust generates its rule functions from these specs. The FASM grammar, the feature lookup, file I/O and the text output are written by hand; the bit arithmetic is not. Each spec section cites the prjxray file and line it reproduces (prjxray c9f02d857, prjxray-db 517d66a).

Measured

The mutation gate earned its place again while this post was being written. Adding kintex7 support changed how the driver counts bits outside a tile, and one seeded defect survived: a tile window one word too long. The spec tests caught it, but the corpus sweep did not, because the new count absorbed exactly the bit the defect moved. The count is now split in two, so a tile that starts inside its frame can never have its own bits outside it, and the defect is caught again.

Speed

The synthetic files are no longer than a real design, about 1,100 lines against 1,785, yet fasm2frames takes 12 to 45 times longer on them. We have not profiled why, so we make no claim about the cause. We also re-timed fasm2frames on three files at the same load as our runs: 3.4 s, 32.5 s and 104.4 s, which makes the ratios larger, not smaller. The figure keeps the lower ones.

What else does this job

Found on the way

A differential is only useful when the two sides disagree. Three times they did, and each time the tool we compared against had the defect.

• fasm2frames does not refuse a feature of a site that a *_SING tile lacks. On a bottom SING tile the bits wrap into words 99-100 of the frame, which belong to another tile. On a top SING tile they are dropped. The exit code is 0 in both cases, and one line of FASM reproduces it. Reported as f4pga/prjxray#2574. The same happens on kintex7: one synthetic file has 337 wrapped and 356 dropped bits. bitwalk writes the same bytes by default, which is why the 22/22 above holds; --strict refuses the file and names the line.
• xc7frames2bit accepts frames for the wrong part: xc7a100t frames with an xc7a200t part exit 0 and write 192 extra frames. bitwalk refuses them. Reported in f4pga/prjxray#2573, with fixes in openXC7/prjxray#27 and #28.
• In case 05 of lromor/fpga-assembler#49, the 83-bit RXCDR_CFG value, fpga-assembler's own frames differ from the reference: 18 bits missing, 5 extra. bitwalk matches the reference. Our reading of the source: the parser packs a long binary literal into 64-bit words from its most significant end, so for 83 bits the first word holds only the low 19 bits. Emulating that packing gives exactly the 18 missing and 5 extra bits.

One defect was ours. The kintex7 tile grid has four tiles that start 2 words below their frame, and our driver read the offset as unsigned and stopped. The spec now says how such a tile's bits are placed (seg_shift), with a test.

On the board

Files that match are a claim about files. To check the chain on hardware we built one real design for the ALINX AX7203 (XC7A200T): trinet node 0, 121,587 FASM lines, 20,230 frames. On that FASM bitwalk was again byte-identical to openXC7 for both the frames and the .bit, and took about 0.8 s where fasm2frames took about 68 s, on a host that was busy the whole time. openFPGALoader then loaded bitwalk's .bit into SRAM over JTAG, with no flash write, and the FPGA reported DONE.

tri x7-board · t27 back half on the AX7203

Because the two .bit files are identical, this shows nothing the openXC7 file would not have shown. The claim is equivalence on one design on one board, not a better bitstream. The front half, yosys and nextpnr-xilinx, is openXC7's and unchanged.

What this does not show

• One design has run on a board. Every other check above compares files.
• Apart from the board design, no xc7a200t FASM is in the corpus, and there is no Vivado reference for xc7a100t or xc7a200t. There, byte-identical means identical to the prjxray tools, not to Vivado.
• The rule for a tile that starts below its frame is covered by spec tests only. No database bit reaches those kintex7 tiles, so the corpus cannot exercise it.
• The FASM grammar and feature lookup are hand-written Rust, checked by the corpus rather than derived from a spec.

Work with me

Want this kind of check on your own design?

I audit RTL and build independent, bit-exact models, then take the result through synthesis and, when useful, onto an Artix-7 board. The first conformance module is free.

Discuss your projectSee the verification service