A build, itemised
You will learn
Every stage from a spec to a bitstream, with its time, tool and hash.
A whole build from a t27 spec to an Artix-7 bitstream, written out like a shop receipt: each stage, the tool and its version, the time it took, and the sha256 of what it wrote. No Vivado anywhere. When a number on a receipt can be checked, anyone can rebuild it and compare the hash.
Try it
Read the receipt: which stage took the longest, and which tool ran it? In the spec frame, RECEIPT_KINDS names two kinds of receipt: which one is the build alone, and which entry in ERRORS catches it posing as the other?

One real open-flow build itemised like a shop receipt: each stage from a t27 spec to an Artix-7 200T bitstream with its time, tool version, output size and sha256.
specs/fpga/adapter.t27
// SPDX-License-Identifier: Apache-2.0
; specs/fpga/adapter.t27 -- the FPGA adapter contract: how a bitstream travels from a
; build record to a device run and back as a receipt. S11 of gHashTag/trinity#988
; (gHashTag/t27#3573, dmitrii-f-t27/trinity-memory#66). Two laws from #3573 hold the
; whole contract: no hardware run may be inferred from synthesis, and physical
; acceptance is tied to a recorded device and transcript. The tool that enforces it
; is tools/trinity_fpga_adapter.py (check / --self-check); the receipts it checks
; live in conformance/trinity/fpga_adapter.json. ASCII only (L3), English only (LANG-EN).
; phi^2 + 1/phi^2 = 3 | TRINITY
module trinity_fpga_adapter;
pub const KIND : str = "spec";
pub const VERSION : str = "1";
; The receipt schema this contract version emits and accepts.
pub const RECEIPT_SCHEMA : str = "trinity.fpga-receipt.v1";
; A receipt is exactly one of: a build-only record (nothing touched a device) or a
; device record (a board ran and a transcript exists). No third kind, no defaults.
pub const RECEIPT_KINDS : [2]str = ["dry_run", "device"];
; ---- Inputs (what a caller must bring) -------------------------------------
; bitstream_path: a file path. bitstream_sha256: the hex sha256 of that file's
; bytes, checked before anything else. provenance: the build record -- commit,
; tool versions (yosys, nextpnr-xilinx, prjxray image), the routed Fmax verdict.
; board identity: the device's IDCODE under the rule below, DNA when read.
; The IDCODE rule: the full 32-bit value, high nibble included (0x13636093 for the
; Artix-7 XC7A200T of the AX7203 bench). openFPGALoader prints it without the
; revision nibble (0x3636093); a receipt records BOTH forms once, and every later
; comparison uses the full value, so a masked match can never pass for identity.
pub const IDCODE_FULL : str = "0x13636093";
pub const IDCODE_PRINTED : str = "0x3636093";
pub const BOARD : str = "alinx_ax7203";
pub const PART : str = "xc7a200tfbg484-2";
; ---- Configuration ---------------------------------------------------------
; flasher: the program that writes the device. The bench's is openFPGALoader
; (-c digilent_hs2, SRAM by default); trinity-fpga's openocd path is a legal
; second value once a receipt exercises it. cable: the JTAG adapter. target:
; "sram" (volatile, the bench default) or "flash" (persistent).
pub const FLASHERS : [2]str = ["openFPGALoader", "openocd"];
pub const CABLE : str = "digilent_hs2";
pub const TARGETS : [2]str = ["sram", "flash"];
; ---- Errors (distinct, one status each; no error is a prefix of another) ----
pub const ERRORS : [8]str = ["wrong_version", "hash_mismatch", "bitstream_absent",
"bitstream_empty", "placeholder_command", "idcode_mismatch",
"transcript_missing", "dry_run_as_device"];
; wrong_version the receipt's schema is not RECEIPT_SCHEMA of contract VERSION
; hash_mismatch the bitstream's sha256 is not the provenance's
; bitstream_absent the bitstream path names no file
; bitstream_empty the file exists and holds zero bytes
; placeholder_command the flasher line is a placeholder ("" or "TBD" or "<...>")
; idcode_mismatch the device's full IDCODE is not the receipt's recorded one
; transcript_missing a device receipt with no transcript hash / empty transcript
; dry_run_as_device a build-only record carrying a hardware result line
; ---- Receipt ---------------------------------------------------------------
; Every device receipt carries: the bitstream sha256, the full IDCODE, DNA when
; read, the transcript sha256, the result line ("HW RESULT: N/M bit-exact" for
; exact comparisons; counters for measurements), the captured UTC time and the
; tool versions. A dry_run receipt carries the build half and an explicit
; "hardware": false; it must NOT contain a hardware result line. The receipt is
; the only currency of evidence: a claim without one is a plan, not a result.
; ---- Device results of this stage (the receipts' sources) ------------------
; dmitrii-f-t27/trinity-memory: reports/fpga/matvec-capture-2026-09-27-m6d5-golden.json
; (dense5, 320/320 bit-exact), ...-golden-b2.json (baseline2, 320/320),
; ddr3-matvec-measure-2026-09-27-{d5,b2}.json (12 runs each), and the #61 pattern
; capture. conformance/trinity/fpga_adapter.json embeds them; the tool checks.
fn error_count() -> u32 {
return 8;
}
test error_codes_are_distinct {
// The eight statuses are pairwise distinct strings by construction of the
// ERRORS table; the count is what the tool's self-check plants one by one.
assert_eq(error_count(), 8);
}
// The printed form is the full form without its revision nibble; a receipt
// that recorded only the printed form could pass a masked comparison. The
// rule is arithmetic, not stringly: full == printed + 0x10000000.
fn idcode_full_of(printed: u32) -> u32 {
return printed + 268435456;
}
test idcode_rule_records_both_forms {
assert_eq(idcode_full_of(0x3636093), 0x13636093);
assert_eq(idcode_full_of(0x3636093) & 0xF0000000, 0x10000000);
}
fn receipt_kind_count() -> u32 {
return 2;
}
test receipt_kinds_exhaustive {
assert_eq(receipt_kind_count(), 2);
}
endmodule
All lessons
Module 1 · The chip
What an FPGA is, which chip we use, and how its pins meet the board.
Module 2 · Numbers in hardware
Bits, trits and number formats, and what arithmetic costs in logic.
Module 3 · Your t27 program
Write a spec, test it, and see why compiling is not the same as being right.
Module 4 · Inside t27c
How the compiler reads a spec and what it writes, including the native t27b.
Module 5 · From spec to hardware
The Verilog t27c writes, the cells it becomes, and what one LUT does.
Module 6 · Reading synthesis
What yosys reports about your design, and which warnings matter.
Module 7 · Place, route, timing
Where the cells land on the die, and whether the clock is met.
Module 8 · The bitstream
How a routed design becomes the bits the chip loads, with no Vivado.
Module 9 · On the board
Ask the chip who it is, load the bits, and check them.