Blog
Buses and peripherals with t27, in 27 lessons
Course 7 of the catalog: UART frame by frame, SPI mode by mode, the APB handshake, the five AXI4 channels, memory maps, the packet bridge, Ethernet frames and RGMII timing, and the bench IO discipline -- every lesson opens one widget and one t27 spec, and 31 of the widgets are new recordings of native t27c on a real machine.
The catalog holds seven courses now. "Buses and peripherals" is 27 lessons in 9 modules of 3, chained after the clocks course: the capstone of that course links forward, lesson 1 links back. The subject is the middle of every real design -- how blocks talk. UART frame by frame, SPI mode by mode, the APB handshake, the five AXI4 channels, memory maps, the packet bridge between buses, Ethernet frames and RGMII timing, and the bench IO discipline that guards the hardware the whole track has been building toward.
Nine modules
| Module | What it teaches |
|---|---|
| 1, What a bus is | Why shared wires need an agreed conversation; the UART as the two-wire archetype, SPI as the clocked answer, APB as the register bus with roles. |
| 2, UART | The frame (start, 8 data, stop, idle high), the divisor 100,000,000 / 115,200, the status codes a driver polls and the 16-deep FIFOs. |
| 3, SPI | CPOL and CPHA as four modes, the prescaler ladder from the one 50 MHz clock, chip-select timing of 100 ns and data widths up to 32 bits. |
| 4, APB | The setup and access phases of PSEL and PENABLE, strobe bytes for 32-bit and 16-bit writes, and how many address bits 1, 4 or 8 peripherals cost. |
| 5, AXI4 | The five channels with their widths (address 32, data 32, strobe 4, ID 4, LEN 8, SIZE 3), what Lite drops, and what an ID buys a burst. |
| 6, Memory | The memory map as who lives at which address: kinds, up to 8 ports, read-only ROM refusing a write port, and latency a wait state must cover. |
| 7, Bridges | Why one design grows several buses, and the packet bridge with its 256-byte RX and TX buffers, 64-byte SPI buffer, 128-byte packets and 10,000-cycle timeout. |
| 8, Ethernet | The frame check sequence as a CRC-32, RGMII moving a nibble on both edges at 125 MHz, and a pre-registered bring-up plan read step by step. |
| 9, The bench | Who holds the IO right now (tri fpga-ioclients), taking and returning the claim, and the capstone that opens the whole design, 8 MAC units and 19 tests. |
Thirty-three recordings, and what they honestly show
The course needed a framable widget for every lesson, and minted 33 new cast recordings. Most of them run native t27c 0.4.0 on a laptop against the bus specs. But the native runner cannot take most of these specs whole: uart, spi, apb_bridge, axi4, bridge and top_level are BLOCKED for comptime resolution the runner cannot finish. Four of them run clean natively: memory.t27 -- 15 tests and 6 invariants proved comptime -- spi_tb.t27 with 7 tests, and the two new Ethernet specs, eth_crc.t27 with 8 tests and rgmii.t27 with 7 tests plus its comptime invariant. So the recordings show what the compiler does complete on every spec: t27c check (0 errors, 0 warnings), t27c gen-verilog (the synthesizable module, its port list, its wires), and t27c debug-hir (the hardware IR view). The lesson texts say which is which; no recording claims a test run that did not happen.
The bench module records the live tools instead: tri fpga-ioclients reading the registered IO clients, tri fpga-claim and tri fpga-release taken and given back back-to-back, tri fpga-next reading what runs next, and the Ethernet bring-up plan of tri fpga-steps E3, pre-registered step by step. The capstone lesson lowers the whole design: top_level.t27 carries CLK_FREQ_HZ 100,000,000, SYSTICK_HZ 1000, NUM_MAC_UNITS 8 and the four opcodes (CMD_NOP, CMD_MAC_MULT, CMD_MAC_DOT, CMD_UART_SEND) over 19 tests.
Two new specs, landed in the compiler repo first
The Ethernet module needed specs the tree did not have. specs/fpga/eth_crc.t27 carries the CRC-32 the frame check sequence computes, and specs/fpga/rgmii.t27 the double-data-rate timing arithmetic, 125 MHz for gigabit and the single-data-rate downshift for 10 and 100. Both were written in gHashTag/t27 (PR 7626), then vendored into the website files tree -- the direction the own-language rule wants: the spec lives in the repo that owns the language, the site serves a copy it can prove identical. Every constant in them that is not from IEEE 802.3 is labelled as an assumption in the spec header, with the document it is not from. The first version of the CRC spec was wrong in a way its own CI could not see: the gates check that a spec compiles, not that its asserts hold, and 6 of its 8 tests failed natively -- every failing assert compared the running register against zlib post-inverted values, and the receiver test claimed the register returns to its preset, which no 802.3 CRC-32 does. The spec now carries the physical model: the FCS is the post-inverted register, and a receiver digesting frame plus FCS lands on the residue 0xDEBB20E3, computed with the same Python zlib the header names as oracle. All 8 tests pass, none vacuous.
Four specs that only looked compiled
The last gate the course runs counts discarded tokens, and four lesson specs failed it while reporting that they compiled: uart, spi, bridge and top_level carried test and invariant bodies the parser silently threw away -- a bare statement where a clause was expected, implies conditions in assert bodies, a call to a method that does not exist, comments inside clauses. The compiler said these files were fine; a reader was never told their tests were not even being read (the defect is filed as gHashTag/t27#2474, and the parser repair is stage0-frozen, so the specs were rewritten into the subset the parser already consumes -- gHashTag/t27 PR 7659, with the wasm/native divergence on bridge array writes recorded in it). Every lesson that says here is the spec and it compiles now points at a spec that parses to the end.
What this does not show
- The browser player still skips test and invariant blocks (trinity#1477, fix open as PR 1495), so every recorded verdict runs natively and the lesson says so.
- Six of the seven bus specs are BLOCKED in the native runner for comptime resolution; their recordings show check, gen-verilog and debug-hir, never a claimed test run.
- t27c test-report exits 0 on a blocked spec (t27#7370), so the minting pipeline screened status from the run text, not exit codes.
- The t27 CI gates caught nothing of the wrong CRC: they prove a spec compiles, not that its asserts hold. The 6-of-8 failure was found by running the spec natively before recording it, and fixed on the PR branch (t27#7626) before either cast was minted.
- The RGMII and CRC numbers are the specs' own model with header-labelled assumptions, not board measurements; the E3 bring-up steps are pre-registered, and steps that did not run are recorded as not run.
- The Russian bundle covers all 27 lessons (the contract refuses a missing field), but widget strings stay English: each widget is its own t27 spec.
Try it
- Course: t27.ai/learn/buses-and-peripherals/
- The frame, start to stop: t27.ai/learn/the-frame/
- A spec the native runner takes whole: t27.ai/learn/memory-maps/
- In the app: t27.ai/#/buses-and-peripherals
What this does not settle
- The in-browser runner still skips test and invariant blocks (trinity#1477, fix open as PR 1495); lessons show recorded t27c output.
- Six of the seven bus specs are BLOCKED in the native runner for comptime resolution; their recordings show check, gen-verilog and debug-hir, never a claimed test run.
- The RGMII and CRC constants that are not from IEEE 802.3 are labelled assumptions in the spec headers, not board measurements.
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.