Blog
Course 3: verifying hardware with t27, in 27 lessons
[the browser runner cannot execute testbench test blocks yet (trinity#1477); three lesson specs were swapped for clean siblings; specs/fpga/coverage.t27 lands in gHashTag/t27 separately] The fourth t27 course answers the question the other three left open: how do you know the design works? 27 lessons in 9 modules of 3 -- testbenches, waveforms, vectors, cosimulation, coverage, formal, mutation, sign-off -- each opening one working widget and one t27 spec, with every number on the page measured by the widget it sits beside.
Course 3 is live: Verifying hardware with t27, 27 lessons in 9 modules of 3, and like its three siblings every lesson opens one working widget and one t27 spec the reader can run in the player. Course 1 taught the flow from spec to chip, course 2 the numbers AI chips store; this one answers the question both left open: how do you know the design works? Testbenches, waveforms, vectors, cosimulation, coverage, formal, mutation, sign-off -- in that order, each step with a receipt.
The nine modules
| Module | Title | The question it answers |
|---|---|---|
| 1 | Why verify | Designs that compile and are still wrong; the golden model; the plan written before the code |
| 2 | Testbenches | Stimulus, expectation, checks and a verdict in one spec |
| 3 | Waveforms | Reading a VCD as text, debugging a real measured bug, diffing two runs |
| 4 | Conformance vectors | Inputs with the answer recorded beside them, where the compiler can reach them |
| 5 | Cosimulation | Spec, simulator and board brought to one answer on the bench |
| 6 | Coverage | What the tests touched, bit by bit, arc by arc -- and what the number hides |
| 7 | Formal | Assertions checked every cycle, bounded search, honest induction |
| 8 | Mutation | Break the design on purpose and count what the tests caught |
| 9 | Sign-off | One command, every receipt, a verdict you can show |
Every number was measured
The widgets are recordings of real tool runs, and the lesson texts use only numbers those recordings or the named spec show. The UART link that asked for 115,200 baud and got 115,385 on the wire -- a +0.16 % divider error invisible in code and obvious in the capture, while 3,000,000 divides exactly and the wire agrees. The 31 of 1,428 merged specs whose seals record no output, on 16 specs, 3 of them unnamed by the ledger that owes them a name. The 367 pull requests that arrived in 14 days, 11 of which deleted tests or asserts, one deleting all 26 tests in its file with nothing failing. A course about verification does not get to cite numbers it cannot show.
A new spec: coverage.t27
Lesson 16 needed a coverage model, and there was none, so it was written where specs live -- gHashTag/t27, specs/fpga/coverage.t27 -- and the site serves a vendored copy for the lesson. It models line, toggle, FSM state and FSM transition points with hit counters, integer percentages that return 0 when nothing was measured, and illegal transitions that must stay at 0 hits; it carries 26 tests and 4 invariants of its own, in the flat-arrays style of its siblings simulator.t27 and vcd_trace.t27.
What the gallery paid for it
A course needs 27 framable widgets that no other lesson in any course uses. The gallery had 96 casts and almost all of them spoken for, so 17 recordings of real tool runs -- conformance sweeps, self-test runs, seal audits, a census recount, mutation and test-touch counts -- were cast and shelved in the two categories they belong to, and each became exactly one lesson's main widget. The gallery spec now declares 113 widgets, and its tests pin the shelf anchors so the fpga, compiler and game runs stay contiguous.
What it does not do
- The in-browser runner compiles each lesson spec on all 7 backends but cannot execute testbench test blocks yet (trinity#1477); the lessons show recorded t27c output instead of working around it.
- Three lesson specs named in the issue did not compile clean under the browser compiler (discarded statements and a typecheck failure); those lessons open clean siblings that teach the same step.
- specs/fpga/coverage.t27 is written in gHashTag/t27 and lands there in its own PR; until then the site serves the vendored copy, and the vendored-manifest check does not yet know the new file.
Try it
- Course 3, Verifying hardware with t27: t27.ai/learn/verify-hardware/
- In the app: t27.ai/#/verify-hardware
- The course spec: t27.ai/learn/verify-hardware.t27
What this does not settle
- The in-browser runner compiles lesson specs but cannot execute testbench test blocks yet (trinity#1477); lessons show recorded t27c output.
- specs/fpga/coverage.t27 is written in gHashTag/t27 and lands there in its own PR; the site serves the vendored copy until then.
- The vendored-manifest check does not yet list the new coverage.t27 copy.
Receipts
Work with me
Need an FPGA/RTL problem taken to measured hardware?
I work contract and part-time on hardware-AI, FPGA/RTL and ML systems — from specification and open toolchains to reproducible measurements.