Felipe Balbi

Tamal: Everything, Wired

2026-08-14T09:00:00+00:00

The pads exist now, and they are wired to nothing.

That is the odd position the series has arrived in. We have read a CRC unit, a baud generator, a transmitter, a receiver and the umbrella over them; a COBS codec and the loader that streams it; two block RAMs; an engine, in eight instalments, from its eight-phase map down to the two bits of a lane; two pure format models for the bytes that go in and the words that come out; and, last week, the tri-state buffers that turn a (value, enable) pair into a pin that floats. Every piece is open. Not one of them is connected to another.

Tamal.Top connects them. It is a hundred and fifteen lines, and it contains exactly one function that matters — system, which takes a serial line and some sampled bits and hands back a serial line, a bus drive and a blinking LED — and four small pure helpers that exist so the parts of the wiring that could have been logic are not hidden inside it. Reading it is less like reading a module and more like reading a table of contents, because every import is a post.

Six names, and the series behind them

module Tamal.Top
  ( system
  , stepM
  , ringWrite
  , RigState (..)
  , rigState
  , ledPattern
  ) where

import Clash.Prelude

import Tamal.Bus.Serdes (Lanes)
import Tamal.Engine (BusIn (..), BusOut (..), Ring (..), State, initState, step)
import Tamal.Loader (LoaderIn (..), LoaderOut (..), loader)
import Tamal.Mem (instrRam, ringRam)
import Tamal.Params (RW)
import Tamal.Uart (uart)

Six exports, and the asymmetry between them is the design. One of the six is the machine. The other five are pure functions the machine happens to use, hoisted to the door so they can be tested without a clock: stepM, an adapter; ringWrite, a projection; and RigState with rigState and ledPattern, a three-state enum and the two total functions over it that decide how an LED blinks. Nothing in that list computes anything the design needs at speed. They are there because a wiring module that quietly grew logic inside it would be a wiring module you could not check, and the author would rather export four small things than hide them.

The imports are the more striking half. Six modules, and every one of them has a post: Serdes for the Lanes type, Engine for the state machine and the four record types that plug into it, Loader for the frame FSM, Mem for the two block RAMs, Params for the RW address width, Uart for the serial umbrella. The shape post opened with eight closed boxes and called that the exact inversion of the leaves-first UART — a map drawn before any of its territories had been walked. This import list is the same map with every box now open, and it is the first module in the project whose header you cannot read without having read the project.

The moment the engine gets its clock

The engine’s keystone type has been sitting still since the shape post:

step :: State -> BusIn -> (State, BusOut, Maybe Ring)

A pure function. Give it a state and this cycle’s inputs; get back the next state, the pins to drive, and maybe a trace word. Eight posts have described what it computes, and in all eight it has never once run in time — it is a transition, not a machine, and a transition needs something to iterate it.

That something is mealy, which the primer introduced and the transmitter first put at the top of a module. Its type wants a transition of a particular shape:

mealy :: (HiddenClockResetEnable dom, NFDataX s) =>
  (s -> i -> (s, o)) -> s -> Signal dom i -> Signal dom o

A pair. State and output, two elements. step returns three, because the shape post argued at length that splitting the output into pins and trace-word was worth doing — BusOut is what the wires carry right now and Maybe Ring is a thing to remember, and conflating them would have been a smaller type and a worse one. So the two shapes do not quite meet, and three lines bridge them:

stepM :: State -> BusIn -> (State, (BusOut, Maybe Ring))
stepM s i = (s', (bo, mr))
 where
  (s', bo, mr) = step s i

One pair of parentheses moved. (State, BusOut, Maybe Ring) becomes (State, (BusOut, Maybe Ring)), and now the second element is a single o and mealy will take it. That is the entire function, and it is worth stopping on precisely because it is nothing, because the line that uses it is the most consequential in the file:

(busOut, maybeRing) = unbundle (mealy stepM initState busInS)

Read that slowly. mealy stepM initState takes the pure transition and gives back a function from a Signal of inputs to a Signal of outputs: it allocates the register that holds State, initialises it to initState, and arranges for the transition to be applied once per clock edge for the rest of the design’s life. Eight posts of arithmetic acquire a clock in one application. unbundle then splits the paired output back into two signals, so the rest of the module can use busOut and maybeRing separately — the pairing existed only to satisfy mealy, and it is undone the moment it has.

step describes what happens next. mealy stepM initState is what makes next happen.

The loader was called the first block that owns a clock, and it earned the phrase: it had a mealy at its top and eighteen fields of state turning underneath. The engine is bigger than the loader by every measure — seventeen state fields, eight phases, thirty-six opcodes — and it does not own a clock at all. It never did. It borrows one here, in the top, on one line, and that is the whole reason the shape post’s property tests could hammer step with random inputs and no simulation: a function you can call is a function you can test a hundred thousand times a second.

stepM gets a test of its own, and the test is a statement that the adapter is not a place where behaviour can hide:

testProperty "stepM = step re-associated" $ H.property $ do
  i <- H.forAll genBusIn
  let (s', bo, mr) = step initState i
  stepM initState i H.=== (s', (bo, mr))

For a random BusIn — random instruction word, four random sampled IO bits, a random ALERT#, a random start flag — stepM must return exactly what step returned, only re-parenthesised. It looks like testing that a tuple is a tuple. It is really a guard on a seam: stepM is the last thing that touches the engine’s output before the clock does, and a swapped element or a dropped Maybe here would be invisible in every engine test and fatal on the board.

No BiSignal, on purpose

Now the signature that the whole module is arranged around:

system ::
  (HiddenClockResetEnable dom) =>
  Signal dom Bit ->            -- uart RX line
  Signal dom (Vec 4 Bit) ->    -- ioIn
  Signal dom Bit ->            -- alertIn
  ( Signal dom Bit             -- uart TX line
  , Signal dom Lanes           -- lanesOut
  , Signal dom Bit             -- csOut
  , Signal dom Bit             -- sckOut
  , Signal dom Bit             -- rstOut
  , Signal dom Bit             -- led
  )

Three in, six out, and not a BiSignal anywhere. The module’s own doc comment says why in half a sentence — no BiSignal, so the whole integration is cosim-testable — and the previous post is the long version of that half-sentence.

Recall the shape of the trouble. A bidirectional net’s value is a function of every driver attached to it, so a driver derived from a read of the same net is a value defined in terms of itself, and Clash’s simulator does not resolve it — it diverges. The pad post’s test harnesses had to be split into two single-driver directions to say anything at all about four lanes and one synchroniser. That is a tolerable amount of ceremony for a hundred and four lines. It would be an intolerable amount for a test that wants to serialise a program onto a UART, watch a loader parse it, watch an engine execute it, and read the result back out.

So the boundary is drawn to keep the hard part small. system speaks entirely in ordinary unidirectional Signals: ioIn arrives already sampled, four plain Bits, and lanesOut leaves as a plain Lanes, four (value, enable) pairs that are still just numbers. Everything bidirectional lives outside, in espiPads, and the board shell is what puts the two together. The result is a partition with a pleasing property: the part of the design that cannot be simulated conveniently is a hundred and four lines with nine tests, and the part that is the actual machine — fifteen hundred lines of UART, loader, memories and engine — can be driven end to end with a list of Bits.

Draw the boundary where the tooling gets hard, not where the diagram looks tidy.

There is a second thing hiding in that signature, quieter than the first: it is generic in dom. system does not name a clock frequency, a board, or a domain. It says HiddenClockResetEnable dom and lets whoever instantiates it supply the clock — which is what makes one system serve two board shells, and what leaves the whole question of which silicon for the post after this one.

The confluence

The body is thirty lines, and it is the entire design:

system rxLine ioIn alertIn = (txLine, lanesO, csO, sckO, rstO, ledOut)
 where
  -- UART @ 2MBaud
  (rxByte, _rxErr, txLine, txReady) = uart (SNat @2_000_000) rxLine txByteL

  -- Loader FSM
  lOut = loader (LoaderIn <$> rxByte <*> txReady <*> halted <*> ringPtrO <*> ringData)
  txByteL = txByte <$> lOut
  instrWrL = instrWr <$> lOut
  ringAddrL = ringAddr <$> lOut
  startO = startOut <$> lOut

  -- Memories
  instrWord = instrRam pcO instrWrL
  ringData = ringRam ringAddrL (ringWrite <$> maybeRing)

  -- Engine
  (busOut, maybeRing) = unbundle (mealy stepM initState busInS)
  busInS = BusIn <$> instrWord <*> ioIn <*> alertIn <*> startO
  pcO = pcOut <$> busOut
  lanesO = lanesOut <$> busOut
  …

Four comments, four stages, and the four stages are the series in order.

The UART comes first, and it is the umbrella read whole: uart (SNat @2_000_000) rxLine txByteL returns four things, and the design uses three of them. rxByte is a Maybe (BitVector 8) strobing once per received byte, txLine is the outgoing wire, txReady is the transmitter’s back-pressure. The baud rate is passed as a type-level number in the SNat the umbrella demanded, and everything the baud generator did with a fractional 3.125 follows from it and from whatever dom turns out to be.

And _rxErr is dropped. The UART top post noted that the framing error had no consumer yet and left it unwired, and here at the very top — the last place it could have found one — it still has none. That underscore is the project being honest about an unfinished edge rather than inventing a use for it.

The loader is next, and its input is built by applying a constructor across signals:

lOut = loader (LoaderIn <$> rxByte <*> txReady <*> halted <*> ringPtrO <*> ringData)

LoaderIn is an ordinary five-field record. <$> and <*> lift its constructor over Signal, so what comes out is a Signal dom LoaderIn — one record per cycle, its five fields taken from five separate signals at the same instant.^[1] The four outputs come back the same way, each a field projection mapped over lOut: txByte <$> lOut for the byte to transmit, instrWr <$> lOut for a write into the instruction memory, ringAddr <$> lOut for the drain’s read address, startOut <$> lOut for the trigger. The loader’s three lives — receive a frame, hold it, drain the ring — are all behind that one call.

The memories are two lines, and both are the mem post’s four-line leaf instantiated:

instrWord = instrRam pcO instrWrL
ringData = ringRam ringAddrL (ringWrite <$> maybeRing)

instrRam is read by the engine’s program counter and written by the loader. ringRam is read by the loader’s drain and written by the engine’s trace emitter. Each memory has exactly one reader and one writer, and in both cases they are different modules pointing in opposite directions — which is the shape a rig wants: the host writes programs and reads results; the engine reads programs and writes results.

And the engine closes it. busInS assembles a BusIn from four sources — instrWord from the instruction memory, ioIn and alertIn from the caller (and thence from the pads), startO from the loader — and mealy stepM initState runs it. busOut is then fanned out one field at a time: pcOut back to the memory, lanesOut/csOut/sckOut/rstOut out to the caller, haltedOut to the loader and the LED, ringPtrOut to the loader so the drain knows how far to sweep.

Three of those wires are loops.

The whole design, as system wires it. The dashed boundary is the signature: everything inside speaks in ordinary unidirectional Signals, and the four bidirectional IO lanes are somebody else's problem — ioIn arrives already sampled and lanesOut leaves as four (value, enable) pairs. The three accented wires are the feedback loops: pcO into the instruction memory whose answer comes back a cycle later, ringWrite into the trace memory, and ringData back out of it into the loader's drain. Each of the three is a definition that mentions a name defined further down the where block, and each is legal because these are nets, not values.

Those loops are the reason this module reads strangely on a first pass. pcO is defined from busOut, which comes from busInS, which contains instrWord, which comes from instrRam pcO — pcO appears on both sides. ringData feeds the loader, whose lOut produces ringAddrL, which the memory needs to produce ringData. halted is read by the loader four lines above the line that defines it.

None of that is a problem, and the UART top post already explained why: Clash elaborates, it does not evaluate. A where-bound name in a hardware description is the name of a net, and a netlist has no notion of “before”. Writing instrWord = instrRam pcO instrWrL above the line that defines pcO states that the memory’s address port is connected to the engine’s pcOut port, which is a fact about wires and is as true read upwards as downwards. What would be a problem is a loop with no register in it, and there is none: the instruction memory’s one-cycle read latency breaks the fetch loop, the engine’s own state register breaks the trace loop, and the Fetch phase exists precisely to spend the cycle that latency costs.^[2]

One line that keeps a promise

The projection between the engine and the trace memory is a single line, and it is the smallest thing in the file with an argument behind it:

ringWrite :: Maybe Ring -> Maybe (Unsigned RW, BitVector 32)
ringWrite = fmap (\(Ring a d) -> (a, d))

The engine emits Maybe Ring, a record with named fields rAddr and rData. The memory’s write port takes Maybe (Unsigned RW, BitVector 32), a bare tuple. ringWrite unwraps one into the other, and fmap carries it through the Maybe so a cycle with nothing to write stays a cycle with nothing to write.

The mem post spent a section on why the write port is a bare tuple, and gave the reason as an aphorism: a memory that imports the engine is a memory that knows what a trace record is. ringRam is deliberately ignorant. It stores thirty-two-bit words at addresses and has never heard of Ring, or Capture, or the two-bit tag that tells a host which record shape follows. Keeping it that way requires somebody, somewhere, to do the unwrapping — and this is the somebody. The adapter lives in the top, which is the one module that is supposed to know about everything, and so the ignorance the memory was designed to have is paid for in one line by the module that can afford it.

Its tests are two, and they are exactly the two cases: ringWrite Nothing is Nothing, and ringWrite (Just (Ring a d)) is Just (a, d) for random a and d. Trivial — and the sort of trivial that catches a swapped pair.

A status LED, made a truth table

The last eight lines are the user interface, and they are the only part of the design a person looks at directly:

data RigState = Waiting | Running | Done

rigState :: Bool -> Bool -> RigState
rigState _ True = Done
rigState True False = Running
rigState False False = Waiting

ledPattern :: RigState -> Unsigned 26 -> Bit
ledPattern Waiting c = msb c
ledPattern Running c = msb (c `shiftL` 3)
ledPattern Done _ = high

And in system, the three lines that give them time:

running = register False (mux startO (pure True) (mux halted (pure False) running))
ledCnt = register (0 :: Unsigned 26) (ledCnt + 1)
ledOut = ledPattern <$> (rigState <$> running <*> halted) <*> ledCnt

Split that in half and the split is the point. The stateful part is two registers: a one-bit running latch that sets on the loader’s trigger and clears when the engine halts, and a free-running twenty-six-bit counter that does nothing but increment forever. The decision part is two pure total functions, exported and tested, that never touch a clock.

rigState is a truth table with three rows and a wildcard, and the wildcard is a priority: halted wins. A rig that has run and stopped shows Done whether or not the latch is still set, so the terminal state is genuinely terminal. Its tests are the truth table, written out — both halted cases, the running case, the idle case — which is what a three-line function deserves and rarely gets.

ledPattern is the blink, and it says a great deal in three lines. msb c is the top bit of the counter, which at 100 MHz toggles every 2²⁵ cycles: about a third of a second on and a third off, a slow, patient pulse.^[3] msb (c `shiftL` 3) reads bit 22 instead — shifting left by three brings a lower bit into the top position — so Running blinks eight times faster on exactly the same counter, no second divider, no second register. And Done is high with the counter ignored: solid on, and the underscore in ledPattern Done _ is the whole statement that a finished rig does not blink.

Its tests check the two rates against the same count, which is the sharp way to do it:

ledPattern Running 0x400000 @?= high
ledPattern Waiting 0x400000 @?= low   -- same count => Running is faster

At count 2²², Running is on and Waiting is still off. One assertion, and the relationship — faster — is pinned rather than the absolute rates. That is the property that actually matters to a person squinting at a board: not that the LED blinks at 1.5 Hz, but that a running rig looks visibly different from a waiting one.

There is a general point here worth naming, because it is why these functions are exported at all. A status indicator is the least testable part of most designs — it is inherently about what something looks like over time, and it usually ends up as three lines of ad-hoc logic buried in a top-level module where nothing can reach it. Splitting it into a state derivation and a pattern function turns the question “does the LED do the right thing” into two questions with yes-or-no answers, and moves the only untestable part — how fast a third of a second feels — into a constant.

The tests: the first time the whole thing runs

Everything so far has been checked in pieces. Test.Top is the first time the pieces run together, and the harness it needs is instructive.

cyclesPerBit :: Int
cyclesPerBit = 50

100 MHz over 2 Mbaud is fifty cycles a bit — the same arithmetic the baud generator did with a fractional accumulator, done here in whole numbers because the test bench drives the line rather than recovering it. From that, serialize turns a list of bytes into a list of Bit samples: fifty low for the start bit, fifty per data bit LSB-first, and then two bit-times high.

That last detail is an admission, and the comment makes it:

-- one idle bit-time between bytes (a realistic transmitter's inter-byte gap ---
-- the RX needs it to resync; truly back-to-back bytes drop on the falling-edge
-- resync).

A stop bit and one idle bit before the next start. That is what a real UART transmitter emits and what a real host sends, so the bench is not cheating — but it is recording that the receiver’s falling-edge resynchronisation wants the gap, and that a stream with literally none would lose bytes. The kind of thing you learn when the pieces meet.

The decoder in the other direction is the nicer trick:

deserialize samples =
  [ b | Just b <- sampleN (L.length samples)
          (fst (uartRx (oversampleTick (SNat @2_000_000)) (fromList …))) ]

It does not reimplement UART framing. It runs the captured txLine back through the real uartRx, fed by the real oversampleTick, and collects the bytes that strobe out. The receiver post closed on a byte-exact TX-to-RX loopback and called it the keystone; this is that keystone used as laboratory equipment. The transmitter under test and the receiver reading it are the two halves the loopback already proved agree, so a decoding failure here is a system failure and not a bench artefact.

runSystem then drives the machine, and its one subtlety is at the front:

leadN = cyclesPerBit

Fifty idle-high cycles before the real stream, so that the domain’s cycle-zero reset settles while the line is idle rather than in the middle of the first start bit. It is the same sampleN idiom the memory tests needed, applied to a whole design.

And then the payoff. Two test cases, and the first is the smallest complete run the rig can perform:

testCase "cosim: load [HALT], trigger -> drain = REVISION + HALT terminator"
  $ loadRunDrain [encode (Halt 0)] 20000
  @?= Right [0x0001_0000, 0xC000_0000]

Follow what that sentence asks for. encode (Halt 0) produces one thirty-two-bit instruction word. encodeControl (LoadProgram …) wraps it in a CRC, COBS-stuffs it and appends a zero delimiter; encodeControl Trigger adds a second frame. serialize lays both out as ten thousand-odd line samples. Then system runs: the UART receives the bytes, the loader peels the frames and writes the word into the instruction memory, the trigger raises startOut, the engine leaves Idle, stamps its REVISION preamble, fetches, executes a HALT, and pushes a terminator record. The loader sees haltedOut, drains the ring, re-frames the words, and clocks them out of the transmitter. deserialize reads them back with the real receiver and decodeResult unwraps the frame.

What comes out is two words. 0x0001_0000 is the REVISION preamble the shape post said Preamble stamps. And 0xC000_0000 is a HALT record, which you can read straight off the trace post’s field ruler: the top two bits are the tag 0b11, and every other field — seventeen reserved zeros, a three-bit reason, the trap flag, the overflow flag, the status byte — is zero. A clean stop, no trap, no dropped records, status nought. Exactly what Halt 0 should leave behind.

That single assertion exercises the wire format, the COBS codec, the CRC, the baud generator, the transmitter and receiver, the loader’s three lives, both memories, the instruction decoder, the engine’s phase machine, the trace records and the ring discipline. Fourteen posts, one @?=.

The second case adds the pins:

let prog = [encode CsAssert, encode (PutByteImm 0xA5), encode CsDeassert, encode (Halt 0)]
…
assertBool "cs_n asserts low" (low `L.elem` cs)
assertBool "sck toggles" (low `L.elem` sck && high `L.elem` sck)
decodeResult (deserialize tx) @?= Right [0x0001_0000, 0xC000_0000]

A real, if minimal, eSPI transaction: assert chip select, put a byte, deassert, halt. The assertions are deliberately weak — CS# goes low at some point, SCK takes both values at some point — because the bus post already pinned the five-cycle beat and the rising edge at the 2→3 boundary with sharp unit tests against step. What this test adds is not precision but reach: it shows that a byte typed into a serial port at one end of the design comes out the other end as motion on the eSPI wires, and that the trace still drains cleanly afterwards. The sharp tests prove the waveform; this one proves the waveform is connected to anything.

What we read

A hundred and fifteen lines, and the project stops being a collection of modules. Tamal.Top exports one machine and four pure helpers, and imports six modules that are six posts. stepM re-associates the engine’s three-element output into the pair mealy wants, and that one application — mealy stepM initState — is where eight posts of pure transition acquire a clock, a register and a life; a property test holds the adapter to being nothing but parentheses. system is the whole design over plain Signals, with BiSignal deliberately excluded so the pad post’s simulation knot stays confined to a hundred and four lines while everything larger stays drivable from a list of bits. Its body is four stages — UART, loader, memories, engine — and three feedback loops, each written as a definition that mentions a later name, each legal because these are nets and each broken by a register that was placed for other reasons a long time ago. ringWrite unwraps a Ring into a bare tuple so the memory can go on not knowing what a trace record is. And the LED is a latch, a counter, and two total functions that turn “is it working” into a truth table.

Then the tests run the whole thing, which nothing before now could. A program is framed, serialised bit by bit onto a wire, received, parsed, stored, triggered, executed, traced, drained, re-framed, and read back with the project’s own receiver — and it comes back as a REVISION word and a HALT terminator with every field zero. The introduction described a rig that loads a program over a serial link and reports what happened on the bus. Two hundred lines of test say it does.

What is still missing is small and absolute. system is generic in its domain: it never says how fast its clock runs, never names a pin, and its four IO lanes are plain signals that no bonded pad has ever seen. It is a machine with no address. The next post gives it one — fifty-one lines that tie a real oscillator to a real domain, wrap system in espiPads, and name every port on the package so the place-and-route tool knows which ball of solder is IO[0]. Below that there is no more Haskell.

LoaderIn <$> rxByte <*> txReady <*> halted <*> ringPtrO <*> ringData looks like effectful code and is nothing of the sort. Signal dom is an applicative functor over time: <$> maps a pure function across every cycle of a signal at once, and <*> applies a signal of functions to a signal of arguments cycle by cycle. Feed a five-argument constructor into that machinery and what comes back is Signal dom LoaderIn — a record assembled fresh every cycle from whatever its five sources carry at that moment. In hardware it is not an assembly at all: a record is a bundle of wires, so the expression describes five groups of wires being routed into one named bundle, and it costs exactly nothing. The field projections on the other side (txByte <$> lOut and friends) are the same move reversed — selecting a sub-bundle out of a wider one. The primer’s framing of Signal as a stream you map over, not a value you inspect is what makes this style read naturally: you never write down a cycle, so you never have to say which one. ↩
A where block in Clash is a set of simultaneous equations over nets, not a sequence of assignments, so mutual reference between its bindings is ordinary. What is not ordinary — and what the compiler will reject or the simulator will hang on — is a cycle with no state element in it, since that describes a combinational loop: a value that must be known in order to compute itself. All three loops here are broken by registers that were placed for independent reasons. The fetch loop pcO → instrRam → instrWord → engine → pcO crosses the instruction memory’s one-cycle read latency, which is a register inside the block RAM primitive and the reason the engine has a Fetch phase at all: it spends a cycle doing nothing so the word has time to arrive. The trace loop maybeRing → ringRam → ringData → loader → ringAddr → ringRam crosses the ring memory’s read latency and the loader’s own state. And halted and startO, which appear above their definitions, are both projections of registered outputs — haltedOut from the engine’s state register, startOut from the loader’s. The design was never arranged to make this module typecheck; it typechecks because a machine that talks to memories has registers in all the right places anyway. ↩
ledCnt is an Unsigned 26 incrementing once per clock, so its top bit is high for 2²⁵ cycles and low for 2²⁵ cycles. At 100 MHz that is 33.5 million cycles, about 336 ms each way — roughly a 1.5 Hz blink, which is about as slow as an LED can flash and still read as waiting rather than broken. msb (c `shiftL` 3) observes bit 22 instead, one eighth of the period: about 12 Hz, fast enough to read as activity and slow enough not to look solid. The whole thing costs one twenty-six-bit counter, because both rates are taps on the same count rather than two dividers — which is also why the two patterns stay in phase with each other, and why the test can compare them at a single value of the counter. ↩

Tamal: Out to the Pins

2026-08-13T09:00:00+00:00

The serdes post ended with a promise and an apology. It had just finished arguing that a (value, enable) pair is the whole of tri-state — three wire states carried in two bits — and then it admitted that none of it was real yet. Every Lanes the engine computes is still just numbers, it said; a description of a drive, not a drive. Something has to carry those pairs the last step out.

This is that something. Tamal.Io is a hundred and four lines, and it contains the single line the last eight posts have been walking toward:

toDrive (o, oe) = if oe == 1 then Just o else Nothing

That is the crossing. On the left of it, the engine’s arithmetic — two Bits in a tuple, computed by pure functions, checked by property tests, meaning nothing to any wire. On the right, a Maybe Bit, which Clash knows how to turn into an FPGA’s output-enable and a pad that either drives or floats. Everything the introduction meant when it said the pins are the hard part happens in this file, and the file is short enough to read in one sitting.

Two names on the door

The door is the shortest of the whole series bar one, and the imports beneath it are shorter still:

module Tamal.Io
  ( espiPads
  , alertSync
  ) where

import Clash.Prelude
import Tamal.Bus.Serdes (Lanes)

Two functions, no types. The CRC’s wall-with-a-door still holds, and this wall has exactly two openings: the pad boundary itself, and the synchroniser that guards the one asynchronous wire in the design. Everything else in the file is a where-bound helper.

The import list is the more interesting half. Clash.Prelude, the one line that turns a Haskell file into a hardware description, and then a single name from a single sibling: Lanes, from Tamal.Bus.Serdes. That is the whole dependency graph. Tamal.Io has never heard of the engine. It does not import Tamal.Engine, does not know what a BusOut is, has no idea a phase field exists or that a PUT is different from a TAR. It takes a Signal dom Lanes — four (value, enable) pairs per cycle — and asks no questions about where they came from.

That is the same discipline the memories were held to, and for the same reason. A blockRamPow2 that imported the engine would be a memory that knows what a trace record is; a pad boundary that imported the engine would be a pad that knows what an instruction is. Neither needs to. The shape post observed that the engine’s busOut is a projection and not a computation — the pins are read out of registers that were already settled — and this module is the consumer that projection was written for. It receives a settled drive and makes it physical. Nothing more.

A pad that imports the engine is a pad that knows what an instruction is.

The line that makes it physical

Read toDrive again, because it is doing something more delicate than it looks:

toDrive (o, oe) =
  if oe == 1
    then Just o
    else Nothing

The type is Lane -> Maybe Bit, which is (Bit, Bit) -> Maybe Bit. Two bits in, one optional bit out. Count the inhabitants and the shape of the move becomes clear. The input type has four values: (0,0), (1,0), (0,1), (1,1). The output type has three: Nothing, Just 0, Just 1. toDrive is the function that collapses four onto three, and it collapses exactly the pair the serdes post said was redundant — (0,0) and (1,0), released with the value ignored — onto the single Nothing.

The serdes post called that redundancy not waste, but the shape of the thing, and it was right about the encoding. Two bits are how you carry three states through a register file, a Vec, a bitCoerced record, all the machinery that wants fixed widths. But the moment those bits reach a pad, the redundancy is a liability: a pad has no use for the value of a lane it is not driving. Maybe Bit is the type with no redundancy in it. Three states, three constructors, and no way to write down a released lane that also carries a value, because there is no such thing.

The engine says the enable may veto the value. The pad type says the veto has already happened.

So toDrive is not a conversion so much as a normalisation — it takes the engine’s convenient encoding and hands the synthesiser the canonical one. And Just/Nothing is exactly the vocabulary Clash’s bidirectional primitive expects:

writeToBiSignal ::
  (BitPack a, NFDataX a, …) =>
  BiSignalIn ds d (BitSize a) -> Signal d (Maybe a) -> BiSignalOut ds d (BitSize a)

Just x means drive x onto this net this cycle; Nothing means let go. Which is why the body of drive is one line with nothing clever in it:

drive :: Index 4 -> BiSignalIn 'PullUp dom 1 -> BiSignalOut 'PullUp dom 1
drive i padIn = writeToBiSignal padIn (toDrive <$> (laneSigs !! i))

laneSigs = unbundle lanesOut splits the one Signal dom (Vec 4 Lane) the engine produces into four separate Signal dom Lanes, one per wire.^[1] laneSigs !! i picks lane i; toDrive <$> maps the collapse across time, cycle by cycle; writeToBiSignal attaches the result to the net as a driver. Three combinators and the (value, enable) pair has become a tri-state buffer. Post 3’s beatLanes decided what to drive; serializeX1 and tarBeat and hiZ built the drive; this line performs it.

A pad has two ends

The signature of espiPads is the longest thing in the file, and worth reading as a shape before reading it as a list. Five plain Signal inputs, four pad inputs, and a nine-element tuple out:

espiPads ::
  forall dom.
  (HiddenClockResetEnable dom) =>
  Signal dom Lanes ->                 -- engine lanesOut
  Signal dom Bit ->                   -- csOut
  Signal dom Bit ->                   -- sckOut
  Signal dom Bit ->                   -- rstOut
  Signal dom Bit ->                   -- ALERT# (raw, async, active-low)
  BiSignalIn 'PullUp dom 1 ->         -- IO0 pad (read side)
  BiSignalIn 'PullUp dom 1 ->         -- IO1 pad (read side)
  BiSignalIn 'PullUp dom 1 ->         -- IO2 pad (read side)
  BiSignalIn 'PullUp dom 1 ->         -- IO3 pad (read side)
  ( BiSignalOut 'PullUp dom 1         -- IO0 pad (drive side)
  , BiSignalOut 'PullUp dom 1         -- IO1
  , BiSignalOut 'PullUp dom 1         -- IO2
  , BiSignalOut 'PullUp dom 1         -- IO3
  , Signal dom Bit                    -- CS#    pin out
  , Signal dom Bit                    -- SCK    pin out
  , Signal dom Bit                    -- RESET# pin out
  , Signal dom (Vec 4 Bit)            -- ioIn    -> BusIn.ioIn
  , Signal dom Bit                    -- alertIn -> BusIn.alertIn
  )

Four of those inputs and four of those outputs are the same four wires.

That is the thing to understand about BiSignalIn and BiSignalOut: they are not two ports, they are two views of one port. A unidirectional signal has a direction baked into where it appears — an argument is an input, a result is an output. A bidirectional wire has no such luxury, because at different moments it is both. Clash’s answer is to split the wire into its two roles and make you name each: BiSignalIn is the net as something you may read, BiSignalOut is the net as something you may drive. Hand espiPads the read view of IO0 and it hands you back the drive view of IO0 — and when Clash lowers the design to Verilog, it recognises that the result was derived from the argument and fuses the pair into one inout port.^[2]

The 'PullUp in BiSignalIn 'PullUp dom 1 is a type-level tag for what the net does when nobody drives it, and here that is the physically honest answer for an eSPI bus: idle high. Every eSPI lane has a pull-up on the board, so a fully released net floats up rather than drifting undefined — which is why the turnaround drives high before letting go, settling the line to the level the pull-ups would have chosen anyway.^[3] The 1 is the width in bits: each lane is one wire, so each pad is a BiSignal … 1. And the whole thing carries HiddenClockResetEnable dom — not because the pads need a clock, but because alertSync, further down, holds two registers.

The last two results are the return path, and they are the fields the shape post introduced without saying where they came from:

data BusIn = BusIn
  { instrWord :: BitVector 32
  , ioIn :: Vec 4 Bit
  , alertIn :: Bit
  , startIn :: Bool
  }

ioIn is the four IO lanes sampled off the pads, that post said, and alertIn the synchronised alert pin. This module is the pads and the synchroniser. The loop the bus post ran — drive a beat, sample the far end, shift the bit in — closes here, through eight signal wires and four bidirectional ones.

Scalar, not Vec

The file’s longest comment is a warning, and it is the kind of warning that only gets written after somebody has lost an afternoon:

-- Per-lane scalar BiSignals, deliberately not a Vec. […] Clash fuses a scalar
-- BiSignalIn argument with the scalar BiSignalOut result derived from it into
-- one inout port per lane --- but if the lanes are routed through a Vec of
-- BiSignals (zipWith/map/:> over BiSignalIn/BiSignalOut), Clash treats the
-- vector as an opaque bundle and drops the drive: the inout ports get a read
-- path but no tri-state driver (the write collapses to a dead net).

Look at what this forbids, because the forbidden version is the version a Haskell programmer writes first. Four lanes, four identical operations, a Vec 4 already in hand from unbundle — of course you write zipWith writeToBiSignal pads laneSigs and get a Vec 4 (BiSignalOut …) back. It is one line instead of four, it is obviously correct, and every other four-lane operation in the project is written exactly that way. serializeX1 maps over eight bits. beatLanes returns a whole Vec 4. The ISA packs and unpacks by field. Tamal is a project that trusts Vec.

And the Vec version compiles, simulates correctly, and passes its tests. It produces silicon that cannot drive a pin.

The failure is entirely in the lowering. Clash’s inout support is a pattern-matching feature, not a type-level one: the compiler looks for a scalar BiSignalIn argument in the top entity’s signature and a scalar BiSignalOut result that was derived from it, and when it finds that pair it emits one inout port and wires the tri-state driver to it. Wrap the pair in a Vec and the pair is no longer visible — the argument is now one opaque aggregate and the result another, and the derivation relating them is buried inside a bundle the fuser does not open. So it does the only safe thing it knows: it keeps the read path, because reading an input is always valid, and it drops the write, because it cannot see which port the write belongs to. The result is a port that can be sampled and never driven. A pad that can only listen.

The type system will not save you here. The Vec version has the same type as the scalar version and does something different in Verilog.

Which is why the fix is not a fix but a shape: the lanes stay scalar end to end, four arguments in and four results out, spelled once each, and the tuple that returns them is nine elements long because collapsing it would undo the whole point.

espiPads lanesOut csOut sckOut rstOut alert pad0 pad1 pad2 pad3 =
  ( drive 0 pad0
  , drive 1 pad1
  , drive 2 pad2
  , drive 3 pad3
  , …

Four calls, hand-written, with the index and the pad matched up by eye. It reads like a regression rather than a design, and in a sense it is: this is the one place in Tamal where the natural Haskell abstraction has to be declined because the backend cannot see through it. The comment even records how the constraint was established — verified from the emitted Verilog: each io0..io3 must carry its own tri-state driver — which is the only way such a thing can be established. No test in the Haskell world distinguishes the two versions. You have to go read the output.

This is the introduction’s thesis arriving as a concrete scar. The pins are the hard part not because tri-state logic is conceptually difficult — it is two bits, and the serdes post spent five thousand words showing how simple — but because the pins are where your abstraction meets somebody else’s compiler, and the meeting has rules that live outside your type system. The engine got eight posts of increasingly confident reasoning. The pad boundary gets a hand-unrolled loop and a comment saying check the Verilog.

Reading the net back

The drive side is four scalars. The read side, one line down, is a Vec again:

ioIn =
  bundle
    ( readFromBiSignal pad0
        :> readFromBiSignal pad1
        :> readFromBiSignal pad2
        :> readFromBiSignal pad3
        :> Nil
    )

That looks like it should trip the same wire, and it does not — for a reason worth being precise about. The Vec here is not a vector of BiSignals. Each readFromBiSignal padK has already turned a pad into an ordinary Signal dom Bit, an everyday unidirectional value, and those are what get consed together and bundled into a Signal dom (Vec 4 Bit). The four pads are still touched one at a time, by name; only their sampled results are gathered. The rule is narrower than “no Vecs near pads” — it is that the fusible pair, the BiSignalIn argument and the BiSignalOut derived from it, must both be scalar and visible. Once a pad has been read into a plain Signal, ordinary Haskell resumes.

So the asymmetry in the source — four hand-written drive calls, then a four-element :> chain — is not inconsistency. It is the boundary of the constraint, drawn exactly where the constraint ends.

What comes out is Signal dom (Vec 4 Bit), which is BusIn.ioIn, which is where the bus post’s sampleGet was reading from all along:

PendGet{} -> t{shifter = shifter t `shiftL` 1 .|. zeroExtend (pack (ioIn inp !! (1 :: Index 4)))}

Index 1. IO[1], the eSPI response lane, sampled at the rising edge, shifted into the accumulator a bit at a time. That expression has been in the series since the bus post, and this is the first time we can point at the wire it names: readFromBiSignal pad1, the second of four, reading whatever the target is driving while all four of our own enables are low.

Note also that the read is combinational. readFromBiSignal puts no register in the path; what ioIn carries this cycle is the net’s level this cycle. The engine samples it inside stepBusBeat, at a phase of its own choosing, and the bus post chose phase 3 of the five-cycle beat — comfortably after the rising edge at the 2→3 boundary, comfortably before the next. The pad boundary does not schedule anything. It presents a level; the engine decides when that level means something.

Three wires that pass straight through

Three of the nine results are pure pass-through:

  , csOut
  , sckOut
  , rstOut

No transformation at all. The value that arrives is the value that leaves. And that is correct, because the shape post made a point of it: csN, sck and rstN are fields of the engine’s State, written by the transition function and read out by busOut, which means they emerge from the engine already registered — settled outputs of flip-flops, not combinational functions of this cycle’s inputs. There is nothing left to do to them. Adding a register here would only delay them by a cycle relative to the lanes, which are equally registered, and skew the bus.

So why route them through espiPads at all, if the function does nothing to them? Because the module’s job is to be the pad boundary, singular. It is the one place in the design where the outside world is named. A board shell that wired CS# straight from system and IO[0] through espiPads would have the pin list living in two places, and the next person to add a sideband would have to guess which. Routing all seven eSPI pins through one function costs three lines of nothing and buys a single answer to where do the pins leave. It is the same argument the UART top made for a module with no behaviour of its own: the value is in the wiring being in one place.

The one asynchronous wire

Everything else in Tamal is synchronous. The engine, the loader, the memories, the serialiser: one clock, one domain, every signal generated inside it. There is exactly one exception, and it is the only wire in the design that arrives from outside with no relationship to our clock at all:

alertSync ::
  (HiddenClockResetEnable dom) =>
  Signal dom Bit ->
  Signal dom Bit
alertSync alert = alert''
 where
  alert' = register high alert
  alert'' = register high alert'

Two registers in series, both initialised high. The receiver built the same thing for the same reason and spent a long section on why: an asynchronous input will eventually violate a flip-flop’s setup or hold window, that flop can go metastable — its output hovering at neither level for an unbounded time — and the second flop exists to give the first a whole clock period to settle before anything downstream is allowed to look. It does not make metastability impossible. It makes it improbable enough to ignore.^[4]

Two details are specific to this wire rather than to synchronisers in general.

The first is high. Both flops power up at one, and one is deasserted — ALERT# is active-low, as the trailing hash says. The receiver made the same choice for the idle-high UART line, and the argument is identical: a synchroniser that powers up at zero powers up believing the world is asserting something. Here that would be worse than a spurious byte. WAIT_ON blocks the engine until the alert asserts, so a synchroniser that came out of reset low would release a waiting engine on a signal that was never sent. Initialising the flops to the wire’s resting state is what makes the first two cycles of a run quiet instead of a lie.

The second is that this synchroniser is unconditional. The receiver’s flops were also clocked every cycle — deliberately not gated by the oversample tick, because a metastable strike does not wait for the tick — and the same holds here with nothing to gate it against. Two flops, every cycle, output lagging the raw pin by exactly two. That lag is the cost, and for this signal it is free: ALERT# is a request for attention with no timing requirement finer than the engine’s own beat, so two cycles at 100 MHz is twenty nanoseconds of latency on a signal that exists to be waited on.

Worth noticing where the synchroniser is, too. It is in the pad module, not in the engine and not in the board shell. That is the same placement argument the receiver made about rxLine: a wire is asynchronous because it comes from a pin, so it should be synchronised at the pin, and every consumer downstream can then treat it as ordinary. BusIn.alertIn is a clean synchronous bit because espiPads cleaned it. The engine never learns that one of its inputs came from outside the clock domain.

Synchronise a wire where it enters, once, and no one downstream has to know it was ever dangerous.

One lane, drawn

Four lanes, and they are four copies of one picture:

One of the four IO lanes, from the engine's arithmetic to the bonded pin. The accented path is the enable: toDrive collapses (o, oe) into a Maybe Bit, and writeToBiSignal turns Just o into a driven level and Nothing into a released output. When nobody drives, the 'PullUp holds the net at one. The same net is tapped combinationally by readFromBiSignal and returned as ioIn !! i, which is where the engine's sampleGet reads IO[1]. Clash fuses the scalar BiSignalIn argument and the scalar BiSignalOut result into the single inout port on the right — which is precisely why the four lanes may not be bundled into a Vec.

Four copies of this, plus three wires that pass through and one that gets caught by two flops, and the file is done.

The tests, and the knot

The test module is twice the length of the module it tests, and about half of it is comment explaining why the harnesses are shaped the way they are. That is unusual for this project, and the explanation is worth the detour, because it is about a hazard that only exists once signals become bidirectional.

Here is the problem. The obvious test for a pad boundary is a loopback: hand espiPads a net, let it drive that net, read the same net back through the same espiPads, and check that what you drove is what you sampled. The comment says what happens if you try:

-- NB: feeding espiPads's own drive-side 'outs' back into the 'padsIn' it also
-- reads makes the Clash BiSignal loopback diverge (self-drive + self-read knot).

It diverges — hangs, rather than failing. And it diverges for a reason that is not a bug: a bidirectional net’s value is a function of every driver on it, so to compute what the net carries, the simulator must first know what each driver is putting there. If one of those drivers is derived from a read of the same net, the value depends on itself. When the lane is driven the knot happens to untie, because Just o does not consult the net. When the lane is tri-stated it does not: the net’s level is only the other drivers, so Nothing leaves the simulator resolving a value defined in terms of itself, and Haskell’s laziness turns that into a loop rather than an error.

Which is a fair model of the world, if you think about it. A real net whose driver is a combinational function of its own level is a real oscillator. The simulator is not being difficult; it is refusing to invent a fixed point that hardware would not have.

So the harnesses split the loopback into its two directions, each with a single driver:

idleNet :: Vec 4 (BiSignalIn 'PullUp Dom100 1)
idleNet = repeat (veryUnsafeToBiSignalIn (mempty :: BiSignalOut 'PullUp Dom100 1))

idleNet is a net nobody drives — mempty is the empty set of drivers — so it reads as the pull-up’s idle high. It is the stub you hand espiPads when you want it to not depend on its read side. simSample gives espiPads a DUT-driven net and makes it a pure consumer; simDrive lets espiPads drive while handing it idleNet to read, and routes its drive-side results to a fresh reader. Two linear paths instead of one circular one, and the physical justification is one line of comment: the engine never drives and samples one lane in the same cycle. The thing the harness cannot simulate is a thing the design never does.

There is a second shim, and it is a small joke at the module’s expense:

espiPadsVec :: … Vec 4 (BiSignalIn 'PullUp dom 1) -> (Vec 4 (BiSignalOut 'PullUp dom 1), …)
espiPadsVec lanes cs sck rst alert pads = (d0 :> d1 :> d2 :> d3 :> Nil, …)
 where
  (d0, d1, d2, d3, csO, sckO, rstO, ioIn, alertO) =
    espiPads lanes cs sck rst alert (pads !! 0) (pads !! 1) (pads !! 2) (pads !! 3)

The tests wrap the scalar-per-lane interface back up into the Vec interface it was so carefully not given — because, as its comment notes, bundling BiSignals in a Vec is fine in simulation; only Clash synthesis needs the scalar-per-lane form for inout fusion. The constraint we spent a section on is a backend constraint, and the test bench, which never goes near the backend, is free to ignore it. That is worth stating plainly, because it is exactly what makes the scar dangerous: the version that breaks silicon behaves identically everywhere a Haskell programmer can see.

The assertions themselves are short. Two oracles, one per direction:

sampleOracle = map (maybe 1 id)
driveOracle  = map (\(o, oe) -> if oe == 1 then o else 1)

Read them together and they are the pull-up written twice. sampleOracle says a lane reads the DUT’s value when the DUT drives and 1 when it does not. driveOracle says a lane carries o when our enable is high and 1 when it is not. Both fall back to one, and both times the one is the pull-up. The Hedgehog properties then sweep random drive patterns against each model, and two testCases pin the interesting corners: drive nothing and everything reads high; drive lane zero only and read 0 :> 1 :> 1 :> 1 :> Nil, one driven low and three floating up.

One case reaches back a post and welds the two modules together:

testCase "io: x1 beat0 drives IO[0] only, IO[1..3] hi-Z (independent OE)"
  $ let byte = 0b0111_1111 :: BitVector 8   -- MSB (IO[0]) = 0
        lane0 = serializeX1 byte !! (0 :: Index 8)
     in L.head (simDrive [lane0]) @?= (0 :> 1 :> 1 :> 1 :> Nil)

That is not a made-up Lanes value — it is serializeX1’s beat zero, the real drive the engine emits for the first bit of a PUT. The byte 0b0111_1111 is chosen so the MSB is the only zero, so beat zero drives a low onto IO[0] while the other three lanes are released and pull up to one. The expected vector, 0 :> 1 :> 1 :> 1, therefore distinguishes a driven zero from a floating one by position alone. Change any part of the chain — the serialiser’s bit order, toDrive’s enable test, the per-lane indexing in drive — and the zero lands on the wrong lane or does not land at all. It is the smallest test in the file and the only one that checks the two modules agree about which wire is which.

The synchroniser gets three of its own, and the first is the clearest statement of what it does:

simAlert [1, 1, 0, 0, 0, 1, 1] @?= [1, 1, 1, 1, 0, 0, 0]

The input drops on sample two; the output drops on sample four. Two cycles, exactly, and the leading ones are the init-high flops showing through before the pin’s own value has walked the pipeline. A property test then holds the general form against a three-line reference model — refAlert xs = take (length xs) (1 : 1 : xs), which is the input with two idle-high samples in front of it — and a second testCase checks that a single-cycle assertion survives the trip rather than being swallowed. That last one matters: a synchroniser is allowed to delay a pulse but not to eat it, and a one-cycle ALERT# that vanished on the way in would strand a WAIT_ON forever.

Even the sideband pass-through is tested, which sounds like testing that id is id — and functionally it is:

simSide xs H.=== xs

But the property is not really about the function. It is about the wiring: that CS#, SCK and RESET# come out in that order, uncrossed, unregistered and unmolested. Swap two of the nine result positions in espiPads and this is the test that goes red.

What we read

A hundred and four lines, and the series has crossed out of arithmetic. Tamal.Io imports nothing but Clash.Prelude and the Lanes type, and it does four things. It turns each lane’s (value, enable) pair into a Maybe Bit with toDrive — four states collapsed onto three, the redundancy of a released-but-valued lane finally made unwritable — and hands that to writeToBiSignal, which is the tri-state driver the serdes post promised the pair would one day meet. It taps each net back with readFromBiSignal and bundles the four into BusIn.ioIn, the vector sampleGet has been indexing since post three. It passes CS#, SCK and RESET# through untouched, because they left the engine already registered and the only value in routing them here is that the pin list then lives in one place. And it catches ALERT#, the single asynchronous wire in the design, with two flops that both power up deasserted, so a WAIT_ON is never released by a signal nobody sent.

The scar in the middle of it is the one the introduction predicted. Four lanes that every instinct in the project says should be a Vec 4 have to be four scalar arguments and four scalar results, because Clash fuses inout ports by matching a scalar BiSignalIn with the scalar BiSignalOut derived from it, and a Vec of BiSignals hides the match — silently keeping the read path and dropping the driver. The types do not distinguish the two versions. The simulation does not distinguish them; the test bench cheerfully wraps the scalar form back into a Vec because in simulation the Vec is fine. Only the emitted Verilog distinguishes them, which is why the comment says to go and look. Eight posts of the engine could be reasoned about from the source alone. The first post of the shell cannot.

The pads exist now, and they are wired to nothing. espiPads takes a Signal dom Lanes and produces four inout ports, but the design that computes those lanes — the engine, the loader that feeds it a program, the two block RAMs it reads and writes, the UART that carries frames in and out — is still a pile of modules that have never been connected to one another. Every piece has been read; none of them have been joined. The next post joins them: one function that takes a UART line and the four sampled bits and gives back a serial line, a drive, three sidebands and a status LED, with the engine’s pure step lifted into a clocked signal at the centre of it and every module in the series hanging off the result. Everything, wired.

unbundle :: Signal dom (Vec n a) -> Vec n (Signal dom a) turns a signal of vectors into a vector of signals, and bundle goes the other way. Both are identities on the hardware — a Vec 4 Lane was always four separate pairs of wires, and neither combinator adds a gate — so the pair exists purely to let you choose which shape is convenient at each point in the source. Here the choice is forced by what comes next: writeToBiSignal wants a Signal dom (Maybe Bit) per pad, one pad at a time, so unbundle splits the engine’s single lane signal into four the moment it arrives. readFromBiSignal then produces four separate Signal dom Bits, and bundle regathers them because BusIn.ioIn is a Vec 4 Bit. The module unbundles on the way out and bundles on the way back, and both moves are free. The primer’s point about Signal being a stream you map over rather than a value you inspect is what makes this legal: toDrive <$> laneSig applies a pure function at every cycle at once, which is exactly what a combinational circuit is. ↩
In Verilog a port is input, output, or inout, and only the third can be both driven and read by the module that declares it. Clash has no inout in its type system — BiSignalIn and BiSignalOut are ordinary Haskell types — so the mapping is done structurally at lowering time: the compiler looks for a top-entity argument of type BiSignalIn ds dom n and a result of type BiSignalOut ds dom n that was produced from that argument, and emits a single inout port carrying both roles, with the Maybe given to writeToBiSignal becoming the value and output-enable of a tri-state driver on that port. Nothing lowers to the driver disabled, which in Verilog is an assignment of 1'bz. The recognition is syntactic in the sense that matters: it depends on the shape the pair appears in, not on the types alone. Route the pair through a Vec — zipWith writeToBiSignal pads lanes, or even a map over the results — and the argument becomes one opaque aggregate and the result another, with nothing at the port boundary relating lane k of one to lane k of the other. Clash keeps what it can prove, the read, and discards what it cannot place, the write. The emitted module still has four inout ports and still compiles; each one is simply never driven, so the bus sits at its pull-ups forever and every GET returns ones. Nothing in Haskell reports this. The verification step recorded in the source comment — read the Verilog, confirm each of io0..io3 carries its own tri-state driver — is the whole of the available evidence, which is why it is written down. ↩
BiSignalIn’s first parameter is a BiSignalDefault, a type-level tag saying what the simulator should believe an undriven net carries: 'PullUp for one, 'PullDown for zero, 'Floating for undefined. It generates no hardware — a real pull-up is a resistor on the board or a pad attribute in the constraints file, not a gate in your netlist — so the tag is a claim about the physical world that you are responsible for making true elsewhere. 'PullUp is the correct claim for eSPI: the bus idles high, every lane has a pull-up, and a released net rises rather than drifting. It is also what makes the test oracles read the way they do, both falling back to 1 whenever nothing drives. Get the tag wrong and simulation quietly disagrees with the board about what a floating wire means — and since the whole point of a tri-state bus is that wires spend most of their time floating, the disagreement would not be a corner case. ↩
The receiver post worked this through at length, so only the shape is worth repeating. A flip-flop sampled while its input is changing can enter a metastable state, in which its output sits between the two valid levels for an unbounded — though exponentially improbable — time. You cannot prevent the first flop from going metastable, because the input is asynchronous and asynchronous means will eventually violate setup and hold. What a second flop buys is a full clock period of settling time before any logic downstream is allowed to look, which pushes the mean time between failures from seconds to geological. Two flops is the standard dose; safety-critical designs add a third. ALERT# gets two, and the choice to run them unconditionally — no enable, every cycle — matters for the same reason it mattered in the receiver: a strike arrives when the outside world decides, not when your logic is ready for it. The cost is a fixed two-cycle lag, and for a signal whose consumer is a blocking wait, twenty nanoseconds is not a cost at all. ↩

Tamal: The Record and the Ring

2026-08-12T09:00:00+00:00

The wire post left a word-stream sealed. encodeResult wrapped a drained ring — a REVISION word, some records, a HALT terminator — behind an opcode and never looked inside. This post looks inside. It is the smallest file of the whole descent, sixty-four lines, and it is the pure twin the bus post kept promising: every time the engine packed a CAPTURE or a MARK or a HALT inline, a comment said mirrors Trace.encodeRecord. Tamal.Trace is that mirror.

Like Tamal.Wire, nothing here runs on the fabric. encodeRecord returns a list; ringPush recurses over one. The engine emits at most one word per cycle, inline, in the fast synchronous path the bus post read. This module exists so the layout lives somewhere readable, and a test can prove the fast path and the readable model agree. Two functions on the door:

module Tamal.Trace
  ( Record (..)
  , encodeRecord
  , ringPush
  ) where

Three shapes

A run leaves behind a stream of records, and there are exactly three kinds:

data Record
  = Capture (BitVector 4) (BitVector 8)          -- nbits (1..8), sampled byte
  | Mark (BitVector 14) (BitVector 32)           -- label, payload
  | Halt Bool (BitVector 3) Bool (BitVector 8)   -- trap, reason, overflow, status

These are the same three the bus post met from the engine side. Capture reports a sampled byte with its valid-bit count; Mark carries a host↔trace correlation label and a register payload; Halt terminates the run, folding in the sticky trap and overflow flags, a 3-bit reason, and a status byte. What the engine built with hand-rolled bitCoerce calls, this type names.

One encoder, laid in field rulers

encodeRecord is the whole point of the file — three lines, one per shape:

encodeRecord :: Record -> [BitVector 32]
encodeRecord = \case
  Capture n b        -> [bitCoerce (0b00 :: BitVector 2, 0 :: BitVector 18, n, b)]
  Mark lbl pl        -> [bitCoerce (0b10 :: BitVector 2, 0 :: BitVector 16, lbl), pl]
  Halt trp rsn ovf st -> [bitCoerce (0b11 :: BitVector 2, 0 :: BitVector 17, rsn, trp, ovf, st)]

Read these against the engine’s inline builders and they are identical tuples. captureWord was bitCoerce (0b00, 0 :: BitVector 18, nbits, byte); markLabelWord was bitCoerce (0b10, 0 :: BitVector 16, lbl); haltWith built bitCoerce (0b11, 0 :: BitVector 17, reason, trap, ovf, status). Same tags, same zero padding, same field order. The engine open-codes them for speed; this gathers them in one place you can actually read. (The REVISION preamble lives in the engine, not here — this is the record encoder, nothing more.)

Every shape sums to a clean 32 bits, and the two-bit tag column is what a host reads first to know which shape follows:

The three record shapes as 32-bit field rulers, each field's width drawn in proportion to its bit count. Each first word opens with a two-bit tag (accented) the host reads to know which shape follows; every row spans a full 32 bits. In HALT, t and o are the single-bit trap and overflow flags. MARK is the only two-word record --- its label word then a full 32-bit payload --- which is exactly why the push has to be atomic.

The test-style oracle is a handful of literal-shift assertions — Capture 8 0xA5 must equal 0b00 << 30 | 8 << 8 | 0xA5, Mark 0x1234 0xDEADBEEF must be two words with the label in the first and the payload verbatim in the second — each computed by a different arithmetic than bitCoerce, so a drift in field placement would show as a mismatch against a number no bitCoerce produced.

The push that never tears

The other function is the ring discipline, made pure:

ringPush ptr limit ovf ws
  | ovf       = (ptr, True, [])
  | fits      = (ptr + count, False, ws)
  | otherwise = (ptr, True, [])
 where
  count = fromIntegral (L.length ws)
  fits  = L.length ws > 0 && (ptr + count - 1) <= limit

Three cases, and they are the whole drop-on-full contract the bus post met a word at a time. Already overflowed: drop the record, keep the sticky flag high. Fits — the last index this record would occupy, ptr + count - 1, stays within limit — write every word and advance the pointer by the record’s whole word count. Otherwise: drop, and latch overflow. The pointer never lands past limit, so the terminator slot beyond it is always free for the HALT that ends the run.

The load-bearing word is atomically. ringPush writes all of a record’s words or none of them — where the engine’s pushWord went one word per cycle, this goes record at a time. The reason is Mark: it is two words, and a Mark half-written — its label word in the ring, its payload word dropped at the limit — desyncs the host’s parse, because the host reads the label, expects a payload word next, and finds the HALT terminator instead. Both words or neither. The test pushes ten one-word records into a ring with limit = 3 and checks the invariants the contract promises: the pointer never passes limit + 1, at most four words are ever written, and the sticky overflow flag ends True.

What we read

Sixty-four lines, and both formats are now closed. Tamal.Trace is the record side made pure: three Record shapes — Capture, Mark, Halt — encodeRecord laying each into 32-bit words with the exact bitCoerce tuples the engine builds inline, and ringPush enforcing the drop-on-full, never-past-the-limit, record-atomic push whose atomicity exists to keep a two-word MARK from tearing. Not because the fabric calls any of it — the fabric emits a word a cycle in its own fast path — but because a readable specification is what lets a test prove the fast path honest. The third time the series has kept a pure twin alive for exactly this reason, after the serdes finale’s deserializeX1 and the wire post’s whole reference model.

The wire carries a program in; the trace carries a run out; both are pure and done. What is left is not a format at all — it is the impure shell that turns (value, enable) pairs into real pins that float and drive. That crossing, out to the silicon, is the next post.

Tamal: Frames on the Wire

2026-08-11T09:00:00+00:00

The engine is open entire. The outside-in descent that began with the shape post’s map of eight boxes ended when the serdes finale opened the last of them, and everything the fabric does — fetch, decode, compute, drive the pins, record what happened — has now been read leaf by leaf. But a running engine on a board is only half a system. A host has to load a program into it and read a trace back out of it, and between the host and the fabric there is a wire. This post is about what travels on that wire: not the electrical layer, not the UART that carries the bytes, but the format — the seams that turn a bare stream of bytes into messages a host and an FPGA can agree on.

We have been here before, from the other side. The loader was “the streaming realization of the pure Tamal.Wire model,” and the COBS-codec post realized the streaming byte-stuffing the loader clocks a byte at a time. Both of those posts implemented something. This post opens the thing they were implementing against — the pure reference model they were proven equal to. It is two files, Tamal.Wire.Cobs (68 lines) and Tamal.Wire (158), and neither of them ever runs on the fabric. They are pure [BitVector 8] functions over ordinary lists, the same “honest surplus” the serdes post’s unused deserializeX1 was: a readable specification that exists so the hardware has something to be checked against.

Two files, three layers, read bottom-up: the byte-stuffing that removes every zero, the frame that wraps a payload in a CRC and a delimiter, and the messages the frames carry. We start at the bottom, with the leaf that owes nothing to anyone.

The leaf that removes every zero

A bare stream of bytes has no seams. Send two messages back to back and the receiver cannot tell where the first ends and the second begins — unless you reserve a byte to mean stop here. The obvious candidate is 0x00, but it is only usable as a delimiter if it never appears inside a message, and real payloads are full of zeros. COBS — Consistent Overhead Byte Stuffing — buys that guarantee cheaply: it removes every 0x00 from a payload, at a cost of at most one extra byte per 254, so a single 0x00 can be reserved — unambiguously — to mean end of frame.

Tamal.Wire.Cobs is the pure model of that transform, and its door lists two functions:

module Tamal.Wire.Cobs
  ( cobsEncode
  , cobsDecode
  ) where

import Clash.Prelude
import qualified Data.List as L

It is a leaf: it imports no other Tamal.Wire.* module, only the prelude and Data.List. That isolation is deliberate — COBS knows nothing about CRCs, opcodes, or frames; it is a pure list-to-list transform, and everything above it in the stack treats it as a black box that removes zeros and puts them back.

The encoder groups the input:

cobsEncode :: [BitVector 8] -> [BitVector 8]
cobsEncode = go []
 where
  go grp [] = emit grp
  go grp (b : bs)
    | L.length grp == 254 = emit grp <> go [] (b : bs) -- group full: flush, reprocess b
    | b == 0 = emit grp <> go [] bs -- zero terminates the group (implied)
    | otherwise = go (grp <> [b]) bs
  emit grp = fromIntegral (L.length grp + 1) : grp

Read emit first, because it defines the shape of the output. A group is a code byte followed by its data bytes, and the code byte is length + 1 — so an empty group emits [0x01], a group of three data bytes emits [0x04, …]. The + 1 is what keeps zeros out of the code byte itself: the smallest code is 0x01, never 0x00, so no code byte can ever collide with the delimiter.

Then go walks the input, accumulating non-zero bytes into grp. Three arms, and the order they are written in is the whole subtlety of the algorithm:

b == 0 terminates the group. The zero is consumed — it never appears in the output — and its presence is recorded implicitly, by the fact that a new group starts after it. A code byte less than 0xFF means “this group was closed by a zero the encoder ate,” and the decoder puts that zero back.
otherwise appends the non-zero byte and keeps going.
length grp == 254 is checked first, before either of the others, and that ordering is load-bearing.

The load-bearing case is worth slowing down for, because it is the one bug this whole design is arranged to avoid. A group can hold at most 254 data bytes — the code byte is length + 1, and 254 + 1 = 255 = 0xFF is the largest byte. When a group fills to 254, it must be flushed, and the flush code 0xFF carries a special meaning: this group was full, not closed by a zero. There is no implied zero after a 0xFF group.

Now imagine a zero arrives exactly when the group is full. If the b == 0 case ran first, the zero would fold into the full group — which flushes as 0xFF, which carries no implied zero — and the zero would silently vanish on decode. Checking length == 254 first prevents that: the full group flushes as 0xFF and reprocesses b in a fresh empty group, so a zero landing on a full boundary terminates that fresh group and survives as an implied zero. The source comment spells it out, and there is a regression test pinned to exactly this input:

testCase "cobsEncode 254 non-zero then 0x00 == FF,<254>,01,01"
  $ cobsEncode (run254 <> [0x00])
  @?= (0xFF : run254) <> [0x01, 0x01]

The 0xFF flushes the full group, and the trailing [0x01, 0x01] is a fresh empty group (code 0x01) closed by the zero (another 0x01). Fold the zero into the full group and that [0x01, 0x01] disappears — and so does the zero. This is the same ordering the streaming COBS post had to get right in its s -> i -> (s, o) form: same algorithm, same trap, two realizations, and the differential tests weld them together.

Putting the zeros back

cobsDecode is the inverse, and it carries the totality discipline the whole series leans on: it returns Maybe, Nothing on anything malformed.

cobsDecode :: [BitVector 8] -> Maybe [BitVector 8]
cobsDecode bytes
  | L.null bytes = Nothing -- empty is not a valid frame
  | L.elem 0 bytes = Nothing -- a valid (delimiter-stripped) frame has no 0x00
  | otherwise = go bytes
 where
  go [] = Just []
  go (code : rest) =
    let n = fromIntegral code - 1 -- data bytes in this group
     in do
          (grp, more) <- takeExactly n rest
          if L.null more
            then Just grp -- final group: no trailing zero
            else do
              decoded <- go more
              Just (grp <> (if code == 255 then [] else [0]) <> decoded)

The two guards reject the two ways a delimiter-stripped frame can be malformed on its face: it cannot be empty, and it cannot contain a 0x00 — because COBS by construction removed all of them, so a zero in the input means corruption. Everything else is handled by go, one group at a time. It reads the code byte, takes exactly code - 1 data bytes via takeExactly (which returns Nothing if the input is too short — a code byte demanding more bytes than remain), and then decides whether to reinsert a zero. The final group — more is empty — gets no trailing zero, because nothing came after it. An interior group gets a zero unless its code was 0xFF, because 0xFF means “full group, no implied zero,” the exact flag cobsEncode set.

That single if code == 255 then [] else [0] is the decoder’s half of the load-bearing case. It is why the full-group flush and the zero-terminated group decode back to different things, and why the regression test round-trips.

The round-trip law is stated as a property, and it is tested over two generators for a reason:

testProperty "cobsDecode . cobsEncode == Just" $ property $ do
  xs <- forAll (Gen.list (Range.linear 0 300) genByteZeros)
  cobsDecode (cobsEncode xs) === Just xs

genByteZeros is zero-dense — it produces many group boundaries by emitting frequent zeros — but by design it cannot build a 254-byte non-zero run, so it never reaches the full-group cap. A second generator, genRuns, concatenates non-zero runs up to 260 long, each optionally followed by a single zero, so it crosses the 254 boundary and exercises the full-group / trailing-zero interaction directly. Two generators, one law, and the boundary the first one cannot reach is exactly where the algorithm is subtlest.

From bytes to a word, and back

With the zero-stuffing in hand, we climb to Tamal.Wire, and its first job is smaller than COBS: turn a 32-bit instruction word into bytes. The engine speaks 32-bit words; the wire speaks bytes; something has to choose an order.

wordToBytesLE :: BitVector 32 -> Vec 4 (BitVector 8)
wordToBytesLE = reverse . unpack

bytesToWordLE :: Vec 4 (BitVector 8) -> BitVector 32
bytesToWordLE = pack . reverse

unpack splits the word into a Vec 4 (BitVector 8) with the most significant byte first; reverse flips it to little-endian — least significant byte first, so 0xAABBCCDD becomes <0xDD, 0xCC, 0xBB, 0xAA> (ISA §4). This is a detail worth naming out loud, because it runs against the grain of everything the bus side of the engine did: the CRC post and the serdes post both unpacked bytes MSB-first onto the eSPI wire, because that is what the eSPI spec demands. Here, the host transport is little-endian — the natural order for a host CPU writing words to a serial port. The two orderings live in different worlds and never meet: the eSPI wire is MSB-first, the host word transport is LE, and wordToBytesLE is the seam that keeps them straight.

The inverse is pack . reverse, and bytesToWordLE (wordToBytesLE w) == w falls out by construction — reverse is its own inverse and pack/unpack are total, zero-cost reinterpretations. The test states it as a property and pins the concrete vector:

testCase "wordToBytesLE 0xAABBCCDD == [DD,CC,BB,AA]"
  $ toList (wordToBytesLE 0xAABBCCDD)
  @?= [0xDD, 0xCC, 0xBB, 0xAA]

The CRC, one layer up

A frame needs integrity, and the CRC post already built the primitive: crc8Update, one byte folded into a running CRC-8 (polynomial 0x07, initial 0x00, MSB-first). Tamal.Wire reuses it, unchanged, one layer up:

crc8 :: [BitVector 8] -> BitVector 8
crc8 = L.foldl' crc8Update 0

That is the whole function — fold crc8Update over a byte list, starting from 0. The CRC block did the hard per-byte arithmetic; the frame layer just sequences it over a payload. And because it is the CRC-8/SMBUS parameterization, it satisfies the standard check vector, which the test uses as an independent oracle:

testCase "crc8 matches CRC-8/SMBUS check vector (0xF4)"
  $ crc8 [fromIntegral (fromEnum c) | c <- "123456789"]
  @?= 0xF4

The string "123456789" is the canonical CRC check input, and 0xF4 is the published CRC-8/SMBUS result. If the polynomial or the fold order ever drifted, this one line would catch it against a number no Tamal code produced.

The frame: CRC, then stuff, then delimit

Now the three pieces — CRC, COBS, delimiter — assemble into a frame. The encoder is one line, and the order of operations is the entire format:

frameEncode :: [BitVector 8] -> [BitVector 8]
frameEncode logical = cobsEncode (logical <> [crc8 logical]) <> [0]

Read it inside out. Start with the logical bytes (an opcode and its payload). Append the CRC of those bytes. COBS-encode the whole logical ++ [crc] blob — which removes every 0x00 from it. Then, and only then, append a single 0x00 delimiter. The delimiter is safe precisely because COBS guaranteed there are no other zeros in front of it: the one 0x00 on the wire is unambiguously the end of the frame.

A frame is built in four steps. The logical bytes are an opcode and its payload; frameEncode appends the CRC-8 (accented), COBS-encodes the whole blob so every interior 0x00 is removed and each group gains a leading code byte, then appends a single 0x00 delimiter (accented) --- the only zero on the wire, and therefore an unambiguous end-of-frame marker.

The decoder runs the pipeline backwards, and every step that can fail names its failure:

frameDecode :: [BitVector 8] -> Either WireError [BitVector 8]
frameDecode wire = do
  stripped <- stripDelim wire
  content <- maybe (Left BadCobs) Right (cobsDecode stripped)
  (logical, crc) <- splitLastByte content
  if crc8 logical == crc
    then Right logical
    else Left BadCrc

Strip the trailing 0x00 delimiter (stripDelim, failing ShortFrame on empty or BadCobs if the last byte is not a zero), COBS-decode (lifting the codec’s Nothing to BadCobs), split off the trailing CRC byte, and verify it against a freshly recomputed CRC. Four steps, each in the Either WireError monad, so the first failure short-circuits and names itself.

That WireError sum is the same “total, named failures” discipline as the ISA post’s DecodeError:

data WireError
  = BadCrc          -- CRC byte did not match the recomputed CRC
  | BadCobs         -- malformed COBS or missing delimiter
  | UnknownOpcode (BitVector 8)
  | ShortFrame      -- decoded frame lacks an opcode and/or CRC byte
  | BadPayloadLen   -- payload length invalid for the opcode
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

Five ways a frame can be wrong, each a constructor, none of them an exception or a crash. A decoder that returns Either WireError cannot silently accept a corrupt frame — the caller must handle every arm — and the property test proves the pipeline never lies:

testProperty "single-byte corruption is never a silent success" $ property $ do
  xs <- forAll (Gen.list (Range.linear 1 32) genByte)
  let f = frameEncode xs
  i <- forAll (Gen.int (Range.linear 0 (L.length f - 1)))
  let f' = [if j == i then x `xor` 1 else x | (j, x) <- L.zip [0 ..] f]
  frameDecode f' /== Right xs

Flip a single bit anywhere in a valid frame and decode must not return the original bytes. It might return a Left of some WireError, or a Right of different bytes — but never a silent success on corrupted input. That is the CRC earning its byte, checked at every position in the frame.

The messages the frames carry

The top layer gives the frames meaning. A frame is just an opcode and a payload; a message is what those mean. Two directions, host-to-FPGA control and FPGA-to-host results, and a small type for the control plane:

data ControlMsg
  = LoadProgram [BitVector 32]  -- instruction words to load into the instr BRAM
  | Trigger                     -- start-of-run pulse
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

Three opcodes name the traffic (§8.1), and 0x00 is conspicuously not among them, because it is the delimiter and can never be an opcode:

opLoadProgram = 0x01
opTrigger     = 0x02
opTraceDrain  = 0x81

Encoding a control message is opcode-prefix plus payload, run through frameEncode:

encodeControl :: ControlMsg -> [BitVector 8]
encodeControl (LoadProgram ws) =
  frameEncode (opLoadProgram : L.concatMap (toList . wordToBytesLE) ws)
encodeControl Trigger = frameEncode [opTrigger]

LoadProgram splits each 32-bit word into its four little-endian bytes and concatenates them behind the opcode; Trigger is a lone opcode with no payload. Decoding reverses it and enforces the per-opcode payload rules:

decodeControl :: [BitVector 8] -> Either WireError ControlMsg
decodeControl wire = do
  logical <- frameDecode wire
  case logical of
    [] -> Left ShortFrame
    (op : payload)
      | op == opLoadProgram -> LoadProgram <$> bytesToWords payload
      | op == opTrigger ->
          if L.null payload then Right Trigger else Left BadPayloadLen
      | otherwise -> Left (UnknownOpcode op)

Every branch is total: an empty logical frame is ShortFrame, a Trigger with a non-empty payload is BadPayloadLen, an opcode outside the set is UnknownOpcode op carrying the offending byte. And LoadProgram defers to bytesToWords, which regroups the little-endian byte payload back into words and refuses anything that is not a clean multiple of four:

bytesToWords :: [BitVector 8] -> Either WireError [BitVector 32]
bytesToWords [] = Right []
bytesToWords (a : b : c : d : rest) =
  (bytesToWordLE (a :> b :> c :> d :> Nil) :) <$> bytesToWords rest
bytesToWords _ = Left BadPayloadLen

Four bytes make a word; zero bytes left over is success; one, two, or three trailing bytes is BadPayloadLen. A program is a whole number of 32-bit instructions or it is not a program.

The result direction is the mirror. encodeResult wraps a drained ring word-stream — the REVISION word, the records, the HALT terminator (§8.3) — behind the opTraceDrain opcode, and decodeResult unwraps it:

encodeResult ws = frameEncode (opTraceDrain : L.concatMap (toList . wordToBytesLE) ws)

decodeResult wire = do
  logical <- frameDecode wire
  case logical of
    [] -> Left ShortFrame
    (op : payload)
      | op == opTraceDrain -> bytesToWords payload
      | otherwise -> Left (UnknownOpcode op)

Same shape as the control path, same LE byte regrouping, same named failures — and the content of that word-stream, the records the ring holds, is the subject of the next post. The two directions round-trip in tests (decodeControl . encodeControl == Right, decodeResult . encodeResult == Right), and each rejects the other’s opcodes: a Trigger frame fed to decodeResult comes back Left (UnknownOpcode 0x02), because the result decoder answers only to 0x81.

The reference-model role, made explicit

Nothing in either file is synthesizable. cobsEncode builds an unbounded list with <>; bytesToWords recurses over a list of runtime-unknown length; frameDecode returns Either — these are ordinary Haskell over [BitVector 8], and no fabric ever runs them. So why do they exist, if the loader already implements the streaming form the hardware actually clocks?

Because the streaming form needs something to be right against. The loader walks the wire a byte per cycle, threading state through a mealy machine; Tamal.Wire describes the same result in one pure pass over a list. The two are welded together by differential property tests — feed both the same input, assert the same output — so the readable model is the specification and the streaming machine is the implementation, and the tests prove they agree. This is the third time the series has used this move: the serdes post’s deserializeX1, the Tamal.Trace model the bus post kept pointing at, and now the wire format. Each is a pure twin kept alive not because the fabric calls it, but because a specification you can read is what lets you trust the machine you cannot.

What we read

The pure wire format, opened whole. Tamal.Wire.Cobs first — the leaf that removes every 0x00 so one 0x00 can delimit frames, its groups a code byte (len + 1) and up to 254 non-zero data bytes, its one subtle case the full group flushed as 0xFF before the zero case is checked, so a zero on a full boundary opens a fresh group instead of vanishing. Then Tamal.Wire above it: wordToBytesLE splitting a word into little-endian bytes (the host transport LE, against the eSPI wire’s MSB-first), crc8 folding the CRC post’s crc8Update over a list, frameEncode appending the CRC then COBS-encoding then the delimiter, and frameDecode undoing it through a WireError sum of named failures. And the message layer on top: ControlMsg, the 0x01/0x02/0x81 opcodes, the control and result codecs, bytesToWords insisting on whole words. All of it pure, all of it a specification the loader and the streaming COBS codec were proven equal to.

The wire carries a program in and a trace out. We have read the program side — LoadProgram, the words, the LE bytes. The trace side ended at encodeResult, wrapping a word-stream this post never looked inside: the REVISION word, the records, the HALT terminator. Those records — what a CAPTURE packs, what a MARK carries, how the ring pushes them without ever tearing a two-word record in half — are the Tamal.Trace model, the pure twin the bus post kept promising. That is the next post, and with it both formats, in and out, are done — and the series turns, at last, to the impure shell that makes the pins physical.

Tamal: Value and Enable

2026-08-10T09:00:00+00:00

The compute post ended on the one leaf still shut, and it named that leaf by what it does rather than what it is: the drive on the lanes when a PUT walked the beats, the turnaround when the bus changed hands, a byte becoming MSB-first bits on IO[0] — all of it, it promised, built out of a single tiny type, a (value, enable) pair, the whole tri-state story in two bits. That type and the handful of functions around it are Tamal.Bus.Serdes, and they are the last box in the engine. This post opens it.

It is the leaf nearest the wire and the smallest of all of them — fifty-four lines, no clock, no state, every function a pure combinational map from a byte or an index to the drive on four pins for one bus beat. Post 3’s beatLanes reached into it three times without once looking inside: hiZ to release the bus for a GET, tarBeat to turn it around, serializeX1 to lay a byte out bit by bit for a PUT. Post 1’s State carried a Lanes in a field and idled it to hiZ at reset; post 2’s startPut primed the first beat with serializeX1 byte !! 0 as it armed a transfer. We have been leaning on this module since before we could name it. Now we read how two bits carry a whole bus.

The last door

A Haskell file opens by naming itself and its door, and this one’s door is short:

module Tamal.Bus.Serdes
  ( Lane
  , Lanes
  , hiZ
  , driveHigh
  , serializeX1
  , deserializeX1
  , tarBeat
  ) where

import Clash.Prelude

Seven names, and the shape of the list is worth a beat before the code behind it. Two of the seven are types — Lane and Lanes — and the other five are functions that build or transform them. The CRC’s image of a module as a wall with a door in it holds: the export list is the complete public surface, and everything the module can do leaves through one of these seven names. But the more telling line is the one beneath it. import Clash.Prelude, alone, with no hiding clause and nothing qualified.

The compute post made a small drama of its imports — the ALU hiding And and Xor from the prelude, pulling Isa in qualified, two scars from two naming collisions. Serdes has none. Its vocabulary — Lane, Lanes, hiZ, serializeX1, tarBeat — collides with nothing in Clash.Prelude and nothing in the rest of Tamal, so it borrows no trouble and needs no clause to keep its names clear. The lone prelude swap is the one line every block in the project carries, the line that turns a Haskell file into a hardware description, and here it is the only import. This is as plain as a module header gets, and the plainness is a fair advertisement for what is inside: no cleverness, no ceremony, just two bits and what you can do with them.

A tuple, on purpose

The whole module rests on one line, and it is a type synonym:

-- | One I/O lane's per-beat drive state: (output value, output enable).
type Lane = (Bit, Bit)

A Lane is a pair of bits: an output value and an output enable. That is the entire type, and the choice to write it as a type synonym — a bare alias for (Bit, Bit) — rather than a newtype wrapper is the first decision worth reading. The CRC post gave us the image of a module as a wall with a door; a newtype is a wall of its own, a distinct type the compiler forces every caller to construct and unwrap. A type synonym is the opposite:

If a module is a wall with a door in it, a type synonym is a door with no wall — a nickname.

Lane and (Bit, Bit) are the same type; Lane is only a more readable name for it. Everywhere the engine touches a lane — pattern-matching it, reading its value with fst and its enable with snd, building one with (v, e) — it does so with ordinary tuple machinery, no wrapper in the way. For a type this pervasive — carried in the State, produced eight at a time by the serialiser, compared bit-for-bit in the tests — that transparency is exactly right: a newtype would buy a little safety against confusing a lane with some other pair and charge for it in Lane (…) and unLane noise on every use. The author declined the wall because there is nothing behind it to hide.

So what do the two bits mean? This is the sentence the whole eSPI story compresses into. A wire on a shared, bidirectional bus is not simply high or low — it has a third state, released, in which this end drives nothing at all and lets the other end drive instead. That released state — high-impedance, hi-Z — is what makes a bus bidirectional: one physical wire that the controller drives on a PUT and the target drives on a GET, so long as the two never drive at once. One bit cannot express three states. It takes a second:

The value says what to put on the wire; the enable says whether to put anything there at all — and on a shared bus, the enable is the bit that keeps two drivers from fighting.

When oe = 1, the pad drives value onto the pin. When oe = 0, the pad lets go — the pin floats, the value bit is a don’t-care, and whatever is on the other end owns the wire. Two bits, four combinations, but only three distinct behaviours: drive-0, drive-1, and release, which is (0, 0) and (1, 0) both, the value ignored once the enable is low. The redundancy is not waste; it is the shape of the thing. The value is a suggestion the enable may veto, and on a bus where two simultaneous drivers is not a wrong answer but a short circuit, the enable is the load-bearing bit.^[1]

Four lanes, one beat

One lane is two bits; the bus is four lanes, so its drive state is four of those pairs:

-- | The drive state of all four I/O lanes for one SCK beat.
type Lanes = Vec 4 Lane

Lanes is a Vec 4 Lane — a fixed-length vector of four (Bit, Bit) pairs, one per I/O wire, IO[0] through IO[3], all for a single bus beat. This is the type post 1’s State held in its lanes field and the type post 3’s beatLanes returned: the complete instruction to the pins for one tick of the serial clock, four wires at once. Eight of these, walked one at a time, drive a byte; post 3 did the walking, indexing serializeX1 (shifter t) !! bi a beat per rising edge.

Four is more than x1 needs. Single-I/O drives one wire and releases the other three, so three of the four pairs in every PUT beat are the same released (0, 0). The width is built for a bus this module does not yet serialise: dual-I/O uses two wires, quad all four, and Lanes is sized for the widest of them from the start. It is the same deliberate room to grow the ISA post found in Reg — a five-bit selector naming thirty-two registers when v1 implements sixteen — the type describing the whole design space while the code fills one corner. We will come back to that corner; first, the two simplest values of the type.

Two whole-bus constants sit right under it, and between them they are the bus at rest and the bus asserted:

hiZ :: Lanes
hiZ = repeat (0, 0)

driveHigh :: Lanes
driveHigh = repeat (1, 1)

hiZ is all four lanes released — every enable low, the whole bus handed off. It is the value post 1’s initState powered up into, the state post 3’s safePins slammed the bus to before a trap, the GET idle where the engine samples rather than drives. Across the project hiZ has meant one thing, and now we can see it is not a special state at all, only four copies of “enable off”:

hiZ is hands off the bus.

driveHigh is its mirror — all four enables on, all four values one, the bus actively pulled to logic high. It has exactly one use, the first clock of a turnaround, and we will meet it there in a moment. Both are written with repeat, which fills a Vec with copies of one element; neither says how many, because neither has to. The count lives in the type — hiZ :: Lanes is Vec 4, so repeat makes four — the same widths-live-in-the-type discipline that let bitCoerce pack a word by its field sizes.^[2] Change Lanes to Vec 2 for a narrower bus and these two definitions do not move; the 4 they never mention becomes a 2.

A byte, eight beats

Now the function the module is named for. A byte goes in; the drive for all eight of its beats comes out:

serializeX1 :: BitVector 8 -> Vec 8 Lanes
serializeX1 b = map beat (unpack b :: Vec 8 Bit)
 where
  beat :: Bit -> Lanes
  beat bit' = (bit', 1) :> (0, 0) :> (0, 0) :> (0, 0) :> Nil

The type is half the documentation: a BitVector 8 in, a Vec 8 Lanes out — one byte, mapped to eight beats, each beat a full four-lane drive. Not one lane value but the entire schedule for the byte, computed in one go, which is what a combinational block does: no loop, no clock, just a map laying eight beats down side by side. Post 2’s startPut took serializeX1 byte !! 0 to prime the very first beat as it armed a transfer; post 3’s beatLanes took serializeX1 (shifter t) !! bi to fetch beat bi as the bus walked forward. Both were indexing into this vector, the eight-beat schedule this line builds.

Two moves make it, and we have read both before. unpack b :: Vec 8 Bit takes the opaque eight-wire byte and lays it out as eight individual Bits — the same structural, zero-cost reinterpretation the CRC opened its fold with, and with the same convention riding on it: index 0 of the vector is the most significant bit, so the vector runs MSB-first. That convention is not decorative. eSPI, like SPI and SMBus before it, clocks the most significant bit onto the wire first, so beat 0 must carry bit 7, and unpack’s ordering delivers exactly that with no reversal.^[3]

Then map beat turns each of those eight bits into a full Lanes. And beat is the two-bit story spelled out one more time: for a data bit bit', it drives IO[0] with (bit', 1) — the value is the bit, the enable is on — and releases IO[1], IO[2], IO[3] with three (0, 0)s. That is single-I/O in one line: one wire driven, three let go, the data on IO[0] and the rest of the bus floating. Fold the map over the eight bits and you have the byte’s whole life on the pins — eight beats, each driving one bit MSB-first on one wire, the other three released the entire time — which is precisely what the loopback and drive tests will check, and what post 3 spent its beats emitting.

The inverse the engine never calls

The serialiser has an inverse, and it is even shorter:

deserializeX1 :: Vec 8 Bit -> BitVector 8
deserializeX1 = pack

Eight sampled bits in, one byte out, and the body is a single word: pack, the exact partner of the unpack a few lines up. Where unpack scattered a byte into MSB-first bits, pack gathers MSB-first bits back into a byte, and because the two are inverse halves of the same bitCoerce reinterpretation, pack . unpack is the identity by construction. Read against serializeX1, deserializeX1 is the undo: it takes the eight bits a GET sampled off the wire, MSB-first, and assembles the byte they spell.

There is a quiet surprise here, though, and it is worth stopping on: the engine never calls this function. Post 3’s sampleGet did the receiving, and it did not batch eight bits and pack them — it shifted each sampled bit into an accumulator by hand, one per rising edge — shifter `shiftL` 1 to open a slot at the bottom, an .|. to drop the new bit in — interleaved with the beat loop it lived inside. The engine assembles a received byte incrementally because it receives incrementally, a bit at a time across eight beats, with nowhere to hold a Vec 8 Bit in the meanwhile. So deserializeX1 describes the same result by a different route than the engine actually takes.

Why write it, then, if nothing on the fabric runs it? Because it earns its place as a specification rather than as code on a path. It names the inverse, and naming it is what lets the round-trip law — serialise a byte, sample it back, deserialise, and get the byte — be stated and a property test check it, pinning the MSB-first convention down from both ends at once. It is a move the project has made before with a name it never quite uses: the ISA’s OpcodeUnimplemented, declared to reserve a vocabulary the decoders never return; the trace module’s encodeRecord, which never runs on the fabric and exists only so the engine’s inline packing has a readable reference to be proven equal to. deserializeX1 is that kind of honest surplus — a line that is not on the critical path but makes a promise the critical path can be checked against.^[4]

Drive once, then let go

The last function is the turnaround, and it is a single conditional:

tarBeat :: Unsigned 4 -> Lanes
tarBeat i = if i == 0 then driveHigh else hiZ

tarBeat takes a beat index and answers with a drive: on beat 0 it returns driveHigh — all four lanes pulled high — and on every beat after it returns hiZ — all four released. That is the whole of the turnaround, the TAR the bus post fetched as tarBeat bi, and it is the choreography an eSPI bus performs whenever the wire changes hands. Between a command the controller drove and a response the target will drive, the two ends have to swap roles without ever both driving at once; the turnaround is the handshake in the middle, a beat or two where the outgoing driver gives the bus a defined push and then lets go, so the line is never left floating and undefined at the instant of handover.^[5]

driveHigh’s one use is right here: it is that defined push, the first turnaround clock that drives the bus to a known high before the release. And after that single beat, every later index falls through to hiZ.

Drive the turnaround clock once, then let go.

The type is Unsigned 4 -> Lanes, and the argument is the same beat index beatLanes threaded in — but tarBeat reads only whether it is zero. The function is total over all sixteen values an Unsigned 4 can take, and fifteen of them give the same answer; only beat 0 is special. It is a small, blunt shape for a small, blunt job: one beat of drive, then the hiZ the rest of the module already meant by release.

Three drives, one field

Step back from the four functions and the module snaps into a single picture — because post 3’s beatLanes, the one place all of this was used, is a three-way case whose three arms are three of the names we have just read:

beatLanes t bi = case pending t of
  PendGet{} -> hiZ
  PendTar   -> tarBeat bi
  _         -> serializeX1 (shifter t) !! bi

Three directions off one pending field. A GET releases the bus so the other end can drive it — hiZ. A TAR turns it around — tarBeat bi. Anything else is a PUT, and it serialises — serializeX1 (shifter t) !! bi. The whole of Serdes exists to answer that case: hiZ is the release arm, tarBeat the turnaround arm, serializeX1 the drive arm, and Lane is the two-bit alphabet all three answer in. Every eSPI direction the engine can point the bus is one of these three drives, and each is this module handing back four (value, enable) pairs.

The three drives beatLanes selects, each a full Lanes of four (value, enable) pairs. A PUT beat drives the data bit on IO[0] and releases IO[1..3]; a GET beat releases all four and samples IO[1]; a TAR beat 0 drives all four high before the release that follows. The shaded cells are the driven ones --- enable high --- and everywhere else the enable is low and the value a don't-care. One byte is eight PUT beats, MSB first; only IO[0] is ever driven in x1.

The three modes are the same four lanes read three ways. Look only at the enables: a PUT turns exactly one on (IO[0]), a TAR beat turns all four on for its one clock, and a GET turns them all off and reads IO[1] instead of driving it. The values matter only where an enable is high — the shaded cells — which is the two-bit story made visual: the column that carries data is the column whose enable let it through.

One corner of a wider bus

The module’s doc-comment states the rules the code obeys, and reading them against what we have seen names the one corner of eSPI this file actually serialises:

x1 rules: PUT drives the data bit on IO[0], MSB first, with IO[1..3]
tri-stated; GET samples IO[1] with all engine drivers tri-stated.
Dual/quad maps land in Phase 3.

Every claim in that comment is now a line we have read. PUT drives IO[0] MSB-first — serializeX1’s (bit', 1) on lane zero, fed by unpack’s MSB-first order. IO[1..3] tri-stated — its three (0, 0)s. GET samples IO[1] with all drivers released — hiZ, and post 3’s sampleGet reading lane one. The x1 in the function’s name is the promise the comment keeps: this is single-I/O, one data wire in each direction, the simplest of the eSPI width modes.

The other modes are named and deferred in a single clause — dual/quad maps land in Phase 3 — and that deferral is the ISA post’s honesty turned on the serialiser. Lanes is a Vec 4 because the bus has four data wires and dual-I/O drives two of them, quad all four; the type is sized for the widest mode from the first line. But serializeX1 fills only the x1 corner, driving IO[0] and no other, exactly as decodeConfig accepted only the one controller-x1-20MHz configuration and named every wider mode an error rather than pretending to implement it. The space is drawn in full — four lanes, the modes that would use them — and one corner of it is wired, honestly, the rest marked reserved. A serializeX2 and serializeX4 are the shape of the Phase 3 work; when they come they will produce the same Vec 8 Lanes, only with two or four enables high per beat instead of one.

The tests

Three tests, and between them they hold down every claim the module makes. A small helper sets them up:

io0 :: Lanes -> Bit
io0 lanes = fst (lanes !! (0 :: Index 4))

io0 reads one thing off a beat: the value bit of lane zero, fst of IO[0]’s pair — the bit serializeX1 drives. It is the sampler the tests use to look at what a PUT put on the wire.

The first test is the round trip, a Hedgehog property:

testProperty "x1 serialize/deserialize round-trips (loopback)" $ property $ do
  b <- forAll genByte
  deserializeX1 (map io0 (serializeX1 b)) === b

Read it inside out. serializeX1 b drives the byte into eight beats; map io0 reads IO[0]’s value back out of each beat, recovering the eight driven bits as a Vec 8 Bit; deserializeX1 packs them into a byte. The law is that this returns b unchanged, for every byte Hedgehog can draw. The comment calls it loopback, and the name is the picture: on a real loopback the driven IO[0] is wired round to the sampled IO[1], so reading IO[0]’s value stands in for sampling what came back. It is serialise-then-sample-then-deserialise closing to the identity — the MSB-first convention proven consistent from the drive end to the receive end, because a single reversed bit anywhere in that chain would make some byte come back wrong and the property would shrink to it.

The second test drives one specific, well-chosen byte and checks the pins directly:

let beats = serializeX1 0b1000_0000     -- MSB set only
io0 (head beats) @?= 1                   -- first beat carries the MSB
io0 (last beats) @?= 0
map (\l -> snd (l !! (1 :: Index 4))) beats @?= repeat 0

0b1000_0000 is the sharpest possible probe of bit order: only the most significant bit is set. If serialisation is MSB-first, the first beat must drive a one and the last must drive a zero — which is exactly what io0 (head beats) @?= 1 and io0 (last beats) @?= 0 assert. Flip the convention to LSB-first and the two swap, and the case goes red. The third line checks the other half of the x1 rule: snd (l !! 1) is IO[1]’s enable, and mapping it over every beat must give repeat 0 — lane one released on all eight beats, never driven. One byte proves both that the bits leave in the right order and that the idle lanes stay out of the way.

The last test pins the turnaround:

tarBeat 0 @?= repeat (1, 1)  -- first clock drives all high
tarBeat 1 @?= repeat (0, 0)  -- then releases
tarBeat 5 @?= repeat (0, 0)

Beat 0 is driveHigh, beats 1 and 5 are hiZ — the “drive once, then let go” shape asserted on both sides of the only boundary the function has. tarBeat 5 is there to make the point that every beat past the first releases, not merely the second; the function has one special case and fifteen identical ones, and the test samples both kinds. Three small assertions, and the two-bit vocabulary is checked in all three of the directions the bus can face.

What we read

The last box, opened — and the smallest. Tamal.Bus.Serdes is one transparent type and a handful of functions over it. Lane is a (value, enable) pair, a type synonym with no wall around it because the engine handles it as the bare tuple it is; the value says what to drive and the enable says whether to drive at all, and on a shared bidirectional bus that second bit — the one that chooses between driving and releasing — is the whole of tri-state, three wire states carried in two bits. Lanes is four of them, one per I/O wire, sized for a four-wide bus the module does not yet fill. hiZ and driveHigh are the bus released and the bus asserted, repeat taking their width from the type. serializeX1 lays a byte out MSB-first into eight beats, driving IO[0] and releasing the rest — single-I/O in one map — and deserializeX1 is its pack inverse, kept for the round-trip law even though the engine, receiving a bit at a time, never calls it. tarBeat drives one turnaround clock high and then lets go. And post 3’s beatLanes was these three drives all along — a GET’s release, a TAR’s turnaround, a PUT’s serialise — three eSPI directions off one field, each a fistful of (value, enable) pairs. The tests close the loop from drive to sample, pin the MSB-first order to a single-bit probe, and stake down the turnaround.

And with that the descent is done. We read the engine’s map first, then watched it dispatch an instruction and run its wire, holding every leaf shut — and then we opened them, each in the order the engine first reached for it. decode and the instruction set; the sixteen registers its operands named; the compute those registers fed, dataResult and branchTaken; and now the serialiser nearest the wire, serializeX1 and tarBeat and the two-bit Lane they speak. The CRC had its own post before this arc began, and AW and RW were read inline with the memories; every other black box the three outside-in posts named has now been opened and read whole. The engine is open entire — map and every piece.

What is left is not inside the engine but around it. step is pure: it takes a State and an input and returns a State, a BusOut, and maybe a trace word, and every Lanes it computes is still just numbers — four (value, enable) pairs, a description of a drive, not a drive. Something has to carry those pairs the last step out: take each lane’s enable and its value and turn them into a real bidirectional pad, a wire that is driven when the enable is high, floats when it is low, and is sampled back into the engine’s inputs when the other end drives. That is the impure shell — Tamal.Io and its tri-state buffers, Tamal.Top wiring the engine to the clock and the pins, the Tamal.Board.* layers that pin it to real silicon — and it is where the (value, enable) pair we have just called the whole story meets the FPGA primitive that makes it physical. The introduction warned that the pins are the hard part; the engine has spent seven posts being precise about what to drive and when, so that the shell can be left the narrower, sharper job of driving it. That shell is a story for another day — a later batch, out to the pins.

The three states a shared wire can take — driven high, driven low, and released — are electrical, not logical, and the third is the one a single logic bit cannot name. A released output is high-impedance: the driver disconnects, presenting so large a resistance that it neither pulls the line high nor low but lets another driver anywhere on the net decide the level. A bidirectional bus is exactly a set of wires more than one device may drive at different times, and its one unbreakable rule is that no two drive at once — two enabled outputs fighting over a line, one high and one low, is a near short from supply to ground, the contention that overheats pads and corrupts every bit. The enable bit is what enforces the rule: it is the wire that goes to a pad’s output-enable, 1 to drive and 0 to float, and a protocol like eSPI is in large part a discipline for ensuring exactly one end has its enable high on any given lane at any given beat. The (value, enable) pair is that discipline in its smallest form — and it is also, not by coincidence, the interface of the FPGA primitive that will implement it: a tri-state buffer takes a data input and an enable, and does precisely what Lane describes. The later shell batch is where the pair meets that primitive. ↩
repeat :: KnownNat n => a -> Vec n a fills a vector with copies of one element, and the length n is a type-level number the compiler supplies from context — here from the signatures hiZ :: Lanes and driveHigh :: Lanes, which fix n = 4 because Lanes = Vec 4 Lane. There is no count in the source because there is none to write: the type carries it, the same way bitCoerce took its field widths from the types it coerced between and unpack b :: Vec 8 Bit took its 8 from the annotation. It is the primer’s widths-live-in-the-type discipline in miniature — a definition that stays correct when the width changes because it never mentioned the width in the first place. ↩
beat builds its four-lane vector by hand with :> and Nil: (bit', 1) :> (0, 0) :> (0, 0) :> (0, 0) :> Nil. :> is Vec’s cons — prepend an element to a shorter vector — and Nil is the empty one, so the expression conses four Lanes onto Nil and has type Vec 4 Lane, which is Lanes. The length is not asserted anywhere; it is counted by the compiler from the four :>s and checked against the Lanes the signature demands, so a beat that built three lanes or five would not typecheck. It is the same structural guarantee repeat gave from the other direction — there the 4 came from the type, here it comes from the literal — and both meet in the middle at Vec 4. ↩
A function the fabric never runs might look like waste, but deserializeX1 is the third instance of a pattern the project uses on purpose. The ISA’s OpcodeUnimplemented is a DecodeError the decoders never return, declared so a future partial implementation has the word ready. The trace module’s encodeRecord never executes on the engine — step packs its records inline with bitCoerce — and exists only as the readable reference that inline packing is proven equal to. deserializeX1 is the same kind of surplus: it is the named inverse of serializeX1, and naming it is what lets the round-trip property be written, so the MSB-first convention has a law guarding it from both ends. The engine’s own sampleGet shifts bits in one at a time because it receives them one at a time, across eight separate rising edges, with no Vec 8 Bit ever in hand; deserializeX1 is the batch statement of the same result, kept for the test and for the reader, not for the synthesiser. ↩
The turnaround is spec §5’s answer to a hazard the SCK waveform created. Command and response travel on the same lanes in opposite directions, so at the seam between them the controller must stop driving and the target must start, and for a beat or two neither may — or both might, the contention a shared bus must never allow. TAR fills that seam: driveHigh gives the bus one defined, driven-high clock so the line is never left floating at the instant of handover, and then hiZ releases it for the other end to take. Driving high rather than low for that single beat matches the bus’s idle-high convention, so the release settles to the level the pull-ups would hold anyway. It is a small courtesy with a real payoff: a receiver watching for the first response edge sees a clean transition rather than the ambiguous drift of a wire that changed owners mid-float. ↩

rambo v0.1.2: the boring release is the point

2026-08-07T09:00:00+00:00

rambo — the CLI that maps which of a Cortex-M’s SRAM a boot ROM clobbers before your firmware’s first instruction runs — is at v0.1.2. If you’re looking for a new feature, there isn’t one:

### Other
- (deps) bump dependencies
- add dependabot configuration
- chain release binaries from release-plz workflow
- allow manual dispatch of release workflow

Every flag you might reach for — the --json reports, the --expectations RAM contracts, custom chip descriptions — shipped back in v0.1.1, which I already wrote up. v0.1.2 is pure plumbing, and that’s the point.

The one change you’ll actually notice: every tagged release now ships pre-built binaries for Linux, macOS (Intel and Apple Silicon), and Windows, built and attached automatically. No Rust toolchain required to run rambo — download, unzip, go.

Under the hood that’s the whole release pipeline earning its keep. I write conventional commits; release-plz keeps a “Release X.Y.Z” pull request open with the version bump and changelog already written for me. Merging it publishes to crates.io, tags the release, and — new in v0.1.2 — kicks off the per-OS binary build and uploads the archives to that release. A manual trigger lets me rebuild those binaries for an existing tag if a run ever fails, without cutting a new version.

The other half of “boring” is a dependabot config that files one grouped, conventional-commit pull request a week for Rust and Actions updates, so it folds into a clean patch bump instead of a pile of noise. Most of what changed between v0.1.1 and v0.1.2 is exactly that: actions/checkout and action-gh-release bumped themselves and I just merged.

None of this is novel. It matters because a one-person tool doesn’t die from bad code — it dies when every release costs twenty minutes of bookkeeping and one day you don’t have twenty minutes. v0.1.2 drops that cost to roughly zero, so the next release, the one with actual features in it, is one I’ll actually ship.

rambo is on crates.io (cargo install rambo) and GitHub; grab a binary from the releases page, including this boring one.

Tamal: Add, And, and the Taken Branch

2026-08-07T09:00:00+00:00

The register file handed the datapath two values, and we followed them to the door of the next box. rs1v and rs2v — read through one register port, bound for the other — do not travel straight from the read to the write. Between the two ports sits a layer that turns them into something: the value that comes back to writeReg, or the single bit that decides whether to jump. That layer is this post. The dispatch post held two boxes shut over exactly these two acts — dataResult, the value its dataWb wrote, and branchTaken, the decision its branch turned on — and we open both here, in the two small modules that hold them: Tamal.Alu and Tamal.Branch.

These are leaves, read whole — Alu is eighty-six lines, Branch is thirty-four — and together they are the engine’s compute layer: pure, combinational, single-cycle functions of operand values. Neither knows there is a register file above it or an engine around it; each takes thirty-two-bit values and answers. This is where the machine finally does arithmetic — and where, in two import lines, it collides with the rest of the language over what to call it.

Two boxes, one kind of thing

The dispatch post left seven leaves shut, and two of them sat over the only places Exec actually computed. One was dataResult, called from dataWb — the handler that thirteen DATA instructions all funnelled through, each supplying a destination register and letting the box work out the value. The other was branchTaken, called from branch — the helper the four conditional branches deferred their condition to while the engine kept the program-counter arithmetic for itself. We open them together because they are the same kind of thing: a pure, total, single-cycle function of two register values, no state, no clock, no wire. The difference is only in what they return — one a thirty-two-bit value, the other a single Bool — and that difference is exactly the line between the DATA group’s compute and the CTRL group’s branches.

They come as two modules, and the split is deliberate: one concern each, the way the ISA, the CRC, and the rest are one concern each.

That has been the shape of this whole descent: the engine’s map named eight boxes and opened one, and every post since has opened the next in the order the engine reaches for it — decode first, then the registers its operands named, and now the compute those registers feed. Two boxes fall in one post here because they are siblings: both are handed the same pair of register reads, both answer in a single cycle, and only the shape of the answer — a value, or a verdict — tells them apart.

The ALU is the larger story, so we read it first, all the way down — and its very first two lines are a puzzle worth stopping on.

The two-layer plan

Tamal.Alu’s door lists one type and two functions:

module Tamal.Alu
  ( AluOp (..)
  , alu
  , dataResult
  ) where

AluOp is exported with (..) — all its constructors, because callers name them — and then alu and dataResult. Two functions for one module is the shape to notice: they are two layers, and the layering is the whole design. alu is the thin core — give it an operation and two values, it computes. dataResult is the wrapper — give it a decoded Instr and two register values, and it works out which operation, pulls any immediate out of the instruction, and calls alu. The core knows arithmetic; the wrapper knows the instruction set. Keeping them apart is what let the dispatch post’s dataWb hand the whole instruction to dataResult and collapse thirteen arms into one: the wrapper reads the operation off the instruction, so no caller has to.

Two import lines, two collisions

Under the header sit three imports, and two of them carry scars:

import Clash.Prelude hiding (And, Xor)
import Tamal.Isa (Instr)
import qualified Tamal.Isa as Isa

The prelude swap is the line every block carries — but here it comes with a hiding (And, Xor) clause, and that clause is the first symptom of a collision this module walks straight into on purpose. The ALU wants to name its operations the obvious way: Add, Sub, And, Or, Xor. That vocabulary is the plainest in all of computing — and it is already spoken for, twice.

The first claimant is the standard library. Modern Data.Bits ships newtype wrappers called And and Xor — little monoid boxes whose <> is bitwise-and and bitwise-xor, handy for folding a pile of bits down with mconcat — and Clash.Prelude re-exports them.^[1] So the moment AluOp declares a constructor And, it clashes with the And the prelude just brought in. The module’s answer is to slam that door: hiding (And, Xor) drops those two names from the import, leaving AluOp’s constructors the only And and Xor in scope. The core never needed the wrappers anyway — it does bitwise work with the operators .&. and xor, not the monoids. And Or escapes the whole affair, because Data.Bits spells its or-wrapper Ior, not Or, so there is nothing to hide.

The second claimant is closer to home: the instruction set itself. Tamal.Isa’s Instr has constructors Add and Sub — the DATA opcodes — and AluOp wants those exact names for its operations. Two types in scope, each with an Add: an unresolvable ambiguity. So Instr comes in qualified, import qualified Tamal.Isa as Isa, and every instruction constructor must be written Isa.Add, Isa.Sub, and so on, while the bare Add and Sub belong to AluOp. (The unqualified import Tamal.Isa (Instr) on the line between is just so the type Instr can be named without a prefix in the signatures.)

Read together, the two lines are not clumsiness to apologise for — they are the two-layer split showing through the namespace. AluOp and Instr both need a word for “add,” because they live at two different levels: one is a hardware operation, the other an instruction. The whole job of dataResult is to translate the second into the first — Isa.Add into alu Add — and a translator between two vocabularies only exists because the two vocabularies are, deliberately, distinct. The collision is the design, made visible at the import list.

When two layers both need the word “add,” the import list is where you can see the seam between them.

The core: eight total operations

With the names sorted out, the enum is plain:

data AluOp = Add | Sub | And | Or | Xor | Sll | Srl | Sra
  deriving stock (Generic, Show, Eq, Enum, Bounded)
  deriving anyclass (NFDataX)

Eight operations: add, subtract, the three bitwise ops, and three shifts — shift-left-logical, shift-right-logical, shift-right-arithmetic. The deriving refrain is the usual four, with two additions worth naming: Enum and Bounded. Those two let a caller write [minBound .. maxBound] and get every AluOp in order — which is precisely how the tests will enumerate the operations later, and a small example of a derived instance bought for a specific downstream use.

The core itself is one total case:

alu :: AluOp -> BitVector 32 -> BitVector 32 -> BitVector 32
alu op r1 r2 = case op of
  Add -> r1 + r2
  Sub -> r1 - r2
  And -> r1 .&. r2
  Or -> r1 .|. r2
  Xor -> r1 `xor` r2
  Sll -> r1 `shiftL` sh
  Srl -> r1 `shiftR` sh
  Sra -> pack (shiftR (unpack r1 :: Signed 32) sh)
 where
  sh :: Int
  sh = fromIntegral (unpack (truncateB r2) :: Unsigned 5)

The type is half the documentation: an operation and two thirty-two-bit values in, one out, always — no Maybe, no failure. The first five arms are the ones that need no comment: Add and Sub are BitVector’s Num, wrapping modulo $2^{32}$; And, Or, Xor are the operators .&., .|., `xor` the module hid the wrappers to keep clear. That Sub is r1 - r2 and nothing fancier is the same two’s-complement fact the branch offset leaned on and the CRC met in its own algebra: subtraction is addition of the negation, one operation on the hardware, which is why the tests can assert alu Sub a b === alu Add a (complement b + 1) and have it hold by construction.

The shifts are where the close reading earns its keep. All three take their distance from sh, and sh is defined once in the where: the low five bits of operand B, truncateB r2 narrowed to a BitVector 5, unpacked to an Unsigned 5, and read as an Int in 0..31. Masking the shift amount to five bits is a RISC-V habit with a real payoff — a five-bit count can only ask for a shift of zero through thirty-one, so a shift by thirty-two or more is impossible to express, and the “shift wider than the word” undefined behaviour that haunts C simply has no encoding here. A shift by 32 masks to a shift by 0; the operation stays total because its argument was range-limited before it arrived.^[2]

Then the split between Srl and Sra, which is the subtlest line in the module. Srl is r1 `shiftR` sh — and BitVector’s shiftR is logical, filling from the top with zeros. Sra wants the arithmetic shift, the one that fills with copies of the sign bit so that shifting a negative number right divides it. BitVector has no sign to preserve, so Sra borrows one: unpack r1 :: Signed 32 reinterprets the same thirty-two bits as a signed number, shiftR on Signed sign-fills, and pack puts the bits back as a BitVector. Nothing moved but the type. The bits are identical going in; reading them as Signed is what makes the shift arithmetic, and reading them back as BitVector is what returns them to the untyped wires the rest of the datapath speaks.^[3] It is the CRC’s “the kind of value is part of the contract” turned into a tool: when the operation needs a sign, the code manufactures one by changing how the bits are read, for exactly one expression, and changes it back.

And notice what is not in the case: a ninth arm, an error, a reserved op. AluOp has eight constructors and alu handles eight; it is total with nothing left over. That is only possible because the one reserved shift encoding — the 0b11 op field — never reaches here: the instruction set traps it at decode, the SHIFT op 0b11 that the isa post’s test pinned. The reserved case is handled one layer out, at the decoder, so the core can be a clean eight-way truth table — which in hardware is exactly what it becomes, a bank of adders and shifters and gate arrays with op selecting one.^[4]

And a truth table computes everything at once. There is no clock inside alu and no sequencing — the primer’s combinational logic — so every arm’s gates exist and run every cycle: the adder adds, the shifters shift, the gate arrays and-or-xor in parallel, and the case is a multiplexer at the output that keeps the one result op asked for and discards the rest. The apparent waste is the shape of hardware, and it is also why the whole of alu resolves inside the single Exec cycle the dispatch post spent on a DATA instruction: one operation chosen from eight computed, no time borrowed.

The wrapper: resolving operand B

alu computes; it does not know an instruction from a hole in the ground. dataResult is the layer that does, and it is where the DATA group’s compute opcodes fold onto the core’s eight operations:

dataResult :: Instr -> BitVector 32 -> BitVector 32 -> BitVector 32
dataResult instr rs1v rs2v = case instr of
  Isa.LoadImm _ imm -> signExtend imm
  Isa.Lui _ imm21 -> (zeroExtend imm21 :: BitVector 32) `shiftL` 11
  Isa.Mov _ _ -> rs1v
  Isa.Add _ _ _ -> alu Add rs1v rs2v
  Isa.Addi _ _ imm -> alu Add rs1v (signExtend imm)
  -- … Sub, And_/Andi, Or_/Ori, Xor_/Xori, all the same shape …
  Isa.Shift _ _ shOp amt -> alu (toAluShift shOp) rs1v (zeroExtend amt)
  _ -> 0 -- BUS / CTRL / RDSR: never routed here by the Engine
 where
  toAluShift :: BitVector 2 -> AluOp
  toAluShift = \case
    0b00 -> Sll
    0b01 -> Srl
    _ -> Sra -- 0b10; 0b11 is unreachable (decode traps it)

Read the arms in three groups. The first three bypass alu entirely, because none of them is arithmetic — they are ways to get a constant, or a copy, into a register. LoadImm sign-extends its twenty-one-bit immediate, so one instruction reaches the whole signed-twenty-one range (li rd, -1 in a single word); Lui places the upper immediate for the two-instruction constants; and Mov is the degenerate case, an operation with nothing to compute — it copies rs1v, ignores rs2v, the identity function wearing an opcode. The last real arm, Shift, dispatches to one of the three shift ops via toAluShift. And everything between — the arithmetic and logic — is the group that reveals why the wrapper exists: look at Add and Addi sitting one line apart.

  Isa.Add _ _ _ -> alu Add rs1v rs2v
  Isa.Addi _ _ imm -> alu Add rs1v (signExtend imm)

Both call alu Add rs1v. The only difference is the second operand: Add uses rs2v, the value of the second register; Addi uses signExtend imm, the instruction’s immediate widened to thirty-two bits. That is the entire distinction between a register-register op and its immediate form, and it repeats for And/Andi, Or/Ori, Xor/Xori. So the arithmetic and logic opcodes collapse onto eight operations not by coincidence but because each register/immediate pair is one operation over one choice of operand B: a register value, or an immediate. dataResult’s job, boiled down, is to resolve operand B and hand off. This is the other side of the dispatch post’s collapse — there, thirteen arms became one dataWb because “dataResult reads the operation off the instruction”; here is the reading, and the eight-fold fan-out it feeds.

Step back and the operand path is complete across three posts. The dispatch post’s operandRs1 and operandRs2 tables said which registers an instruction reads; the register file turned those names into the values rs1v and rs2v; and dataResult says which operation, and where operand B comes from. Four pieces in a line — the selector tables, readReg, dataResult, writeReg — are a DATA instruction’s entire datapath, and every one of them was built and tested alone before the engine wired them in a row. That was the wager of reading outside in, paid back a leaf at a time.

The immediates are widened by one rule, almost: every I-form immediate sign-extends — signExtend imm, so an immediate with its top bit set is negative and addi rd, rd, -1 subtracts one — and the single exception is the shift amount, zeroExtend amt, because a shift distance is a count, not a signed value.^[5] Lui is the one placement worth a second look: (zeroExtend imm21 :: BitVector 32) `shiftL` 11 takes the twenty-one-bit immediate the ISA post watched get carved out of the rs1 ++ rs2 ++ imm fields — the widest immediate in the set, from the fields its opcodes had spare — and lays it into bits [31:11], low eleven zero. That shift of eleven is chosen so Lui’s bottom edge meets Addi’s sign-extended top, which is what lets the assembler build any thirty-two-bit constant in two instructions.^[5]

Two things the wrapper does not do, both by design. It takes register values rs1v and rs2v, never a Regs — so it has no idea the register file exists, and the x0-hardwiring and the discarded-write-to-x0 we read last post are not its concern; the engine reads x0 as zero on the way in and drops writes to x0 on the way out, and dataResult computes on whatever values it is handed. The compute layer sits between the two register ports and touches neither: the engine wires readReg’s outputs into dataResult and dataResult’s output into writeReg. Each leaf minds one concern — the register file was engine- ignorant, the ALU is register-file-ignorant — and the engine is the only place that knows them all.

And the _ -> 0 at the bottom is the totality tax. dataResult matches on the whole Instr type, so Clash demands every constructor have an answer — but the BUS, CTRL, and RDSR instructions never arrive here, because the engine routes only DATA-compute through dataResult and handles the rest itself. The default is unreachable in the engine; 0 is a safe, deterministic value for a case the wiring guarantees will never come up.^[6]

The compute layer as two functions. dataResult (top) resolves operand B --- a register value rs2v or a sign-extended immediate --- and feeds the accent alu core, the eight AluOps the DATA compute collapses onto; Lui, Mov and LoadImm bypass the core as constants, and a final select yields the value written back. branchTaken (bottom) is the sibling: the same two register values, one of four comparisons, a single taken bit --- the decision, with the PC arithmetic kept in the engine. Both take values, not registers; the compute layer sits between the two register ports and touches neither. (The shift amount uses zeroExtend amt, not sign-extension.)

The comparator

Tamal.Branch is the sidecar in that diagram, and it is small enough to read whole:

module Tamal.Branch
  ( BranchOp (..)
  , branchTaken
  ) where

import Clash.Prelude

data BranchOp = Beq | Bne | Bltu | Bgeu
  deriving stock (Generic, Show, Eq, Enum, Bounded)
  deriving anyclass (NFDataX)

branchTaken :: BranchOp -> BitVector 32 -> BitVector 32 -> Bool
branchTaken op r1 r2 = case op of
  Beq -> r1 == r2
  Bne -> r1 /= r2
  Bltu -> r1 < r2
  Bgeu -> r1 >= r2

Note the import: a plain import Clash.Prelude, no hiding clause. The ALU had to fight for its names; the branch comparator does not, because Beq, Bne, Bltu, Bgeu collide with nothing — they are the module’s own coinage, not words the standard library or the instruction set already owns. The absence of a scar is itself a small tell: this module reuses no vocabulary, so it borrows no trouble.

branchTaken returns a Bool and nothing else — taken, or not. That is the entire point of the split the dispatch post set up: the comparator decides, and the engine jumps. When the engine ran branch, it called Br.branchTaken for the yes/no and then did the program-counter arithmetic itself — the eleven-bit signed offset truncated to ten bits and added modulo the counter, backwards jumps falling out of the two’s-complement wraparound. None of that is here. branchTaken never sees the offset, never sees the PC; it is a pure predicate on two values, and the offset math belongs to the only thing that knows where the program counter is. That is why Branch needs no Instr wrapper the way Alu did: there is no immediate to resolve, no operand B to mux — both operands are registers — so mapping the four branch constructors to BranchOp is a one-line remap the engine does inline, and a branchResult- on-Instr layer would earn nothing. Alu grew a second layer because it had immediates to fold in; Branch stayed one because it did not.

The four comparisons hold one detail that is easy to miss and important to get right. Beq and Bne are == and /=, unremarkable. But Bltu and Bgeu — the “u” is for unsigned — are just < and >=, and they are unsigned for free, because they operate on BitVector, and BitVector’s Ord is unsigned. A BitVector 32 has no sign bit to interpret; ordered, it compares as a plain thirty-two-bit magnitude, 0xFFFFFFFF the largest value rather than $-1$. That is exactly the BLTU/BGEU semantics, so the comparator gets them by writing < and doing nothing else.

This is the mirror image of the ALU’s Sra, and the two together are the whole story of how this layer handles number types. Sra reached for Signed 32, reinterpreting its bits to borrow a sign it needed for an arithmetic shift. branchTaken stays on BitVector to keep the sign away, because an unsigned compare is what it wants. Same thirty-two bits, opposite choices — and each is made by choosing the type the bits are read through, for exactly the operation that needs it.

The bits never change. The type you read them through is the operation.

Signed branches — BLT, BGE, the ones that would need Signed’s Ord — are simply not in v1, reserved for a later phase; the four here are the unsigned pair and the two equalities, and every one of them is a single operator on the untyped word.

The tests

Two test files, and they pose a question the CRC and the memories did not have to: when your reference model is nearly identical to your implementation, what does a test buy? alu Add a b === a + b checks that add is add — a near-tautology. The answer is that the boring arms are there to catch a wiring slip (an Add that quietly does .|.), and the real value lives in the arms where the behaviour is subtle. Those get pinned twice, by property and by hand:

testProperty "Sub == Add of two's complement" $ property $ do
  a <- forAll genWord
  b <- forAll genWord
  alu Sub a b === alu Add a (complement b + 1)

testCase "Sra 0x80000000 by 1 = 0xC0000000 (sign-fill)"
  $ alu Sra 0x80000000 1
  @?= 0xC0000000
testCase "Srl 0x80000000 by 1 = 0x40000000 (zero-fill)"
  $ alu Srl 0x80000000 1
  @?= 0x40000000

The first states the two’s-complement identity as a law. The two concrete vectors are the sharpest lines in the suite: the same input, 0x80000000, shifted right by one, gives 0xC0000000 under Sra and 0x40000000 under Srl — the arithmetic shift copying the sign bit down, the logical shift feeding a zero. If the unpack … :: Signed 32 reinterpretation in Sra were ever dropped, the first case goes red instantly. Around them sit the property that the shift amount is masked to five bits (alu Sll a b === alu Sll a (b .&. 0x1F)), that a shift by zero is identity, and that Sra preserves the sign bit — the whole subtle corner, staked down.

The dataResult tests check the other layer: not the arithmetic, but the wiring that routes each opcode to it. Mov returns rs1v; LoadImm sign-extends; Lui lands its immediate at [31:11] with the low eleven zero ((r .&. 0x7FF) === 0); each immediate form agrees with alu on the sign-extended operand, each register form agrees with alu on rs2v. They prove the wrapper dispatches correctly, independently of whether the core computes correctly — two layers, two sets of tests.

Test.Branch gets to do something the others cannot, and it is the Enum/Bounded deriving paying off:

testProperty "branchTaken matches reference (all ops)" $ property $ do
  op <- forAll (Gen.element [minBound .. maxBound])
  a <- forAll genWord
  b <- forAll genWord
  branchTaken op a b === ref op a b

[minBound .. maxBound] is every BranchOp, enumerable because the type derives Enum and Bounded, so “for all ops” is literal rather than a hand-kept list that could fall out of date. Beside it, the complementarity properties — Beq is exactly not Bne, Bltu exactly not Bgeu — fall free out of the comparator’s structure, and three concrete vectors stand guard over the unsigned reading:

testCase "Bltu is unsigned: 0x7FFFFFFF < 0x80000000"
  $ branchTaken Bltu 0x7FFFFFFF 0x80000000
  @?= True

Read as signed, 0x80000000 is the most negative number and 0x7FFFFFFF the most positive, so a signed < would call this False. Read as unsigned — which is what BitVector’s Ord does — 0x80000000 is the larger, and the answer is True. This one case is the tripwire: the day someone reinterprets the operands as Signed by mistake, it goes red and names the bug. It is the regfile tests’ discipline in a different key — the smallest input that distinguishes the behaviour you want from the one you might slip into.

What we read

The two computing boxes of the dispatch post, opened. Tamal.Alu in two layers: a thin, total alu core dispatched by an eight-constructor AluOp over register values — its Sub the two’s-complement add, its shifts masked to five bits so a shift past the word is well-defined, its Sra borrowing a Signed reading for one expression while Srl stays logical — and above it dataResult, the wrapper that places the Lui, Mov, and LoadImm constants and resolves operand B, so the arithmetic and logic opcodes collapse onto eight operations because each register/immediate pair is one operation over one choice of second operand. It takes values, so it never meets the register file; it sits between the two ports and touches neither. Two import lines that were both naming collisions — And and Xor hidden from the prelude, Isa qualified — because a compute layer and an instruction set both need the word “add,” and the translator between them exists precisely because they are kept apart. And Tamal.Branch, four lines returning only taken-or-not, its Bltu/Bgeu unsigned for free from BitVector’s own Ord, the PC arithmetic left to the engine — the clean inverse of Sra’s reach for a sign. The bits never changed; the type read through them was the operation, every time. And tests that pin the subtle corners against near-identical references, and enumerate every op because the enums derive Bounded.

dataResult’s value now flows back to writeReg, and branchTaken’s bit to the program counter — and with that, the compute is accounted for. Of the leaves the dispatch post named and held shut, only one is still closed, and it is the one nearest the wire. When a PUT loaded its shifter and the bus post walked the beats, the drive on the lanes came from serializeX1, and a turnaround from tarBeat — names for a byte becoming MSB-first bits on IO[0], and for the handover clock, all of it built out of a single tiny type: a lane, a (value, enable) pair, the whole tri-state story in two bits. That serialiser is the last box. We open it next — and when it is open, the engine is open entire, map and every piece — before the series turns, in a later batch, to the impure shell that carries those (value, enable) pairs the last step out, to the pins.

Since base 4.16 Data.Bits provides the newtype wrappers And, Ior, Xor, and Iff, whose Semigroup/Monoid instances fold a collection under bitwise-and, -or, -xor, and -xnor — so getAnd (foldMap And xs) ands a list together. Clash.Prelude re-exports Data.Bits, And and Xor among them, so the moment AluOp declares constructors of those names they clash; hiding (And, Xor) drops the imports, and the core does its bitwise work with the operators .&. and `xor` anyway. Or survives only by luck of spelling: the or-wrapper is Ior (“inclusive or”), not Or, so nothing shadows AluOp’s Or. ↩
sh is fromIntegral (unpack (truncateB r2) :: Unsigned 5). truncateB r2 keeps the low five bits as a BitVector 5; unpack reads them as an Unsigned 5 (0..31); fromIntegral makes the Int that shiftL/shiftR want. The detour through Unsigned 5 is not optional: BitVector has no Integral instance — you cannot fromIntegral it directly — because a bare bag of bits has no agreed numeric reading, the CRC’s point that a value’s kind is part of its contract. Masking to five bits before shifting is what makes a shift-by-≥-32 well-defined: the count physically cannot exceed thirty-one, so the C-style “shift wider than the type is undefined” has no representable input. ↩
unpack and pack are the bitCoerce family — total, zero-cost reinterpretations between types of the same bit-width, lowering to no gates, only a relabelling of wires. unpack r1 :: Signed 32 reads the thirty-two bits as a two’s-complement number; shiftR on Signed is arithmetic, replicating the sign bit; pack reads the result back as a BitVector. That sandwich is the whole mechanism: BitVector’s own shiftR is logical, and the only difference between Srl and Sra is which type does the shifting. Nothing is added or dropped — the bits match on both sides of the unpack/pack — only their reading differs, signed for the length of one shift. ↩
The “small total alu core plus a decode that returns Either” division is borrowed from Lion, an RV32I core in Clash: keep the arithmetic core total by pushing every reserved or illegal encoding out to the decoder, so the datapath never has to represent “no answer.” tamal diverges from RV32I in the particulars — its own opcode groups, eleven-bit immediates, unsigned-only branches in v1 — so it does not inherit RV32I’s formal-verification harness; hedgehog property tests are the verification baseline instead. ↩
The eleven-bit shift on Lui is not arbitrary. Lui carries a twenty-one-bit immediate (the ISA post’s rs1 ++ rs2 ++ imm, $5 + 5 + 11 = 21$) and places it at bits [31:11]; Addi sign-extends its eleven-bit immediate across [10:0] and up. Because Lui’s bottom bit meets Addi’s sign-extended top, li = LUI + ADDI builds any thirty-two -bit constant in at most two instructions, with sign-extension used uniformly (the shift amount, a count, is the exception, zeroExtend amt). An earlier draft shifted Lui by twelve to mirror RISC-V and left a reachability gap needing a third instruction; widening the immediate to twenty-one and realigning the shift to eleven closed it. The primitive here fixes only Lui = imm21 << 11; the constant-tiling lives in the assembler. ↩ ↩2
dataResult matches the entire Instr type, so Clash requires a total function — every constructor needs a right-hand side. The BUS, CTRL, and RDSR instructions have one only as a formality: the engine dispatches on the decoded group and routes just DATA-compute through dataResult, handling RDSR (which reads engine state, not operands) and the branches and bus ops on their own paths. So _ -> 0 is unreachable by construction, and 0 is a deterministic placeholder, not a computed value. A Maybe-returning variant was considered and rejected: every input the engine actually delivers yields a real value, so the Nothing would never fire and would only burden every caller with an unwrapping. ↩

Tamal: Sixteen Registers and a Hardwired Zero

2026-08-06T09:00:00+00:00

The instruction set closed on a name it declined to open. decode had turned a word into an Instr, pulled the operands out as five-bit Reg fields, and handed them on — and the very next thing the dispatch post watched execInstr do was read the registers those fields named: readReg (regs s) (operandRs1 i). But a Reg was only ever a name, five bits wide, not yet an index into anything. The thing it names is this post: Tamal.RegFile, the sixteen registers, the register hardwired to zero, and the two ports the datapath read and wrote through the whole arc while we held them shut.

This is a leaf again, read whole the way the CRC and the memories were — small enough to hold entire, fifty-one lines with nothing left closed when the post ends. And it is a leaf the series has already promised. The memories kept their write port ignorant of the engine — a block RAM that will not import Tamal.Engine, because “a memory that imports the engine is a memory that knows what a trace record is” — and pointed here as its sibling: the same discipline that produced Tamal.RegFile, built before Engine.step existed to use it and never importing the engine whose registers it holds. By the time we opened it, that post said, the shape would be familiar. Here it is.

The door, again

A Tamal module opens by naming itself and listing what leaves through the wall, and after the engine’s eleven-name sprawl this one is a return to the narrow doors of the leaves:

module Tamal.RegFile
  ( Regs
  , initRegs
  , readReg
  , writeReg
  ) where

Four names. We have read this shape before, and the aphorism the CRC gave it still holds:

A module is a wall with a door in it, and the export list is the door.

But look at what the four names are, because the split is the whole design in miniature. One is a noun — Regs, the type of the register bank — and three are verbs: initRegs makes one, readReg inspects one, writeReg evolves one. The engine had to export six types because something one level up assembles it and must name its plugs; a leaf like the CRC exported only a verb and hid its types entirely. Tamal.RegFile sits between: it publishes one type, because its callers must be able to hold a Regs and pass it around, but it publishes that type opaquely — the name Regs crosses the wall, and its constructor does not. You will not find Regs (..) on that list, the way the engine wrote State (..) to export a record and all its fields. Just Regs, the bare name, a handle to a thing whose insides stay home.

That is a deliberate choice, and it is the same choice that kept step private inside the CRC: the export list is a place to say less than you could. Everything a caller is allowed to do to a register bank is on those four lines, and the shape of the bank behind them is not. Hold that; it is about to matter twice.

The prelude, and the only import

Two lines sit under the header, and the first is the one every block in this series has carried:

import Clash.Prelude
import Tamal.Isa (Reg)

The prelude swap is old news by now — the line that throws out ordinary Haskell’s furniture and moves in the Bit, BitVector, Vec, and Signal that lower to gates, the line that says compile me to hardware. I will not re-derive it a seventh time. It is the second import that repays a look, and it repays it precisely because of how little it says.

import Tamal.Isa (Reg) reaches across the wall for exactly one name, and that name is a type synonym: Reg, which we met as BitVector 5, the five-bit register selector decode carves out of an instruction word. The register file imports the name of a selector — and nothing else. It does not import Tamal.Engine. It does not import the State that will hold it, or the step that will call it, or the ALU whose results it will store. It imports one width-carrying synonym from the instruction set and stops.

This is the discipline the memories named when they refused to let their write port learn what a trace record was, and it is worth stating as its own rule now that we are standing inside the leaf it promised:

A leaf that holds the engine’s registers has never heard of the engine.

The dependency arrow runs one way only. Tamal.Isa knows nothing of Tamal.RegFile; Tamal.RegFile knows only the name Reg; and Tamal.Engine, one level up, imports both and wires them together. The register file was, as the mem post said, “built before Engine.step existed to use it” — a small, hedgehog-tested warm-up written so that when the keystone step finally landed, its operand-fetch and writeback path would be wiring, not invention. And importing Reg rather than re-declaring a bare BitVector 5 is the small courtesy that makes that wiring seamless: readReg and writeReg take the exact type decode produces, so the engine can pass rs1, rs2, and rd straight through with no conversion at the seam.

The bank, sealed

Here is the type the whole module exists to serve, and the reason its constructor stayed off the door:

newtype Regs = Regs (Vec 16 (BitVector 32))
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

A Regs is a Vec 16 (BitVector 32) — sixteen thirty-two-bit words, a fixed-length vector, five hundred and twelve bits of architectural state — wrapped in a newtype whose constructor is also called Regs. The wrapper is the wall. Because the constructor does not leave the module, nothing outside can write Regs someVector to forge a bank, or pattern- match Regs v to reach the raw vector inside; the Vec 16 never leaks. The outside world holds a Regs as a sealed handle and touches it only through initRegs, readReg, and writeReg, exactly the three verbs on the door. Should a later version want a different representation — a packed BitVector 512, a pair of banked halves, whatever a timing closure demands — it can change this line and the three functions and break not a single caller, because no caller was ever allowed to see the shape it is changing.^[1]

The deriving block is the four-class refrain every stateful Tamal block wears, and I will be quick with it: Generic lets Clash work structurally, Show and Eq are for the tests — and Eq earns a specific keep here, since one property will assert writeReg rs 0 v === rs and needs to compare two banks — and NFDataX is the one that means “this value can be the contents of a register.” Everywhere else in the series that phrase was a near-metaphor. Here it is literal: the engine’s State has a field regs :: Regs, the whole State is what the mealy wrapper clocks, and so a Regs is not like a register’s contents — it is sixteen registers’ contents, five hundred and twelve flip-flops on the fabric. NFDataX is the class that lets those flip-flops have a defined power-up value; without it, Regs could not sit in the state at all.

Power-up is sixteen zeros

One line says what the bank holds before anything happens:

initRegs :: Regs
initRegs = Regs (repeat 0)

repeat 0 is the Vec repeat that fills a whole fixed-length vector with one value; here it lays down sixteen copies of 0, and Regs wraps them. Every register powers up holding zero. This is the same move the memories made with repeat 0 for their INIT contents, and it does the same double duty: on hardware it becomes the flip-flops’ reset value, and in simulation it means every slot is defined from the first cycle, so a randomised test that reads a register nobody has written gets a zero rather than an exception.

And initRegs is not merely a starting value; it is the one. The shape post read initState and found regs = initRegs sitting in it, and read the larger fact folded into initState existing at all: Tamal has no reset port. The top ties reset permanently deasserted and leans on power-up init, so initRegs is not what a reset line loads — there is no reset line — it is what the register bank powers up holding. When a second program runs, softInit throws the whole machine back to initState, regs included, so every run begins from sixteen zeros and the byte-identical re-run the intro promised extends cleanly through the register file. The determinism has to reach all the way down here, and repeat 0 is where it lands.

A name is not a slot

Between the five-bit name a caller hands in and the physical register it means sits one private helper — private, like the CRC’s step, kept off the door because nothing outside should depend on how a name becomes a slot:

regIndex :: Reg -> Index 16
regIndex r = unpack (truncateB r)

A Reg is a BitVector 5; an Index 16 is a number in 0..15, the type Clash uses to index a sixteen-element vector safely. regIndex is the translation, and it is two operations read right to left. truncateB r keeps the low four bits of the five-bit selector and discards the top one, yielding a BitVector 4; unpack then reinterprets those four bits as an Index 16, whose bit-width is exactly four.^[2] The wider selector is narrowed to the width the bank actually has.

This is a small instance of the width-changing family — truncateB, zeroExtend, signExtend — as opposed to the structural bitCoerce that reshapes bits without changing how many there are. truncateB changes the count: five bits in, four out, the fifth dropped on the floor. And the choice of which bit to drop is the design.

Look at the result type. regIndex returns an Index 16, and an Index 16 cannot be out of range — the values it can hold are 0 through 15 and no others, guaranteed by the type. So when readReg and writeReg reach for the total Clash primitives (!!) and replace, there is no bounds check to write and no out-of-range case to handle, because the index they are handed made the bound part of its own type.^[3] This is the memories’ “widths live in the type, so there is no branch to have,” moved one level over: the safety is not enforced at runtime, it is made unrepresentable at compile time.

But narrowing five bits to four has a visible consequence, and the design chose it on purpose. Two selectors that differ only in their top bit — x1 (00001) and x17 (10001) — truncate to the same four bits and therefore the same slot. The out-of-window selectors x16..x31 alias their low-four twins. The leaf does not reject them; it folds them back into the sixteen it has. That keeps the function total — every one of the thirty-two names a five-bit field can hold yields a defined slot, none traps — and totality is the property a leaf is supposed to guarantee. Whether x16..x31 should be refused is a real question, but it is the assembler’s and the engine’s question, not this leaf’s: the instruction set noted that Reg is “wider than the register file behind it … deliberate room to grow,” and the fifth bit is that room, reserved for a future that implements thirty-two registers. Until then the register file stays total by aliasing, and leaves the rejecting to the layers whose job rejecting is.

`readReg`: the hole at x0

The first of the two ports:

readReg :: Regs -> Reg -> BitVector 32
readReg (Regs v) r
  | idx == 0 = 0 -- x0 is hardwired to 0.
  | otherwise = v !! idx
 where
  idx = regIndex r

The type is half the documentation: a bank and a name in, a thirty-two-bit value out, and — the part the type says by saying nothing — always a value, no Maybe, no error. Reading a register cannot fail. It pattern-matches the bank open as Regs v (allowed, we are inside the wall), computes idx = regIndex r, and forks on one guard.

That guard is the design decision the whole RISC-V flavour turns on. When idx == 0, readReg does not return v !! 0 — it does not read slot zero’s contents at all. It returns the literal 0. Register x0 is hardwired to zero: reading it yields zero no matter what is physically stored in slot zero, and nothing can make it read anything else. Every other index falls to v !! idx, the total vector index that pulls slot idx’s word straight out.

We have already spent this guarantee, a whole post before we built it. The dispatch post’s operand selectors ended every table with a catch-all _ -> 0, so that an instruction with no second source “reads x0” and gets zero — “a read that is always safe, always defined, and costs nothing, because x0 is not a register you can get wrong.” This guard is why. The reason reading x0 is free is that readReg answers 0 without so much as glancing at the vector; LoadImm, which names no sources and reads x0 twice, pays nothing for the two reads because both short-circuit here. The engine leaned on a promise, and the promise is one line of guard in a leaf.

In hardware readReg is combinational — the truth-table totality the series keeps returning to, cashed as a 16-to-1 multiplexer: the four-bit index selects one of sixteen thirty-two-bit lanes, and the lane for slot zero is tied to constant zero rather than to a flip-flop’s output.^[3] No clock, no latency; the value is there the moment the index is. And because it is combinational, the datapath can call it twice in one cycle — once for rs1, once for rs2 — and get both source values at once, which is why a module that exports a single readReg gives the datapath two read ports. The one function, instantiated twice, is the classic two-read shape of a register file; the x0 register even earns a second keep as the always-true branch, where j off is really beq x0, x0, off, a comparison of zero against zero that readReg makes free on both sides.

`writeReg`: the write that replaces

The second port, and the more quietly radical one:

writeReg :: Regs -> Reg -> BitVector 32 -> Regs
writeReg regs@(Regs v) r x
  | idx == 0 = regs -- writes to x0 are ignored!
  | otherwise = Regs (replace idx x v)
 where
  idx = regIndex r

Read the type first, because its return is the whole story. writeReg takes a bank, a name, and a value, and hands back — a bank. Not (), not IO (), not a mutation performed on the side: a fresh Regs. A write to a register does not change the register file. It computes a new one and returns it, leaving the old one exactly as it was.

This is the primer’s “mapping, not procedure,” cashed the way the CRC’s fold cashed it: nothing is overwritten. In C, regs[rd] = x reaches into an array and clobbers a cell. Here replace idx x v produces a new vector identical to v but with slot idx set to x, and Regs wraps it; the argument v is never touched and is simply not referenced again. What looks like the mutation of a register is a pure function from an old bank to a new bank, and the “mutation” you imagine happens exactly once, elsewhere: when the Mealy wrapper clocks the returned State – the one now carrying the new Regs — into the fabric flip-flops at the edge. The datapath itself assigns nothing.

The guard is x0 again, from the writing side. idx == 0 returns regs — the whole original bank, unchanged — so a write to x0 is silently discarded, which is the other half of “hardwired to zero”: you cannot read anything but zero out, and you cannot put anything in. The dispatch post promised this too, noting that writeReg “quietly enforces one rule … a write to x0 is discarded, because x0 is hardwired zero.” Here is the enforcement, one guard wide. Every other index takes the replace path. And the as-pattern regs@(Regs v) is a small convenience doing real work: it binds the whole argument as regs and its unwrapped vector as v in one shot, so the x0 arm can return the original regs without rebuilding it while the other arm still has v in hand to hand to replace.

One invariant, one place, twice

Two things are worth pausing on together, because they are really one decision. First, x0 is guarded in both ports — read returns zero, write is discarded — and both guards test the truncated index, idx == 0, not the raw five-bit selector. That is what makes the hole consistent under aliasing: x16 truncates to slot zero, so x16 reads zero and discards its writes exactly as x0 does. The aliasing and the hardwiring compose without anyone arranging it; the same idx == 0 that protects x0 protects its out-of-window twin for free.

Second, and larger: the x0 rule lives here, in the register file, and nowhere else. The engine reads and writes registers uniformly — readReg (regs s) rd, writeReg (regs s) rd result — and never checks whether rd is zero, because it never has to. If the rule lived in the engine instead, every one of the thirteen DATA arms that writes a register would need an if rd /= 0 around its writeback, and the invariant would be scattered across a dozen call sites, each an opportunity to forget it. Housed in one leaf, it is impossible to forget: the register file is the thing that makes x0 behave, so anything that goes through the register file inherits the behaviour.

x0 is not a register the engine keeps at zero. It is a register that cannot be anything else, because the only door to it refuses to carry a value either way.

The register file as the datapath sees it. The sixteen cells are the opaque Regs, a Vec 16 (BitVector 32); x0 (accent) is the hole, ≡0 --- readReg returns zero for it and writeReg discards writes to it, both keyed on the truncated index so x16‥x31 alias x0‥x15 and inherit the same behaviour. A five-bit Reg is truncated to its low four bits (regIndex) to pick a slot, so the index is an Index 16 that cannot be out of range. One writeReg port returns a fresh bank; one readReg, instantiated twice, gives the two combinational read ports the datapath fetches rs1 and rs2 through.

Read-old, write-new, for free

Step back up one level, to the dispatch post’s dataWb, and watch all three functions meet in a single cycle:

  rs1v = readReg (regs s) (operandRs1 i)
  rs2v = readReg (regs s) (operandRs2 i)
  dataWb rd =
    let s' = (advance s){regs = writeReg (regs s) rd (dataResult i rs1v rs2v)}
     in (s', busOut s', Nothing)

Every one of them touches regs s — the current cycle’s bank. The two reads pull rs1v and rs2v out of it; the write builds a new bank from it and tucks that into s' under regs. Because readReg reads the value the state holds now, and writeReg merely computes the value the state will hold next, the two cannot collide. Even when a DATA instruction writes the very register it read — add x3, x3, x1, where rd and rs1 are both x3 — rs1v is the old x3, sampled before the write, and the new x3 does not exist until the Mealy wrapper clocks s' at the edge. Read-old, write-new, hazard-free, and nobody wrote a hazard check: it falls out of the read and the write being pure functions of the same value, with the “write” a separate return that only becomes state a cycle later.^[4]

This is why the register-file design rejected a blockRam-backed bank, and it is worth naming because it is the road not taken. A block RAM has a one-cycle read latency and lives at Signal level; it could not be a field of a pure Mealy State, and reading and writing the same address in one cycle would open exactly the read-during-write hazard the pure version closes by construction. Five hundred and twelve bits is small enough to live in fabric flip-flops with a combinational read, so it does — and the purity that made the whole engine testable makes its register hazards vanish as a side effect. The same choice buys both.

The tests

Test.RegFile is short, the way a leaf’s tests are short, and it makes the same quiet point the CRC and the memories made: a claim this small can be pinned down completely. Its cleverest line is a generator:

genRegs :: Gen Regs
genRegs = do
  ws <- Gen.list (Range.linear 0 20) ((,) <$> genReg <*> genWord)
  pure (foldl' (\rs (r, v) -> writeReg rs r v) initRegs ws)

Read what it does not do. It builds an arbitrary register bank by drawing a random list of up to twenty (register, value) pairs and folding writeReg over them, starting from initRegs — so every Regs the tests ever see is constructed only through the public door. The generator never reaches for the Regs constructor, because the constructor is not exported and is not the test’s to touch, exactly as the CRC’s tests “exercise the byte-level crc8Update and never reach for step.” The wall holds even here; the properties test the bank the way a real caller builds it, one writeReg at a time. (The foldl' is Data.List’s, not the Vec fold import Clash.Prelude shadowed — ws is a list — the same prelude-swap wrinkle that made the CRC tests reach for L.foldl'.)

The properties then stake down every corner of the design at once:

testProperty "read-after-write (r /= x0)" $ property $ do
  rs <- forAll genRegs
  r <- forAll genNonZeroReg
  v <- forAll genWord
  readReg (writeReg rs r v) r === v

Write a value to any non-x0 register and read it straight back: you get the value, whatever the slot held before. That is the ordinary register’s contract — an overwrite wins — and it is the first thing to prove. Three more guard the x0 hole from all sides: readReg rs 0 === 0 says the read is always zero; writeReg rs 0 v === rs says the write is a no-op, and it leans on the derived Eq Regs to compare whole banks (the reason Eq was on the door); and a register independence property draws two selectors with distinct low-four indices and checks that writing one leaves the other’s read untouched — no write scribbles on a neighbour. One pins the power-up state, readReg initRegs r === 0 for every name. And two pin the truncation itself:

testProperty "x16..x31 alias x0..x15" $ property $ do
  r <- forAll genNonZeroReg -- x1..x15
  v <- forAll genWord
  readReg (writeReg initRegs (r + 16) v) r === v

testCase "x16 aliases x0 (write discarded)"
  $ writeReg initRegs 16 42
  @?= initRegs

The property writes to r + 16 — an out-of-window selector — and reads back through r, demanding the value land in the twin slot; the Hedgehog run fires it across every r in x1..x15. The HUnit case nails the one corner the property cannot reach, since x0 has no non-zero twin to read: writing 42 to x16, which aliases x0, must leave the bank identical, because the write is discarded. Six checks and a witness, and between them they describe the whole surface of the leaf — the bijection on x1..x15, the hole at x0, the aliasing of everything above — with nothing left to guess.

What we read

The last pure leaf, opened whole. A four-name door that exports one type and three verbs, and exports the type opaquely, so a Vec 16 (BitVector 32) can be sealed behind the wall and touched only through initRegs, readReg, and writeReg. A single import — Tamal.Isa, for the name of a selector — and, pointedly, not the engine whose registers it holds: the memories’ discipline, cashed as promised, a leaf built before the step that would use it. A newtype bank of five hundred and twelve bits that powers up to sixteen zeros and, deriving NFDataX, is the engine’s register flip-flops in its Mealy state. A private regIndex that truncates a five-bit name to a four-bit slot, so the index is an Index 16 that cannot be out of range and the out-of-window x16..x31 alias their low-four twins rather than trap — totality by construction, room to grow left in the fifth bit. readReg’s hole at x0, the hardwired zero that made “no operand” free a post ago; writeReg’s discarded write and its functional update, a fresh bank returned rather than a cell mutated, the primer’s mapping-not-procedure one last time. One x0 invariant, kept in one place and keyed on the truncated index so aliasing inherits it. The read-old/write-new hazard-freedom that falls out of a pure step for nothing. And a test file that builds every bank through the public door and pins the bijection, the hole, and the aliasing from six directions at once.

The register file hands the datapath two values every cycle, and those values do not sit idle. rs1v and rs2v — the two reads dataWb took before it wrote — flow straight on into the one box the dispatch post still had shut over its writeback: dataResult, the ALU, which turns two register values and an instruction into the one value that comes back to writeReg. And the same two reads feed the branch comparator that decided whether a jump was taken. Both were named and left closed. Next we open them together — Tamal.Alu and Tamal.Branch, the add and the and and the taken branch — the compute layer that sits between the two ports we just read, consuming what one hands out and producing what the other takes in.

newtype rather than data is a deliberate, zero-cost choice. A newtype may wrap exactly one field, and Haskell guarantees it is erased at compile time: at runtime a Regs is a Vec 16 (BitVector 32), with no box, no tag, no indirection — the wrapper exists only in the type-checker, where it does the work of keeping the two types distinct and the constructor private. So the encapsulation the opaque export buys is free: it costs a name in the type system and nothing in the gates. Clash lowers the Vec 16 to a bank of flip-flops exactly as it would an unwrapped vector, and the Regs label vanishes before synthesis ever sees it. You get the wall without paying for a wall. ↩
The widths line up by type inference, read outside in. regIndex is annotated to return Index 16, and the BitSize of Index 16 is 4 (four bits address sixteen slots). That return type fixes unpack :: BitVector 4 -> Index 16, which in turn fixes truncateB r :: BitVector 4 — truncateB is polymorphic in its output width, so the surrounding type is what tells it to keep four bits rather than three or five. Nothing here names the number four; it is deduced from Index 16, so changing the bank to Vec 32 and the selector’s window would re-derive the truncation width automatically. The type carries the arithmetic, and the code only says “narrow to fit.” ↩
(!!) :: Vec n a -> Index n -> a and replace :: Index n -> a -> Vec n a -> Vec n a are Clash’s total vector primitives: because the index has type Index n, there is no out-of-range value to pass and thus no partial case, no runtime bounds fault. In hardware (!!) on a Vec 16 lowers to a 16-to-1 multiplexer selected by the four index bits, and readReg’s x0 guard is a further two-way mux tying the output to constant zero when the index is zero. writeReg’s replace lowers to sixteen thirty-two-bit registers, each with a load-enable asserted when idx equals its position and idx is non-zero — which is precisely why slot zero is never written. All of it is combinational logic over five hundred and twelve flip-flops; none of it is a blockRam, and that is the point. ↩ ↩2
The hazard-freedom is a property of values, not of careful sequencing. readReg (regs s) rs and writeReg (regs s) rd v are both functions of the same immutable regs s; neither can observe the other, because there is no mutable cell for one to write and the other to read. The new bank is a distinct value that the caller places into s', and only the clock edge — the one genuinely stateful event, owned by the mealy wrapper a level up — turns s' into the next regs s. So “read the old, write the new” is not a rule the register file implements; it is the only thing that can happen when reads and writes are pure and state advances once per cycle. A conventional imperative register file has to design around the write-during-read case; this one cannot express it. ↩

Tamal: The Instruction Set

2026-08-05T09:00:00+00:00

For three posts we held the leaves shut. We read the engine’s shape, watched it dispatch an instruction, and ran its wire, and all the while decode, dataResult, branchTaken, and the rest were names with one-line jobs and no insides. Now we start opening them — in the order the engine reaches for each — and the very first thing the engine does to any word, before it can compute or branch or drive a pin, is decode it. So the descent begins where every road out of Exec began: in Tamal.Isa, the instruction set itself.

This is a leaf again, read whole the way the CRC and the memories were — but it is the leaf the entire engine is written against. Every constructor execInstr matched, every field it pulled out with an underscore or a name, every trap that fired on a word the engine could not read: all of it is defined here, in one file, as a type and two functions that are exact inverses of each other over exactly the words that are legal.

The word

Every tamal instruction is exactly thirty-two bits, and those bits are carved into six fields the same way for every opcode. The module’s doc-comment draws the map:

 31 30 | 29 .. 26 | 25 .. 21 | 20 .. 16 | 15 .. 11 | 10 .. 0
 group |   sub    |    rd    |   rs1    |   rs2    |  imm

Two bits of group, four of sub, then three five-bit register selectors — rd, rs1, rs2 — and an eleven-bit imm at the bottom. The group and sub together are the opcode: the group picks one of four families, the sub picks an operation within it. The three register fields and the immediate are the operands, and which of them an opcode actually uses depends on the opcode — the rest are reserved, and we will see that “reserved” is a promise the decoder enforces, not a comment.

The 32-bit instruction word, MSB (bit 31) on the left. The two-bit group and four-bit sub form the opcode; rd, rs1, rs2 are five-bit register selectors and imm is an eleven-bit immediate. Widths sum to exactly 32. Every opcode reads the same fields from the same bits; which operands it uses is what distinguishes them, and every bit an opcode does not use is reserved-must-be-zero.

The register fields are five bits wide, and that width is a small piece of the RISC-V flavour the project borrows:

-- | A 5-bit register selector (RISC-V-standard field width). v1 uses x0..x15.
type Reg = BitVector 5

Five bits can name thirty-two registers; v1 implements sixteen and lets the top bit go unused, so Reg is wider than the register file behind it. That is deliberate room to grow, and it means a register selector is just five bits of a word — not yet an index into anything, only a name. The thing it names is the next post’s subject; here it is a field.

One constructor per opcode

The instruction set is a Haskell data type. Every opcode is a constructor, and every constructor carries exactly the operands its opcode uses — no more, so the type itself refuses to build an Add without three registers or a Halt without a status:

data Instr
  = -- BUS group (group 00)
    CsAssert
  | CsDeassert
  | PutByteImm (BitVector 8)
  | PutByteReg Reg
  | GetByte Reg
  | PutBitsImm (Index 8) (BitVector 8)  -- n-1, bits (n = count in 1..8)
  | PutBitsReg Reg (Index 8)
  | GetBits Reg (Index 8)
  | TarImm (BitVector 4)
  | TarReg Reg
  | RstAssert
  | RstDeassert
  | GetAlert Reg
  | -- CTRL group (group 01)
    Halt (BitVector 8)
  | Beq Reg Reg (BitVector 11)
  | Bne Reg Reg (BitVector 11)
  | Bltu Reg Reg (BitVector 11)
  | Bgeu Reg Reg (BitVector 11)
  | WaitOn Reg (BitVector 2) (BitVector 9)  -- rd, cond, timeout
  | SetConfig (BitVector 6)
  | Mark (BitVector 11) Reg               -- label, payload reg
  | CrcReset
  | -- DATA group (group 10)
    LoadImm Reg (BitVector 21)
  | Lui Reg (BitVector 21)
  | Mov Reg Reg
  | Add Reg Reg Reg
  | Addi Reg Reg (BitVector 11)
  | Sub Reg Reg Reg
  -- … And_, Andi, Or_, Ori, Xor_, Xori, all Reg Reg (Reg | imm) …
  | Shift Reg Reg (BitVector 2) (BitVector 5)  -- rd, rs1, op, amt
  | Rdsr Reg (BitVector 5)                     -- rd, sr#
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

Thirty-six constructors, three groups, and every one of them is a name you have already seen execInstr match on. The grouping is the opcode’s top structure made into comments: group 00 is BUS, the thirteen opcodes that touch the wire; group 01 is CTRL, the nine for flow and configuration; group 10 is DATA, the fourteen that compute. The fourth group, 11, has no constructors at all — it is reserved, and a word in it decodes to nothing.

Read the operand types and the encoding starts to show through the ADT. PutByteImm carries a BitVector 8, the byte it will drive. Beq carries two Regs and a BitVector 11, the two sources and the branch offset — the PC arithmetic from the dispatch post operated on exactly that eleven-bit field. PutBitsImm carries an Index 8 and a byte, because “put n bits” needs both a count and the bits; the comment n-1 warns that the field holds one less than the count, a detail the encoder will handle. And LoadImm carries a BitVector 21 — a twenty-one-bit immediate, wider than the eleven-bit imm field, which is the one interesting packing problem in the whole module. Hold that thought; the encoder solves it in two lines.

Beside Instr sits the type that says why a word was not an instruction:

data DecodeError
  = ReservedFieldNonZero
  | OpcodeUnimplemented
  | IllegalOpcode
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

Three ways to fail: a reserved field that was not zero, an opcode recognised but not yet built, an opcode that is illegal outright. These are the Left the dispatch post’s stepExec turned into a trap^[1] — and now we are on the other side of that Left, in the code that produces it.

Encode: the easy direction

Turning an Instr into a word is the easy half, because an Instr is already valid by construction — the type would not let you build a malformed one — so the encoder only has to place the operands and zero everything else. It is a total \case, one arm per constructor, and every arm calls the same helper:

encode :: Instr -> BitVector 32
encode = \case
  CsAssert       -> joinW (0b00, 0x0, 0, 0, 0, 0)
  PutByteImm b   -> joinW (0b00, 0x2, 0, 0, 0, zeroExtend b)
  GetByte rd     -> joinW (0b00, 0x4, rd, 0, 0, 0)
  Beq a b off    -> joinW (0b01, 0x1, 0, a, b, off)
  WaitOn rd c t  -> joinW (0b01, 0x5, rd, 0, 0, bitCoerce (c, t))
  Add rd a b     -> joinW (0b10, 0x3, rd, a, b, 0)
  Shift rd a op a5 -> joinW (0b10, 0xC, rd, a, 0, bitCoerce (op, 0 :: BitVector 4, a5))
  -- … thirty-odd arms in the same shape …

Every arm reads the same way: pick the group and sub that name the opcode, drop the operands into their fields, and put 0 everywhere else. CsAssert has no operands, so it is all opcode and zeros. GetByte uses only rd. Beq fills rs1, rs2, and imm with its two sources and its offset, and leaves rd zero. The zeros are the reserved fields, and the encoder writes them faithfully — which is what makes a decode able to check them later.

joinW is the field-packer, and it is one of a small family of functions that are all the same trick:

type Fields = (BitVector 2, BitVector 4, BitVector 5, BitVector 5, BitVector 5, BitVector 11)

splitWord :: BitVector 32 -> Fields
splitWord = bitCoerce

joinW :: Fields -> BitVector 32
joinW = bitCoerce

Fields is the word’s six fields as a tuple, and joinW and splitWord are both just bitCoerce — the same structural bit-reinterpretation the trace records used to pack a tag and a payload into one word. Here it lays six fields end to end into thirty-two bits, or takes them back apart, and the type system checks the arithmetic: 2 + 4 + 5 + 5 + 5 + 11 = 32, so the coercion is total and lossless, a reshaping of bits with nothing added and nothing dropped.^[2] WaitOn and Shift reach for bitCoerce a second time, to pack sub-fields of the immediate — a condition and a timeout, or a shift-op and an amount — into the eleven bits they share.

And the twenty-one-bit immediate that did not fit? It is split across the three fields nobody else was using:

joinImm21 :: BitVector 5 -> BitVector 5 -> BitVector 11 -> BitVector 21
joinImm21 rs1 rs2 imm = bitCoerce (rs1 ++# rs2 ++# imm)

LoadImm and Lui have no register sources, so rs1, rs2, and imm — five plus five plus eleven — sit empty and adjacent, exactly twenty-one bits, exactly the room a wide immediate needs. The encoder glues them into one BitVector 21 on the way out and the decoder splits them back on the way in. It is a small, satisfying piece of format design: the widest immediate in the ISA is carved out of the fields the immediate-loading opcodes had no other use for.

Decode, and the reserved zero

Decoding is the hard direction, because now the input is any thirty-two bits, most of which are not valid instructions, and the decoder has to tell which is which. It begins by splitting the word and dispatching on the group:

decode :: BitVector 32 -> Either DecodeError Instr
decode w =
  case grp of
    0b00 -> decodeBus sub' rd rs1 rs2 imm
    0b01 -> decodeCtrl sub' rd rs1 rs2 imm
    0b10 -> decodeData sub' rd rs1 rs2 imm
    _ -> Left IllegalOpcode -- group 11 reserved
 where
  (grp, sub', rd, rs1, rs2, imm) = splitWord w

splitWord takes the word apart into the six fields — the inverse of the joinW the encoder used — and the group selects one of three per-group decoders, or, for the reserved group 11, rejects outright. Each per-group decoder is a case on the sub-opcode that rebuilds the constructor. But rebuilding is not enough: the decoder must also refuse a word whose reserved fields are not zero, and that refusal is the heart of the module. It runs through one tiny guard:

only :: Bool -> Instr -> Either DecodeError Instr
only ok r = if ok then Right r else Left ReservedFieldNonZero

only takes a condition and an instruction and hands back the instruction only when the condition holds. The condition is always the same kind of thing — “every field this opcode does not use is zero” — and you can read it plainly in the BUS decoder:

decodeBus sub' rd rs1 rs2 imm =
  case sub' of
    0x0 -> only (z rd && z rs1 && z rs2 && z imm) CsAssert       -- no operands
    0x2 -> only (z rd && z rs1 && z rs2 && immHi8 == 0) (PutByteImm (truncateB imm))
    0x3 -> only (z rd && z rs2 && z imm) (PutByteReg rs1)         -- rs1 used
    0x4 -> only (z rs1 && z rs2 && z imm) (GetByte rd)            -- rd used
    -- …
    0xc -> only (z rs1 && z rs2 && z imm) (GetAlert rd)
    _ -> Left IllegalOpcode
 where
  z = (== 0)
  immHi8 = slice d10 d8 imm  -- imm[10:8] reserved for PUT_BYTE

z is “is zero.” Every arm names the fields its opcode uses and asserts z on all the others. CsAssert uses nothing, so all four operand fields must be zero. GetByte uses rd, so rs1, rs2, and imm must be zero. PutByteImm uses the low eight bits of imm for its byte and reserves the top three — immHi8 == 0 — so a PUT_BYTE word with junk in imm[10:8] is rejected even though its opcode is real. The decoder is strict about the whole word, not just the opcode: a legal instruction is a legal opcode and clean reserved bits. decodeCtrl and decodeData are the same shape at greater length, each checking the exact bits its opcodes leave unused — HALT reserving imm[10:8], SET_CONFIG reserving imm[10:6], the reserved shift-op 0b11 refused, and so on.

Total, both ways

Why be this strict? Because the strictness buys two laws, and the two laws are what make an instruction encoding trustworthy.

The first is the round trip: decode (encode i) == Right i. Encode any instruction and decode the result and you get the instruction back. This is nearly free — the encoder places operands and zeroes reserved fields, the decoder reads operands and checks reserved fields are zero, so of course they agree. It says the encoder and decoder are inverses on the instructions.

The second is deeper and is the one the reserved zero is really for: canonicity. Over every thirty-two-bit word — not just the ones the encoder produces, but all four billion of them — any word decode accepts re-encodes to itself: encode (decode w) == w whenever decode w succeeds. There are no two words that decode to the same instruction, because the only words decode accepts are the ones with zero reserved fields, which is exactly the set the encoder emits. Drop the reserved-field checks and this law dies: a hundred different imm[10:8] values would all decode to the same PUT_BYTE, the mapping would be many-to-one, and the word would no longer be a canonical name for the instruction. The only guard is what keeps the correspondence one-to-one.

And under both laws sits totality. decode :: BitVector 32 -> Either DecodeError Instr is a total function: every one of the $2^{32}$ possible words has a defined answer, an Instr or a named error, with no partial case, no crash, no loop. That is the primer’s “totality is a truth table” cashed at scale — decode is a four-billion-row truth table, which in hardware is exactly what it becomes: a combinational decoder that wires every input pattern to an output.^[3] The dispatch post’s Left -> trap was this totality made visible from the outside: because decode has a defined answer for every word, a corrupted or malicious program cannot reach an undefined state through the front door. Every word either is an instruction or is a trap with a reason.

A decode within the decode

One BUS-group neighbour we passed over has an inside of its own. SetConfig carries a BitVector 6, and back in the dispatch post its arm ran that payload through decodeConfig and trapped on a Left. That function lives in Tamal.Config, and it is the fold-in this post promised — because decoding a configuration payload is the same act as decoding an instruction, one level down.

The shape is identical: a total function from a bitfield to Either an error or a typed value.

decodeConfig :: BitVector 6 -> Either ConfigError Config
decodeConfig p =
  case (role, io, sck) of
    (0b0, 0b00, 0b00) -> Right (Config Controller X1 Sck20 alertSrc)
    (0b1, _, _)         -> Left UnsupportedRole
    (_, io', _) | io' /= 0b00 -> Left UnsupportedIoMode
    _                   -> Left UnsupportedSck
 where
  (role, io, sck, alert) = bitCoerce p :: (BitVector 1, BitVector 2, BitVector 2, BitVector 1)
  alertSrc = if alert == 0 then AlertPin else AlertIo1

Six bits come apart by bitCoerce — the same field-split, smaller — into a one-bit role, a two-bit I/O mode, a two-bit clock, and a one-bit alert source. And then the striking part: only one combination is accepted. (0b0, 0b00, 0b00) — controller role, single I/O, 20 MHz — decodes to a Config; every other role traps UnsupportedRole, every other I/O mode UnsupportedIoMode, every other clock UnsupportedSck. The values it decodes into are a little vocabulary of their own:

data Role        = Controller | Target
data IoMode      = X1 | X2 | X4
data Sck         = Sck20 | Sck33 | Sck50 | Sck66
data AlertSource = AlertPin | AlertIo1
data Config = Config
  { cfgRole :: Role, cfgIoMode :: IoMode, cfgSck :: Sck, cfgAlertSource :: AlertSource }

The types describe the whole eSPI configuration space — Target, X2/X4, the faster clocks — but decodeConfig accepts only the corner of it v1 actually implements, and names the rest as errors rather than pretending they work. This is the introduction’s honesty line turned into code: the shape post’s powerUpDefault — controller, x1, 20 MHz, alert pin — is the one config that decodes, and the alert source is the single bit v1 lets you actually choose. The reserved-zero discipline of the ISA has a cousin here: a config the engine cannot honour is refused at decode, so SET_CONFIG can never quietly leave the engine in a mode its gates do not implement. It traps instead, reason two.

The tests

A module whose whole job is a bijection over a word space is a module you can test completely, and Test.Isa does, from both directions at once. The round trips are one property per group:

testProperty "BUS: decode . encode == Right" $ property $ do
  i <- forAll genBusInstr
  decode (encode i) === Right i

Hedgehog draws a random instruction, encodes it, decodes the result, and demands the original back — the first law, checked across hundreds of generated instructions per group. But the property that earns its keep is the second one, and it runs over the whole word space, not the image of the encoder:

testProperty "any 32-bit word: decode is canonical or traps" $ property $ do
  w <- forAll genWord
  case decode w of
    Right i -> encode i === w
    Left _  -> success

Read what this checks. Draw any thirty-two-bit word — valid or garbage, any group, any junk in any reserved field. If decode rejects it, fine, success. But if decode accepts it, the accepted instruction must re-encode to the very word we started from. That is canonicity stated as a test: there is no word decode accepts that is not the encoder’s own output for that instruction. A single too-lax reserved-field check — one only that forgot a field — and Hedgehog would find a word that decodes to an instruction whose encoding differs, and the property would go red with the counterexample in hand. It is the reserved zero, guarded from the outside.

Two HUnit cases pin the reserved discipline to specific words:

testCase "reserved non-zero field traps (CS_ASSERT with junk imm)" $
  decode (busWord 0b00 0x0 + 1) @?= Left ReservedFieldNonZero
testCase "reserved SHIFT op (0b11) traps" $
  decode (encode (Shift 0 0 0b11 0)) @?= Left ReservedFieldNonZero

The first takes a clean CS_ASSERT word and sets one reserved bit; it must trap. The second is sharper: encode never validates, so it will happily build a SHIFT word with the reserved op 0b11 — and the tightened decoder must reject what the encoder was willing to write. That gap between a permissive encoder and a strict decoder is the safe direction to err: the engine only ever runs decode, so the decoder is the gate, and the test proves the gate is shut.

Test.Config does the same for the fold-in, five cases wide: the v1 default decodes, the in-band alert source decodes, and target role, dual I/O, and 33 MHz each trap with their own error. The whole legal surface and three witnesses that the illegal surface is refused.

What we read

The first box, opened. The instruction set is a thirty-two-bit word in six fields, a data type with one constructor per opcode across three groups and a reserved fourth, and two functions that are inverses over exactly the legal words. encode is the easy direction — an Instr is valid by construction, so encoding only places operands and zeroes the reserved fields, bitCoerce doing the packing the way it packed the trace records, the widest immediate carved from the fields its opcodes left spare. decode is the hard one, dispatching on the group and accepting a word only when every reserved field is zero — and that strictness buys the round trip, canonicity, and a totality that gives every one of four billion words a defined home, which is the trap seen from the inside. The folded Config is the same function one level down, six bits to a role and a mode and a clock, accepting the single corner v1 implements and naming the rest as errors. And the tests check the bijection across the whole word space, not a sample of it.

We opened decode because it was the engine’s first act on any word. Its last act on that word — once decoded, the very next thing execInstr did — was to read the registers the operands named: readReg (regs s) (operandRs1 i). Those register selectors were Regs, the five-bit fields we met at the top of this post, still only names. Next we open the thing they name: Tamal.RegFile, the sixteen registers, the hardwired zero, and the two ports the datapath read and wrote through the whole time we were holding it shut.

OpcodeUnimplemented is the one DecodeError the current decoders never actually return — they reject with IllegalOpcode (an unknown sub-opcode, or the reserved group) or ReservedFieldNonZero (a dirty reserved field). It exists in the type for the case of an opcode that is recognised but not yet built, so that a future partial implementation can distinguish “this is not an instruction” from “this is an instruction I have not finished.” Declaring the variant now costs nothing and reserves the vocabulary; the engine treats all three the same way, as a trap. ↩
bitCoerce is Clash’s total, zero-cost reinterpretation of a value as another type of the same bit width — it is pack followed by unpack, and it lowers to no gates at all, only a relabelling of wires. The safety is entirely in the widths: joinW :: Fields -> BitVector 32 typechecks only because the six fields sum to thirty-two, so a field-layout error is a compile error, not a silently truncated word. It is the same “widths live in the type” guarantee the primer opened with, doing the load-bearing work in a format definition — the reason the ISA can be described as tuples of BitVectors and trusted to pack correctly. ↩
The hardware reading matters because decode is not a program the engine runs step by step — it is a combinational function the Fetch-to-Exec boundary evaluates in a single cycle. Clash turns the nested cases into a tree of multiplexers and comparators: the group selects a per-group decoder, the sub selects an arm, the reserved-field tests become AND-reductions over the unused bits. There is no loop and no sequencing, because a truth table has none; the whole of decode is one wide slab of logic that turns thirty-two input wires into a decoded instruction and a valid bit, every cycle, for whatever word Fetch happened to hand it. ↩

Tamal: The Wire and the Record

2026-08-04T09:00:00+00:00

The last post ended four instructions mid-gesture. PUT, GET, TAR, MARK, and WAIT_ON each spent their one cycle in Exec not finishing but arming — a shifter loaded, a beat count set, a write recorded in pending, a phase changed — and then the cycle ended and they handed off to a longer phase. This post is the other side of that handoff: BusBeat, TraceEmit, and WaitAlert, the three phases where the arming is spent. It is where the engine finally touches the wire.

Everything until now has been decision. The shape was the map; Exec was the choice of what to do. Here the engine does it: it drives and samples two-and-a-half wires on a clock it makes itself, and records what happened into a ring the host will later read back. Two subjects, then — the wire and the record — and they meet in the one phase that runs the bus.

SCK is the fabric clock, divided by five

The introduction made a point of insisting that Tamal is not a throughput problem but a timing-alignment problem — that the engine does not need to be fast, it needs to be precise about when it drives, samples, and lets go. All of that precision lives in one small counter and the function that reads it:

sckOf :: Index 5 -> Bit
sckOf = boolToBit <$> (>= 3)

SCK, the serial clock, is the fabric clock divided by five. The shape post named the field that does the dividing: busPhase :: Index 5, a counter that walks 0, 1, 2, 3, 4 and wraps, one step per 100 MHz fabric cycle. sckOf turns that counter into a clock level with a single comparison — (>= 3) is true for phases three and four, false for zero, one, two, and boolToBit maps that to a Bit.^[1] So SCK is low across phases {0, 1, 2} and high across phases {3, 4}: three cycles low, two cycles high, five to a beat, one bit of eSPI per beat.

The duty cycle is lopsided — three-fifths low — and that is a deliberate, honest compromise. A clean fifty-percent clock at this divisor would need a hardware clocking primitive; a plain counter cannot split five evenly. Rather than spend an MMCM to make the clock pretty, the engine takes the asymmetry, which at 20 MHz an eSPI target does not care about: what it cares about is that the edges are where the spec says, and they are. The rising edge — the one that matters — falls at the two- to-three boundary, and both directions of the transfer are pinned to it.

SCK is the fabric clock ÷ 5. Each beat is busPhase 0–4: three cycles low, two high, one eSPI bit. A PUT places its bit on IO0 at the start of the beat (φ0); a GET samples IO1 at the rising edge (the 2→3 boundary, φ3). Eight beats make a byte, forty fabric cycles. The waveform is the whole of the engine's timing discipline --- a counter, a comparison, and one edge everything is pinned to.

One beat, five cycles

stepBusBeat runs once per fabric cycle while a transfer is in flight, and its whole logic is a three-way guard — am I mid-beat, between beats, or done?

stepBusBeat :: State -> BusIn -> (State, BusOut, Maybe Ring)
stepBusBeat s inp
  | busPhase s < 4 = (tick s, busOut (tick s), Nothing) -- mid-beat: advance phase
  | beatIx s + 1 < beatTot s = (nextBeat s, busOut (nextBeat s), Nothing) -- more beats
  | otherwise = complete s

Read the three arms as the life of a beat. While busPhase < 4 the beat is still running, so tick advances it one phase. Once busPhase reaches 4 the beat is over, and the question becomes whether there is another: if beatIx + 1 < beatTot — more bits to go — nextBeat starts the next one; otherwise the transfer is finished and complete closes it out. beatIx is the bit we are on, beatTot the total the Exec setup wrote (eight for a byte). The whole of a PUT, a GET, or a turnaround is this guard, iterated: five cycles a beat, beatTot beats, then done.

tick is where a single fabric cycle of a beat happens:

  tick t =
    let p = busPhase t + 1
        t1 = t{busPhase = p, sck = sckOf p}
     in if p == 3 then sampleGet t1 else t1

It steps busPhase up by one and sets sck to sckOf of the new phase — the waveform, generated one cycle at a time. And it carries the one event that has to happen on the rising edge: if p == 3 then sampleGet. Phase three is the first high phase, the tick that crosses the two-to- three boundary, and that is exactly when a GET must read the wire. So tick samples there and nowhere else.

Between beats, nextBeat resets the phase counter and sets up the next bit:

  nextBeat t =
    let bi = beatIx t + 1
     in t{busPhase = 0, beatIx = bi, sck = 0, lanes = beatLanes t bi}

busPhase back to zero, beatIx up by one, SCK back to idle-low, and — the important part — lanes = beatLanes t bi, the drive for the new bit placed now, at the start of the beat, at phase zero. That is the “drive @ φ0” the diagram marks: each bit’s value goes onto the lanes as its beat begins, and holds for the whole five cycles while SCK pulses once beneath it.

What each beat drives

beatLanes is the function that decides what the lanes carry, and it is a three-way case on the one thing that distinguishes a PUT from a GET from a turnaround — the pending field:

beatLanes :: State -> Unsigned 4 -> Lanes
beatLanes t bi = case pending t of
  PendGet{} -> hiZ
  PendTar -> tarBeat bi
  _ -> serializeX1 (shifter t) !! bi

Three directions, one field. A GET has pending = PendGet …, so its lanes are hiZ — all drivers released, the bus handed to the other side to drive, because on a read we are the one sampling. A turnaround has PendTar, so its lanes are tarBeat bi — the turnaround waveform for bit bi, which drives the first clock and releases the rest, the handover choreography an eSPI bus does between command and response. Anything else — a PUT, whose pending is PendNone — serialises: serializeX1 (shifter t) !! bi takes the byte in the shifter and picks out bit bi, MSB-first, to drive on IO0.

Two of those three — serializeX1 and tarBeat, along with hiZ and the Lanes type itself — are the last shut box in this arc, Tamal.Bus.Serdes, the serialiser. We are using it exactly as before: serializeX1 turns a byte into per-bit lane drives, tarBeat turns a clock index into a turnaround drive, hiZ means “release.” How they do it is the final post. Here it is enough that beatLanes reads the pending field and asks the serialiser for the right drive, and the fact that all three eSPI directions fall out of one three-way case is the whole shape of the thing.

Sampling a GET

The other half of a transfer is reading, and it is the sampleGet that tick fires at phase three:

  sampleGet t = case pending t of
    PendGet{} -> t{shifter = shifter t `shiftL` 1 .|. zeroExtend (pack (ioIn inp !! (1 :: Index 4)))}
    _ -> t

Only a GET samples — the guard is PendGet{}, and everything else passes the state through untouched. When it is a GET, the move is the classic serial-in shift: shifter << 1 makes room at the bottom, and .|. … (ioIn inp !! 1) drops the sampled bit of IO1 — the eSPI response lane — into that new low bit. Do that once per beat, at each rising edge, and after eight beats the shifter holds the byte that came back, assembled MSB-first: the first bit sampled has been shifted left seven times to the top, the last sits at the bottom. It is the mirror of the PUT’s serialise — one drives a byte out a bit at a time, the other shifts a byte in a bit at a time, both pinned to the same phase-three edge.

Completing the transfer

When the last beat’s busPhase reaches four with no beats left, complete closes the op — and this is where a GET finally pays out everything it recorded as pending back in Exec:

complete :: State -> (State, BusOut, Maybe Ring)
complete s = case pending s of
  PendGet rd nbits crc ->
    let byte = shifter s
        crc' = if crc then crc8Update (rxCrc s) byte else rxCrc s
        capW = captureWord (pack nbits) byte
        (ptr', ovf', mw) = pushWord (ringPtr s) (ovf s) capW
        s' =
          (advance s)
            { sck = 0, busPhase = 0, beatIx = 0, pending = PendNone
            , rxCrc = crc'
            , regs = writeReg (regs s) rd (resize byte)
            , ringPtr = ptr', ovf = ovf'
            }
     in (s', busOut s', mw)
  _ ->
    let s' = (advance s){sck = 0, busPhase = 0, beatIx = 0, pending = PendNone}
     in (s', busOut s', Nothing)

The second arm is the easy one: a PUT or TAR has nothing to hand back, so completion just idles SCK, clears the beat scratch, and advances to the next instruction. The first arm is where a GET’s three recorded promises — the rd, the nbits, the crc flag it wrote into PendGet — come due at once.

byte = shifter s is the assembled result. Three things happen to it. It is written to the register: writeReg (regs s) rd (resize byte), the rd the instruction named, widened to the register’s width. It is folded into the CRC residue — but only if crc: if crc then crc8Update (rxCrc s) byte else rxCrc s. That flag is the difference between GET_BYTE, which advances the CRC so a program can check a packet’s residue, and GET_BITS, which is CRC-neutral and leaves the residue alone. crc8Update is the CRC block we read whole, called here on the byte just sampled — the residue the last post’s RDSR reads is built right here, one received byte at a time. And it is recorded into the trace: captureWord and pushWord, which are the record half of the post.

Notice what completion never does: stall. The register write, the CRC fold, and the advance happen unconditionally; only the trace push can fail, and when it does it drops the record and sets a flag rather than holding the bus. That is the introduction’s load-bearing rule — never block the bus on trace backpressure — and it is enforced here, in the order of these bindings: the bus work is done before the trace is even attempted, so the trace can never delay it.

The trace ring

A GET’s completion writes one record — a CAPTURE — and the two functions that build and place it are the whole of how the engine writes to the trace. First the word:

captureWord :: BitVector 4 -> BitVector 8 -> BitVector 32
captureWord nbits byte = bitCoerce (0b00 :: BitVector 2, 0 :: BitVector 18, nbits, byte)

A CAPTURE is thirty-two bits: a two-bit tag 00, eighteen zero bits of padding, the four-bit nbits (how many bits this capture holds), and the eight-bit byte. bitCoerce packs that tuple into a single word by laying its fields end to end — 2 + 18 + 4 + 8 = 32, exactly full. The tag in the top two bits is how the host, reading the ring back later, tells one kind of record from another.

Then placement, which is the ring’s one interesting decision:

pushWord :: Unsigned RW -> Bool -> BitVector 32 -> (Unsigned RW, Bool, Maybe Ring)
pushWord ptr ov w
  | ov = (ptr, True, Nothing)
  | ptr <= termAddr - 1 = (ptr + 1, False, Just (Ring ptr w))
  | otherwise = (ptr, True, Nothing)

Three cases, and they are the trace ring’s whole contract. If the overflow flag ov is already set, the ring has given up: drop the word, keep the flag high, write nothing. If there is room — ptr <= termAddr - 1, at or below the last usable slot — write the word at ptr and bump the pointer. Otherwise the ring is full: set overflow, drop the word, and — the important part — write nothing, so the pointer never climbs onto termAddr.

That last slot is reserved on purpose. The memories post noticed it from the other side: the ring is 4096 words, termAddr = maxBound, and the top slot is kept empty so a terminator always has somewhere guaranteed to land. pushWord is the code that keeps the promise — records fill from the bottom up to termAddr - 1 and stop, dropping themselves with a sticky flag rather than ever clobbering the slot the HALT word is going to need. Drop on overflow, never wrap, never stall, never touch the terminator. A compliance transcript wants an honest ordered prefix and a flag that says “there was more,” not a silently overwritten tail.

MARK: a two-word record

Most records are one word and are written in the cycle that produces them. MARK is the exception — it is two words, a label and a payload — and it is the reason the shape post’s lifecycle had a phase called TraceEmit that did nothing but “write a MARK’s second word.” Back in Exec, a MARK wrote its first word (the label) and set pending = PendMark payload; TraceEmit is where the second word lands:

stepTraceEmit :: State -> BusIn -> (State, BusOut, Maybe Ring)
stepTraceEmit s _ = case pending s of
  PendMark payload ->
    let s' = (advance s){ringPtr = ringPtr s + 1, pending = PendNone}
     in (s', busOut s', Just (Ring (ringPtr s) payload))
  _ -> (advance s, busOut s, Nothing)

It spills the payload the Exec cycle stashed in pending to the next ring slot, bumps the pointer, and advances. The label word it followed was built by a sibling of captureWord:

markLabelWord :: BitVector 14 -> BitVector 32
markLabelWord lbl = bitCoerce (0b10 :: BitVector 2, 0 :: BitVector 16, lbl)

Tag 10, sixteen zeros, a fourteen-bit label. Then the payload word, whole and untagged, in the cycle after. Splitting the write across two cycles is why the Exec side checked that two slots were free before committing to either — a half-written MARK, a label with no payload, would be a corrupt record, so the engine writes both or neither. The two cycles are one atomic act stretched over a phase boundary, and TraceEmit is the second half of it.

WAIT_ON: blocking on the alert

WaitAlert is the last of the three deferred phases, and the only one that can spend more than a fixed number of cycles. It is where a WAIT_ON sits and watches the alert line:

stepWaitAlert :: State -> BusIn -> (State, BusOut, Maybe Ring)
stepWaitAlert s inp = case pending s of
  PendWait rd
    | asserted -> done rd 1
    | waitTimer s == 0 -> done rd 0
    | otherwise -> (s{waitTimer = waitTimer s - 1}, busOut s, Nothing)
  _ -> (advance s, busOut s, Nothing)
 where
  b =
    if cfgAlertSource (cfg s) == AlertPin
      then alertIn inp
      else ioIn inp !! (1 :: Index 4)
  asserted = b == 0 -- ALERT#/IO[1] are both active low (§6.5)
  done rd v =
    let s' = (advance s){regs = writeReg (regs s) rd v, pending = PendNone}
     in (s', busOut s', Nothing)

Each cycle in WaitAlert asks one question in priority order. Is the alert asserted? The alert is active-low — b == 0 — and b is chosen the same way GET_ALERT chose it, the configured pin or in-band IO[1]. If asserted, the wait is satisfied: done rd 1 writes a one into the result register and moves on. Otherwise, has the timer run out? waitTimer == 0 means it has, and done rd 0 falls through with a zero — timed out, no alert. Otherwise, decrement waitTimer and wait another cycle. The register ends up holding a one if the alert came and a zero if the clock beat it, so the program can branch on which happened. WAIT_ON armed the timer in Exec; WaitAlert counts it down.

HALT, and the record a run ends on

Every run ends by writing one last record, and every trap in the last post — the decode error, the config trap, the reserved status register — ended by calling this:

haltWith :: Bool -> BitVector 3 -> BitVector 8 -> State -> (State, BusOut, Maybe Ring)
haltWith trap reason status s =
  let s' = s{phase = Halted}
      w = bitCoerce (0b11 :: BitVector 2, 0 :: BitVector 17, reason, trap, (ovf s), status)
   in (s', busOut s', Just (Ring termAddr w))

haltWith builds the terminator and drops the machine into Halted. The word is the third record shape: tag 11, seventeen zeros, a three-bit reason, a one-bit trap flag, the sticky ovf bit, and an eight-bit status. A plain HALT calls it with trap = False, reason = 0 and the program’s own status byte; a trap calls it with trap = True, one of the five reasons, and — crucially — on a state that has been run through safePins first:

safePins :: State -> State
safePins s = s{csN = 1, sck = 0, rstN = 1, lanes = hiZ}

CS# high, SCK low, RESET# released, lanes hiZ — the bus put back to idle before the machine stops, so a program that dies mid-frame leaves nothing driving. And the terminator goes to Ring termAddr — the reserved top slot pushWord guarded so carefully. That guarding pays off exactly here: no matter how many records overflowed, the slot the HALT word needs is free, so a run always ends with a readable terminator that carries its overflow bit along. A truncated trace still says, in its last word, that it was truncated.

That is the fourth and last record shape, and it completes a small taxonomy. Every word the ring ever holds is one of four:

REVISION at slot zero — [major | minor | patch], the version stamp the shape post’s Preamble wrote on the first cycle.
CAPTURE, tag 00 — one word, a sampled byte and its bit count.
MARK, tag 10 — two words, a label then a payload.
HALT, tag 11 — the terminator, with trap, reason, ovf, and status.

And there is a quiet honesty in how they are built. Every one of these words is assembled inline with bitCoerce, right here in the engine, because step has to be synthesizable — it emits at most one word a cycle, and it cannot call the list-returning encoder that would be the natural way to describe a record. So the layouts live twice: once here, as bitCoerce tuples in captureWord, markLabelWord, and haltWith, and once in Tamal.Trace, as an encodeRecord that the tests use as the reference model. Every comment in this file that says mirrors Trace.encodeRecord is a promise that the two agree — the engine’s fast inline form and the trace module’s readable canonical form, checked against each other so the bytes the host reads back are the bytes the format says. Tamal.Trace never runs on the fabric; it exists so the engine’s inline packing has something to be proven equal to.

What we read

The wire and the record, both. On the wire: SCK is the fabric clock over five, low three, high two, and every edge that matters is the rising one at the two-to-three boundary. stepBusBeat is a three-way guard that ticks a beat, starts the next, or completes; beatLanes reads one pending field and gets all three eSPI directions — release for a GET, turn around for a TAR, serialise for a PUT — out of the still-shut serialiser; sampleGet shifts the response in MSB-first on the rising edge; and complete writes the register, folds the CRC residue that RDSR will read, and pushes the capture — bus work first, so the trace can never stall it.

And the record: a ring that fills from the bottom, drops on overflow with a sticky flag, and never touches the terminator slot the memories kept empty; a MARK whose two words are written across a phase boundary or not at all; a WAIT_ON that counts down against an active-low alert; and a HALT that ends every run with a status, a reason, and, on a trap, a bus set safe — four record shapes, built fast inline but pinned to Tamal.Trace’s readable encoder so the two can be checked equal.

With that, the engine is whole as a map. The shape drew it, the dispatch chose within it, and this post ran its wire and wrote its trace. Across three posts we have used — and never opened — every leaf it composes: decode, dataResult, branchTaken, readReg and writeReg, decodeConfig, serializeX1, and tarBeat. That was the whole wager of reading outside in: hold the pieces as one-line promises long enough to understand the machine that spends them, and only then open them.

Now we open them, in the order the engine first reaches for each. And the engine’s very first act on any word — before compute, before the bus, before anything — was decode. So that is where we go next: down into Tamal.Isa, the instruction set itself, the box every road out of Exec began by opening.

The point-free spelling boolToBit <$> (>= 3) reads oddly the first time. (>= 3) is a function Index 5 -> Bool; <$> over the function “functor” is ordinary composition, so boolToBit <$> (>= 3) is \p -> boolToBit (p >= 3) — take a phase, test whether it is three or four, turn the answer into a Bit. It is the same fmap-is-composition trick the primer noted, used to write a one-liner that would otherwise need a lambda. Clash lowers it to a comparator and nothing else. ↩

Tamal: One Instruction, One Cycle

2026-08-03T09:00:00+00:00

The last post drew the map and left every road on it unwalked. We read the engine’s shape — the pure step, the eight phases, the seventeen-field state it threads — and then stopped at the one phase where the work actually happens: Exec, with the instruction word from memory finally valid in hand, decoded by nothing yet. This post walks in.

Exec is the hub. Every instruction the engine runs passes through it exactly once, and what happens in that one cycle is the whole of the machine’s behaviour above the wire. Most instructions finish here — compute a value, take a branch, poke a pin — and hand the machine back to Fetch for the next word. A few use their one cycle in Exec not to finish but to arm themselves and hand off to a longer phase. Either way, the cycle is the same shape: decode the word, and dispatch on what it turned out to be.

Decode, then dispatch

The phase helper step hands the cycle to is stepExec, and it is two lines:

stepExec :: State -> BusIn -> (State, BusOut, Maybe Ring)
stepExec s inp = case decode (instrWord inp) of
  Left _ -> haltWith True 1 0 (safePins s) -- decode error -> reason 1
  Right i -> execInstr i s inp

Everything the engine does with a word begins with decode (instrWord inp). decode is the first of the shut boxes we reach for — it lives in Tamal.Isa, it turns the raw 32 bits the memory handed back into a typed Instr, and it is the whole subject of a later post. Here we treat it exactly as its type asks us to: it returns an Either — a cousin of Rust’s Result<T,E> —, and the two sides are the fork this function is built on.

Left is a decode error: the word was not a legal instruction — a reserved opcode, a bad field, a bit pattern the ISA refuses. There is no “ignore it and move on”; an engine that silently skips a word it cannot read is an engine that turns a corrupted program into undefined behaviour. So a decode error traps: haltWith True 1 0 (safePins s). We will read haltWith in full in the next post — it writes the terminator record that ends a trace — but its arguments already tell the story. True is the trap flag; 1 is the reason, and it is the first of five the engine can give^[1]; safePins s drives CS#, RESET#, SCK, and the lanes back to their safe idle before the machine stops, so a program that dies mid-transaction does not leave the bus wedged. A trap is a HALT with a cause and clean pins.

Right i is the good path: a decoded Instr, handed to execInstr along with the state and this cycle’s inputs. That function is the rest of the post.

A case as wide as the ISA

execInstr dispatches on the decoded instruction, and its case is the widest in the series — one arm per instruction the ISA defines. Here is its shape, the DATA block collapsed to save your scrolling:

execInstr :: Instr -> State -> BusIn -> (State, BusOut, Maybe Ring)
execInstr i s inp = case i of
  LoadImm rd _ -> dataWb rd
  Lui rd _ -> dataWb rd
  Mov rd _ -> dataWb rd
  Add rd _ _ -> dataWb rd
  -- … Addi, Sub, And_, Andi, Or_, Ori, Xor_, Xori, Shift: all dataWb rd
  Halt st -> haltWith False 0 st s
  Rdsr rd srn -> {- status read or trap -}
  Beq a b off -> branch Br.Beq a b off
  -- … Bne, Bltu, Bgeu
  CsAssert -> pinOp (s{csN = 0})
  -- … CsDeassert, RstAssert, RstDeassert, CrcReset, SetConfig, GetAlert
  PutByteImm b -> startPut b 8
  -- … the other PUT/GET forms, TarImm, TarReg
  Mark lbl a -> {- arm TraceEmit -}
  WaitOn rd _ timeout -> {- arm WaitAlert -}

The width is real — there are more than thirty constructors — but the handlers are few, and that gap is the first thing worth seeing. A total case over Instr means every instruction the ISA can produce has a defined action here, checked by the compiler: leave one out and Clash refuses to build. But thirteen of those arms say the same three words, dataWb rd, and four of them say branch, and a cluster of them say pinOp. The case is wide because the instruction set is wide; the behaviour behind it collapses into a handful of shapes. Read the shapes, and you have read the dispatch.

There are exactly three destinations, and they are the three exits from Exec the shape post’s lifecycle diagram drew without opening:

One Exec cycle, zoomed in from the shape post's lifecycle. decode turns the fetched word into an Instr (or fails, and traps). execInstr sends it to one of three destinations: the accent path is the single-cycle majority that computes or jumps or pokes and returns to Fetch; the middle path arms a multi-cycle transfer and hands off to the phases the next post opens; the bottom path stops the machine. The case is wide, but every arm lands in one of these three.

We walk the accent path first, because it is where nearly every arm ends up.

Thirteen instructions, one handler

The DATA group is the engine’s compute: load an immediate, move a register, add, subtract, the three bitwise operations and their immediate forms, the shift. Thirteen instructions — and all thirteen dispatch to the same three words:

  LoadImm rd _ -> dataWb rd
  Lui rd _ -> dataWb rd
  Mov rd _ -> dataWb rd
  Add rd _ _ -> dataWb rd
  Addi rd _ _ -> dataWb rd
  Sub rd _ _ -> dataWb rd
  And_ rd _ _ -> dataWb rd
  Andi rd _ _ -> dataWb rd
  Or_ rd _ _ -> dataWb rd
  Ori rd _ _ -> dataWb rd
  Xor_ rd _ _ -> dataWb rd
  Xori rd _ _ -> dataWb rd
  Shift rd _ _ _ -> dataWb rd

Every arm names its destination register rd and throws the rest of its fields away with underscores, because the fields do not matter here — they matter to the thing that computes the value. The arm’s whole job is to say “this instruction writes a register, and the register is rd.” The computing is dataWb, one of the helpers in the where block:

  rs1v = readReg (regs s) (operandRs1 i)
  rs2v = readReg (regs s) (operandRs2 i)
  dataWb rd =
    let s' = (advance s){regs = writeReg (regs s) rd (dataResult i rs1v rs2v)}
     in (s', busOut s', Nothing)

Read dataWb inside out. dataResult i rs1v rs2v is the value — computed by dataResult, another shut box, the ALU that a later post opens. Notice how it is called: it is handed the whole instruction i and two operand values, and it works out the rest — which operation, which immediate — from i itself. That is why all thirteen arms could collapse into one handler: they do not each need to pick out their own operation, because dataResult reads the operation off the instruction. The arm supplies rd; the ALU supplies everything else.

writeReg (regs s) rd (…) stores that value into the register file — writeReg belongs to the register file, a box for a later post, and it quietly enforces one rule we will lean on: a write to x0 is discarded, because x0 is hardwired zero. advance s sets the phase back to Fetch and steps the program counter to pc + 1. And the output is (s', busOut s', Nothing) — next state, its projected pins, and Nothing, because a register write leaves no trace record. One cycle, one register, back to Fetch.

Which registers, though

Two lines in that where block did the reading: rs1v and rs2v, the values of the two source registers, each readReg (regs s) applied to a register number that comes from operandRs1 i and operandRs2 i. Those two selectors are small tables, and they are pure engine logic — not a leaf, nothing shut, so we read them here:

operandRs1 :: Instr -> Reg
operandRs1 = \case
  Mov _ a -> a
  Add _ a _ -> a
  -- … every instruction with a first source register returns it …
  Beq a _ _ -> a
  PutByteReg a -> a
  Mark _ a -> a
  _ -> 0

operandRs2 :: Instr -> Reg
operandRs2 = \case
  Add _ _ b -> b
  Sub _ _ b -> b
  -- … only the instructions with a second source register …
  Bgeu _ b _ -> b
  _ -> 0

Each is a \case — a bare case on the function’s one argument — that picks the relevant field out of the constructors that have one, and falls through to 0 for everything else. operandRs1 returns the first source register of any instruction that has one; operandRs2 the second, which far fewer instructions have. The catch-all _ -> 0 is doing real work: 0 is x0, the register hardwired to zero, so an instruction with no second operand “reads x0” and gets zero — a read that is always safe, always defined, and costs nothing, because x0 is not a register you can get wrong. An immediate instruction like Addi names one source and lets the other resolve to x0; LoadImm names neither and reads x0 twice. The value it does not use is a harmless zero, and the ALU ignores it.

This is the RISC-V flavour the engine borrows showing through: sources named rs1 and rs2, a zero register that makes “no operand” and “the zero operand” the same thing, so the datapath never needs a special case for an absent argument.

The one status the engine answers

Most of what a program might ask about lives in the host, not the engine — but there is exactly one status read the engine answers itself:

  Rdsr rd srn
    | srn == 0 ->
        let s' = (advance s){regs = writeReg (regs s) rd (zeroExtend (rxCrc s))}
         in (s', busOut s', Nothing)
    | otherwise -> haltWith True 3 0 (safePins s) -- reserved sr# -> reason 3

RDSR — read status register — names a status register number srn, and the engine defines exactly one: number 0, the running receive CRC-8 residue. When srn == 0 the engine writes zeroExtend (rxCrc s) into rd — the eight-bit residue, widened to the register’s thirty-two — and advances. Any other srn is a register the engine does not have, and reading it traps with reason 3.

That residue is not new; it is the CRC block cashed in. rxCrc is the accumulator that post built, folded over every byte the engine reads off the bus, and the introduction’s peripheral_io_read.s ended its response phase by reading it — rdsr t2, CRC — and branching on whether it had driven to zero. This arm is the other end of that program line: the one place the engine reaches into its own CRC state and hands it to a register a program can test. The residue law the CRC post proved by algebra is the check a real eSPI program runs, and RDSR sr0 is how it runs it.

Branches, and arithmetic the engine owns

Four arms are conditional branches, and all four defer to one helper:

  Beq a b off -> branch Br.Beq a b off
  Bne a b off -> branch Br.Bne a b off
  Bltu a b off -> branch Br.Bltu a b off
  Bgeu a b off -> branch Br.Bgeu a b off

branch is where the engine does arithmetic that is genuinely its own — not delegated to a leaf, but computed right here, because it is about the program counter and nothing else knows the program counter:

  branch op a b off =
    let taken = Br.branchTaken op (readReg (regs s) a) (readReg (regs s) b)
        -- offset is 11-bit signed; PC is AW=10-bit. Take the low AW bits;
        -- pc + off ≡ pc + (off mod 2^AW) (mod 2^AW)
        offAw = unpack (truncateB off) :: Unsigned AW
        s'
          | taken = s{phase = Fetch, pc = pc s + offAw}
          | otherwise = advance s
     in (s', busOut s', Nothing)

The condition, taken, is Br.branchTaken op … — the comparator from Tamal.Branch, imported qualified as Br, a shut box for the compute post. It takes the comparison (Beq, Bne, and the unsigned Bltu/Bgeu) and the two register values and answers yes or no. Give that to the engine and the rest is the program counter.

The offset arithmetic repays a close look, because it is a small, exact piece of hardware reasoning. The branch offset off is an eleven-bit signed number — it can reach forwards or backwards. The program counter is ten bits (AW), addressing the thousand-and-twenty-four-word instruction store. So the offset is one bit wider than the counter it adjusts, and the code reconciles them in one move: truncateB off keeps the low ten bits, unpack … :: Unsigned AW reads them as an unsigned ten-bit number, and pc s + offAw adds. That looks like it throws the sign away — and it does, and it is still correct, because the addition is modular. A backwards jump of four is the signed offset -4, which in eleven bits is 0x7FC; its low ten bits are 0x3FC, which is 1020 unsigned; and pc + 1020 modulo 1024 is pc - 4. The two’s-complement wraparound that makes signed and unsigned addition the same operation — the CRC post’s “add and subtract are one thing” has a cousin here — means the engine needs no signed adder and no special case for a backwards branch. It adds the low bits and lets the tenth-bit overflow fall off, and the arithmetic comes out right.^[2]

The two outcomes differ in one field. Taken: s{phase = Fetch, pc = pc s + offAw} — jump, by pointing the counter at the target and going straight to Fetch. Not taken: advance s — the ordinary pc + 1. The offset is measured from the branch’s own address, because pc still holds that address in Exec; Fetch spent a cycle but never touched it. And the unconditional jump the assembler offers, j off, is not a new instruction at all — it is beq x0, x0, off, a branch whose condition compares x0 to itself and is therefore always taken. The zero register earns its keep twice: once as the absent operand, once as the always-true comparison.

Pokes: pins and config

A cluster of arms change one piece of state and step on. They share a handler, and the handler’s name is a small, honest lie:

  CsAssert -> pinOp (s{csN = 0})
  CsDeassert -> pinOp (s{csN = 1, lanes = hiZ})
  RstAssert -> pinOp (s{rstN = 0})
  RstDeassert -> pinOp (s{rstN = 1})
  CrcReset -> pinOp (s{rxCrc = 0})
  SetConfig p -> case decodeConfig p of
    Right c -> pinOp (s{cfg = c})
    Left _ -> haltWith True 2 0 (safePins s) -- unsupported config -> reason 2

pinOp :: State -> (State, BusOut, Maybe Ring)
pinOp s = let s' = advance s in (s', busOut s', Nothing)

pinOp is the single-cycle latch: take a state that already has one field changed, advance it to the next instruction, project the pins, write no trace. Read the arms as “change this, then step.” CsAssert pulls CS# low to open a frame; CsDeassert raises it and releases the lanes to hiZ, ending the frame cleanly; RstAssert/RstDeassert drive the RESET# sideband; CrcReset clears the receive residue so the next RDSR starts fresh.

The name is a lie because CrcReset and SetConfig are not pins — pinOp is really “the shape of a single-cycle state poke,” and it just happened to be named for its most common user. SetConfig is the one with a fork: it runs its immediate through decodeConfig — a shut box, and the one whose contents fold into the ISA post, since decoding a configuration field is the same act as decoding an instruction — and either latches the new cfg or, on a configuration the engine does not support, traps with reason 2. The two traps we have now met in passing, config and RDSR, are reasons 2 and 3; the decode error was 1; the fourth and fifth wait for the parts that raise them.

One arm in this neighbourhood is not a pinOp, because it does not just change state — it reads the world and writes a register:

  GetAlert rd ->
    let b =
          if cfgAlertSource (cfg s) == AlertPin
            then alertIn inp
            else ioIn inp !! (1 :: Index 4)
        s' = (advance s){regs = writeReg (regs s) rd (zeroExtend (pack b))}
     in (s', busOut s', Nothing)

GET_ALERT samples the alert line and drops it into rd. Which line “the alert” is depends on configuration: an eSPI target can raise its alert on a dedicated ALERT# pin or in-band on IO[1], and cfgAlertSource (cfg s) picks between alertIn (the synchronised pin from this cycle’s BusIn) and ioIn inp !! 1 (lane one of the sampled IO). Either way the sampled bit is zero-extended into the register. It is a single-cycle read — no clock toggles, no beat — because electrically it is just a sample, which is exactly why it lives here in Exec among the one-cycle arms rather than out in the bus phase with the transfers.

The ones that don’t finish here

Everything so far has finished inside its one Exec cycle and returned to Fetch. The remaining arms are the transfers and the trace and the wait — the instructions the shape post drew detouring through BusBeat, TraceEmit, and WaitAlert — and their arms do something subtly different. They spend their Exec cycle arming the state and setting the next phase, then hand off. The finishing is the next post’s subject; the arming is this one’s, because it happens right here.

The PUT and GET families are the clearest pair. Putting a byte on the wire:

  PutByteImm b -> startPut b 8
  PutByteReg a -> startPut (truncateB (readReg (regs s) a)) 8

  startPut byte total =
    let s' =
          s
            { phase = BusBeat
            , busPhase = 0
            , beatIx = 0
            , beatTot = total
            , shifter = byte
            , pending = PendNone
            , lanes = serializeX1 byte !! (0 :: Unsigned 4)
            }
     in (s', busOut s', Nothing)

Read what startPut writes into the state, because every field is a piece of setup the shape post named and left idle. phase = BusBeat points the machine at the bus phase. busPhase, beatIx reset the SCK counter and the bit counter to the start of a transfer. beatTot = total records how many bits — eight for a byte. shifter = byte loads the bits to send. And lanes = serializeX1 byte !! 0 drives the first bit onto the lanes immediately, using serializeX1, the serialiser that is a shut box for the last post in this arc. startPut does not run the transfer; it loads the gun and points the machine at the phase that pulls the trigger, and then it is done, in one cycle, like everything else in Exec.

Getting a byte is the mirror image, and it uses the pending field the shape post introduced as the machine’s “deferred work” slot:

  startGet rd total crc =
    let s' =
          s
            { phase = BusBeat
            -- … busPhase, beatIx, beatTot as before …
            , shifter = 0
            , lanes = hiZ
            , pending = PendGet rd total crc
            }
     in (s', busOut s', Nothing)

A GET cannot write its result now — the bits have not been sampled yet. So it records what it will owe when they have: pending = PendGet rd total crc says “when this transfer completes, write the result into rd, it is total bits wide, and crc decides whether to fold it into the residue.” The register the shape post saw in PendGet’s first field is filled in right here, by the instruction that will be paid out cycles later. lanes = hiZ releases the bus so the other side can drive it. The rest — TAR, which drives a turnaround; MARK, which writes the first word of a two-word trace record and arms TraceEmit for the second; WAIT_ON, which loads waitTimer and enters WaitAlert — are the same move in different clothes: set the phase, arm the scratch, record what is pending, hand off. Their completions, and the bus timing that drives them, are the next post.

What we read

Exec, walked end to end. It begins by asking decode to turn the fetched word into an Instr, and forks on the answer: a Left traps with reason one and safe pins, a Right goes to a case as wide as the instruction set. That width is a surface; underneath it the arms collapse to three destinations. Thirteen DATA instructions share one dataWb that hands the whole instruction to the still-shut ALU and writes one register; the operand-selector tables say which registers each reads, and x0 makes “no operand” free. RDSR answers the one status the engine owns, the CRC residue. The four branches defer their condition to the shut comparator but keep the PC arithmetic for themselves — an eleven-bit signed offset added modulo a ten-bit counter, backwards jumps falling out of wraparound, j revealed as beq x0, x0. The pin and config pokes latch one field through a handler misnamed for its commonest user, and GET_ALERT samples a line the configuration chooses. And the transfers, the trace, and the wait spend their one cycle here not finishing but arming — loading a shifter, counting out beats, recording in pending what they will owe — and pointing the machine at a longer phase.

We have now used, without opening, every leaf the engine composes: decode, dataResult, branchTaken, readReg and writeReg, decodeConfig, and serializeX1. That was the bet of reading outside in, and it has paid: you can follow every instruction the engine runs while holding those seven as one-line promises. The promises come due later in the arc.

But first, the handoff. Four arms pointed the machine at BusBeat, TraceEmit, and WaitAlert and stopped mid-gesture — a shifter loaded, a beat count set, a write pending, a phase changed — and the cycle ended there. Next we follow them across that seam: the bus micro-FSM that divides the fabric clock into an SCK, walks the beats a PUT or GET counts out, samples what comes back and folds it into the residue and the trace ring, and finally writes the terminator records — HALT and the traps we kept meeting — that end a run. The engine has decided what to do; next it does it, on the wire, one quarter-clock at a time.

The engine gives five trap reasons, and this post meets three of them where they are raised: 1 for a decode error (here in stepExec), 2 for an unsupported configuration (SetConfig), and 3 for a reserved status register (RDSR). The remaining two — 4 for an illegal or reserved-group instruction, and the machinery that folds the reason, a trap flag, and the sticky overflow bit into a single terminator word — belong to the next post, where haltWith is read in full. Every trap is a HALT that also says why, and drives the pins safe on the way down, so a program that dies mid-frame cannot leave CS# or the lanes stuck driving the bus. ↩
The one thing the truncation does cost is range: an eleven-bit offset can name distances a ten-bit counter cannot, so the top bit of the offset is redundant with the sign that the low ten bits already imply modulo 1024. In practice the assembler only emits offsets that resolve to a real target inside the thousand-and-twenty-four-word program, so the reachable set is the whole store either way, and the wraparound is a correctness argument, not a reachability limit. It is the same reason a byte-addressed CPU can use a signed branch displacement narrower than its full address space: you never branch further than the program is long. ↩

Tamal: Eight Phases and a Pure Step

2026-07-31T09:00:00+00:00

The memories closed on a promise: next, we walk through. Every block before them — the CRC, the UART, the loader, the two block RAMs — was read the same way, opened and emptied and set back down, and each ended by pointing at the one door still shut. This is that door. Tamal’s engine is the machine the whole series has been circling: the thing the loader fills, triggers, and drains; the thing that turns the words in one memory into the records in the other; the reason any of the plumbing exists.

But you do not read a machine the way you read a leaf.

Read the shape first

The CRC was twenty-eight lines and one idea; the memories were four lines and a contract. Each fit on a screen, and each was read whole — top to bottom, every line accounted for, nothing left shut when the post ended. That is what a leaf is: small enough to hold entire.

Tamal.Engine is not small. It is five hundred and thirty-four lines (four hundred and ten of which are actual code), and — this is the part that changes how we have to read it — it composes eight other modules. It calls the CRC we already read, and seven blocks we have not: a decoder, an ALU, a branch comparator, a register file, a serialiser, a configuration decoder, and a pair of width aliases. Open all of that at once, in the order the lines happen to fall, and the shape is gone before the second page — you are three levels deep in a bus-timing detail with no memory of the machine it serves.

So we read it the other way. This post reads the engine’s shape — its skeleton, its lifecycle, the type of the one function that is the whole machine — and it leaves the rooms shut. When the engine reaches for decode we will say decode turns a word into an instruction and walk on; when it reaches for dataResult we will say that is the ALU and walk on. The boxes get names here and get opened later, one post each, in the order the engine actually touches them.

This is the exact inverse of how we read the UART. There we built up: the baud generator, then the transmitter, then the receiver, and only at the end the five-line uart umbrella — which could simply name oversampleTick, uartRx, and uartTx, because by then we knew every one of them. Leaves first, umbrella last. The engine turns that around. We start at the umbrella — the biggest one in the project — and it will name blocks we have not read, on purpose, because with a machine this size the shape is the thing you need before the pieces, not after. Outside in, not inside out.

Here is the whole map in one sentence, and the rest of the post is its legend: the engine is a single pure function that, once a cycle, looks at where it is and decides what to do next. Everything below is what “where it is” and “what to do next” are made of.

The widest door yet

A Tamal module opens by naming itself and listing what leaves through the wall. We have read that opening five times now, and each time the door was narrow: the CRC exported one name, the memories exported two. Here is the engine’s:

module Tamal.Engine
  ( Phase (..)
  , Pending (..)
  , State (..)
  , BusIn (..)
  , BusOut (..)
  , Ring (..)
  , initState
  , powerUpDefault
  , revisionWord
  , busOut
  , step
  ) where

Eleven names — the widest export list in the series — and the first thing to notice is that six of them are types. Phase, Pending, State, BusIn, BusOut, Ring: half the door is given over not to functions but to the shapes of data, each exported with the (..) that says “and all of its constructors too.” The CRC exported a verb; the engine exports mostly nouns.

That is not clutter, and it is worth pausing on, because it tells you what kind of module this is. A leaf like crc8Update can hide its types — it takes a BitVector 8 and gives one back, and the outside world never needs a name for anything inside. The engine cannot hide its types, because the engine does not run itself. Look at the last two names on the list: step, the transition function, and busOut, a projection of it. Neither is mealy. Neither touches a Signal. Tamal.Engine is a pure description of a machine, and something one level up — the board’s system, a later post — has to lift it onto a clock and wire its inputs and outputs to real pins. To do that, the top must be able to say State, and BusIn, and BusOut. The types are exported because they are the engine’s contract with whatever runs it: the wiring diagram one level up is written in these nouns. A machine that will be assembled elsewhere has to publish the shape of its own plugs.

Eight closed boxes

Under the header sit the imports, and this is where reading outside in first costs us something:

import Clash.Prelude
import Tamal.Alu (dataResult)
import qualified Tamal.Branch as Br
import Tamal.Bus.Serdes (Lanes, hiZ, serializeX1, tarBeat)
import Tamal.Config (AlertSource (..), Config (..), IoMode (..), Role (..), Sck (..), decodeConfig)
import Tamal.Crc (crc8Update)
import Tamal.Isa (Instr (..), Reg, decode)
import Tamal.Params (AW, RW)
import Tamal.RegFile (Regs, initRegs, readReg, writeReg)

The prelude swap on the first line is the same one every block has carried — the line that trades ordinary Haskell’s furniture for the Signal, Bit, Vec, and BitVector that lower to gates — and I will not re-derive it a sixth time. It is the eight lines under it that are new. When we read the UART umbrella, its three imports pulled in blocks we had already opened; naming uartRx meant something because we had spent a post inside it. Here, eight modules come across the wall, and we have opened exactly one of them.

That one is the CRC: crc8Update, the polynomial-remainder block we read whole, arrives here to keep a running residue over the bytes the engine reads off the bus. And one more is not quite an import of code but of vocabulary — Tamal.Params (AW, RW), the two width aliases we met alongside the memories: AW = 10 for the program counter, RW = 12 for the ring pointer. Those two are known quantities.

The other six are the boxes this series will open next, and it is worth naming what each one is now, precisely because we are about to spend three posts using them without looking inside:

Tamal.Isa — decode. Turns a raw 32-bit word into a typed Instr, or fails. The instruction set itself: every opcode the engine knows, and the reserved patterns it refuses. The engine’s first act on any word is to call this.
Tamal.Alu — dataResult. The combinational compute for the DATA instructions: add, subtract, the bitwise operations, the shift. Give it a decoded instruction and two register values, it hands back the result.
Tamal.Branch — branchTaken (imported qualified as Br). The unsigned comparator behind the conditional branches: given a comparison and two values, is the branch taken?
Tamal.RegFile — readReg, writeReg, initRegs, Regs. The sixteen general-purpose registers, x0 hardwired to zero, that the datapath reads its operands from and writes its results to.
Tamal.Bus.Serdes — serializeX1, tarBeat, Lanes, hiZ. The bit-level serialiser: how a byte becomes MSB-first drive on the IO lanes, what a turnaround looks like, and what “all lanes released” means. The closest thing to the wire.
Tamal.Config — decodeConfig and the configuration types (Role, IoMode, Sck, AlertSource). How a SET_CONFIG immediate becomes the role, IO width, clock rate, and alert source the engine runs under.

Six modules, four posts, opened in that rough order once the shape is drawn. For now they are names with one-line jobs, and that is enough — which is the whole bet of reading outside in. You can understand what the engine does with a decoder long before you understand how the decoder works, the same way you can read a paragraph knowing a word means “remainder” without having derived long division. Hold the eight names. We will spend them.

One line that is the whole machine

Skip past the type declarations for a moment — we will come back and read every field — to the function they all exist to serve. Stripped of its doc-comment, this is step:

step :: State -> BusIn -> (State, BusOut, Maybe Ring)
step s inp = case phase s of
  Idle -> stepIdle s inp
  Halted -> stepHalted s inp
  Preamble -> stepPreamble s inp
  Fetch -> stepFetch s inp
  Exec -> stepExec s inp
  BusBeat -> stepBusBeat s inp
  TraceEmit -> stepTraceEmit s inp
  WaitAlert -> stepWaitAlert s inp

The signature is the map, and under the primer’s reading — a type is half the documentation — it very nearly tells the whole story before the body does. Read it as three arrows’ worth of intent:

Given the machine’s current State and this one cycle’s inputs (BusIn), produce the next State, the pins to drive right now (BusOut), and maybe one word to write into the trace ring.

That is a Mealy machine, the exact shape the primer introduced and the transmitter, receiver, and loader each wore: a pure function from current-state-and-input to next-state-and-output, with all the memory pulled out into that first argument and threaded back out as the first result. What makes the engine’s version the keystone is not its shape — it is the same s -> i -> (s, o) as every mealy before it — but its size, and one deliberate choice hiding in the return type.

The choice is that the output is split in three: (State, BusOut, Maybe Ring), not the two-tuple (State, output) the primer’s mealy wants. The middle element, BusOut, is the pins — everything the engine is driving onto the world this cycle. The third, Maybe Ring, is a write: Just a record to store in the trace memory, or Nothing, at most one per cycle. Keeping them separate is a readability decision the top pays back for; when the engine is finally lifted, a four-line adapter re-bundles the pins and the write into the single output mealy expects, and step itself is never touched.^[1]

And note what the body of step actually is: a case on phase s — one field of the state — dispatching to eight helpers, one per phase, and doing nothing else. step does not compute; it routes. The real work lives in the eight step* functions, and the machine’s entire behaviour is “look at which phase you are in, and hand the cycle to the helper that owns it.” That is the skeleton. The rest of this post reads the state the case inspects, the phases it dispatches on, and the four simplest helpers; the next post opens stepExec, and the one after that opens the three bus-and-trace phases.

One more thing the signature says by saying nothing: there is no mealy here, no register, no Signal anywhere in the type. step is a pure function — same state and input, same three outputs, every time. That is not an aesthetic preference; it is the reason the engine is testable at all. Because the whole transition, bus timing and trace emission included, is one pure function, hedgehog can drive it by folding it over a list of cycles and check the results against a reference model — no simulator, no waveform, no clock. The intro promised a design where the entire machine runs in a sub-second test suite. This signature, pure to its bones, is where that promise is kept.

Eight phases

The field the case inspects is phase, and its type is the machine’s spine:

data Phase
  = Idle
  | Preamble
  | Fetch
  | Exec
  | BusBeat
  | TraceEmit
  | WaitAlert
  | Halted
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

Eight constructors, no fields — a plain enumeration, the hardware equivalent of a state register wide enough to hold eight states. This is the lifecycle of the whole engine, and every one of the step* helpers is named for exactly one of these. Read them as the stages of a life:

Idle — powered up, pins safe, waiting for a start trigger. The resting state.
Preamble — the first cycle of a run: write the REVISION word into the top of the trace ring so the host can confirm what bitstream it is talking to.
Fetch — the one-cycle bubble while the instruction memory hands back the word at the program counter. We will see exactly why it costs a cycle.
Exec — the hub: decode the fetched word and dispatch on what it is. Every instruction passes through here.
BusBeat — sequencing an SCK-timed transfer on the eSPI bus: the multi-cycle drive-and-sample of a PUT, GET, or turnaround.
TraceEmit — the second cycle of a two-word trace record (a MARK), spilling its payload word after its header.
WaitAlert — blocked inside a WAIT_ON, watching the alert line and counting down a timeout.
Halted — stopped, after a HALT or a trap, holding the pins safe and asserting a flag that tells the top to drain the ring.

The deriving block is the same four-class refrain every stateful block in the series has carried, and I will be quick with it: Generic lets Clash derive the rest structurally, Show and Eq are for the tests, and NFDataX is the one that earns its place — it is Clash’s promise that a value of this type can be the contents of a register, with a defined-enough representation to sit in a flip-flop.^[2] A Phase is going to be a register on the fabric; NFDataX is what lets it.

The state it carries

Phase says where the machine is. The State record says everything else the machine remembers — and at seventeen fields it is the largest record in the project. Do not read it as a list; read it as six groups, which is how it is written:

data State = State
  { phase :: Phase
  , pc :: Unsigned AW
  , regs :: Regs
  , cfg :: Config
  , rxCrc :: BitVector 8
  , ringPtr :: Unsigned RW
  , ovf :: Bool
  , csN :: Bit
  , sck :: Bit
  , rstN :: Bit
  , lanes :: Lanes
  , busPhase :: Index 5
  , beatIx :: Unsigned 4
  , beatTot :: Unsigned 4
  , shifter :: BitVector 8
  , pending :: Pending
  , waitTimer :: BitVector 9
  }
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

The lifecycle is one field: phase, the enum we just read, the thing step dispatches on.

The architectural state — four fields — is what a program can see and change, the machine’s equivalent of a CPU’s visible registers: pc, the program counter, an Unsigned AW indexing the instruction store; regs, the sixteen general-purpose registers (a Regs, from the still-shut register file); cfg, the current configuration (role, IO width, clock, alert source); and rxCrc, the running CRC-8 residue over bytes read from the bus — the accumulator the CRC block was built to advance, living here as engine state.

The trace state — two fields — is the outflow bookkeeping: ringPtr, the next free slot in the trace ring (an Unsigned RW), and ovf, a sticky boolean that latches high the first time a record is dropped because the ring filled. Together they are the “drop on overflow, never stall the bus” rule the intro set out, reduced to a pointer and a flag.

The pin latches — four fields — are the outputs, stored: csN, sck, rstN, and lanes. This is a deliberate choice worth naming now and cashing later. The engine does not compute its pins fresh each cycle from its inputs; it holds them in the state and updates them on transitions. That makes them registered outputs — glitch-free, and depending only on where the machine is, not on what arrived this cycle.^[3] lanes is a Lanes, the per-lane drive-and-enable bundle from the still-shut serialiser.

The bus scratch — four fields — is the working memory of a transfer, meaningless outside a BusBeat: busPhase, an Index 5 that counts the five fabric cycles of one SCK period; beatIx and beatTot, which bit of how many; and shifter, the eight-bit register that bits are driven out of or sampled into. We will read every one of these in the bus post; here they are just named.

The deferred work — two fields — is how a single Exec cycle arranges for something to finish later: pending, a small sum type we will meet in a moment, and waitTimer, the countdown a WAIT_ON arms. When decoding an instruction needs an after-effect — a register to write once a GET completes, a second word to spill, an alert to wait for — Exec records it here and a later phase carries it out.

Seventeen fields, six jobs. And the shape of Pending, exported beside State, is the catalogue of those deferred after-effects:

data Pending
  = PendNone
  | PendGet Reg (Unsigned 4) Bool
  | PendMark (BitVector 32)
  | PendTar
  | PendWait Reg

PendNone is the resting value: nothing owed. The other four each name a piece of work an Exec decode sets up and a later cycle discharges — a register write-back waiting on a completed GET, a payload word waiting to be spilled, an in-flight turnaround, a register waiting on an alert. Reading Pending in full is reading the multi-cycle instructions in full, so it belongs to the posts that open those; for now it is enough to see that “deferred work” has exactly five shapes, and that the machine is never owed more than one thing at a time.

What goes in, what comes out

Three types remain, and together they are the engine’s boundary — the plugs the exported nouns exist to let the top wire. First, what the top feeds in every cycle:

data BusIn = BusIn
  { instrWord :: BitVector 32
  , ioIn :: Vec 4 Bit
  , alertIn :: Bit
  , startIn :: Bool
  }

instrWord is the word the instruction memory hands back — and here the memories post pays off exactly. That post spent its length pinning down a one-cycle read latency: ask a block RAM for the word at an address this cycle, get it next cycle. instrWord is that word, arriving one cycle after the engine offered its pc — which is the whole reason Fetch exists as a phase, as we are about to see. ioIn is the four IO lanes sampled off the pads; alertIn is the synchronised alert pin; startIn is the control-plane trigger the top holds high once a program is loaded.

Then what the engine drives out, every cycle:

data BusOut = BusOut
  { pcOut :: Unsigned AW
  , csOut :: Bit
  , sckOut :: Bit
  , rstOut :: Bit
  , lanesOut :: Lanes
  , haltedOut :: Bool
  , ringPtrOut :: Unsigned RW
  }

Every one of these is something the top wires to a pin or a memory. pcOut is the fetch address handed to the instruction RAM — the other half of the round trip instrWord completes. csOut, sckOut, rstOut, lanesOut are the eSPI pins. haltedOut is the flag the loader watches to know when to start draining. And ringPtrOut is how deep the trace ring filled, so the drain knows how much to sweep. If you read the loader and wondered where startIn, haltedOut, and ringPtrOut reached to — this is their other end.

And last, the write itself:

data Ring = Ring
  { rAddr :: Unsigned RW
  , rData :: BitVector 32
  }

A Ring is one word rData bound for one address rAddr in the trace memory. It is the third element of step’s output wrapped in Maybe, because a cycle writes at most one trace word — and most cycles write none.

The pins are a projection, not a computation

We said the pins live in the state. busOut is the function that reads them back out, and it is deliberately the dullest function in the file:

busOut :: State -> BusOut
busOut s =
  BusOut
    { pcOut = pc s
    , csOut = csN s
    , sckOut = sck s
    , rstOut = rstN s
    , lanesOut = lanes s
    , haltedOut = phase s == Halted
    , ringPtrOut = ringPtr s
    }

Read it and there is nothing to compute: five of the seven outputs are a field of State copied straight across, ringPtrOut is one more, and the only field that is not a bare copy is haltedOut, which is the single comparison phase s == Halted — the flag is not stored, it is derived, true exactly when the machine is in its stopped phase. That is the whole function.

That dullness is the point, and it is the same point the UART umbrella made about wiring: busOut adds no behaviour. It is a projection — a lens that shows the outside world the fields of the state it is allowed to see, and nothing more. Because the pins were already decided when the state was built, presenting them costs no logic; the outputs are a view of the machine, computed once, the same whether you look this cycle or leave it be. Every step* helper ends by calling busOut on the state it produced, and so the pins are always exactly the state’s own pins. There is no second place where an output could disagree with the state that owns it.

Power-up

Three small definitions set the machine’s power-up contents. The first two are the constants a fresh run starts from:

powerUpDefault :: Config
powerUpDefault = Config Controller X1 Sck20 AlertPin

revisionWord :: BitVector 32
revisionWord = 0x00_01_0000

powerUpDefault is the configuration the engine assumes before any SET_CONFIG runs: controller role, x1 IO width, 20 MHz clock, alerts on the pin. These four are the design’s default posture — the intro’s “controller only, single IO, one clock rate” v1, written as a value. revisionWord is the version stamp 0x0001_0000 — major 0, minor 1, patch 0 — that Preamble lays down as the first word of every trace, so a host reading the drain can confirm the gateware matches the tool talking to it.

Then initState, the whole machine at rest:

initState :: State
initState =
  State
    { phase = Idle
    , pc = 0
    , regs = initRegs
    , cfg = powerUpDefault
    , rxCrc = 0
    , ringPtr = 1
    , ovf = False
    , csN = 1
    , sck = 0
    , rstN = 1
    , lanes = hiZ
    , busPhase = 0
    , beatIx = 0
    , beatTot = 0
    , shifter = 0
    , pending = PendNone
    , waitTimer = 0
    }

Read it as the answer to “what is every field before anything happens.” phase = Idle, waiting. The pins safe: csN = 1 and rstN = 1 (both active-low, so both deasserted), sck = 0, and lanes = hiZ — all IO lanes released, driving nothing, the serialiser’s name for “hands off the bus.” The architectural state cleared: pc at zero, regs at initRegs, cfg at the power-up default, rxCrc at zero. And one field that is not zero: ringPtr = 1, not 0, because slot zero of the ring is reserved for the REVISION word Preamble writes — the pointer starts one past it, at the first slot a program’s own records may use.

There is a larger design decision folded into initState existing at all, and it is one the intro flagged: Tamal has no reset port. The top ties reset permanently deasserted and leans on power-up init, the way the sibling Clash examples do. So initState is not what a reset line loads — there is no reset line — it is what the registers power up holding. Which raises the obvious question: if there is no reset, how does a second program run after the first one halts? The answer is the next section.

The four trivial phases

Four of the eight step* helpers do so little that we can read them all here and leave the substantial four — Exec, and the three bus phases — for the posts that own them. Start with the two resting states, Idle and Halted, which are almost the same function written twice:

stepIdle :: State -> BusIn -> (State, BusOut, Maybe Ring)
stepIdle s inp
  | startIn inp = (softInit, busOut s, Nothing)
  | otherwise = (s, busOut s, Nothing)

stepHalted :: State -> BusIn -> (State, BusOut, Maybe Ring)
stepHalted s inp
  | startIn inp = (softInit, busOut s, Nothing)
  | otherwise = (s, busOut s, Nothing)

Both say the same thing: hold until told to start. With startIn low, each returns the state it was handed, unchanged — (s, busOut s, Nothing), the machine standing still, driving its stored pins, writing nothing. When startIn goes high, both hand back softInit, and that is where a run begins. The only difference between the two is which pins they hold while waiting: Idle holds the safe power-up pins, Halted holds the safe pins a halt left behind — but the response to start is identical, which is exactly why re-running works.

softInit is that response, and it is one line:

softInit :: State
softInit = initState{phase = Preamble}

It is initState — the entire power-up state, every field back to its rest value — with the one change that the phase is Preamble rather than Idle. So start, from Idle or from Halted, throws the whole machine back to power-up and points it at the preamble. This is the answer to the no-reset question: a second run does not need a reset line because softInit is the reset, performed in the datapath, synchronous and total. Every architectural field, the ring pointer, the overflow flag, the config — all of it returns to the same values it powered up with, which means a re-run is byte-for-byte identical to a first run. Load a program, run it, halt, pulse start, and you get the same trace you got the first time, with no power cycle and no reset pin. The determinism the intro promised falls out of one record update.

Then Preamble, the first cycle of any run:

stepPreamble :: State -> BusIn -> (State, BusOut, Maybe Ring)
stepPreamble s _ = (s{phase = Fetch}, busOut s, Just (Ring 0 revisionWord))

It ignores its input (_), advances the phase to Fetch, and — the one thing it does — emits Just (Ring 0 revisionWord): write the revision stamp to slot 0 of the trace ring. That is why ringPtr started at 1; slot 0 is spoken for, here, on the first cycle, so that the very first word a host reads back is always the version of the machine that produced the trace. One cycle, one write, and on to Fetch.

And Fetch itself, the shortest of all:

stepFetch :: State -> BusIn -> (State, BusOut, Maybe Ring)
stepFetch s _ = (s{phase = Exec}, busOut s, Nothing)

It does nothing but advance to Exec. No write, no state change beyond the phase. And this apparent do-nothing is the one-cycle bubble the memories warned us to expect. The program counter pc is offered to the instruction RAM as pcOut; the RAM’s read latency means the word at that address — instrWord — does not arrive until the next cycle. Fetch is the machine spending that cycle on purpose: it steps to Exec, and by the time Exec runs, instrWord in its BusIn is valid and ready to decode. The bubble is not waste; it is the phase that lets a synchronous memory be the program store. One cycle of patience, bought knowingly, exactly as the memories post said it would be.

Put the four together and the outer loop of the machine is already visible: Idle waits; start soft-inits to Preamble; Preamble stamps the revision and goes to Fetch; Fetch waits a cycle for the RAM and goes to Exec. What Exec does — and how it loops back to Fetch for the next instruction, or detours through the bus phases, or lands in Halted — is the rest of the engine, and the rest of this arc. Here is the shape it all hangs on:

The whole engine as a lifecycle. The spine reads left to right: Idle waits for start; Preamble stamps the REVISION word and falls to Fetch; Fetch spends the one-cycle memory bubble and hands a valid instruction to Exec. The accent arc is the main loop --- Exec back to Fetch, one instruction retired, PC advanced. The multi-cycle instructions detour through the dashed group below (BusBeat, TraceEmit, WaitAlert) and return to Fetch when they finish; those three phases are the subject of a later post. HALT or a trap leaves the spine for Halted, and a fresh start soft-inits all the way back to Preamble for a byte-identical re-run. This post read the spine and the two resting states; the arc through Exec and the detour through the group are what remains.

What we read

The last door in the series, opened just wide enough to see its plan. Not the way we opened a leaf — whole, in a screenful — but the way you open a machine too big to hold at once: shape first, rooms shut. We read the widest export list yet and found six of its eleven names were types, because an engine assembled one level up has to publish the shape of its own plugs. We read eight imports and opened only the one we already knew, holding the other seven as named boxes — decode, ALU, branch, registers, serialiser, config — to be spent now and opened later, the exact inversion of the UART’s leaves-first climb.

We read the one line that is the whole machine: step, a pure Mealy transition from state-and-input to state-and-pins-and-maybe-a-write, routing each cycle to one of eight phase helpers and computing nothing itself. We read the spine those helpers hang on — eight phases, Idle through Halted — and the seventeen-field State they thread, in its six groups, its pins deliberately stored so that busOut can be a dull and honest projection rather than a computation. We read the boundary types that plug into the memories and the loader, and saw the one-cycle fetch latency reappear as a phase spent on purpose. And we read the four trivial helpers: two resting states that hold until start, a preamble that stamps a revision, and a fetch that waits a beat for a block RAM — and, hiding in softInit, the reset that a machine with no reset port performs in its own datapath, byte-for-byte repeatable.

What we did not read is the machine’s actual work. Exec is still a name in a case; the seven boxes are still shut; the bus scratch fields have been named and not used. That is on purpose. The shape is drawn now — the loop from Fetch to Exec and back, the detours below it, the exits to Halted — and against that shape the work will make sense.

Next we stand in Exec and watch a single instruction go by: one word, one cycle, decoded and dispatched — the DATA compute, the branch and its PC arithmetic, the pin and config pokes — with the leaves it calls still treated as the black boxes we promised to open after. The map is drawn. Now we walk the first road on it.

The adapter is the four lines the PLAN calls stepM: stepM s i = let (s', bo, mr) = step s i in (s', (bo, mr)), and then engine = mealy stepM initState. All it does is glue the second and third elements of step’s output into one pair, because mealy wants a single output value, not two. Splitting them in step keeps the pure function readable — pins here, trace write there — and paying a four-line tax at the one place it is lifted is cheaper than blurring the two everywhere they are produced. It is the same “keep the core pure, let the shell adapt” seam the whole design is built on. ↩
NFDataX is Clash’s “can be stored in a register” class — roughly, a type whose values have a normal form Clash can reason about, including how they behave when partly undefined at power-up. Every type that lands in a flip-flop needs it: Phase, Pending, State, all of them. It is derived anyclass — the compiler writes the instance from the type’s structure — while Generic, Show, and Eq are derived stock, the built-in strategy. The split into two deriving clauses is just Haskell keeping the two derivation mechanisms apart; the four classes together are the standard kit every stateful Tamal block wears. ↩
In the strict vocabulary this makes the pins a Moore output — a function of the state alone, busOut s, with no path from this cycle’s BusIn to this cycle’s pins — while the next state and the Maybe Ring write remain Mealy, since they do depend on the input. Driving the pins from stored state rather than combinationally from the input is what keeps them glitch-free: they change only on a clock edge, when the state updates, never in the middle of a cycle because an input wiggled. ↩

Tamal: Four Lines and Three Promises

2026-07-29T09:00:00+00:00

The loader spent its entire length driving two memories. It wrote instruction words into one of them, four bytes at a time, straight through as they came off the wire. It swept the other one out after HALT in seven patient phases, dancing with a one-cycle read latency that it never stopped to explain. Both memories were named, used, and leaned on — and neither was ever opened.

This post opens them. Tamal.Mem is forty-one lines including the licence header and the doc-comments, and the part that becomes gateware is four. You can read it in less time than it takes to read this paragraph, and you would be forgiven for wondering why it gets a post at all.

It gets one because the four lines are not the module. The module is a contract — a set of promises about latency, about ordering, and about what a memory says before it has been told anything — and the four lines are only where those promises get pinned to a width and given a name. The file that holds them down is a hundred and forty-seven lines of tests, three and a half times the module it checks. That ratio is not an over-test. It is the honest shape of a module whose entire content is contract.

The entire source

Minus the SPDX header and the doc-comments:

module Tamal.Mem
  ( instrRam
  , ringRam
  ) where

import Clash.Prelude

import Tamal.Params (AW, RW)

instrRam ::
  forall dom.
  (HiddenClockResetEnable dom) =>
  Signal dom (Unsigned AW) ->
  Signal dom (Maybe (Unsigned AW, BitVector 32)) ->
  Signal dom (BitVector 32)
instrRam = blockRamPow2 (repeat 0)

ringRam ::
  (HiddenClockResetEnable dom) =>
  Signal dom (Unsigned RW) ->
  Signal dom (Maybe (Unsigned RW, BitVector 32)) ->
  Signal dom (BitVector 32)
ringRam = blockRamPow2 (repeat 0)

Two signatures, two identical bodies, one import that is a pair of type aliases. The instruction store and the trace ring — the two halves of the machine’s memory, one that the engine reads from and one that it writes to — are the same expression twice, differing only in the width of the number you address them with.

What isn’t here

There is no data declaration. There is no state record, no where clause, no mealy. The CRC computed a residue; the loader remembered where it stood in a frame. Nothing in this file computes and nothing in this file remembers.

That is worth sitting with, because it makes Tamal.Mem the second kind of nothing the series has met. The UART top was the first: a module with no behaviour of its own, whose whole content was composition — three blocks that each own an idea, wired into one block that owns none. Tamal.Mem does not even compose. It applies a library function to a constant, twice. Its content is neither computation nor wiring but naming: it takes a primitive that already exists, fixes the two parameters that make it this machine’s memory, and gives the result a name that the rest of the design can say out loud.

So if the code is four lines, what is the module for? The answer is the rest of this post, and it comes in two halves that say the same thing twice — once in English, once in a language a machine can check.

One decision, made once and reused

There is exactly one engineering decision in the file, and it is which primitive, not which code.

Clash offers several block-RAM shapes. blockRam takes an Enum-addressed vector and wants an Index n. blockRamU starts with undefined contents; blockRam1 starts with one repeated value. blockRamPow2 takes a Vec (2^n) and addresses it with an Unsigned n. The engine already carries its program counter as an Unsigned AW and its ring pointer as an Unsigned RW, and both depths are exact powers of two, so blockRamPow2 maps onto them one to one — no Unsigned-to-Index conversion at the call site, and no out-of-range case to guard, because at these widths there are no out-of-range addresses to have — the primer’s point about widths living in the type, cashed in as a branch that does not need to exist.^[1]

The initial contents, repeat 0, do double duty. On hardware Clash lowers the vector into the block RAM’s INIT strings, which is what makes Vivado infer a real BRAM rather than scattering the array across LUTs. In simulation it means every address is defined from the first cycle onward, which is what makes randomised testing possible at all — a generator that reads an address nobody has written yet gets a zero rather than an exception.

The widths themselves live somewhere else. AW and RW come from Tamal.Params, a leaf that imports nothing but Clash.Prelude and exists so that the engine, the memories, the loader, and the trace model can all name the same number without importing one another. Resizing the instruction space becomes one edit in one file instead of a hunt for hand-copied Unsigned 10 literals.

The write port is the last piece of the decision, and the most deliberate. The engine emits its trace writes as Maybe Ring, a proper record with named fields. The obvious signature would take that type. This one takes a bare Maybe (Unsigned n, BitVector 32) instead — because accepting Ring would mean importing Tamal.Engine, and a memory that imports the engine is a memory that knows what a trace record is. The unpacking is one line, and it lives up in the topEntity where the two are already being wired together:

ringWrite :: Maybe Ring -> Maybe (Unsigned RW, BitVector 32)
ringWrite = fmap (\(Ring a d) -> (a, d))

One fmap is the entire price of keeping the memory ignorant. It is the same discipline that produced Tamal.RegFile, built before Engine.step existed to use it and never importing the engine whose registers it holds. We have not opened that one yet — it is waiting for a later post — but by the time we do, the shape will be familiar.

What falls out of the two widths is the geometry:

Memory	Depth	Address	Data	≈ BRAM36
instruction	1024 = 2^10	`Unsigned AW`	`BitVector 32`	1
trace ring	4096 = 2^12	`Unsigned RW`	`BitVector 32`	4

Five block RAMs out of the 135 an xc7a100t carries, which is a rounding error. And one small gift: with the ring at 4096 words, the engine’s reserved terminator slot at maxBound :: Unsigned RW is exactly the last address that exists. termAddr = maxBound and termAddr = D - 1 are the same constant, so choosing the full width of the address type made the overflow-proof terminator free. What that slot is for is the engine’s business, and stays behind its door.

Three promises

Here is the part that actually matters. blockRamPow2 comes with three semantics, and Tamal.Mem implements none of them — it inherits all three, and its contribution is to pin them at a width where the rest of the design can rely on them.

One cycle, not zero and not two. The output at cycle t is the value read at cycle t-1. Write 0xDEAD_BEEF to address 5 on cycle 0 and read address 5 from then on:

let addrs    = [0, 5, 5, 5]
    writes   = [Just (5, 0xDEAD_BEEF), Nothing, Nothing, Nothing]
    expected = [0, 0xDEAD_BEEF, 0xDEAD_BEEF, 0xDEAD_BEEF]

The value appears one output later than the read that asked for it, and then stays. The leading zero is the load-bearing part of that expectation: it is the cycle-0 read of address 0, surfacing on cycle 1 while the write to address 5 is still in flight. Drop it and the very same test would pass against a memory with no latency at all, because everything after it would still line up. Pinning a delay means pinning where the trace starts, not only what it settles to.

Reads see the memory as it was. Read and write the same address in the same cycle and the read wins; the new value shows up on the cycle after. Write 0x1111 to address 3, then on the very next cycle write 0x2222 to address 3 while reading it:

simInstr
  [0, 3, 3, 3]
  [Just (3, 0x1111), Just (3, 0x2222), Nothing, Nothing]
  @?= [0, 0x1111, 0x2222, 0x2222]

This one is not a convention that Clash picked and could change its mind about. It is a fact about the silicon.^[2]

The first output is a lie you must not read. At cycle 0 the memory has not yet been asked anything, and blockRamPow2 reports deepErrorX — an undefined value that explodes if you force it. Every sampler in the test file therefore drops sample 0 before comparing anything. That is not defensive tidying; it is the third promise, and ignoring it is how you get a test suite that fails with a stack trace instead of a diff.^[3]

None of those three sentences is about code that lives in Tamal.Mem. All three are about code that lives in Clash.Prelude. What Tamal.Mem does is make them this machine’s promises, at 10 bits and at 12 bits, so that the loader and the engine can be written against them.

The same three promises, in Haskell

Prose promises do not fail a build. So the test file states the same three things again, as an executable oracle — a pure model of a block RAM in eight lines of ordinary Haskell, with no Signal and no clock anywhere in sight:

refRam ::
  (KnownNat n) =>
  [Unsigned n] ->
  [Maybe (Unsigned n, BitVector 32)] ->
  [BitVector 32]
refRam addrs writes = go [] (L.zip addrs writes)
 where
  go _ [] = []
  go mem ((a, w) : zs) = fromMaybe 0 (L.lookup a mem) : go (push w mem) zs
  push Nothing m = m
  push (Just (wa, wd)) m = (wa, wd) : m

Read it against the list above and the three promises are all sitting there, one per detail.

fromMaybe 0 is the zero-initialisation: an address that appears in no prior write reads as zero, exactly as repeat 0 guarantees on the hardware side.

The order of the two expressions in go is the read-before-write rule. The cons cell emits L.lookup a mem — a lookup in the memory as it stands before this cycle — and only then recurses on push w mem, the memory with this cycle’s write applied. Swap those and the model would describe a write-first RAM, and every collision test would fail. The rule is not commented; it is structural, which is the better place for it.

The shape of go is the one-cycle latency. Each step consumes one (address, write) pair and produces one output, but the output it produces is the read taken before that step’s write landed — so the list refRam returns is [out 1, out 2, ...], offset by exactly one from the stimulus that produced it. The undefined out 0 is not in the list because the model never had a reason to invent it.

Two smaller things earn their place. The assoc list is kept most-recent-first, so L.lookup — which returns the first match — naturally yields the newest write to an address, and a slot that has been written five times reads back the fifth value with no bookkeeping. And the whole thing is polymorphic in the address width n, so a single oracle serves a 1024-word instruction store and a 4096-word ring without a line of duplication. One model, both memories.

Getting a clock into a test

The oracle is pure; the thing it is checked against is not. Bridging them takes a sampler:

simInstr :: [Unsigned 10] -> [Maybe (Unsigned 10, BitVector 32)] -> [BitVector 32]
simInstr addrs writes =
  L.drop 1
    $ sampleN
      (L.length addrs + 1)
      ( instrRam (fromList (addrs <> L.repeat 0)) (fromList (writes <> L.repeat Nothing)) ::
          Signal Dom100 (BitVector 32)
      )

Three things are load-bearing here, and each of them is the kind of detail that costs an afternoon the first time.

sampleN is what supplies the clock, reset, and enable that HiddenClockResetEnable is asking for. Crucially, the RAM has to be applied directly inside sampleN’s argument. You cannot factor instrRam out into a parameter and write one generic sampler for both memories, because the constraint can only be discharged inside that rank-2 position. Hence two nearly identical samplers — simInstr here, simRing the same shape at width 12 — rather than one clever one. The duplication is not a failure of imagination; it is where the type system draws the line.

fromList (addrs <> L.repeat 0) makes the stimulus infinite. A Signal has no end, so a finite input list would run out and force an exception on some cycle you never meant to look at. Padding with a harmless tail means the signal is total and only the prefix is ever compared.

And sampleN (n + 1) followed by L.drop 1 is the third promise, operationalised. Take one more sample than you have stimulus for, throw the undefined one away, and what remains is [out 1 .. out n] — the same length as refRam’s output, index-aligned with it. That alignment is what earns the right to write === between them. Get it wrong by one and the property still typechecks; it just compares the wrong cycles and tells you a lie.

What the properties buy

With a model and a sampler, the hedgehog properties are short. The main one feeds random interleaved sequences of read addresses and optional writes to both, at both widths, and demands they agree. Addresses are drawn from a deliberately tiny window — 0 to 15 — so that random reads frequently land on addresses that were recently written. A generator ranging over all 4096 ring slots would produce a beautiful stream of zeros and test nothing; the small window is what makes collisions and read-after-write hits common enough to matter.

The second property is more interesting, because it declines to reuse refRam. It writes a random pile of values into the window, sweeps the whole window, and checks the result against a different oracle computed on the spot — a lookup over the reversed write list:

oracle = fmap (\a -> fromMaybe 0 (L.lookup a (L.reverse ws))) win

Same answer, arrived at independently: last write wins, everything else is zero. Checking refRam against the hardware proves they agree, which is worth a lot — but two implementations that share an idea can share a misunderstanding of it. A second oracle written a different way is a second opinion. It is also the same two-implementations habit the COBS post named as the house style, applied to a model rather than a codec.

Why test a primitive you didn’t write

The obvious objection is that all of this tests Clash. It does not. blockRamPow2 is correct, and its correctness was never the question.

What is under test is the reading of it — the three promises, at these two widths, in this domain, written down somewhere that fails loudly rather than somewhere that fails quietly. If a Clash release ever changes the collision behaviour, one unit test goes red with a two-value diff instead of the engine mysteriously fetching a stale instruction on one path in one program. If someone swaps blockRamPow2 for blockRamU to save an INIT string, the zero-initialisation property catches it immediately, rather than the loader catching it three modules later as an intermittent bad word after power-up.

That is why a hundred and forty-seven lines of test sit on top of four lines of module without any embarrassment. The four lines are not the deliverable. The contract is the deliverable, and the tests are the only form in which a contract can be enforced rather than merely intended.

The door

There is one promise left to spend.

The one-cycle read latency has been, for this entire post, a nuisance — something to drop a sample for, to align a list around, to pin with a test so it does not drift. On the other side of the door it stops being a nuisance and becomes a design.

The engine’s program counter is a register inside its state, projected out as pcOut. That signal feeds instrRam, whose output feeds the instruction word back into the engine, which computes the next PC. A loop — but a loop containing two registers, the PC and the block RAM’s own output register, so there is no combinational path anywhere in it and nothing for a synthesiser to complain about. The memory’s one-cycle delay does not have to be worked around, hidden, or paid for out of the clock period. It is absorbed whole, as a phase, and the engine’s own source calls that phase by name: Fetch is documented as the 1-cycle instruction-BRAM bubble.

The cost this post spent eight sections testing around is, one level up, a pipeline stage the engine spends on purpose.

Both memories are known quantities now. The instruction store holds 1024 words and hands back what you asked for one cycle later. The ring holds 4096, the top one reserved, and behaves identically. Neither knows what a program is, what a trace record means, or which of its neighbours is writing. They are four lines and three promises, and everything above them is now allowed to depend on that.

Which leaves the engine. We have circled it since the first post — the machine the loader loads, triggers, and drains; the thing that turns the words in one memory into the records in the other. It is the last door in the series, and there is nothing left standing in front of it.

Next, we walk through.

blockRam uses only the clock and the enable — it has no content reset, and cannot have one, because a block RAM’s array is not resettable silicon. The wrappers still carry the broader HiddenClockResetEnable constraint rather than the precise (HiddenClock dom, HiddenEnable dom), which is technically looser than necessary; GHC simply discharges the two it needs and ignores the third. Uniformity with every other block in the codebase won that trade, and it costs nothing here, because Tamal’s top has no reset port anyway — the no-reset power-up design is deliberate, and a memory that cannot be reset fits it exactly rather than fighting it. ↩
A synchronous RAM latches the read address at the clock edge, and the array is read before that same edge’s write commits. Xilinx names the three possible port behaviours READ_FIRST, WRITE_FIRST, and NO_CHANGE; Clash’s blockRam models READ_FIRST. That makes read-before-write a property of the hardware you are going to get, not a convention you are free to choose — which is precisely the sort of thing that belongs in an assertion rather than a comment. A comment describing the behaviour of silicon is a comment that will one day be describing the behaviour of different silicon. ↩
deepErrorX is Clash declining to lie. A real block RAM’s output register powers up holding whatever it powers up holding, and there is no honest 32-bit value to report for the cycle before the first read completes — so Clash reports a value that is fine to carry around and fatal to inspect. This is why Clash’s own blockRam doctests begin with L.tail, and why L.drop 1 appears in both samplers here. A test that forces sample 0 has asked the simulator a question about hardware that has not happened yet, and deserves the exception it gets. ↩

Agentic Gallo: Introducing gallo-mcp

2026-07-28T20:00:00+00:00

Pico de Gallo turns an RP2350 into a USB-attached bridge that lets a host program drive real I²C, SPI, UART, GPIO, PWM, ADC, and 1-Wire straight from your laptop — so you can write and test device drivers in std Rust, C, or Python instead of cross-compiling for an MCU every time. Today there’s a new way to reach that hardware, and it isn’t for you: gallo-mcp is a Model Context Protocol server that hands the board to the AI agent writing your driver.

One tool per peripheral, over stdio

gallo-mcp runs an MCP server over stdio, wraps pico-de-gallo-lib, and exposes one tool for every peripheral operation across all seven buses. Point an MCP-capable agent at it and the model can probe and drive real silicon through the same board the gallo CLI talks to — read a sensor register, scan a bus, toggle a pin — while it’s writing the driver, without cross-compiling or flashing anything.

That closes a loop that used to need a human in the middle. Instead of you running gallo i2c scan, pasting the output into the chat, and asking “now what?”, the agent can:

explore an unfamiliar device interactively,
generate register-level driver code and validate it against the actual chip, and
turn “what does this chip return?” into a tool call it makes itself.

Wiring it into a client

Install the server:

$ cargo install gallo-mcp

gallo-mcp speaks MCP on stdout and logs to stderr, so it’s meant to be launched by a client, not run by hand. Add it as a local (stdio) server. These config files are safe to commit per project, so the tools show up only in the repos that opt in:

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pico-de-gallo": { "type": "local", "command": ["gallo-mcp"], "enabled": true }
  }
}

// Claude Code — .mcp.json
{ "mcpServers": { "pico-de-gallo": { "command": "gallo-mcp", "args": [] } } }

// Cursor — .cursor/mcp.json
{ "mcpServers": { "pico-de-gallo": { "command": "gallo-mcp", "args": [] } } }

One detail worth calling out: the server holds no persistent USB claim. Each tool call opens the board, runs, and releases it, so the device stays free for the gallo CLI or another host process between calls. There’s a small fixed connection cost per call in exchange, but it also means the server starts fine with nothing plugged in — you can attach the board mid-session and the tools start working. If you have more than one board attached, --serial-number <SN> picks one.

The tool surface

Tools are grouped by peripheral, and every one is annotated: reads carry MCP’s readOnlyHint, writes and actuation carry destructiveHint (more on why that matters below).

Peripheral	What the agent can do
device	list boards, check attach state, read firmware/schema version, ping
I²C	read, write, write-then-read, scan, batch, get/set frequency
SPI	read, write, full-duplex transfer, flush, batch, get/set config
UART	read, write, flush, get/set config
GPIO	read a pin, drive a pin, set direction/pull, bounded edge waits
PWM	get/set duty cycle, enable/disable, get/set config
ADC	read a sample, read config
1-Wire	reset, read, write, parasitic-power write, ROM search

The full catalog is in the book. A couple of conventions are worth knowing up front. Byte payloads go in as hex strings — comma-separated or bare, "0x00,0x10" or "0010" — and come back as both hex and a decimal array:

// i2c_write_read {"address":72,"data":"0x00","count":2}
{ "hex": "0x0B,0xCF", "bytes": [11, 207] }

And the GPIO edge waits are timeout-bounded only: each requires a non-zero timeout_ms. This first release deliberately leaves out infinite waits and push-based edge subscriptions — a wait that never returns would wedge the stdio session, and event streaming is out of scope for now.

Seeing the same truth as the shell

The server was validated on real hardware: a Pico de Gallo (firmware v0.10.0, schema v0.6.0 — the reliability release) with a TMP108 temperature sensor on I²C.

Over stdio, status reports the attached board:

{ "attached": true, "firmware_version": "0.10.0", "schema_major": 0, "schema_minor": 6 }

i2c_scan finds the sensor at 0x48:

// i2c_scan {"include_reserved":false}
{ "addresses": ["0x48"], "raw": [72] }

And i2c_write_read pulls its two temperature bytes:

// i2c_write_read {"address":72,"data":"0x00","count":2}
{ "hex": "0x0B,0xCF", "bytes": [11, 207] }

Those bytes are byte-for-byte identical to what the CLI returns:

$ gallo i2c write-read -a 0x48 -b 0x00 -c 2
0b cf

Turning 0x0BCF into degrees Celsius is between you and the TMP108 datasheet — the point is that the MCP round-trip returns exactly what the shell does. An agent driving the board through gallo-mcp sees the same truth you would at the prompt.

A word on safety

gallo-mcp does not gate writes itself. It annotates them and delegates approval to the MCP client: read tools are marked readOnlyHint, write and actuation tools are marked destructiveHint. A well-configured client uses those hints to prompt you before it drives a pin or writes a bus.

That delegation cuts both ways. Under a permission-less or blanket-allow client, an agent can actuate hardware — toggle GPIOs, write I²C/SPI, change bus configuration — with no confirmation at all. If the board is wired to anything you care about, run the server behind a client that honors destructiveHint, and set your permissions accordingly. The bytes are real, and so are the volts.

The plumbing: `pico-de-gallo-lib` 0.7.1

Handing the board to an agent turned up two rough edges in the host library, and smoothing them out is the other half of today’s release.

try_new(). The existing PicoDeGallo::new() (and new_with_serial_number()) enumerate USB at construction and panic when no matching board is present or the interface can’t be claimed — the old “constructing never fails” doc comment was simply wrong. That’s fine for a CLI that’s about to exit anyway, but a long-lived MCP server that connects per call can’t panic just because you haven’t plugged the board in yet. So 0.7.1 adds fallible try_new() and try_new_with_serial_number(), returning Result<PicoDeGallo, String> so the caller can report “no device attached” or retry a transient claim failure. The panicking constructors stay exactly as they were.

Nameable comms errors. 0.7.0 re-exports HostErr and WireError (and makes the host_client path public), so a downstream crate can name the transport error types when it maps PicoDeGalloError into its own representation — without pulling in postcard-rpc directly. That’s what lets gallo-mcp match on PicoDeGalloError::Comms(HostErr::Closed) and turn a dropped USB connection into a clean “no device attached” message instead of an opaque error.

Both changes are additive and non-breaking; hal, ffi, gallo, and the Python bindings resolve 0.7.1 without any changes of their own. If you’re building your own host tooling on the library, try_new() is the constructor you want.

Get it

$ cargo install gallo-mcp

crate: gallo-mcp · docs: docs.rs/gallo-mcp
library: pico-de-gallo-lib 0.7.1
everything else: the Pico de Gallo book and the repo

Wire up a board, point your agent at it, and let it read the chip itself.

Hi, I'm Norbert

2026-07-27T12:00:00+00:00

Meet Norbert — a small command-line tool I wrote to program SPI NOR flash chips. Its defining trait is patience: it reads and parses the SFDP tables, verifies its work, and would rather wait a second than guess.

Hand Norbert a chip and it works out what the part is — reads the JEDEC ID, parses the SFDP tables, or falls back to a table of chips it already knows. From there it can erase the device, program an image, verify every byte it wrote, and read the flash back. It drives a bare flash chip over a Pico de Gallo bridge, so there’s no adapter board to wire up.

A normal session looks like this:

$ norbert detect
Hmm... let's see what we've got here.
Found Winbond W25Q128JV.

$ norbert program firmware.bin
Programming firmware.bin — 512 KiB at 0x000000.

  erase    [██████████████████████████]  8/8 blocks
  program  [██████████████████████████]  512 KiB/512 KiB
  verify   [██████████████████████████]  512 KiB/512 KiB

Done. Have a nice boot.

That chattiness is the point of the name: Norbert has a personality, but only in its output. Underneath, the engineering is deliberately dull — programming flash should be predictable, transparent, reliable, and, above all, boring. It won’t skip verification because a write is probably fine, and it won’t assume every chip behaves the same.

It’s early — version 0.1 — but it already recognizes a fair number of chips — anything supporting SFDP should just work —, and --quiet gives scripts machine-friendly output when you don’t want the commentary. The source is on GitHub; if Norbert doesn’t know your chip yet, teaching it one is the easiest contribution to make.

Tamal: The Loader's Three Lives

2026-07-27T09:00:00+00:00

Yesterday we read two pure step functions and made the same promise about each of them, the promise we have been making all series: the codec describes what one byte does to the state, and someone else owns the register that makes it sequential. Someone else holds the clock. We made that promise for the CRC’s step a month of posts ago, and again for the transmitter and the receiver, and one last time yesterday for cobsDecodeStep and cobsEncodeStep. Five pure s -> i -> (s, o) machines, each admired precisely for not having a clock, each handing the clock off to a someone we kept naming and never met.

Today we meet the someone. The loader is where the clock finally lives.

It is also where everything else we have built finally meets. The receiver and transmitter gave us a byte pipe; the top sealed it and left four wires hanging at the loader’s door. Behind that door is a block that does not compute a residue or drive a line or recover a bit — it conducts. It embeds the COBS codec and threads it through its own clock; it folds the CRC over every byte in both directions; it drives the two block RAMs on the ports the engine leaves free; and it pulses the engine awake and waits for it to halt. The whole series has been building leaves. The loader is the first branch.

Yesterday’s post promised this one in as many words: the loader “wears the silhouette we have now read five times — a sum for its phase, a record for the rest, a step function beside a mealy.” That is exactly right, and exactly the shape of what follows — only scaled up. The sum is now two sums. The record is eighteen fields. And the step is the longest in the series. Same silhouette, far more mass. The mass is worth it, because it buys the loader three distinct lives — listen, run, drain — lived over and over in a loop, and a rig you can load, trigger, read, and load again.

The entire source

Minus the SPDX header and the doc-comments — but this time keeping the inline notes on the state fields, which earn their place — here is src/Tamal/Loader.hs, the longest module in the series:

module Tamal.Loader
  ( LoaderIn (..)
  , LoaderOut (..)
  , loader
  ) where

import Clash.Prelude
import Data.Maybe (fromMaybe, isJust)

import Tamal.Crc (crc8Update)
import Tamal.Loader.Cobs
import Tamal.Params (AW, RW)

data LoaderIn = LoaderIn
  { rxByte :: Maybe (BitVector 8)
  , txReady :: Bool
  , halted :: Bool
  , ringPtrIn :: Unsigned RW
  , ringData :: BitVector 32
  }
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

data LoaderOut = LoaderOut
  { txByte :: Maybe (BitVector 8)
  , instrWr :: Maybe (Unsigned AW, BitVector 32)
  , ringAddr :: Unsigned RW
  , startOut :: Bool
  }
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

data Lifecycle = RxControl | Run | Drain
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

data DrainPhase = DrOpcode | DrFetch | DrLatch | DrWordByte | DrCrcByte | DrDrainOut | DrDelim
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

data LoaderSt = LoaderSt
  { lPhase :: Lifecycle
  , lDec :: DecSt
  , lEnc :: EncSt
  , lHeld :: Maybe (BitVector 8) -- one-byte holdback (separates the trailing CRC)
  , lCrcRx :: BitVector 8 -- running CRC over confirmed bytes
  , lHaveOp :: Bool -- opcode confirmed yet?
  , lOpcode :: BitVector 8
  , lByteIx :: Unsigned 2 -- payload byte within the current word (0..3)
  , lWordAcc :: BitVector 32 -- LE word being assembled
  , lHadPay :: Bool -- any payload byte seen (TRIGGER must have none)
  , lAddr :: Unsigned AW -- next instr write slot
  , lFull :: Bool -- instr store overflowed (> 2^AW words)
  , lDrn :: DrainPhase
  , lWord :: BitVector 32 -- ring word being emitted
  , lWIx :: Unsigned 2 -- LE byte of lWord (0..3)
  , lCrcTx :: BitVector 8 -- running CRC over the drain
  , lDrCnt :: Unsigned RW -- ring record index being fetched
  , lTerm :: Bool -- fetching/emitting the terminator word
  }
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

initLoader :: LoaderSt
initLoader =
  LoaderSt -- RxControl, both codecs seeded, every counter 0, every flag False
    { lPhase = RxControl
    , lDec = initDec
    , lEnc = initEnc
    , {- … the remaining fifteen fields, all at their zero/False resting value … -}
    }

idleOut :: LoaderOut
idleOut = LoaderOut{txByte = Nothing, instrWr = Nothing, ringAddr = 0, startOut = False}

loader :: (HiddenClockResetEnable dom) => Signal dom LoaderIn -> Signal dom LoaderOut
loader = mealy loaderStep initLoader

loaderStep :: LoaderSt -> LoaderIn -> (LoaderSt, LoaderOut)
loaderStep s inp = case lPhase s of
  RxControl -> rxStep s inp
  Run -> runStep s inp
  Drain -> drainStep s inp

runStep :: LoaderSt -> LoaderIn -> (LoaderSt, LoaderOut)
runStep s inp
  | halted inp =
      ( s{lPhase = Drain, lEnc = initEnc, lDrn = DrOpcode, lCrcTx = 0, lDrCnt = 0, lWIx = 0, lTerm = False}
      , idleOut
      )
  | otherwise = (s, idleOut)

rxStep :: LoaderSt -> LoaderIn -> (LoaderSt, LoaderOut)
rxStep s inp =
  let din = case rxByte inp of
        Just 0 -> (Nothing, True) -- delimiter => frame end
        Just b -> (Just b, False)
        Nothing -> (Nothing, False)
      (dec', (mDec, done, bad)) = cobsDecodeStep (lDec s) din
      s1 = s{lDec = dec'}
   in if done
        then finalize s1 bad
        else case mDec of
          Nothing -> (s1, idleOut)
          Just d ->
            let (s2, mw) = case lHeld s1 of
                  Just h -> confirm s1 h
                  Nothing -> (s1, Nothing)
             in (s2{lHeld = Just d}, idleOut{instrWr = mw})

confirm :: LoaderSt -> BitVector 8 -> (LoaderSt, Maybe (Unsigned AW, BitVector 32))
confirm s h
  | not (lHaveOp s) =
      ( s
          { lHaveOp = True
          , lOpcode = h
          , lCrcRx = crc8Update (lCrcRx s) h
          , lAddr = if h == 0x01 then 0 else lAddr s
          , lFull = if h == 0x01 then False else lFull s
          }
      , Nothing
      )
  | otherwise =
      let crc' = crc8Update (lCrcRx s) h
          acc' = lWordAcc s .|. (zeroExtend h `shiftL` (8 * fromIntegral (lByteIx s)))
          isLoad = lOpcode s == 0x01
       in if lByteIx s == 3
            then
              let doWrite = isLoad && not (lFull s)
                  (addr', full') = if lAddr s == maxBound then (lAddr s, True) else (lAddr s + 1, lFull s)
               in ( s
                      { lCrcRx = crc'
                      , lWordAcc = 0
                      , lByteIx = 0
                      , lHadPay = True
                      , lAddr = if isLoad then addr' else lAddr s
                      , lFull = if isLoad then full' else lFull s
                      }
                  , if doWrite then Just (lAddr s, acc') else Nothing
                  )
            else
              ( s{lCrcRx = crc', lWordAcc = acc', lByteIx = lByteIx s + 1, lHadPay = True}
              , Nothing
              )

finalize :: LoaderSt -> Bool -> (LoaderSt, LoaderOut)
finalize s bad =
  let crcCand = fromMaybe 0 (lHeld s)
      crcGood = not bad && isJust (lHeld s) && lHaveOp s && lCrcRx s == crcCand
      trigOk = crcGood && lOpcode s == 0x02 && not (lHadPay s)
      s0 = resetFrame s
   in if trigOk
        then (s0{lPhase = Run}, idleOut{startOut = True})
        else (s0, idleOut)

resetFrame :: LoaderSt -> LoaderSt
resetFrame s =
  s
    { lDec = initDec
    , lHeld = Nothing
    , lCrcRx = 0
    , lHaveOp = False
    , lOpcode = 0
    , lByteIx = 0
    , lWordAcc = 0
    , lHadPay = False
    }

drainStep :: LoaderSt -> LoaderIn -> (LoaderSt, LoaderOut)
drainStep s inp = case lDrn s of
  DrOpcode ->
    feedByte s inp 0x81 False (\s' -> s'{lDrn = DrFetch, lDrCnt = 0, lTerm = False})
  DrWordByte ->
    feedByte s inp (leByte (lWord s) (lWIx s)) False (afterWordByte inp)
  DrCrcByte ->
    feedByte s inp (lCrcTx s) True (\s' -> s'{lDrn = DrDrainOut})
  DrFetch ->
    let addr = if lTerm s then maxBound else lDrCnt s
        (enc', (_, mOut, _)) = cobsEncodeStep (lEnc s) (Nothing, txReady inp)
     in (s{lEnc = enc', lDrn = DrLatch}, idleOut{txByte = mOut, ringAddr = addr})
  DrLatch ->
    let addr = if lTerm s then maxBound else lDrCnt s
        (enc', (_, mOut, _)) = cobsEncodeStep (lEnc s) (Nothing, txReady inp)
     in ( s{lEnc = enc', lWord = ringData inp, lWIx = 0, lDrn = DrWordByte}
        , idleOut{txByte = mOut, ringAddr = addr}
        )
  DrDrainOut ->
    let (enc', (_, mOut, encDone)) = cobsEncodeStep (lEnc s) (Nothing, txReady inp)
     in (s{lEnc = enc', lDrn = if encDone then DrDelim else DrDrainOut}, idleOut{txByte = mOut})
  DrDelim ->
    if txReady inp
      then (resetFrame s{lPhase = RxControl}, idleOut{txByte = Just 0})
      else (s, idleOut{txByte = Nothing})
 where
  afterWordByte i s'
    | lWIx s' /= 3 = s'{lWIx = lWIx s' + 1}
    | lTerm s' = s'{lDrn = DrCrcByte}
    | lDrCnt s' + 1 >= ringPtrIn i = s'{lTerm = True, lDrn = DrFetch}
    | otherwise = s'{lDrCnt = lDrCnt s' + 1, lDrn = DrFetch}

feedByte ::
  LoaderSt -> LoaderIn -> BitVector 8 -> Bool -> (LoaderSt -> LoaderSt) -> (LoaderSt, LoaderOut)
feedByte s inp b lst advance =
  let (enc', (readyIn, mOut, _)) = cobsEncodeStep (lEnc s) (Just (b, lst), txReady inp)
      s1 = s{lEnc = enc'}
      s2 =
        if readyIn
          then advance s1{lCrcTx = if lst then lCrcTx s1 else crc8Update (lCrcTx s1) b}
          else s1
   in (s2, idleOut{txByte = mOut})

leByte :: BitVector 32 -> Unsigned 2 -> BitVector 8
leByte w i = case i of
  0 -> slice d7 d0 w
  1 -> slice d15 d8 w
  2 -> slice d23 d16 w
  _ -> slice d31 d24 w

A dozen things, top to bottom: a three-name export list; the two I/O records LoaderIn and LoaderOut; two little sums, Lifecycle and DrainPhase; the eighteen-field LoaderSt that is the machine’s whole memory; two initialisers; the mealy one-liner and the loaderStep that dispatches on phase; and then the three step functions with their helpers. We wave past the export list and imports, slow right down for the types, and walk the machine one life at a time.

The ritual, skipped

You know this opening beat cold. A module header with its export list; the import Clash.Prelude prelude swap; the deriving stock (Generic, Show, Eq) and deriving anyclass (NFDataX) refrain stamped on every type so Clash can put it in a register. Six posts have paid that toll in full — the CRC and primer posts derived it at length — and I will not charge it a seventh time. Everyone already knows what those are about.

The one line worth stopping on is not ritual at all. It is the three imports in the middle:

import Tamal.Crc (crc8Update)
import Tamal.Loader.Cobs
import Tamal.Params (AW, RW)

The CRC fold, the COBS codec, and the shared address widths. The loader imports the very blocks the last six posts built and puts them all to work at once. This is the confluence in three lines: read them and you already know the loader will fold a CRC, stream a COBS codec, and address two memories sized by AW and RW. Everything we have read plugs in right here.

Params, since it has nowhere else to live

One of those imports has no post of its own, and never will: Tamal.Params is two type aliases and a doc-comment, and two lines do not earn a post of their own. So we settle the small debt here, once, where the loader first leans on them. In its entirety, minus the ritual:

type AW = 10 :: Nat -- instruction-address width: 2^AW = 1024 words
type RW = 12 :: Nat -- ring/trace-address width: 2^RW = 4096 words

That is the whole module. AW is the instruction-address width — 2^AW = 1024 words in the instruction store, and the program counter’s width to match. RW is the ring/trace-address width — 2^RW = 4096 words in the result ring, whose top slot is the reserved HALT terminator the drain fetches last. The point is not the two numbers but the sharing: Tamal.Params is a dependency-free leaf, importing only Clash.Prelude, so the engine, the two BRAM wrappers, the trace model, and the loader can all name the same widths without importing one another — and widening the instruction space or resizing the ring becomes a single edit here instead of a hunt for hand-copied Unsigned 10 and Unsigned 12 literals scattered across the tree. The loader meets both in a moment: lAddr :: Unsigned AW counts instruction slots, ringAddr :: Unsigned RW sweeps the ring. Debt paid; on to the types that do earn their keep.

The types are the design

The primer’s sum-and-product story, told one final time — and told carefully, because with the loader the types are the design. Read the five of them and the machine is most of the way explained; the step functions largely just honour what the records already promise. We take them in the order they appear.

The ports: `LoaderIn` and `LoaderOut`

data LoaderIn = LoaderIn
  { rxByte :: Maybe (BitVector 8)
  , txReady :: Bool
  , halted :: Bool
  , ringPtrIn :: Unsigned RW
  , ringData :: BitVector 32
  }

data LoaderOut = LoaderOut
  { txByte :: Maybe (BitVector 8)
  , instrWr :: Maybe (Unsigned AW, BitVector 32)
  , ringAddr :: Unsigned RW
  , startOut :: Bool
  }

These two records are the seam. The top left four wires hanging at the loader’s door; here they are, named and typed, sitting beside the wires that reach the other way, to the engine and the two memories. Read LoaderIn as “everything the world hands the loader each cycle”:

rxByte — a byte from the UART receiver, or Nothing. A one-cycle strobe: Just b on the cycle a byte lands, Nothing the ~500 cycles in between.
txReady — the UART transmitter is idle and can take a byte. Back-pressure for the drain.
halted — the engine’s haltedOut, a level: high for as long as the engine sits in its Halted phase.
ringPtrIn — how many trace records the engine wrote. The drain’s upper bound, read straight off the halted engine.
ringData — the ring BRAM’s read data, arriving one cycle after the loader drives an address.

And LoaderOut is “everything the loader drives back”:

txByte — a byte for the UART transmitter, or Nothing.
instrWr — a write to the instruction store: Just (addr, word) or nothing this cycle.
ringAddr — the ring BRAM read address the drain sweeps.
startOut — the one-cycle pulse that wakes the engine.

Two details hide in the signatures. First, the Unsigned AW and Unsigned RW we just met surface here as concrete port widths — instrWr’s address into the 1024-word instruction store, and ringAddr/ringPtrIn into the 4096-slot ring. Second, and quietly load-bearing: the loader drives exactly two memory ports, the instruction write and the ring read, and never the two the engine owns. It writes only while loading and reads only while draining, never overlapping the engine’s run — so the two machines share two BRAMs with no arbiter at all, collision-free by construction.^[1]

`Lifecycle`: the three lives

data Lifecycle = RxControl | Run | Drain

Three constructors, and the whole post’s title. The loader is never doing more than one of these at a time, and it moves between them in a fixed loop:

RxControl — listen. The only life that consumes the UART’s receive strobe. Decode each incoming control frame, load programs into the instruction store as they arrive, and watch for a trigger.
Run — stand aside. The engine is executing. The loader drives nothing, listens to nothing, and watches a single bit: halted.
Drain — report. The engine has halted; sweep its trace ring out the transmitter as one frame, then go back to listening.

The entire top of the machine is a case on this type. Load, run, drain, and back to load — three lives lived in a ring, re-runnable forever: a later trigger re-runs the same program, a later load replaces it.

The three lives. RxControl is the resting state and the only one that consumes the UART receiver; a valid LOAD_PROGRAM writes its words and stays put (self-loop), while a valid TRIGGER pulses startOut and steps to Run. Run watches the engine's halted level and, when it goes high, arms Drain. Drain sweeps the trace ring out the UART and returns to RxControl — so the rig is re-runnable, load/trigger/drain, round and round.

`DrainPhase`: a program counter for the sweep

data DrainPhase = DrOpcode | DrFetch | DrLatch | DrWordByte | DrCrcByte | DrDrainOut | DrDelim

Lifecycle has three states because the loader has three jobs. Drain, though, is not one action but a little sequence — emit an opcode, then fetch a ring word, then wait a cycle for the memory to answer, then emit its four bytes, then loop, then emit a CRC, then flush, then cap the frame — and this seven-constructor sum is that sequence’s program counter. The Drain life runs a tiny program, and lDrn is where in the program it is.

Why spell a sequence out as seven named states instead of a loop? Because in hardware a loop is a state machine, and every step of this one is a place the loader might have to wait: a BRAM read does not answer until the next cycle, the UART will not take a byte unless txReady, and the COBS encoder buffers a whole group before it emits. Each stall needs a named state to hold in and come back to. We walk the seven in the drain section; for now note the shape — a fetch/latch pair for the memory’s latency, a per-byte emit state, and three states to close out the frame.

`LoaderSt`: eighteen fields, four records in a trench coat

Here is the field that everyone flinches at:

data LoaderSt = LoaderSt
  { lPhase :: Lifecycle
  , lDec :: DecSt
  , lEnc :: EncSt
  , lHeld :: Maybe (BitVector 8) -- one-byte holdback (separates the trailing CRC)
  , lCrcRx :: BitVector 8 -- running CRC over confirmed bytes
  , lHaveOp :: Bool -- opcode confirmed yet?
  , lOpcode :: BitVector 8
  , lByteIx :: Unsigned 2 -- payload byte within the current word (0..3)
  , lWordAcc :: BitVector 32 -- LE word being assembled
  , lHadPay :: Bool -- any payload byte seen (TRIGGER must have none)
  , lAddr :: Unsigned AW -- next instr write slot
  , lFull :: Bool -- instr store overflowed (> 2^AW words)
  , lDrn :: DrainPhase
  , lWord :: BitVector 32 -- ring word being emitted
  , lWIx :: Unsigned 2 -- LE byte of lWord (0..3)
  , lCrcTx :: BitVector 8 -- running CRC over the drain
  , lDrCnt :: Unsigned RW -- ring record index being fetched
  , lTerm :: Bool -- fetching/emitting the terminator word
  }

Eighteen fields is a lot, and the honest reaction is a wince. But it is not eighteen unrelated things; it is four small records wearing one constructor, because a mealy carries exactly one state value and the loader would rather be one machine with one memory than four machines haggling over turns. Sort the fields by which job they serve and the wince goes away:

Phase (1 field). lPhase — which of the three lives we are living. The one field every cycle reads first.
Embedded codecs (2 fields). lDec and lEnc — the COBS decoder’s DecSt and the encoder’s EncSt, held inside the loader’s state. This is the promise the last post made, kept to the letter: the codec exported its two opaque state types and their initDec/initEnc seeds precisely so the loader could carry them here and thread them through its own clock. “The loader is the machine that clocks them” — these two fields are where.
RX / frame-parse (9 fields). The load path’s scratchpad: lHeld (the one-byte holdback), lCrcRx (running CRC over confirmed bytes), lHaveOp and lOpcode (have we seen the opcode, and what was it), lByteIx and lWordAcc (which of a word’s four bytes we are on, and the little-endian word taking shape), lHadPay (did any payload arrive — a TRIGGER must have none), and lAddr and lFull (the next instruction slot, and whether the store overflowed).
Drain (6 fields). The report path’s scratchpad: lDrn (the DrainPhase program counter), lWord and lWIx (the ring word being emitted and which of its bytes), lCrcTx (running CRC over the drain), lDrCnt (which ring record we are fetching), and lTerm (are we on the terminator word yet).

Read that way it is four modest records, and the two big ones — RX-parse and Drain — are never live at once, since RxControl and Drain are different lives. At any instant half these fields are asleep. They cohabit one record for the reason the whole loader is one mealy: one machine with one memory is simpler to reason about, and to register, than three sharing a bus.

The two one-liners

initLoader is the machine at power-on — RxControl, both codecs seeded with initDec/initEnc, every counter zero, every flag false: listening, nothing held, nothing owed. idleOut is the do-nothing output — no byte, no write, no pulse — and it earns a name because the loader returns it on the overwhelming majority of cycles. Naming it once lets every step function say “nothing happens this cycle” in five characters, and lets your eye skip to the cycles that matter.

The machine that owns the clock

loader :: (HiddenClockResetEnable dom) => Signal dom LoaderIn -> Signal dom LoaderOut
loader = mealy loaderStep initLoader

loaderStep :: LoaderSt -> LoaderIn -> (LoaderSt, LoaderOut)
loaderStep s inp = case lPhase s of
  RxControl -> rxStep s inp
  Run -> runStep s inp
  Drain -> drainStep s inp

Here is the promise kept. Six posts of pure steps insisting someone else owns the register, and this is the someone. mealy is the Clash primitive the transmitter introduced: hand it a pure s -> i -> (s, o) and a seed, and it wraps exactly one register around the state and lifts the pure function into Signal dom i -> Signal dom o — a clocked thing. loader hands mealy its loaderStep and initLoader, and out comes a signal function with a clock threaded through it. Every pure step we praised for having no clock — the CRC’s, the codec’s two — gets its clock here, because the loader clocks itself and carries them along in lDec, lEnc, lCrcRx, lCrcTx.^[2]

And loaderStep is almost nothing: read the current life off lPhase and delegate. That case is the whole top-level control flow — the three lives are three functions, and the machine is whichever the phase names. So the rest of the post is three smaller ones; we take the easiest first.

Run: the life that waits

runStep :: LoaderSt -> LoaderIn -> (LoaderSt, LoaderOut)
runStep s inp
  | halted inp =
      ( s{lPhase = Drain, lEnc = initEnc, lDrn = DrOpcode, lCrcTx = 0, lDrCnt = 0, lWIx = 0, lTerm = False}
      , idleOut
      )
  | otherwise = (s, idleOut)

The shortest of the three, and the only one that does essentially nothing. While the engine runs, the loader has exactly one job: watch one bit. halted is a level, not a pulse — the engine’s Halted phase is stable, it does not blink — so the guard just tests it every cycle. Low: hold the state, emit idleOut. High: the run is over, so arm the drain and switch lives.

Arming the drain is that record update, worth reading for what it spares. It seeds the encoder fresh, rewinds the program counter to DrOpcode, and zeroes the drain counters and CRC — but pointedly does not touch lAddr, lFull, or the program in the instruction BRAM. A drain must not disturb the loaded code, because the rig is re-runnable: a later TRIGGER with no new LOAD re-runs it. Run is a turnstile — it spins until halted, then clicks one notch into Drain.

RxControl: the load path

RxControl is the loader listening. A control frame arrives on the UART one byte at a time, and the job is to turn that trickle back into a message — an opcode and its payload — verify it, and act. Before the code, the thing being parsed. A frame on the wire looks like this, and so does the frame the drain will later build in the other direction:

One frame shape, both directions. Read it from the inside out: the message — an opcode and its payload — is the Tamal.Wire layer; a CRC-8 byte guards it; COBS stuffs every zero out of the opcode-payload-CRC run; and a lone 0x00 delimiter closes the frame. The last post built the COBS layer. This post builds the two layers outside it — and peels them, on the way in.

Read from the inside out. The innermost thing is the message — an opcode byte and its payload, the logical frame Tamal.Wire’s encodeControl builds before it wraps it. Around it, a CRC-8 byte guards the lot. Around that, COBS stuffs out every zero, so the run holds no interior 0x00. And around everything, a single 0x00 delimiter. The loader’s receive job is to peel those layers in reverse: watch for the delimiter, un-COBS the interior, check the CRC, and read the message. Here is the whole of it.

rxStep :: LoaderSt -> LoaderIn -> (LoaderSt, LoaderOut)
rxStep s inp =
  let din = case rxByte inp of
        Just 0 -> (Nothing, True) -- delimiter => frame end
        Just b -> (Just b, False)
        Nothing -> (Nothing, False)
      (dec', (mDec, done, bad)) = cobsDecodeStep (lDec s) din
      s1 = s{lDec = dec'}
   in if done
        then finalize s1 bad
        else case mDec of
          Nothing -> (s1, idleOut)
          Just d ->
            let (s2, mw) = case lHeld s1 of
                  Just h -> confirm s1 h
                  Nothing -> (s1, Nothing)
             in (s2{lHeld = Just d}, idleOut{instrWr = mw})

Four moves, top to bottom. The delimiter watch comes first: that case rxByte. A received 0x00 is not data — COBS guarantees no interior zeros, so a zero on the wire can only be the frame boundary — so the loader translates it into the codec’s vocabulary: Just 0 becomes (Nothing, frameEnd = True), any other byte (Just b, False), no byte (Nothing, False). That frameEnd pulse is exactly the one cobsDecodeStep expects, and here is the thing that pulses it. The delimiter belongs to the frame layer, not the codec, and this case is where that line is drawn.

Second, feed the codec. cobsDecodeStep runs, threaded through lDec, and hands back the triple we read last post: a maybe-decoded byte mDec, a done pulse, a bad flag.

Third, if done — the delimiter fired — the frame is over; hand off to finalize. If instead the codec produced nothing this cycle (Nothing), idle; that is the common case, a byte mid-flight or a code byte that only armed a counter.

And fourth, the move that deserves its own name. When a decoded byte d does arrive, the loader does not process it. It processes the byte it was already holding, lHeld, and stashes d in its place. That is the holdback, and it exists to solve one specific problem:

The last byte of the logical stream is the CRC. But nothing marks it as the CRC while it streams — it looks like any other byte, right up until the delimiter proves it was the last one. So the loader always lags one byte behind: it holds the newest decoded byte and only confirms the previous one, because only a byte with another byte behind it is provably payload, not the trailing check.

The receive pipeline and its one-byte lag. Bytes flow rxByte → delimiter-watch → COBS decode → holdback → confirm. Because the trailing byte of the logical stream is the CRC — indistinguishable from payload until the frame ends — the loader confirms each byte only when the next one arrives. The final byte is never confirmed: it is the CRC candidate, held back and checked against the running CRC when the 0x00 delimiter closes the frame.

Same field, two fates: when a new byte arrives, the held one is provably not the last, so confirm works on it; when the delimiter arrives, the held byte is the last, so finalize treats it as the CRC. What comes next decides.^[3]

`confirm`: fold, route, assemble, write through

confirm receives a byte h that has just been proven payload — a byte arrived behind it — and does the frame’s real bookkeeping (its full text is in the listing above). Two cases split on whether we have an opcode yet.

The first confirmed byte is the opcode. Record it in lOpcode, set lHaveOp, and fold it into the running CRC. Then one special touch: if the opcode is 0x01, LOAD_PROGRAM, reset the write address to 0 and clear the overflow flag, so a load always writes from the top of the store. No output byte — an opcode writes nothing to memory.

Every later confirmed byte is payload. Fold it into the CRC, then shift it into lWordAcc at the current byte position: zeroExtend h `shiftL` (8 * byteIx). That is little-endian assembly by construction — byte 0 lands in bits 7:0, byte 1 in 15:8, and so on. When lByteIx reaches 3 a full 32-bit word is complete, and this is where the load actually touches memory:

      if lByteIx s == 3
        then
          let doWrite = isLoad && not (lFull s)
              (addr', full') = if lAddr s == maxBound then (lAddr s, True) else (lAddr s + 1, lFull s)
           in ( s{ lCrcRx = crc', lWordAcc = 0, lByteIx = 0, lHadPay = True
                 , lAddr = if isLoad then addr' else lAddr s
                 , lFull = if isLoad then full' else lFull s }
              , if doWrite then Just (lAddr s, acc') else Nothing )
        else
          ( s{lCrcRx = crc', lWordAcc = acc', lByteIx = lByteIx s + 1, lHadPay = True}, Nothing )

The completed word is emitted as Just (lAddr s, acc') — a write to the instruction BRAM at the current slot — provided this is a LOAD and the store has not overflowed. Then the address bumps (saturating at maxBound — 1023 for Unsigned AW — and latching lFull rather than wrapping), the accumulator and byte index reset, and lHadPay records that payload was seen. A word that is not a load, or that lands past the 1024-word cap, just advances the state and writes nothing.

Notice that the write to the instruction BRAM happens here, mid frame, before the CRC is ever checked. The design calls it write-through: rather than buffer the program to commit it atomically, the loader scribbles each word into the store the instant it assembles. A frame that later fails its CRC has already dirtied memory — and that is fine, because loading and triggering are separate frames: nothing runs until a good TRIGGER, and a bad LOAD is overwritten by the host’s retry before any trigger ever fires.^[4]

`finalize`: the delimiter’s verdict

finalize :: LoaderSt -> Bool -> (LoaderSt, LoaderOut)
finalize s bad =
  let crcCand = fromMaybe 0 (lHeld s)
      crcGood = not bad && isJust (lHeld s) && lHaveOp s && lCrcRx s == crcCand
      trigOk = crcGood && lOpcode s == 0x02 && not (lHadPay s)
      s0 = resetFrame s
   in if trigOk
        then (s0{lPhase = Run}, idleOut{startOut = True})
        else (s0, idleOut)

The delimiter fired, so the held byte is not payload — there is no byte behind it — which makes it the CRC candidate, crcCand. Now the verdict, in two conjunctions.

crcGood demands four things at once: the codec did not report the frame bad (no truncated group, no overshoot); a byte was actually held (a frame with nothing in it holds Nothing); an opcode was seen; and the CRC folded over every confirmed byte equals the candidate. Miss any one and the frame is junk. trigOk narrows further: a good frame whose opcode is 0x02, TRIGGER, carrying no payload. Only that pulses the engine.

Then the machine resets its frame-parse state either way (resetFrame clears the codec, holdback, CRC, opcode, and word assembly — but not lAddr/lFull, already committed by the write-through) and branches. A good trigger flips to Run and pulses startOut for one cycle. Anything else — a good LOAD (words already in memory), a bad frame, an unknown opcode — resets and stays in RxControl, silent. That silence is the whole error policy: the loader never NAKs, never raises an error frame; a bad frame simply has no effect, and the host, hearing nothing, times out and re-sends.^[5]

Watching a TRIGGER land

Take the smallest interesting frame — a TRIGGER — and feed it byte by byte. Its logical stream is one opcode, 0x02, plus its CRC-8, which for the single byte 0x02 works out to 0x0E. COBS wraps the pair 02 0E (no zeros) as a single group 03 02 0E, and the frame layer caps it with the delimiter. On the wire: 03 02 0E 00.

03 — delimiter-watch passes (Just 3, False); cobsDecodeStep reads a code byte, arms its counter, emits nothing. lHeld is still Nothing. Idle.
02 — the decoder emits the data byte 02. lHeld is Nothing, so nothing is confirmed yet; stash lHeld = Just 02. Idle.
0E — the decoder emits 0E. Now lHeld holds 02, so confirm runs on it: it is the first byte, so lOpcode = 0x02, lHaveOp = True, and lCrcRx = crc8Update 0 0x02 = 0x0E. Then stash lHeld = Just 0E. Idle. The opcode is confirmed; the CRC byte is held.
00 — delimiter. cobsDecodeStep pulses done, not bad. finalize: crcCand = 0E; crcGood is True because lCrcRx = 0E equals it, an opcode was seen, a byte was held, nothing was malformed. trigOk is True — opcode 0x02, no payload. Pulse startOut, step to Run.

Read the drama in the last two steps. The held 0E was never confirmed as payload — it had no byte behind it — so it stayed the candidate and was checked, not folded. The opcode 02 was confirmed, at the exact moment 0E arrived to prove it was not the last byte. The holdback did its one job perfectly: the opcode got folded, the CRC got checked, and the pulse fired after the delimiter, never a cycle before the frame was known good. Corrupt any byte of 03 02 0E 00 and step 4’s crcGood collapses; no pulse, no run — exactly what a fire-and-forget link wants.

Drain: the result path

Drain is the mirror image. Where RxControl peeled a frame off the wire, Drain builds one and pushes it out — the result frame from the diagram above: opcode 0x81, then the ring’s words as little-endian bytes (the REVISION at word 0, the engine’s trace records, and the HALT terminator at the very top of the ring), then a CRC, all COBS-encoded and capped with a delimiter.

But the drain is harder than the load, and for a nameable reason: three different things can make it wait. A BRAM read takes a cycle to answer. The UART accepts a byte only when txReady. The COBS encoder buffers a whole group before it emits. Every one of those is a stall, and a stall needs a state to wait in and return from. That is why Drain is not a loop but the seven-state sub-machine DrainPhase named earlier — one state per place the sweep might have to pause.

The drain as a seven-step program. DrOpcode emits 0x81; the accent DrFetch/DrLatch pair drives a ring address and captures the data one cycle later; DrWordByte emits the word's four little-endian bytes and loops back to DrFetch for each further record; DrCrcByte emits the drain CRC flagged last; DrDrainOut clocks the encoder until its final group is flushed; and DrDelim appends the lone 0x00 and returns to RxControl. Every emitted byte waits for txReady — the self-pacing a flow-control-less link leans on.

The sub-machine is one case on lDrn, shown in full in the listing above. Three of its arms — DrOpcode, DrWordByte, DrCrcByte — are one-liners that hand a logical byte to feedByte (next section); the other four move memory and manage the encoder. Its only real branching is the where-helper that decides where to go after each emitted word byte:

  afterWordByte i s'
    | lWIx s' /= 3 = s'{lWIx = lWIx s' + 1}
    | lTerm s' = s'{lDrn = DrCrcByte}
    | lDrCnt s' + 1 >= ringPtrIn i = s'{lTerm = True, lDrn = DrFetch}
    | otherwise = s'{lDrCnt = lDrCnt s' + 1, lDrn = DrFetch}

Walk the seven, remembering that the three feeding phases produce the logical stream while the other four move memory and manage the encoder.

DrOpcode — feed the opcode 0x81; when the encoder takes it, advance to DrFetch and zero the record counter. The frame begins.
DrFetch — drive the ring read address (lDrCnt, or maxBound for the terminator) onto ringAddr. The BRAM will answer next cycle, so this state does nothing else but keep the encoder turning (fed Nothing) in case it still has buffered bytes to emit. Advance to DrLatch. This is the address half of a read.
DrLatch — the BRAM’s answer is on ringData now; latch it into lWord, reset the byte cursor lWIx = 0, advance to DrWordByte. The data half. Fetch-then-latch, two states, is exactly the block RAM’s one-cycle read latency written out — a contract the two memories get their own post next to explain, honoured here as a pair of phases.
DrWordByte — feed the current little-endian byte of lWord (via leByte) to the encoder; on consume, run afterWordByte. That helper is the drain’s only real branching: if bytes remain in this word (lWIx /= 3), bump the cursor; else if this was the terminator, go to DrCrcByte; else if the record just fetched was the last one (lDrCnt + 1 >= ringPtrIn), set lTerm and loop to DrFetch for the terminator at maxBound; else bump lDrCnt and loop to DrFetch for the next record. That is the accent loop in the diagram.
DrCrcByte — feed the accumulated drain CRC lCrcTx, flagged last so the encoder knows the logical stream has ended and can flush its final group. Advance to DrDrainOut.
DrDrainOut — no more input; just clock the encoder (Nothing) until it pulses encDone, meaning its last buffered group is out. Then DrDelim.
DrDelim — append the one 0x00 frame delimiter, paced on txReady, reset the frame state, and return to RxControl. The frame is complete; the loader is listening again.

One quiet elegance is worth pausing on. DrFetch and DrLatch re-use lWord for every record, overwriting it each time — safe, because by the time the machine leaves DrWordByte all four of the old word’s bytes are already inside the encoder’s buffer. The word register is a one-word window; the encoder is the real buffer, and its 254-byte look-ahead decouples the fast BRAM sweep from the far slower UART emit.

`feedByte`: one byte to the encoder

feedByte ::
  LoaderSt -> LoaderIn -> BitVector 8 -> Bool -> (LoaderSt -> LoaderSt) -> (LoaderSt, LoaderOut)
feedByte s inp b lst advance =
  let (enc', (readyIn, mOut, _)) = cobsEncodeStep (lEnc s) (Just (b, lst), txReady inp)
      s1 = s{lEnc = enc'}
      s2 =
        if readyIn
          then advance s1{lCrcTx = if lst then lCrcTx s1 else crc8Update (lCrcTx s1) b}
          else s1
   in (s2, idleOut{txByte = mOut})

feedByte is the drain’s workhorse, and the exact dual of the receive side’s fold-and-route. It presents one logical byte b to cobsEncodeStep along with its last flag and the downstream-ready line txReady. The encoder answers with readyIn (did it take the byte?), mOut (a COBS byte to send, maybe), and a done flag we ignore here.

If readyIn — the byte was consumed — fold it into the drain CRC (unless it is the CRC byte itself, flagged lst; you do not CRC the CRC) and run the advance continuation to step the phase. If not consumed — the encoder is mid-group, or txReady is low — hold: same byte, same phase, next cycle. Either way, route mOut to txByte. So every output byte is gated on txReady, and the generator runs exactly as fast as the encoder consumes, which runs exactly as fast as the UART drains.^[5] The separation is the pretty part: the three feeding phases decide which byte comes next; feedByte owns how to hand it over and when to advance. Three call sites, one rule.

`leByte`: the little-endian tap

leByte :: BitVector 32 -> Unsigned 2 -> BitVector 8
leByte w i = case i of
  0 -> slice d7 d0 w
  1 -> slice d15 d8 w
  2 -> slice d23 d16 w
  _ -> slice d31 d24 w

The trivial helper, listed for symmetry: byte i of a 32-bit word, little-endian — slice d7 d0 is the low byte, up to slice d31 d24 the high. It is the exact inverse of the receive side’s lWordAcc `shiftL` (8 * byteIx): the load packs four little-endian bytes into a word, the drain unpacks a word into four. The wire is little-endian in both directions, and these two lines are the two ends of that one agreement.

Watching the minimal drain

The smallest possible drain is a ring with no records at all — just the REVISION word and the terminator. Say ringPtrIn = 1, ring[0] = 0x0001_0000 (REVISION), and the terminator at the top of the ring is 0xC000_0000. The logical stream the phases produce should be 0x81, then the four little-endian bytes of each word, then the CRC:

DrOpcode — feed 0x81; consumed, so fold it into lCrcTx, go to DrFetch, lDrCnt = 0.
DrFetch — drive ringAddr = 0. → DrLatch.
DrLatch — latch lWord = 0x0001_0000, lWIx = 0. → DrWordByte.
DrWordByte ×4 — feed 00 00 01 00, the LE bytes of 0x0001_0000. After the fourth, lWIx was 3, not the terminator, and lDrCnt + 1 = 1 >= ringPtrIn = 1, so set lTerm and loop to DrFetch.
DrFetch (terminator) — drive ringAddr = maxBound. → DrLatch.
DrLatch — latch lWord = 0xC000_0000, lWIx = 0. → DrWordByte.
DrWordByte ×4 — feed 00 00 00 C0. After the fourth, lWIx = 3 and lTerm is set, so → DrCrcByte.
DrCrcByte — feed lCrcTx, the CRC folded over 0x81 and all eight word bytes, flagged last. → DrDrainOut.
DrDrainOut — clock the encoder until encDone. → DrDelim.
DrDelim — emit 0x00, reset, → RxControl.

The logical stream handed to the encoder is 81 · 00 00 01 00 · 00 00 00 C0 · crc — ten bytes, and notice how thoroughly zero-riddled it is. A real ring word is full of 0x00, which is exactly why COBS is in this pipeline at all: the encoder stuffs every one of those zeros out, the loader caps the result with a single 0x00, and the whole thing comes out equal, byte for byte, to Tamal.Wire’s pure encodeResult [0x0001_0000, 0xC000_0000]. Which is precisely what the test suite asserts — so let us turn to it.

The tests

The loader is impure, so unlike the pure COBS steps you cannot apply it to a value and read the answer — you build a Signal, sampleN it, and compare. But the discipline is the COBS post’s, up one layer: a pure reference is the oracle, and the streaming machine is held to it byte for byte. Where COBS checked itself against pure Tamal.Wire.Cobs, the loader checks its whole frame layer against pure Tamal.Wire — encodeControl and encodeResult, the list-to-list functions that are the wire format.

The load path tests feed the exact bytes of encodeControl (LoadProgram ws) and assert the write stream:

testProperty "LOAD_PROGRAM writes the exact words at 0,1,2,.." $ property $ do
  ws <- forAll (Gen.list (Range.linear 0 20) genWord)
  let bytes = encodeControl (LoadProgram ws)
  simInstrWr (fmap Just bytes) === [(fromIntegral i, w) | (i, w) <- L.zip [0 :: Int ..] ws]

For random programs, the words land at 0, 1, 2, … with the right values — the write-through, the little-endian assembly, and the holdback all proven in one line. A TRIGGER pulses startOut exactly once and only after the frame; a LOAD pulses it never. There is one lovely detail in the harness: every stimulus is led by an idle cycle, because sampleN asserts the reset on cycle 0 and a byte fed then would be lost — exactly as it would be lost in hardware, where the line idles before the first frame. The test models the reset hazard rather than papering over it.

The drain tests are the clever ones, because the drain reads a memory the test must supply. The rig closes the ring-BRAM loop with a register for the one-cycle latency and a pure ringModel as the memory:

drainRig lookupRing ringPtrV rxs txr hlt = txByte <$> loaderOut
 where
  loaderOut = loader loaderIn
  ringDataS = register 0 (lookupRing <$> (ringAddr <$> loaderOut))
  loaderIn  = LoaderIn <$> rxs <*> txr <*> hlt <*> pure ringPtrV <*> ringDataS

That register 0 (lookupRing <$> ringAddr) is the BRAM: the loader’s own ringAddr output, delayed one cycle and looked up in the model, becomes its ringData input — the fetch/latch dance closed into a feedback loop. On top of it, one property drives a full lifecycle — TRIGGER, Run, halted, Drain — and demands the drained bytes equal the oracle:

testProperty "drain stream == encodeResult (records ++ terminator)" $ property $ do
  records <- forAll (Gen.list (Range.linear 1 24) genWord)
  term <- forAll genWord
  simDrain records term [True] === encodeResult (records <> [term])

And then the test that justifies the entire no-flow-control design: run the same drain with txReady chopped to a stuttering [True, False, True, True, False] and assert the output is byte-identical. If the self-pacing has a leak — a dropped byte, a duplicated one — this goes red. It stays green, which is the proof that the loader may share an unpaced link with a host and never corrupt a frame.

The robustness cases round it out, each one a design decision made falsifiable: flip any single bit of a TRIGGER and no run ever starts (property over the flip position); over-load 1100 words and the addresses saturate at 1023 with exactly 1024 writes; send two LOADs and each writes from address 0 (the overwrite that makes a failed load harmless); trigger-halt twice and the ring drains twice (re-runnable). The shape is the house style, now familiar: a pure model that is the meaning, a streaming machine that is the silicon, and property tests that weld the two together over a fresh shower of inputs every run.^[6]

What we read

Three lives, one clock. RxControl listens, peeling a frame layer by layer and holding one byte back so the trailing CRC never masquerades as payload, writing each little-endian word straight through to the instruction store and committing nothing until a separate TRIGGER says go. Run waits on a single bit. Drain sweeps the ring out in seven patient phases, dancing with the memory’s latency, folding a CRC, flushing the encoder, and pacing every byte off txReady so an unpaced link never overruns. One mealy, one eighteen-field memory that is really four small ones, one case on the phase.

And inside it, everything the series built. The COBS codec, threaded through the loader’s clock in lDec and lEnc — the promise that post made, kept. The CRC, folded over both directions in lCrcRx and lCrcTx. The UART’s four wires, finally connected. The two block RAMs, driven on the ports the engine leaves free. The clock that six pure steps kept deferring to “someone else” lives here, and the someone has a name.

What the loader loads, triggers, and drains is a program — run by a machine we have circled for the entire series and never once opened. The instruction store the loader fills, the trace ring it sweeps, the halted it waits on and the startOut it pulses: those are all the engine’s, and the engine is the last door. We open it soon — but first, a shorter breath: the two memories the loader has spent this post driving, and that the engine is about to live between, deserve a look of their own. Then, at last, we walk through the door.

The collision-free claim is the block-RAM design’s port-ownership contract cashed in. RxControl/Drain and Run are different lives, never concurrent, so the loader (instruction write, ring read) and the engine (instruction read, ring write) touch disjoint ports at disjoint times. The schedule is the arbitration — which is what lets the loader be one more mealy beside the engine rather than a bus master negotiating for access. ↩
The design doc reached for mealyS — the State-monad flavour of mealy, where the transition is written in do-notation over State s rather than as an explicit s -> i -> (s, o) — and flagged it as “the idiom for exactly this long sequential FSM.” The shipped code uses plain mealy instead, “matching the engine lift.” An honest divergence: the State-monad sugar would have read a shade cleaner in drainStep, but keeping every top-level block lifted the same way — engine and loader both plain mealy over an explicit step — won out: a codebase where every machine wears the same silhouette reads easier than one where each picks its favourite sugar. ↩
The one-byte holdback is a general streaming idiom worth naming, because it recurs anywhere a stream’s last element is special and unmarked. You cannot know an element is the last until the stream ends, so if the last one needs different treatment — a checksum, a terminator, a flush — you buffer exactly one and always act on the previous, then handle the straggler when the end arrives. It is the streaming dual of init and last on a list: the holdback is init (everything but the last), and the delimiter handler is last. One register buys a one-element look-behind, which is all it takes. ↩
Write-through trades atomicity for a BRAM. The alternative — buffer the whole program, check its CRC, and commit only on success — needs somewhere to hold up to 1024 words, a second four-kilobyte block RAM, to guard against a failure the protocol already handles. Because LOAD_PROGRAM and TRIGGER are separate frames (a deliberate wire-format choice), a corrupted load never runs: nothing runs until a good trigger, and a well-behaved host re-sends a failed load — overwriting the garbage from address 0 — before it ever triggers. So the loader gets atomic-enough behaviour for free, and the “two LOADs each write from 0” test proves the overwrite works. ↩
The Arty A7’s FTDI USB-UART has no RTS/CTS wired to the FPGA — a board fact, not a choice — so there is no hardware flow control in either direction, and the loader carries none to match. It survives on three things: the receive side cannot overrun (per-byte work is a handful of cycles against a ~500-cycle byte period at 2 Mbaud); the drain self-paces off txReady; and the backstop for anything that slips is the whole-frame CRC plus fire-and-forget — a bad frame is dropped, the host times out and re-runs, byte-reproducibly. Lower the baud (a top-level SNat) if it ever bites. ↩ ↩2
The same two-implementations pattern the COBS post called the house style, now one layer up. Down there it was pure Tamal.Wire.Cobs beside streaming Tamal.Loader.Cobs; up here it is pure Tamal.Wire — the frame format as list transforms — beside the streaming loader. You write the frame codec twice: once as a fold over lists, where you can think without back-pressure or cycle timing, and once as a clocked machine that must survive a stalling consumer and a dribbling producer. The property tests weld them, so the gnarly clocked version is never the only place the format is written down. ↩

Tamal: The COBS codec

2026-07-25T09:00:00+00:00

The transmitter and receiver built a byte pipe; yesterday we sealed the two halves into a single word — the UART — and left four wires hanging at the loader’s door. Today we walk through that door. But the first thing behind it is not a state machine. It is an answer to a question the pipe cannot answer for itself: a bare stream of bytes has no seams, so where does one message end and the next begin?

I have carried my answer to that question for a little while, and I did not find it in a textbook. I found it in postcard-rpc, James Munns’ crate for speaking to embedded targets over a wire. I liked it enough to become one of its maintainers, and I lean on it — that is, I depend on it — hard on pico de gallo 🌶, where it frames every request and every response that crosses between host and firmware.^[1] So when Tamal’s loader needed a way to tell one message from the next on a bare UART, I did not go looking. I already knew what I wanted, and I reached for COBS: Consistent Overhead Byte Stuffing.

COBS earns its keep with a property that sounds too good until you see how plainly it is bought: it removes every 0x00 byte from a payload, at a cost of at most one extra byte per 254, so that a single 0x00 can be reserved — unambiguously, forever — to mean end of frame. The loader decodes the inbound stream on the way in and encodes its replies on the way out, and both directions are the subject of this post.

Like every Tamal block before it the codec fits in a screenful and change — but unlike the UART halves it holds no clock of its own. What follows are two pure step functions; the loader is the machine that clocks them. We will spend almost all our words on the two that matter, cobsDecodeStep and cobsEncodeStep, and wave past the scaffolding around them, which by now is a ceremony we have read five times.

The entire source

Minus the license header and the doc-comments — and, this once, minus the longer inline notes on the encoder, which we will read in place where they belong — here is src/Tamal/Loader/Cobs.hs:

module Tamal.Loader.Cobs
  ( DecSt
  , initDec
  , cobsDecodeStep
  , EncSt
  , initEnc
  , cobsEncodeStep
  ) where

import Clash.Prelude

data DecSt = DecSt
  { dCnt :: Unsigned 8
  , dFull :: Bool
  , dPend :: Bool
  , dGot :: Bool
  }
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

initDec :: DecSt
initDec = DecSt 0 False False False

data EncMode = EFilling | EEmitting
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

data EncSt = EncSt
  { eMode :: EncMode
  , eBuf :: Vec 254 (BitVector 8)
  , eFill :: Unsigned 8
  , eIx :: Unsigned 8
  , ePend :: Maybe (BitVector 8, Bool)
  , eFinal :: Bool
  , eLast :: Bool
  }
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

initEnc :: EncSt
initEnc = EncSt EFilling (repeat 0) 0 0 Nothing False False

cobsDecodeStep :: DecSt -> (Maybe (BitVector 8), Bool) -> (DecSt, (Maybe (BitVector 8), Bool, Bool))
cobsDecodeStep s (mIn, frameEnd)
  | frameEnd = (initDec, (Nothing, True, not (dGot s) || dCnt s /= 0))
  | otherwise = case mIn of
      Nothing -> (s, (Nothing, False, False))
      Just b
        | dCnt s == 0 ->
            let (out, s1) =
                  if dPend s
                    then (Just 0, s{dPend = False, dGot = True})
                    else (Nothing, s{dGot = True})
                s2 = startGroup s1 b
             in (s2, (out, False, False))
        | otherwise ->
            let cnt' = dCnt s - 1
                s' =
                  s
                    { dCnt = cnt'
                    , dGot = True
                    , dPend =
                        if cnt' == 0
                          then not (dFull s)
                          else dPend s
                    }
             in (s', (Just b, False, False))
 where
  startGroup st c =
    let full = c == 255
        n = (unpack c :: Unsigned 8) - 1 -- c is 1..255 (never 0), so n is 0..254
     in if n == 0
          then st{dCnt = 0, dFull = full, dPend = not full}
          else st{dCnt = n, dFull = full}

cobsEncodeStep :: EncSt -> (Maybe (BitVector 8, Bool), Bool) -> (EncSt, (Bool, Maybe (BitVector 8), Bool))
cobsEncodeStep s (mIn, dsReady) = case eMode s of
  EFilling -> case mIn of
    Nothing -> (s, (True, Nothing, False))
    Just (b, lst)
      | eFill s == 254 ->
          (s{eMode = EEmitting, eIx = 0, ePend = Just (b, lst)}, (True, Nothing, False))
      | b == 0 ->
          (s{eMode = EEmitting, eIx = 0, eFinal = lst, eLast = lst}, (True, Nothing, False))
      | lst ->
          ((store s b){eMode = EEmitting, eIx = 0, eLast = True, eFinal = False}, (True, Nothing, False))
      | otherwise ->
          (store s b, (True, Nothing, False))
  EEmitting
    | not dsReady -> (s, (False, Nothing, False))
    | eIx s <= eFill s ->
        let out :: BitVector 8
            out = if eIx s == 0 then fromIntegral (eFill s) + 1 else eBuf s !! (eIx s - 1)
         in (s{eIx = eIx s + 1}, (False, Just out, False))
    | eFinal s ->
        (s{eFill = 0, eIx = 0, eFinal = False}, (False, Nothing, False))
    | otherwise -> case ePend s of
        Just (pb, pl)
          | pb == 0 ->
              (s{eMode = EEmitting, eFill = 0, eIx = 0, ePend = Nothing, eFinal = pl, eLast = pl}, (False, Nothing, False))
          | pl ->
              ((store s{eFill = 0} pb){eMode = EEmitting, eIx = 0, ePend = Nothing, eLast = True}, (False, Nothing, False))
          | otherwise ->
              ((store s{eFill = 0} pb){eMode = EFilling, ePend = Nothing}, (False, Nothing, False))
        Nothing
          | eLast s -> (initEnc, (False, Nothing, True))
          | otherwise -> (s{eMode = EFilling, eFill = 0}, (False, Nothing, False))
 where
  store st b = st{eBuf = replace (eFill st) b (eBuf st), eFill = eFill st + 1}

Six things, top to bottom: an export list that is wider than any we have seen; a four-field DecSt record; a two-constructor EncMode sum and a seven-field EncSt record; two one-line initialisers; and the two step functions that are the whole point. We will glance at the first four and then slow right down for the last two.

The ritual, one more time

The opening beat is the CRC module’s, played a sixth time, so I will be quick — but there is one genuinely new thing in it, and it is worth a sentence.

module Tamal.Loader.Cobs
  ( DecSt
  , initDec
  , cobsDecodeStep
  , EncSt
  , initEnc
  , cobsEncodeStep
  ) where

import Clash.Prelude

Every module so far has had exactly one name on its export list — crc8Update, uartTx, uartRx, uart. This one has six. The wall still has a door, but the door is wider, and the reason is a real design fact rather than an oversight: the two St types and their initialisers leave the file on purpose. This module is not a self-contained machine you plug a clock into; it is a component the loader embeds. The loader holds a DecSt and an EncSt inside its own state record and threads them through its own mealy, so it must be handed the types to store and the initDec/initEnc values to seed them. The export list is exactly as wide as that contract requires and no wider: two opaque state types, two seeds, two steps. EncMode, dCnt, store, startGroup — the genuinely internal machinery — all stay sealed behind the wall.

import Clash.Prelude is the same prelude swap the CRC post dwelt on — out goes ordinary Haskell’s furniture, in comes the hardware vocabulary. Here it is supplying Vec 254, Unsigned 8, BitVector 8, Maybe, and the Vec operations repeat, replace, and !! that the encoder’s buffer leans on. I will not re-derive it; the CRC and primer posts did that at length.

The two state records are the primer’s sum-and-product story once more, and I will gloss them in a single pass because the step functions are written entirely in terms of their fields. DecSt is what the decoder carries tick to tick:

dCnt — data bytes still owed in the current group; 0 means the next byte is a code byte.
dFull — was this group’s code 255? A full group is special: it carries no implied zero.
dPend — do we owe an injected 0x00 before the next code byte?
dGot — has any byte at all arrived this frame? (Only used to flag an empty frame as malformed.)

EncSt carries more, because encoding buffers a whole group before it can know the group’s length:

eMode — EFilling (accumulating a group) or EEmitting (driving code ++ group out).
eBuf, eFill — the up-to-254-byte group buffer and how many bytes are in it.
eIx — the emit cursor: 0 is the code byte, 1..eFill the data.
ePend — a byte stashed when a full 254-group is flushed; it will start the next group, and it remembers whether it was the stream’s last byte.
eFinal — is a final empty group still owed? (The last input byte was 0x00.)
eLast — has the input stream ended?

Both initialisers are the resting state written out — initDec = DecSt 0 False False False, initEnc = EncSt EFilling (repeat 0) 0 0 Nothing False False — and there is nothing in either worth a paragraph.

The one structural thing worth saying out loud before we start: look at the types of the two steps and notice what is absent.

cobsDecodeStep :: DecSt -> (Maybe (BitVector 8), Bool) -> (DecSt, (Maybe (BitVector 8), Bool, Bool))
cobsEncodeStep :: EncSt -> (Maybe (BitVector 8, Bool), Bool) -> (EncSt, (Bool, Maybe (BitVector 8), Bool))

No Signal. No HiddenClockResetEnable. No mealy. These are s -> i -> (s, o) in the flesh — the exact shape the transmitter taught us to read — but un-lifted, pure functions with no clock anywhere in sight. That is deliberate, and it is the same division of labour the CRC’s step had: the codec describes what one byte does to the state, and someone else owns the register that makes it sequential. That someone is the loader, which wraps both steps in its own mealy. Everything below is combinational; the clock is a floor above.

What COBS actually does

Strip the acronym away and COBS is one idea: turn every zero into a distance.

Here is the whole trick. You want a byte that means “frame boundary,” and 0x00 is the natural pick — it is what an idle line and a cleared buffer are already full of. The trouble is that real payloads contain 0x00 too, so the delimiter is ambiguous the moment you pick it. COBS removes the ambiguity by removing the zeros: it chops the payload into groups at each zero, and prefixes every group with a single code byte that says how long the group is. The zeros themselves are never transmitted — they are implied by the fact that one group ended and the next began.

Concretely, a group of L non-zero bytes (with 0 ≤ L ≤ 254) is emitted as a code byte L + 1 followed by the L bytes. Because the code is L + 1 and L tops out at 254, the code ranges over 0x01..0xFF and is never 0x00. Read the code another way and it becomes a pointer: L + 1 is exactly the distance from this code byte to the next one, i.e. to where the next zero used to be. The decoder follows the chain — jump code bytes, you land on the next code byte; the byte that was there is a zero you re-insert — until the delimiter stops it.

COBS on the payload 11 22 00 33 00. It splits at the zeros into groups [11 22], [33], and a trailing empty group, and prefixes each with a code byte equal to its length plus one: 03 11 22, 02 33, 01. Each code is the distance (accent arcs) to the next code byte — the spot the zero used to occupy — so the decoder can re-insert every zero by following the chain. The encoded stream holds no 0x00, which frees the single trailing 0x00 to mean, unambiguously, end of frame.

Two details in that picture are the entire reason both step functions are more than ten lines long, so let us name them now and meet them again in the code.

The first is the final group. Count the groups above: [11 22], [33], and then an empty one, 01. A payload with k zeros always encodes to k + 1 groups, because every zero marks a boundary between two groups — and a payload that ends in a zero, like this one, leaves an empty run after that last zero, which becomes the trailing empty group. On decode a zero is re-inserted after every group but the last; the final group is closed by the frame delimiter instead. So the decoder owes exactly k zeros across k + 1 groups — one after each group except the final one — and getting that off-by-one asymmetry right is where its trickiest line lives.

The second is the full group. A group holds at most 254 bytes because the code caps at 0xFF. What happens to a run of, say, 300 non-zero bytes with no zero to break it? COBS emits a full group — code 0xFF, 254 bytes — and then simply continues the run in the next group. Crucially, that 0xFF group is a continuation: unlike every code from 0x01 to 0xFE, it does not stand in for a zero, because there was no zero — the run was just too long. “Is this code 0xFF?” is therefore the question that decides whether a zero gets re-inserted, and it is exactly the dFull flag in the decoder and the eFill == 254 test in the encoder.^[2]

With those two facts in hand the code reads like prose. We take the decoder first, as promised, because it is the shorter of the two.

`cobsDecodeStep`: decoding a byte

The decoder’s job is to invert the picture: bytes of a delimiter-stripped COBS frame go in, the original payload comes out, and any structural nonsense is flagged. Start, as always, with the type.

cobsDecodeStep :: DecSt -> (Maybe (BitVector 8), Bool) -> (DecSt, (Maybe (BitVector 8), Bool, Bool))

Read against the primer’s s -> i -> (s, o): the state is DecSt, the input is (Maybe (BitVector 8), Bool), and the output is (Maybe (BitVector 8), Bool, Bool). Name the parts and the contract appears. The input is a maybe-byte — Just b when the UART handed the loader a byte this cycle, Nothing otherwise — paired with a frameEnd flag the loader pulses the instant it sees the 0x00 delimiter on the wire. The output triple is a maybe-decoded-byte, a done pulse, and a malformed flag. The decoder is a valve: bytes trickle in, decoded bytes trickle out, and two one-bit signals announce the end of the frame and whether it held together.

The body is three guarded cases. Take them in the order the hardware does.

Frame end: reset, and the malformed law

  | frameEnd = (initDec, (Nothing, True, not (dGot s) || dCnt s /= 0))

When the loader pulses frameEnd, the current frame is over regardless of what the decoder was in the middle of. The next state is initDec — a hard reset, so the following frame starts clean — the output byte is Nothing, and done is True. The interesting part is the last field, the malformed verdict:

A frame is malformed if no byte ever arrived, or if a group was still owed data when the delimiter cut it off.

not (dGot s) catches the empty frame: two delimiters back to back, nothing between them, dGot never set. dCnt s /= 0 catches the truncated group: a code byte promised n data bytes, the delimiter arrived before all n did, and the counter never wound back to zero. Both are exactly the failures the pure reference rejects — an empty list, or a code byte “demanding more bytes than remain” — checked here in a single cheap disjunction at the one moment the whole frame is known to be complete.

No byte this cycle: hold

      Nothing -> (s, (Nothing, False, False))

If the loader has no byte for the decoder this cycle — the UART is mid-bit, say — the decoder does nothing at all: state unchanged, no output, no pulses. A valve with nothing flowing through it. This is the overwhelmingly common case, and it is one line.

A byte arrives: code byte, or data byte?

Everything real happens when Just b arrives, and the split is the dCnt s == 0 guard, which is precisely the question is the next byte a code byte?

      Just b
        | dCnt s == 0 ->
            let (out, s1) =
                  if dPend s
                    then (Just 0, s{dPend = False, dGot = True})
                    else (Nothing, s{dGot = True})
                s2 = startGroup s1 b
             in (s2, (out, False, False))

When dCnt is zero we are between groups, so b is a code byte — but before we interpret it, we settle a debt. If dPend is set, the previous group ended owing an implied zero, and this is the moment to pay it: out = Just 0. That timing is the subtle heart of the decoder, so let me state it plainly.

The zero between two groups is emitted lazily — not when the group ends, but when the next code byte arrives.

Why lazily? Because the zero only exists if there is a next group. A group that turns out to be the frame’s last is followed by the delimiter, not by another code byte, and its implied zero is not part of the payload — it is the boundary itself. By deferring the zero until the next code byte, the decoder gets this for free: if the next thing is a code byte, the zero was real and we emit it; if the next thing is frameEnd, we reset and the pending zero evaporates, un-emitted, exactly as it should. The 03 11 22 02 33 01 trace below shows both halves of that bargain.

Once the debt is settled, startGroup interprets the code byte:

  startGroup st c =
    let full = c == 255
        n = (unpack c :: Unsigned 8) - 1 -- c is 1..255 (never 0), so n is 0..254
     in if n == 0
          then st{dCnt = 0, dFull = full, dPend = not full}
          else st{dCnt = n, dFull = full}

n = c - 1 is the group’s data-byte count, undoing the encoder’s L + 1. full = c == 255 records the continuation case. Then a fork on n:

n == 0 — the code was 0x01, an empty group. There is no data to wait for, so dCnt stays 0 (the very next byte is again a code byte), and we set dPend = not full. For 0x01, full is False, so dPend becomes True: an empty group is a lone zero, and it owes one. (0x01 is the only way n is zero; full is a formality here, always False, but writing not full keeps the rule uniform.)
n /= 0 — a normal group. Arm the counter, dCnt = n, and remember whether it was full. The implied zero, if any, will be decided when the counter hits bottom, in the other arm.

Inside a group: pass the byte, count down

        | otherwise ->
            let cnt' = dCnt s - 1
                s' =
                  s
                    { dCnt = cnt'
                    , dGot = True
                    , dPend =
                        if cnt' == 0
                          then not (dFull s)
                          else dPend s
                    }
             in (s', (Just b, False, False))

When dCnt is non-zero, b is a data byte, and data bytes are transparent: out = Just b, passed straight through unchanged (they were never touched by the encoder — COBS only ever removed the zeros, never disturbed the rest). Decrement the counter to cnt'. And here is the mirror image of startGroup’s pending logic: the instant the group empties, cnt' == 0, we set dPend = not (dFull s). A normal group just ended and owes its implied zero; a full (0xFF) group ends owing nothing, because it was a continuation. That single not dFull is the 0xFF-is-special rule from the concept section, written once, doing all its work.

Watching it run

Take the frame from the figure, 03 11 22 02 33 01, and feed it in byte by byte, capped with frameEnd. The decoder should hand back 11 22 00 33 00.

One decode, column-aligned. Data bytes (11, 22, 33) fall straight through. The first code byte 03 only arms the counter — no output. Each later code byte (02, 01) first pays the previous group's debt, manufacturing the accent 00, then re-arms: the implied zero is born at the next code byte, not when its group ended. The delimiter raises done and drops the final group's still-pending zero — which is why 01's zero never appears, and the output ends at 33 00, the original payload exactly.

Trace it against the state:

03 — dCnt is 0, dPend is False, so no output; startGroup reads n = 2, sets dCnt = 2.
11 — inside a group; emit 11, dCnt falls to 1.
22 — emit 22, dCnt falls to 0; the group is done, so dPend = not dFull = True. Debt incurred.
02 — dCnt is 0 and dPend is set, so emit the owed 0; then startGroup reads n = 1, dCnt = 1. Output so far: 11 22 00.
33 — emit 33, dCnt falls to 0, dPend = True again.
01 — dPend set, emit the owed 0; startGroup reads n = 0, an empty group, dCnt = 0, dPend = True. Output: 11 22 00 33 00.
frameEnd — reset. dGot is True and dCnt is 0, so malformed is False. The dPend left set by step 6 is simply discarded.

The output is 11 22 00 33 00 — the payload we started from. Notice the whole drama is in that last dPend: step 6 dutifully set it, and step 7 threw it away, which is exactly right, because the final group’s zero was the frame boundary, not a byte. Emit it and we would have handed back 11 22 00 33 00 00, one zero too many. The lazy timing is what makes the difference free.

And the malformed cases fall straight out of the same law. Feed 05 11 then frameEnd: the code 0x05 arms dCnt = 4, one data byte arrives, and the delimiter finds dCnt = 3 /= 0 — truncated, malformed. Feed nothing between two delimiters: dGot is False — empty, malformed. Feed a lone 03: dGot is set but dCnt = 2 still owes two bytes — malformed. The decoder never has to reach for a special error path; the verdict is a one-line consequence of the state it was already keeping.

`cobsEncodeStep`: encoding a byte

Encoding is the harder direction, and the reason is timing. The decoder could act on each byte the instant it arrived, because a code byte tells it everything up front. The encoder cannot: to emit a group’s code byte it must first know the group’s length, and it cannot know the length until it has seen the zero (or the 254th byte, or the end of input) that closes the group. So the encoder is a two-beat machine — fill a buffer, then emit what it holds — and the whole function is a case on which beat we are in.

cobsEncodeStep :: EncSt -> (Maybe (BitVector 8, Bool), Bool) -> (EncSt, (Bool, Maybe (BitVector 8), Bool))

The input is a maybe-(byte, is-last) paired with dsReady, the downstream ready line. The is-last flag rides along with each byte because, again, the encoder needs to know when the stream ends to close the final group. dsReady is back-pressure from whatever consumes the COBS bytes (the transmitter, via the loader): the encoder may only push a byte on a cycle the consumer can take one. The output is (readyIn, mOut, done) — a ready line back toward the source, the maybe-COBS-byte, and a done pulse when the frame is fully emitted. Two ready lines, pointing opposite ways, because the encoder sits in the middle of a pipeline and must talk to both ends.

Filling: buffer a group, and the load-bearing order

  EFilling -> case mIn of
    Nothing -> (s, (True, Nothing, False))
    Just (b, lst)
      | eFill s == 254 ->
          (s{eMode = EEmitting, eIx = 0, ePend = Just (b, lst)}, (True, Nothing, False))
      | b == 0 ->
          (s{eMode = EEmitting, eIx = 0, eFinal = lst, eLast = lst}, (True, Nothing, False))
      | lst ->
          ((store s b){eMode = EEmitting, eIx = 0, eLast = True, eFinal = False}, (True, Nothing, False))
      | otherwise ->
          (store s b, (True, Nothing, False))

Throughout EFilling, readyIn is True: this is the one mode that consumes input, so it is the one mode that says “keep them coming.” With no byte offered (Nothing) it idles, ready. With a byte (b, lst) in hand, four guards decide its fate, and their order is load-bearing — this is the single most important thing in the encoder, so we take the guards in order and dwell on the first.

eFill == 254 comes first, before even the zero check. If the buffer already holds 254 bytes, the group is full and must flush as a 0xFF continuation — whatever b is. We switch to EEmitting, reset the emit cursor, and stash b (with its lst) in ePend to be reprocessed into a fresh group after the flush. Why must this outrank b == 0? Because a 0xFF group carries no implied zero, so if we let a zero landing on a full buffer fold into the full group, that zero would simply vanish on decode. The comment in the source is blunt about it, and it deserves quoting in full:

A 254-byte group flushes as a 0xFF continuation (no implied zero), then b is reprocessed via ePend. A zero landing here must terminate a fresh empty group, not fold into the full group.

So a zero arriving on a full buffer produces …FF,<254> and then 01 — the full group, then a fresh empty group for the zero — never a single 0xFF that quietly eats it. Get the guard order wrong and the encoder loses data on exactly the inputs a naive test suite is least likely to try. (We will see the regression test that pins this down.)

The remaining three guards are the ordinary closes:

b == 0 — the zero terminates the current group. Switch to EEmitting to flush what we have; the zero itself contributes no byte to the buffer (it is implied). Record eFinal = lst and eLast = lst: if this terminating zero was the stream’s last byte, we will owe a final empty group after the flush, and the stream has ended.
lst — a non-zero last byte. store it, then switch to emit. eLast = True (the stream is over) but eFinal = False (a non-zero last byte owes no trailing group; the final group is the one this very byte is in).
otherwise — an ordinary non-zero, non-last byte. store it and stay in EFilling, ready for more. store writes b at index eFill and bumps the count: st{eBuf = replace (eFill st) b (eBuf st), eFill = eFill st + 1}.

Emitting: drive code, then data, then whatever is owed

  EEmitting
    | not dsReady -> (s, (False, Nothing, False))
    | eIx s <= eFill s ->
        let out :: BitVector 8
            out = if eIx s == 0 then fromIntegral (eFill s) + 1 else eBuf s !! (eIx s - 1)
         in (s{eIx = eIx s + 1}, (False, Just out, False))

In EEmitting, readyIn is False throughout — the encoder is draining its buffer, not accepting input. The first guard is the back-pressure gate: if dsReady is low the consumer cannot take a byte, so we stall, holding all state, emitting nothing. Nothing moves until downstream is ready.

When it is ready, the eIx <= eFill guard walks the group out. eIx == 0 emits the code byte, computed right here as eFill + 1 — the group’s length plus one, the encoder’s half of the L + 1 the decoder undoes. Every later index emits a data byte, eBuf !! (eIx - 1), and the cursor advances. So a group of eFill bytes takes eFill + 1 emit cycles: one code, then the data. Straightforward tape-out of code ++ group.

The interesting question is what happens after the cursor runs past the data, and the answer is a little cascade of owed work, tried in a deliberate order.

    | eFinal s ->
        (s{eFill = 0, eIx = 0, eFinal = False}, (False, Nothing, False))
    | otherwise -> case ePend s of
        Just (pb, pl)
          | pb == 0 ->
              (s{eMode = EEmitting, eFill = 0, eIx = 0, ePend = Nothing, eFinal = pl, eLast = pl}, (False, Nothing, False))
          | pl ->
              ((store s{eFill = 0} pb){eMode = EEmitting, eIx = 0, ePend = Nothing, eLast = True}, (False, Nothing, False))
          | otherwise ->
              ((store s{eFill = 0} pb){eMode = EFilling, ePend = Nothing}, (False, Nothing, False))
        Nothing
          | eLast s -> (initEnc, (False, Nothing, True))
          | otherwise -> (s{eMode = EFilling, eFill = 0}, (False, Nothing, False))

eFinal first. If a final empty group is owed — because the last input byte was a zero — clear eFill to 0 and loop back through EEmitting, which will emit the 0x01 of an empty group (eFill + 1 = 1) and then fall through here again with eFinal now False. This is the trailing-empty-group from the concept section, made concrete: a payload ending in a zero needs one last 01, and this is where it comes from.

Then ePend. A stashed byte means we just flushed a full 254-group and must fold that byte into a fresh group. Three sub-cases, mirroring the fill guards:

pb == 0 — the stashed byte was a zero. The full group already flushed as 0xFF (no implied zero); now the zero gets its own fresh empty group. Reset eFill, stay emitting, and set eFinal/eLast from pl — if that zero was the last input byte, we still owe the final empty group after it. This is the …FF,<254>,01,01 path in the flesh, and the reason the guard order upstream had to put eFill == 254 first.
pl — the stashed byte is non-zero and last. store it in a fresh buffer and emit that one-byte group, marking eLast.
otherwise — a non-zero, non-last stashed byte. store it into a fresh group and return to EFilling to keep accumulating from there.

Finally Nothing. No stash, so the group we just emitted was clean. If eLast is set the whole frame is done: reset to initEnc and pulse done. Otherwise there is more payload coming, so drop back to EFilling with an empty buffer.

Watching it run

Run the payload 11 22 00 33 00 through, is-last on the final zero, dsReady always high. It should produce 03 11 22 02 33 01 — the figure’s encoding, now built rather than read.

The encoder as a two-beat machine. EFilling buffers non-zero bytes (self-loop) until a byte closes the group (accent): a zero, the last byte, or the 254th byte — the last of which stashes the offending byte in ePend. EEmitting drives code ++ group out one byte per ready cycle, then settles any owed work before it leaves: eFinal emits the trailing empty group a payload-ending zero requires, and ePend folds a stashed byte into a fresh group. Only with nothing owed and the input ended does it reset and pulse done.

Every emitted byte gets its own cycle, so the trace is longer than the decode, but it breaks into three clean groups:

11, 22 (fill) — non-zero, not last: store each; eFill climbs to 2, and we stay in EFilling.
00 (fill) — the zero closes the group [11 22]; switch to EEmitting. eFinal and eLast stay False: this zero is not the last byte.
emit — eIx 0: code = eFill + 1 = 03; then data 11, then 22. The cursor runs past the data with nothing owed (eFinal false, ePend none, eLast false), so back to EFilling. Out: 03 11 22.
33 (fill) — store, eFill = 1.
00 (fill, last) — the zero closes the group [33], and it is the last byte, so set eFinal = eLast = True. Switch to emit.
emit — eIx 0: code = eFill + 1 = 02; then data 33. Out: 03 11 22 02 33.
emit — cursor past the data; now eFinal fires, clearing eFill for one more empty group and looping.
emit — code = 0 + 1 = 01 for that final empty group. Then ePend is Nothing and eLast is True, so reset to initEnc and pulse done. Out: 03 11 22 02 33 01.

Five bytes of payload became six on the wire, and steps 7–8 are where the extra one is minted: eFinal adds the trailing 01 that a payload ending in a zero always owes. That single byte is the “consistent overhead” — the final group has no zero in the payload to pay for its code byte, so it costs one, flat, and COBS never charges more than one such byte per 254.^[3]

The 254 boundary, where the encoder earns its length

Everything genuinely hard about the encoder lives at the full-group boundary, and three vectors from the test suite map it exactly. All three feed non-zero runs around the 254-byte cap; watch how the guard order pays off.

254 non-zero bytes, [1..254], the last flagged. The 254th byte arrives while eFill is still 253, so eFill == 254 does not fire — the lst guard does. store fills the buffer to exactly 254 and emits one full group, code 0xFF then the 254 bytes: FF,<254>. No trailing anything, because a non-zero last byte owes no final group. One full group, and done.
255 non-zero bytes, [1..255]. Now the 255th byte (lst) arrives with eFill already at 254, so eFill == 254 fires first: flush FF,<254> and stash byte 255 in ePend. After the flush, ePend’s pl case stores it into a fresh group and emits 02,255. Result: FF,<254> then 02,255. The run split across the cap, exactly as a continuation should.
254 non-zero bytes then a 0x00, the zero flagged last. The 254 fill the buffer; the zero arrives with eFill == 254, so — and this is the whole point of the guard order — eFill == 254 fires before b == 0: flush FF,<254> and stash the zero in ePend. After the flush, ePend’s pb == 0 case emits a fresh empty group 01 for the zero and, because it was last, sets eFinal, which adds the final 01. Result: FF,<254>,01,01. The zero survived as its own group instead of being swallowed by the 0xFF — the bug the guard order exists to prevent.

Three vectors, three faces of one boundary, and the encoder handles them with a stash register and a carefully ranked case. That is what those extra fields and that extra mode buy: an encoder that never drops a byte at the seam.

The tests

The module is under a hundred lines of logic, and its tests pin it down the same way the CRC’s did — from more than one direction at once — but with a tool the CRC only hinted at: a pure reference model standing in as an oracle.

There are, in fact, two COBS implementations in Tamal. The one we just read, Tamal.Loader.Cobs, is the streaming, one-byte-at-a-time form the hardware runs (the spec calls it §9). Beside it lives Tamal.Wire.Cobs (spec §5), a pure list-to-list reference:

cobsEncode :: [BitVector 8] -> [BitVector 8]
cobsDecode :: [BitVector 8] -> Maybe [BitVector 8]

cobsEncode is COBS written the easy way — fold over a list, accumulate a group, emit it at each zero — with no state machine, no back-pressure, no is-last flag, nothing but the algorithm. It is short enough to read and trust at a glance, and that is its job: it is the specification made executable. The streaming steps are the optimised, clocked implementation of the very same function, and the tests weld the two together:

testProperty "streaming decode of cobsEncode x reconstructs x" $ property $ do
  x <- forAll (Gen.list (Range.linear 0 300) genByteZeros)
  let (dec, bad) = decDrive (cobsEncode x)
  dec === x
  bad === False

testProperty "streaming encode equals cobsEncode (non-empty)" $ property $ do
  x <- forAll (Gen.list (Range.linear 1 300) genByteZeros)
  encDrive x === cobsEncode x

The first drives the streaming decoder over cobsEncode x — the oracle’s output — and demands the original x back, un-mangled and not malformed. The second is the sharper claim: the streaming encoder, byte for byte, produces exactly what the pure cobsEncode produces, for hundreds of random payloads. Hedgehog manufactures the payloads with genByteZeros, a generator deliberately about one-quarter zeros so that group boundaries — the whole point of COBS — come up constantly rather than by luck.

But genByteZeros has a blind spot, and the suite knows it: a random quarter-zero list almost never contains a 254-byte run of non-zeros, so it never reaches the full-group machinery we spent so long on. So there is a second generator, genRuns, that builds concatenated runs of up to 260 non-zero bytes each — straddling the cap on purpose — and the same equivalence is asserted over it:

testProperty "streaming encode equals cobsEncode (boundary runs)" $ property $ do
  x <- forAll (Gen.filter (not . L.null) genRuns)
  encDrive x === cobsEncode x

Then the round-trips, both directions streaming, over both generators — decDrive (encDrive x) === (x, False) — and, nailing the corner the guard order turns on, the explicit regression:

testCase "encode 254 non-zero then 0x00 == FF,<254>,01,01"
  $ encDrive (L.map fromIntegral [1 .. 254 :: Int] <> [0x00])
  @?= (0xFF : L.map fromIntegral [1 .. 254 :: Int]) <> [0x01, 0x01]

That last one is the guardrail bolted directly over the trap: if some future edit ever lets a zero fold into a full group, this line goes red before the property tests even get their turn. It is the same move the CRC post admired — a hand-derived witness bolted to the workbench beside the sweeping property — here guarding the one input a random generator is least likely to stumble onto.

The shape of the whole suite is worth stepping back for. The pure model is the meaning of COBS; the streaming steps are its hardware; and the property tests are the proof that the hardware means what the model says, checked against a fresh shower of payloads every run, with the awkward boundary explicitly seeded so it is never left to chance. You get to write the algorithm twice — once for clarity, once for the clock — and let the machine hold the two versions to each other.^[4]

What we read

Two pure step functions, no clock between them, and underneath them a whole framing layer: a decoder that walks a COBS stream a group at a time and manufactures each implied zero lazily — at the next code byte, so the last group’s phantom zero falls away at the delimiter for free — and an encoder that buffers a group, flushes code ++ group, and guards the 254-byte seam so carefully that a zero landing on a full group becomes its own honest little group instead of vanishing. Beside them a pure reference model that is the same algorithm written for people, and a property suite that welds the fast version to the readable one.

The transmitter and receiver gave us a byte pipe; the top sealed it; and today the pipe became a protocol — a stream with a reserved delimiter and a codec that honours it in both directions. What is still missing is the little machine that drives these steps: the loader proper, the mealy that catches rxByte strobes and clocks cobsDecodeStep, writes decoded words into instruction memory, and runs cobsEncodeStep in reverse to drain the engine’s results back out while txReady is high. It wears the silhouette we have now read five times — a sum for its phase, a record for the rest, a step function beside a mealy — and it is where these two codecs finally get their clock. That is the next thing we read. And past it, at last, the Engine the whole project has been circling.

postcard-rpc sits on top of postcard, a serde serializer for the embedded world that encodes Rust types into a compact, no_std-friendly wire format. COBS is the framing underneath it — the layer that turns postcard’s byte blobs into delimited messages a receiver can find the edges of. Meeting COBS there, in anger, doing a real job on a real link, is a better teacher than any diagram: you internalise very quickly that a byte stream is not a message stream until something draws the borders. ↩
The “consistent” in Consistent Overhead Byte Stuffing is a promise about the worst case. Older byte-stuffing schemes — the escape-character trick SLIP uses, say — have overhead that depends on the data: a payload full of the reserved byte can double in size, because every occurrence becomes two bytes. COBS refuses that variance. Its overhead is at most one byte per 254 bytes of payload, roughly 0.4%, no matter what the data is — and, just as importantly, it is bounded and predictable, which is what lets a fixed-size buffer on the far end be sized with confidence. You pay a small, flat tax rather than an occasional ruinous one. That flatness is the property the name is bragging about. ↩
Where does the “+1” go in the happy case? A payload with no zeros and under 255 bytes encodes to a single group: one code byte, then the payload verbatim. That is one byte of overhead for the whole frame — the code byte the delimiter cannot be. Every additional group (born at each zero, or at each 254-byte cap) costs one more code byte, but buys back the zero it replaces, so a zero-dense payload is close to break-even and a zero-free one pays the flat one-per-254. The delimiter itself is the only byte that is pure tax, and it buys the thing the whole scheme exists for. ↩
The two-implementations pattern — a pure list model beside a streaming, clocked one, proven equal — is not unique to COBS in Tamal; it is becoming the house style. The pure model is where you think, unencumbered by back-pressure and cycle timing; the streaming model is where you ship, and it has to survive a consumer that stalls and a producer that dribbles. Keeping both and testing one against the other means the gnarly version is never the only place the algorithm is written down — there is always a clean copy to check it against, and to read when the clocked one stops making sense. ↩

Tamal: Wiring Uart Through Composition

2026-07-24T09:00:00+00:00

The receiver we read yesterday closed the keystone. It wired the transmitter’s line into its own, shared one tick between them, fed a random byte in one end and got the same byte, bit-for-bit, out the other — first with an always-true tick, then with the real fractional-3.125 heartbeat the baud generator fought to keep honest. By the last paragraph the UART worked, end to end, and I told you it was behind us.

It was — as behaviour. But there is a small dishonesty in having watched the whole thing run without ever reading the file that makes it a single thing. Those loopback tests called uartTx and uartRx and shared a tick by hand, or they called uart — and that uart, the five-line module this post is about, we leaned on and never once read. This is the shortest post in the series, because its subject is the shortest module in the UART: the top, the umbrella, the seam. And it earns its own post for exactly one reason — it is the first Tamal module with no behaviour of its own. The CRC computed a residue; the baud generator counted a phase; the transmitter drove a wire; the receiver recovered one. Tamal.Uart does none of these. It connects the ones that do. Its whole content is composition, and composition — how three blocks that each own one idea become one block that owns none — is the subject.

Every post so far ended by pointing forward, at the next block. This one points inward, at the wiring.

The entire source

Minus the license header and the doc-comment — and there is nothing else to minus, no helper to hide — here is src/Tamal/Uart.hs in full:

module Tamal.Uart
  ( uart
  ) where

import Clash.Prelude

import Tamal.Uart.BaudGen (oversampleTick)
import Tamal.Uart.Rx (uartRx)
import Tamal.Uart.Tx (uartTx)

uart ::
  forall baud dom.
  (HiddenClockResetEnable dom, KnownDomain dom, KnownNat baud) =>
  SNat baud ->
  Signal dom Bit ->
  Signal dom (Maybe (BitVector 8)) ->
  ( Signal dom (Maybe (BitVector 8))
  , Signal dom Bool
  , Signal dom Bit
  , Signal dom Bool
  )
uart baud rxLine txByte = (rxByte, rxErr, txLine, txReady)
 where
  tick = oversampleTick baud
  (rxByte, rxErr) = uartRx tick rxLine
  (txLine, txReady) = uartTx tick txByte

That is the whole module. A header with something new in it, a type signature longer than the code it types, and a body of four lines — one to name the tick, two to place the machines, and a return that bundles their outputs. No data declarations, because the top remembers nothing. No mealy, no register, because it clocks nothing. No where-hidden step, because it decides nothing. For the first time in the series the entire module fits in a paragraph, and every line is either a type or a wire.

Three imports and one door

The opening beat is the CRC module’s, played a fifth time, and I will be as quick as the fifth playing deserves:

module Tamal.Uart
  ( uart
  ) where

import Clash.Prelude

module Tamal.Uart names the module after its path — src/Tamal/Uart.hs, the one without a third dot, the parent directory of Tamal.Uart.BaudGen, Tamal.Uart.Rx, and Tamal.Uart.Tx. Only uart leaves through the one door in the wall, and this time there is genuinely nothing else behind it: no private step, no helper, no state type. The export list has never been so nearly the whole file. import Clash.Prelude is the same prelude swap every earlier post dwelt on, the line that trades ordinary Haskell’s furniture for Signal, Bit, and the rest of the vocabulary that lowers to gates; I will not re-derive it a fifth time either.

What is new sits just underneath it — three imports, the first the series has had cause to read:

import Tamal.Uart.BaudGen (oversampleTick)
import Tamal.Uart.Rx (uartRx)
import Tamal.Uart.Tx (uartTx)

Each pulls exactly one name across from a child module — the one name that module’s own export list let out. oversampleTick from the baud generator, uartRx from the receiver, uartTx from the transmitter. These three imports are the top’s material: it has no primitives of its own to work with, only the three finished blocks the last three posts built, each sealed to a single public name and each imported by that name. And the parentheses on each import are the mirror of the parentheses on each module line we read one at a time. The export list said “only this leaves”; the import says “only this enters.” Set the four modules side by side and the doors line up exactly: BaudGen lets out oversampleTick and the top lets it in; Rx lets out uartRx and the top lets it in; Tx lets out uartTx and the top lets it in. The top is the room those three doors open into.

The type: the numbers come home

The signature is longer than the body, and every part of it is a reunion:

uart ::
  forall baud dom.
  (HiddenClockResetEnable dom, KnownDomain dom, KnownNat baud) =>
  SNat baud ->
  Signal dom Bit ->
  Signal dom (Maybe (BitVector 8)) ->
  ( Signal dom (Maybe (BitVector 8))
  , Signal dom Bool
  , Signal dom Bit
  , Signal dom Bool
  )

Under the primer’s reading a signature is half the documentation^[1], and this one is visibly assembled out of the three signatures we already know. Begin with what the transmitter and receiver made a point of not having. Both of them, you will remember, shed every number from their types: one lone HiddenClockResetEnable dom constraint, no forall, no SNat, no KnownNat, because neither block names a baud rate — a bit is sixteen ticks and the ticks arrive from elsewhere. The baud generator was the opposite: it carried the whole numeric burden — forall baud dom, the KnownDomain/KnownNat pile, and the SNat baud argument — because it was the one block that turns a baud rate into a tick.

Now look at the top’s constraints and first argument: forall baud dom, (HiddenClockResetEnable dom, KnownDomain dom, KnownNat baud), SNat baud ->. They are the baud generator’s, character for character. The numbers come home. The top wears the baud generator’s exact type obligations because it owns the baud generator: it is the block that will call oversampleTick baud, so it must be handed the SNat baud to pass along, and must carry the KnownNat baud and KnownDomain dom that oversampleTick needs to read the clock frequency out of the domain. The transmitter and receiver got to be numberless precisely because the top volunteered to hold the number for all three. Factoring the timing into one small block did not delete the SNat; it concentrated it — out of TX and RX, into BaudGen, and back out to whoever owns BaudGen, which is here.

Then the ports, and they are just as plainly a concatenation. Two arguments go in:

Signal dom Bit — the RX line, the receiver’s one input, the asynchronous wire from a pin.
Signal dom (Maybe (BitVector 8)) — the TX byte, the transmitter’s one input, the Just b send request.

And the four-tuple comes out as (rxByte, rxErr, txLine, txReady) — the receiver’s two outputs followed by the transmitter’s two:

Signal dom (Maybe (BitVector 8)) and Signal dom Bool — uartRx’s byte strobe and framing-error strobe, unchanged.
Signal dom Bit and Signal dom Bool — uartTx’s line and its ready flag, unchanged.

So the top’s interface is exactly uartRx’s external ports set beside uartTx’s external ports, with the baud generator’s type obligations wrapped around the pair. And notice the one thing that is absent. The tick — Signal dom Bool, the baud generator’s output and the first argument of both uartRx and uartTx — appears nowhere in uart’s type. It was an input to each machine when we read them alone; here it has gone internal. That is the signature telling you, before you read a line of the body, what composition did: it took the wire that ran between the blocks and tucked it inside, leaving only the wires that still face the world. The heartbeat is now a private matter.

Four lines, no state

Here is the body, the only part of the file that is neither ceremony nor type:

uart baud rxLine txByte = (rxByte, rxErr, txLine, txReady)
 where
  tick = oversampleTick baud
  (rxByte, rxErr) = uartRx tick rxLine
  (txLine, txReady) = uartTx tick txByte

Read it as what it is: a wiring diagram written as equations. The head binds the three inputs — baud, rxLine, txByte — and returns the four-tuple. The where block defines the internal names the tuple is built from. And every one of those definitions is an instantiation, not a computation:

tick = oversampleTick baud — place one baud generator, hand it the baud, call its output tick.
(rxByte, rxErr) = uartRx tick rxLine — place one receiver, feed it the tick and the line, name its two outputs.
(txLine, txReady) = uartTx tick txByte — place one transmitter, feed it the tick and the byte, name its two outputs.

There is no arithmetic, no case, no state threaded from cycle to cycle. Every earlier module’s where block hid work — the baud generator’s phase accumulator feeding back through a register, the transmitter’s initTx and the mealy lift over txStep, the receiver’s synchronizer and its mealy over rxStep. This where block hides nothing but names for wires. tick is not a value that gets computed and returned; it is a net, and oversampleTick baud is the sub-circuit driving it. rxByte is not a byte; it is the wire on which the receiver will present its strobes.

The tell is the ordering — or the absence of it. In an imperative reading you would object that tick is used on the second and third lines but defined on the first, so the order is load-bearing: define before use. In Haskell’s where, and in the hardware it denotes, the order does not matter at all. I could write the three bindings in any sequence and the module would be identical, because they are not steps executed in time but nets that all exist at once. tick drives uartRx and uartTx the way a wire drives the pins soldered to it — simultaneously, continuously, with no notion of “first.” The where block is a net-list, and a net-list is a set, not a sequence.^[2]

This is what it looks like when a module’s job is purely structural. It adds no gate that computes anything and no flip-flop that remembers anything; it adds only connections. Put the four modules on a bench and this file is the wiring loom between them — and, like a loom, it is invisible in the behaviour and total in the structure. Nothing in the UART works without it, and it does nothing but let the rest work.

One heartbeat, two machines

Four lines, and only one of them carries a design decision. The other three are forced: a receiver needs the line, a transmitter needs the byte, the outputs are what they are. But the first line, and the way the name it binds gets used twice, is a genuine choice:

  tick = oversampleTick baud
  (rxByte, rxErr) = uartRx tick rxLine
  (txLine, txReady) = uartTx tick txByte

tick is generated once and fanned into both machines. This is decision 2 of the UART design — build RX and TX together, sharing one oversample tick — and it is the whole reason the two halves live in one module instead of two.

Nothing in the types forced it. Each machine takes its own Signal dom Bool tick, so I could have called oversampleTick baud twice, once for the receiver and once for the transmitter, and every signature would still typecheck. It would even work — two identical NCOs in the same domain, same increment, same modulus, are deterministic functions of the one clock and would count in perfect lock-step, bit for bit. But identical is the tell. You would be spending a second phase accumulator, adder, and comparator to build an exact copy of a signal you already have, and then leaning on the two staying exact — a property you now maintain in two places, where changing one generator’s width or modulus and forgetting the other silently splits the one clock into two that disagree^[3]. And even kept in step, the duplication states a falsehood about the design: that the transmit clock and the receive clock are two things that happen to agree, when the whole point is that they are one thing. Sharing tick says the true thing in a single wire.

And because they are one thing, the loopback the receiver closed rests on something firmer than luck. In a real UART the two ends of the link are different chips with genuinely independent clocks, and the receiver’s whole apparatus — oversample sixteen times, sample at the center, majority-vote — exists precisely to tolerate the drift between them. Inside Tamal there is no drift to tolerate, because there are not two clocks: the transmitter holds each bit for sixteen ticks and the receiver centers its 7/8/9 window in the same sixteen ticks, off the same accumulator. The center-sampling margin the receiver spent a whole post earning is, in loopback, slack it never has to spend — the sample lands dead-center by construction, because one counter is timing both ends. The baud generator promised it was handing “the rest of the UART” an enable rather than a clock; this line is where “the rest of the UART” turns out to be precisely two consumers, wired in parallel across the one enable.

The whole of Tamal.Uart as one picture. The dashed box is the module boundary; inside it a single oversampleTick — the baud generator — drives one accent wire, the tick, that fans into both uartRx — the receiver — and uartTx — the transmitter. The compile-time baud enters the generator as a dashed parameter, not a runtime wire. Six signals cross the boundary: rxLine and txByte in, and rxByte, rxErr, txLine, txReady out — the receiver's two ports beside the transmitter's two, which is precisely what uart's type says. The one wire that never crosses the boundary is the tick: generated once, shared by both machines, internal to the module. Composition in a single figure — three blocks that each own an idea, joined by a seam that owns none.

Where the four wires go

Inside uart the story is over and self-contained: the loopback proved the four wires carry what they claim. The interesting question is where that four-tuple goes when the UART stops being read as a closed unit and starts being used. That happens one level up, in the board shell’s system, and the seam is worth seeing even though the shell is a later post’s subject:

(rxByte, _rxErr, txLine, txReady) = uart (SNat @2_000_000) rxLine txByteL

Three things to read here. First, the baud finally gets a number: SNat @2_000_000, two megabaud, the baud generator’s 2_000_000 chosen at the one call site that has to choose it. uart itself stayed baud-generic to the end — the SNat baud in its type — exactly as decision 3 of the design intended; the shell is where the knob is finally turned. Everything below uart inherited its freedom from a number by never naming one, and the shell names it once, here, and the whole tree specialises.

Second, follow the wires into the rig. rxByte feeds a loader FSM that fills the instruction BRAM byte by byte — the RX-to-load path. txReady, paired with the loader’s own txByteL, drains trace words back out — the TX side of the same FSM. txLine goes to the USB-UART pin. These are the four terminals the boring diagram in the introduction drew as a single UART box between the host and the loader; this is that box’s actual boundary, four wires wide.

Third, and most honestly: _rxErr. The framing-error strobe — the output the receiver worked hardest for, the one with no transmitter analogue, the flag it raises when a stop bit comes back low — is bound to _rxErr and dropped. Today’s shell does not consume it. Section 9 of the design reserved it for “abort or flag a corrupt load,” and that consumer is not built yet, so the wire is generated, typed, tested, and — for now — left hanging under the underscore that tells GHC we meant to ignore it. It is a small, true window into how a design grows: the receiver produces the honest signal before the shell is ready to act on it, and the top faithfully carries it to a boundary where it currently goes nowhere. The wire is ready for its consumer the way the whole interface is ready for the loader that plugs in next — built to the right shape, waiting.

What we read

The shortest module in the UART, read at last. Five lines — one exported name, four wires — and no state at all. The type was longer than the code and told most of the story before the code did: the baud generator’s numeric obligations come home to the top, because owning the generator means owning its SNat baud and its KnownNat, and the transmitter’s and receiver’s numberless freedom was bought by concentrating every number here. The interface is the receiver’s ports and the transmitter’s ports set side by side, with the one wire that ran between them — the tick — gone internal, so the type itself shows what composition tucks away and what it leaves facing the world.

The body was a net-list wearing the syntax of equations: not computations run in order but wires existing at once, three sub-blocks placed and connected, a where that hides names rather than work. Its one decision was to generate the heartbeat once and fan it into both machines — decision 2 — which is what makes the loopback a structural certainty rather than a coincidence of two clocks, one time base counting the one “sixteen” that is both the bit the transmitter holds and the center the receiver samples. And its four output wires are the seam: one level up, rxByte and txReady and txLine join a loader FSM and a pin, while rxErr waits, dropped for now, for a consumer the design has promised but not yet built.

The receiver told you the UART was behind us, and it was right about the behaviour — we had watched the byte survive the round trip. Now it is behind us as text, too: every file of the transport read, down to the five-line seam that lets us say “the UART” as a single word. And those four wires reach, for now, exactly one block — the one pressed flush against the UART. Not the Engine but the loader: the FSM that catches rxByte strobes and writes them into instruction memory, and feeds bytes back out while txReady is high, the very four terminals we traced into system a moment ago. Most of it we will read quickly, because it wears the silhouette we have now read four times — mealy over a pure loaderStep, a sum for the phase (RxControl | Run | Drain, with a finer one for draining) and a record for the rest. What is new is the wire it speaks. A UART hands you a bare stream of bytes, and a bare stream is not yet a message: where does one frame end and the next begin? The loader’s answer is COBS — Consistent Overhead Byte Stuffing — which stuffs every payload so the byte 0x00 never appears inside it, freeing that one value to mean frame boundary; the loader decodes the stream on the way in and encodes the drain on the way out. It is where the byte pipe we finished today becomes a byte protocol.

The Engine the introduction promised — the stateful difficulty spike the design kept deferring — still waits its turn beyond the loader. But it waits. The heartbeat is generated, the machines are wired, the bytes cross whole. Next we read the little machine that frames them: the loader, and its COBS.

Yes, the refrain is deliberate. The primer made the point and every block since has leaned on it, because a claim repeated across a series is a claim that sticks: in Haskell, and doubly in Clash, the type signature is half the documentation. Read the type before the body and the body holds few surprises. I will keep saying it until it needs no saying. ↩
This is the difference between composition in software and in hardware, and Clash sits exactly on the seam. In an ordinary Haskell program, uart baud rxLine txByte would call oversampleTick, uartRx, and uartTx — run them, wait for their results, thread values through. Clash does not run them; it elaborates them. Each call site becomes an instance of that sub-circuit stamped into the net-list, and each where-bound name becomes a net joining the instances — tick a single wire with a fan-out of two, driving the enable input of the receiver instance and the transmitter instance at once. That is why naming tick once and using it twice costs one oscillator and not two: it is one net, not two evaluations. It is also why the binding order is immaterial — a net-list is a graph, and a graph has no first line. The top adds no register and no gate that computes; it is a pure structural node, transparent to behaviour and total to structure, which is the precise hardware meaning of “this module is only wiring.” ↩
In fairness, there is a version of two generators that is not mere duplication. Run one at wire speed and one at 16× wire speed — the slow one for the transmitter, the fast one for the receiver — and the transmitter genuinely simplifies: handed a tick already at one-per-bit, it sheds its Index 16 and advances a bit per tick, leaving oversampling to the receiver, the only half that needs it. But weigh it. The split spends a second oscillator — another accumulator, adder, and comparator — to save a four-bit counter: more logic, not less, though at this scale the difference vanishes into the noise. So the choice was never cost; it is which story is cleaner, and one heartbeat, divided where it is needed reads better than two heartbeats that must be kept in tune. Here, reading better and maintaining better are the same thing. ↩

Tamal: The receiver

2026-07-23T09:00:00+00:00

The transmitter we read yesterday drove a wire. It owned the line: it held each level for sixteen ticks, and it made every output a pure function of its own state, so the serial output sat rock-steady between bit boundaries and never once twitched. That was a luxury, and we spent most of the post admiring it. The receiver is the mirror of that module — and a mirror, it turns out, is not a reflection so much as the harder half. The transmitter drove a wire; the receiver must read one it does not control.

That single inversion — drive becomes read — is where every new idea in this post comes from, and it is worth saying up front which parts of the receiver are genuinely new and which are just the transmitter run backwards. The skeleton is the same: the same four-constructor RxState, the same record-of-fields carried tick to tick, the same Index 16 counting sixteen oversample ticks to a bit, the same mealy at the top of the module, the same freeze-off-tick cadence, the same LSB-first convention. If that were all, this post would be short and I would send you back to re-read the transmitter with the names changed. It is not all. The interesting parts of the receiver are precisely the parts that are not “TX in reverse,” and there are five of them:

The line is an input now, arriving asynchronously from a pin, so the very first thing the module does is register it twice — a 2-flop synchronizer against metastability, a thing the transmitter never needed because it drove the wire itself.
The start bit is not commanded but hunted for, and hunted for by its falling edge rather than its mere low level — an edge, so a line simply held low can never fake a frame.
The bit is not held but sampled, and sampled carefully: at the center of the bit-time, three times, and resolved by a majority vote. This is the whole point of oversampling sixteen times, and it is the richest section of the post.
A stop bit that comes back low is a framing error — the byte is dropped and a flag is raised. The transmitter had no notion of a frame going wrong; the receiver must.
The outputs are genuinely Mealy — one-cycle strobes that read the tick input — where the transmitter’s were Moore levels. This is the sharpest contrast between the two halves, and the one the transmitter post set us up to notice.

Like the transmitter, the whole receiver fits in a screenful and change.

The entire source

Minus the license header and the doc-comments — but keeping the short inline comments, because on this module they carry real reasoning — here is src/Tamal/Uart/Rx.hs in full:

module Tamal.Uart.Rx
  ( uartRx
  ) where

import Clash.Prelude

data RxState = RxIdle | RxStart | RxData (Index 8) | RxStop
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

data RxS = RxS
  { rxState :: RxState
  , rxCnt :: Index 16
  , rxShift :: BitVector 8
  , rxS7 :: Bit
  , rxS8 :: Bit
  , rxS9 :: Bit
  , rxPrev :: Bit
  }
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

uartRx ::
  (HiddenClockResetEnable dom) =>
  Signal dom Bool ->
  Signal dom Bit ->
  (Signal dom (Maybe (BitVector 8)), Signal dom Bool)
uartRx tick rxLine = unbundle (mealy rxStep initRx (bundle (tick, synced)))
 where
  -- 2-flop synchronizer, clocked every cycle (not tick-gated); idle line is high.
  sync1 = register high rxLine
  synced = register high sync1
  initRx = RxS RxIdle 0 0 0 0 0 high

maj :: Bit -> Bit -> Bit -> Bit
maj a b c = (a .&. b) .|. (a .&. c) .|. (b .&. c)

captureSample :: RxS -> Bit -> RxS
captureSample s bit' = case rxCnt s of
  7 -> s{rxS7 = bit'}
  8 -> s{rxS8 = bit'}
  9 -> s{rxS9 = bit'}
  _ -> s -- actually unreachable

decideBit :: RxS -> (RxS, (Maybe (BitVector 8), Bool))
decideBit s = case rxState s of
  RxStart
    | bit' == low -> (s{rxState = RxData 0, rxCnt = 0}, (Nothing, False))
    | otherwise -> (s{rxState = RxIdle, rxCnt = 0}, (Nothing, False))
  RxData i ->
    let sh =
          if bit' == high
            then setBit (rxShift s) (fromEnum i)
            else clearBit (rxShift s) (fromEnum i)
        s' = s{rxShift = sh, rxCnt = 0}
     in if i == maxBound
          then (s'{rxState = RxStop}, (Nothing, False))
          else (s'{rxState = RxData (i + 1)}, (Nothing, False))
  RxStop
    | bit' == high -> (s{rxState = RxIdle, rxCnt = 0}, (Just (rxShift s), False))
    | otherwise -> (s{rxState = RxIdle, rxCnt = 0}, (Nothing, True))
  RxIdle -> (s, (Nothing, False)) -- actually unreachable
 where
  bit' = maj (rxS7 s) (rxS8 s) (rxS9 s)

rxStep :: RxS -> (Bool, Bit) -> (RxS, (Maybe (BitVector 8), Bool))
rxStep s (tick, line)
  | not tick = (s, (Nothing, False)) -- only move on oversample ticks
  | otherwise =
      let s0 = s{rxPrev = line} -- remember this tick's level for next tick
       in case rxState s of
            RxIdle
              | rxPrev s == high && line == low -> (s0{rxState = RxStart, rxCnt = 0}, (Nothing, False))
              | otherwise -> (s0, (Nothing, False))
            RxStop ->
              -- Resolve the stop bit at its center sample (count 9) rather than
              -- waiting out the whole window: returning to idle ~6 ticks early
              -- gives the falling-edge detector idle-high ticks to arm rxPrev,
              -- so a back-to-back next frame (stop immediately followed by start)
              -- still resyncs.
              let s1 = captureSample s0 line
               in if rxCnt s == 9
                    then decideBit s1
                    else (s1{rxCnt = rxCnt s + 1}, (Nothing, False))
            _ ->
              -- RxStart / RxData
              let s1 = captureSample s0 line
               in if rxCnt s == maxBound
                    then decideBit s1
                    else (s1{rxCnt = rxCnt s + 1}, (Nothing, False))

A dozen more lines than the transmitter, and every one of the extra lines is one of the five new ideas. Top to bottom: the two data declarations that are the machine’s memory — the transmitter’s two types, mirrored, with four new fields bolted on; the six-line uartRx, which is the transmitter’s mealy lift with a synchronizer soldered in front of it; a tiny maj that is the majority vote; a captureSample that stashes the three center samples; a decideBit that turns those samples into a byte or an error; and rxStep, the transition, which is where the falling-edge hunt and the early stop resolution live. We will read them in roughly that order, spending almost all of our words on the five things the transmitter never had to do.

The module header we can wave past. The CRC, baud generator, and transmitter posts each dwelt on the same opening beat — the single-name export list sealing everything private behind it, and the import Clash.Prelude swap that trades ordinary Haskell’s furniture for Signal, Bit, register, and mealy — and a fourth reading would teach nothing. The one detail worth a glance is an absence: there is no {-# LANGUAGE NumericUnderscores #-}, because the receiver names no clock frequency and converts no baud rate the way the baud generator did. Its idea is not timing but recovery — given a wire it did not schedule, find the bits.

The type: a line in, a byte out

The signature is the transmitter’s, read in a mirror:

uartRx ::
  (HiddenClockResetEnable dom) =>
  Signal dom Bool ->
  Signal dom Bit ->
  (Signal dom (Maybe (BitVector 8)), Signal dom Bool)

Set it beside uartTx and the symmetry is almost too neat. The transmitter took a tick and a Maybe (BitVector 8) and returned a Bit and a Bool; the receiver takes a tick and a Bit and returns a Maybe (BitVector 8) and a Bool. The byte and the wire have swapped ends — same lone HiddenClockResetEnable constraint, same numberless type. The Signal dom Bool tick is the baud generator’s enable plugged in exactly as it was for the transmitter, the receiver being the other block that enable was built to gate. The rest of the signature is where the mirror starts to bend.

Signal dom Bit is the RX line — and this is the first genuinely new thing in the type. For the transmitter, Bit was an output, a wire it drove. Here Bit is an input, a wire it reads, and the comment on the matching argument in the design doc is the whole story in four words: asynchronous; synchronized internally. This wire arrives from a physical pin, from a host whose clock has no relationship to Tamal’s. Its edges fall wherever they fall. The receiver cannot assume it is stable at the clock edge, cannot assume it will not change while a flip-flop is trying to latch it, and so the very first thing uartRx does — before the state machine ever sees the line — is register it twice. We will get to that in a moment; the type is already warning us.

The result, (Signal dom (Maybe (BitVector 8)), Signal dom Bool), is a pair of output wires that are the mirror of the transmitter’s:

Signal dom (Maybe (BitVector 8)) is the received byte, and the Maybe is doing the primer’s job again. Just b on a cycle means “a whole frame just landed and here is its byte”; Nothing, which is the value on the overwhelming majority of cycles, means “nothing completed this cycle.” It is a one-cycle strobe, an event, not a held register — and that word, strobe, is going to matter enormously when we ask whether these outputs are Moore or Mealy.
Signal dom Bool is the framing-error flag, likewise a one-cycle strobe, raised on the single cycle a frame ends without a valid stop bit. Where the transmitter’s second output was ready — a level, high for as long as the machine idled — the receiver’s is an error — a pulse, high for exactly one cycle when a frame goes bad.

So the interface reads: here is a heartbeat and a wire I do not control; take the bytes I recover from it and a flag for the frames that came apart. Two strobes out, no back-pressure, no ready — because a receiver cannot ask the host to slow down anyway. The bytes arrive when they arrive; the strobe simply announces them.

Two types, mirrored — and four new fields

Everything the receiver remembers lives in two data declarations, and the first of them is the transmitter’s phase type with the tags renamed:

data RxState = RxIdle | RxStart | RxData (Index 8) | RxStop

Read against TxState it is identical in shape — the same four constructors, the same eleven inhabitants once RxData (Index 8) fans into eight. What differs is only what each phase does: where TxStart drove the line low, RxStart confirms a start bit it thinks it saw; where TxData i drove bit i out, RxData i shifts bit i in; where TxStop drove a high stop bit, RxStop checks whether the stop bit really came back high. Same skeleton, opposite verbs — drive versus read, the inversion the whole post turns on. The deriving block is the primer’s incantation unchanged, read in full in the transmitter post.

The second type is where the receiver stops being a mirror. The transmitter’s record had three fields; the receiver’s has seven:

data RxS = RxS
  { rxState :: RxState
  , rxCnt :: Index 16
  , rxShift :: BitVector 8
  , rxS7 :: Bit
  , rxS8 :: Bit
  , rxS9 :: Bit
  , rxPrev :: Bit
  }

The first three are TxS again, one of them reordered. rxState is the phase we just met. rxCnt :: Index 16 is the position within the current bit, counting the sixteen oversample ticks — 0..15, never 16, the width load-bearing exactly as it was for txCnt. rxShift :: BitVector 8 is the byte, though here it is assembled rather than emitted — bits are written into it as they arrive, not shifted out of it. Three fields, and if the receiver were merely “TX in reverse” that would be the end of the record.

It is not the end. Four more fields carry the ideas the transmitter never needed:

rxS7, rxS8, rxS9, three lone Bits, are the three samples of the line taken at oversample counts 7, 8, and 9 — the three readings around the center of the bit that the majority vote will resolve into a decision. The transmitter drove a level and knew what it was; the receiver must read a level it does not know, and reads it three times to be sure. These three flip-flops are the physical memory of “I looked at the wire near the middle of this bit and here is what I saw, three times.” Nothing in TxS corresponds to them, because nothing in the transmitter ever had to look.
rxPrev, one more Bit, is the synchronized line as it stood at the previous oversample tick. It exists for one purpose: so that the idle state can trigger on a high-to-low edge rather than a low level. To notice an edge you must remember where you were, and rxPrev is that memory — last tick’s line, held so this tick’s line can be compared against it. Again, the transmitter had no analogue: it chose when the start bit began, so it never had to detect the moment one arrived.

Add it up and the receiver’s memory is a phase, a four-bit counter, a byte, three sampled bits, and one remembered bit — some twenty-odd bits of flip-flop against the transmitter’s fifteen. Every extra bit buys one of the jobs that reading-a-wire-you-do-not-own demands. The initial value wires them all to their resting state:

initRx = RxS RxIdle 0 0 0 0 0 high

Read positionally against the record: rxState = RxIdle, rxCnt = 0, rxShift = 0, rxS7 = rxS8 = rxS9 = 0, and — the one non-zero — rxPrev = high. That last is not an accident. The idle line sits high, so at power-up the receiver must believe the line was high a tick ago; otherwise its very first observation of a genuine high line would look like no change, or worse, a spurious edge. Priming rxPrev to high is the software equivalent of assuming the wire was idle before we started watching — which, on a UART, it was.

The receiver's eleven states as an FSM — the transmitter's diagram read in a mirror, with two genuinely new edges. The accented transition out of RxIdle fires on a high→low edge (tracked through rxPrev), not a low level, so a line simply held low cannot fake a frame. The back-edge RxStart → RxIdle is glitch rejection: if the confirming vote comes back high, the "start" was noise and we abandon it. RxData i's self-loop votes the three center samples and writes bit i with setBit/clearBit. All transitions are tick-gated (they advance only on an oversample tick); RxStart and RxData resolve at the end of the 16-tick window (count 15), but RxStop resolves early, at its center sample (count 9), and it is there that the byte and framing-error strobes fire.

The same silhouette

Here is the line that lifts the whole thing into hardware, and it is the transmitter’s line wearing a hat:

uartRx tick rxLine = unbundle (mealy rxStep initRx (bundle (tick, synced)))
 where
  sync1 = register high rxLine
  synced = register high sync1
  initRx = RxS RxIdle 0 0 0 0 0 high

Strip the where for a second and the outer shape is exactly uartTx’s: unbundle (mealy rxStep initRx (bundle (tick, ...))), the register-plus-pure-function machine the transmitter post read at length — mealy clocking a pure step, bundle/unbundle zipping the several signals into the one the combinator wants and back. The drill is unchanged, so I will not run it again: find the mealy, find the step function beside it, and rxStep is the brain.

What is new is one substitution, and it is the whole reason this section exists. Look at what gets bundled:

mealy rxStep initRx (bundle (tick, synced))

Not bundle (tick, rxLine) — bundle (tick, synced). The state machine is not fed the raw line at all. It is fed synced, a signal that does not appear in the argument list, defined in the where block by two registers standing between the pin and the logic. That little substitution — rxLine in the type, synced into the machine — is the 2-flop synchronizer, and it is the first genuinely new idea in the receiver. It deserves its own section.

The line is now an input: the 2-flop synchronizer

Two lines of the where block are the entire mechanism:

  sync1 = register high rxLine
  synced = register high sync1

rxLine — the asynchronous wire from the pin — goes into a register, whose output sync1 goes into a second register, whose output synced is what the state machine reads. Two flip-flops in series, both initialised high, and the line is delayed by two clock cycles before any logic touches it. That is the whole thing. It is also one of the most important two lines in the codebase, because it is the guard against metastability, and metastability is the failure mode that a transmitter, driving its own wire, is simply never exposed to.^[1]

Here is the problem it solves. A flip-flop is a promise: sample the input at the clock edge, hold it steady until the next edge. But the promise has fine print — the input must itself be steady for a small window around the clock edge, a setup time before and a hold time after. Meet that window and the flip-flop resolves cleanly to 0 or 1. Miss it — change the input while the edge is happening — and the flip-flop can enter a metastable state: its output hovers at neither level, a voltage stuck halfway, for an unbounded and unpredictable time before it eventually, randomly, falls to 0 or 1. A transmitter never risks this because it changes its line in step with its own clock; the setup and hold windows are honoured by construction. A receiver has no such luck. The host’s line changes when the host’s clock says so, which bears no relationship to Tamal’s clock, so sooner or later a bit edge will land exactly on a Tamal clock edge and the first flip-flop that samples it will go metastable. There is no avoiding that first strike. The line is asynchronous; asynchronous means “will, eventually, violate setup/hold”; and no amount of cleverness changes it.

What you can do is contain the damage, and that is what the second flip-flop is for. When sync1 goes metastable, you give it one whole clock cycle — the time between this edge and the next — to settle, untouched by any logic, before synced samples it. A clock period is an eternity next to the time a flip-flop stays balanced on the knife-edge; the probability that sync1 is still undecided a full cycle later is vanishingly small, and synced almost certainly captures a clean 0 or 1. “Almost certainly” is the honest phrase — two flops do not make metastability impossible, they push its mean-time-between-failures out to centuries, which for a hobby FPGA link is the same as impossible. The cost is two flip-flops and two cycles of latency, and the receiver happily pays it: two cycles is nothing against a bit that is fifty clocks wide.^[1]

Two details reward a second look. The first is that these two registers are clocked on every single cycle — they are not tick-gated. This is the sharpest possible contrast with everything downstream. The state machine, rxStep, freezes between oversample ticks; it is enabled by the tick and does nothing on the roughly two cycles in three when the tick is low. The synchronizer must do the opposite. A metastable event can happen on any clock edge, tick or no tick, because the host’s line does not know or care where Tamal’s oversample cadence sits. So the synchronizer runs free, catching and settling the line continuously, and hands the already-cleaned synced to the tick-gated machine. Free-running guard, gated brain: the two live at different rhythms on purpose.

The second is the initial value, register high and not register 0. The idle UART line sits high, so the synchronizer powers up believing the line is idle. Were it to power up low, the machine’s freshly-primed rxPrev = high would meet a synced = low on the very first tick and read a phantom falling edge — a start bit that never happened, out of a line that was never driven. Seeding both the synchronizer and rxPrev to high makes the receiver’s first belief about the world match the world’s actual resting state: quiet, high, waiting.^[1]

This synchronizer is decision 6 in the UART design, and its rationale is placement: the line is asynchronous because it comes from a pin, so the synchronizer belongs with the receiver, inside uartRx, rather than bolted on by whatever shell wires the pin. The receiver is self-contained and metastability-safe on its own terms; a caller need only hand it the raw pad. It is the one piece of the receiver with no transmitter analogue whatsoever — the transmitter drove the wire, and you do not synchronize a wire you are driving.

Where the receiver differs from the transmitter before a single bit is decoded. The asynchronous rxLine crosses out of no clock domain and into Dom100 (accent), and is caught by two back-to-back flip-flops — sync1 then synced — that are clocked on every cycle, with no enable, so they can settle a metastable strike whenever it lands. Only the already-cleaned synced reaches the mealy rxStep machine, which wears the transmitter's silhouette but is tick-gated: the tick enable (accent) freezes it between oversample ticks. Free-running guard, gated brain — the two run at different rhythms on purpose.

Finding the start bit: an edge, not a level

Now we can read rxStep, and the natural place to start is where the frame starts — the idle arm, where the receiver is watching a quiet line and waiting for a byte to begin. Here is that arm, lifted out of the case:

            RxIdle
              | rxPrev s == high && line == low -> (s0{rxState = RxStart, rxCnt = 0}, (Nothing, False))
              | otherwise -> (s0, (Nothing, False))

The transmitter’s idle arm looked at mbyte and, on a Just b, latched the byte and left for TxStart. It decided when the frame began, because it was the one sending it. The receiver cannot decide; it can only notice. And what it notices is not that the line is low but that the line has just gone low — the guard is rxPrev s == high && line == low, which is true on exactly the tick where the previous sample was high and this one is low. A high-to-low transition. The falling edge that opens every UART frame, because the line idles high and the start bit is the first thing to pull it down.

Why insist on the edge? Why not the far simpler line == low — if the line is low, a start bit must be here, so go? Because “the line is low” is true for reasons that are not the start of a frame, and a receiver that triggered on the level would start decoding garbage out of all of them. Consider a break condition: a host holding the line low for a long stretch, deliberately, as an out-of-band signal. A level-triggered receiver would see low, leap into RxStart, decode a frame of zeros, return to idle, see low again — still the same break — and leap right back in, manufacturing frame after frame out of one long silence. Or consider the ordinary end of a normal frame that happens to carry a low most-significant bit: the line is low right up until the stop bit lifts it. A level trigger has no way to tell “the line is low because a new frame is starting” from “the line is low because it never went back up.” An edge trigger does, and trivially: a new frame requires a fresh high-to-low transition, and a line already held low offers none. There is no new edge, so there is no new frame. Break conditions, stuck lines, and lingering low bits all sail past.^[2]

This is exactly what rxPrev was carried for. To notice a transition you must remember the previous value, and rxPrev is that memory — the synchronized line as it stood at the previous tick, not the previous cycle. (It updates only on ticks, because off a tick the whole rxStep returns s untouched, rxPrev included.) On every idle tick, s0 = s{rxPrev = line} refreshes it, so the comparison always pits last tick’s level against this tick’s. When they differ in the falling direction, the frame is on, and the machine moves to RxStart with rxCnt reset to zero to begin timing the start bit. On the non-edge case it returns s0 — staying idle, but with rxPrev freshly updated, always primed to catch the next fall.

There is one honest imprecision to name, because the design names it too. Start detection is checked once per tick, not continuously. The true falling edge on the wire can occur anywhere within a tick interval, so the tick that first observes line == low can lag the real edge by up to one full tick — up to one sixteenth of a bit. The receiver’s whole sense of “where am I in this bit” is therefore up to a sixteenth of a bit late from the very start. This sounds alarming and is completely harmless, and the reason it is harmless is the subject of the next section: the receiver does not sample at the edge of a bit, where a sixteenth’s slip would matter, but at its center, where there is a full eight ticks of margin on either side to absorb the slip and then some. The lag is real; the center swallows it.^[2]

Why the trigger is an edge and not a level. The receiver fires RxStart only on the tick where rxPrev was high and the synchronized line is low — the single accented falling transition at tick 4. Through ticks 5–10 the line stays low, but there is no new high→low edge, so nothing re-triggers: a break condition, or a frame ending on a low bit, cannot manufacture a phantom start the way a bare line == low test would. Detection is checked once per tick, so it can lag the true edge by under one tick — harmless, because the receiver samples each bit at its center, not here at its edge.

Zoom into one bit: the center and the vote

This is the heart of the receiver, the section the whole post has been walking toward, and it answers a question the transmitter never had to ask: given a bit that is sixteen oversample ticks wide, where in those sixteen ticks do you actually look, and how many times? The transmitter’s answer was trivial — it held the level for all sixteen and never looked at all. The receiver’s answer is the one interesting design decision in the module, and it is worth deriving slowly.

Start with the window. Within any bit the receiver counts rxCnt :: Index 16, running 0..15, one step per oversample tick — sixteen positions tiling one bit-time. The transmitter used the same counter to hold a level for sixteen ticks; the receiver uses it to locate itself within a bit it is reading. And of those sixteen positions, the receiver reads the line at exactly three of them — counts 7, 8, and 9 — stashing each reading into its own field:

captureSample :: RxS -> Bit -> RxS
captureSample s bit' = case rxCnt s of
  7 -> s{rxS7 = bit'}
  8 -> s{rxS8 = bit'}
  9 -> s{rxS9 = bit'}
  _ -> s -- actually unreachable

At count 7 the current line goes into rxS7, at 8 into rxS8, at 9 into rxS9, and at every other count — the twelve counts we are not sampling — the function returns s unchanged, a deliberate no-op. Three flip-flops filled once each per bit, at three adjacent positions near the middle of the window. Everything interesting about the receiver’s robustness is in the choice of those three positions, so let us take the choice apart in three questions.

Why the center at all?

Because the center of the bit is the one place on the waveform that is furthest from trouble, and the trouble is at the edges. A bit is bounded by two transitions — the moment the line moves from the previous bit’s level to this one’s, and the moment it moves on to the next. Right at those transitions the line is in flight: slewing between levels, ringing, not yet settled, and — because of everything in the last two sections — possibly a fraction of a tick misaligned from where the receiver thinks the bit boundary is. Sample there and you are reading a value that is changing. Sample at the center, count 8 of 16, and you are as far from both transitions as it is possible to be — eight ticks of clear air on each side — where the line has long since settled to its true level and will sit there untouched until the next boundary.

And here the two halves of the UART clasp hands. Recall the single most important property of the transmitter: its line was a Moore output, a pure function of state, dead-steady for the entire sixteen-tick bit because nothing but a state change could move it and the state changed only at boundaries. The transmitter went to the trouble of making its wire rock-solid across the whole cell precisely so that a receiver sampling the middle would land on solid ground. The receiver is the other end of that bargain: it samples the center because the transmitter guaranteed the center is flat. Center sampling and Moore outputs are one design decision made twice, once at each end. The center is also where the receiver’s own small errors go to be forgiven: the sub-tick start-detection lag from the last section, and any slow baud-rate mismatch that accumulates across a frame, both push the sample point away from the true center — but they have to push it a full eight ticks before it reaches an edge, and neither is remotely that large over one frame. The center is a generous target.

Why three samples and not one?

A single center sample is the classic minimal UART, and it works right up until it doesn’t. One sample means zero noise immunity: a single glitch on the line at the one instant you look — a coupled spike, a runt from imperfect signal integrity, one unlucky sample of a marginal level — and the bit is simply wrong, with nothing to catch it. You looked once, you saw the wrong thing, you believed it.

Three samples, resolved by a majority vote, tolerate exactly one such corruption. If two of the three readings agree — and in a clean signal all three agree, since they sit within two ticks of each other on a flat level — then a single glitched sample is outvoted two-to-one and the bit comes out right anyway. This is, in the design doc’s blunt phrase, the actual point of 16× oversampling. You do not oversample sixteen times in order to sample sixteen times; you oversample so that you can afford to take several readings clustered at the center and let them check each other. Majority-of-three is the smallest arrangement that buys any noise immunity at all, and it turns “one bad sample ruins the byte” into “one bad sample is shrugged off.” The tests prove exactly this, as we will see: they flip a single center sample and demand the byte still decode.

Why 7, 8, and 9 — why not others, why not more?

This is the precise question, and it has a precise answer with four parts.

Odd, so the vote cannot tie. A majority vote needs an odd number of voters or it can deadlock — two against two decides nothing. Three is odd; the vote maj always has a strict winner. Four samples would reintroduce the possibility of a tie and force some tie-break rule, which is complexity bought for nothing.

Three, because it is the smallest odd number greater than one. One sample gives no immunity, as we just saw. Three is the next odd count up, and it already tolerates a single fault — the common case, a lone glitch. Five would tolerate two simultaneous faults, but two independent glitches landing inside the same three-tick-wide center window of the same bit is a scenario a 2 Mbaud hobby link never sees, and you would pay for the guard against it in every bit forever. Three is the sweet spot: the cheapest count that does anything.^[3]

Tight around the center, so drift can never push a sample onto an edge. The three samples sit at 7, 8, 9 — adjacent, packed into the middle three ticks of the sixteen. This matters. Suppose instead you spread the three readings out — say counts 4, 8, 12 — reasoning that a wider spread somehow samples “more” of the bit. It does the opposite of what you want: counts 4 and 12 are only four ticks from their respective transitions, so the moment the receiver’s alignment drifts by even a few ticks — start lag plus a little baud mismatch — one of those outer samples wanders onto a bit edge and reads a value in flight, corrupting the very vote that was supposed to protect you. Keeping all three within two ticks of the center keeps all three deep in the flat region under every realistic drift. The spread is not a feature; it is a liability. Tight is correct.

Cheap, because it is three flip-flops and a three-term boolean. The whole apparatus is rxS7, rxS8, rxS9 — three single-bit registers — and the maj function, which is two ANDs-of-two ORed… three ANDs and an OR, a handful of gates. More samples would mean more capture registers and a wider voting function for a robustness gain the link cannot use. The design spends exactly what buys the one property that matters and not a gate more.

One honest note on symmetry, because it is easy to overclaim. In a 0..15 window the exact geometric center is 7.5 — there is no integer count at the center, because sixteen is even. The design nominates count 8 as the working “center” and brackets it with its two neighbours, 7 and 9. So the three samples are symmetric about count 8, but sit very slightly forward of the true midpoint 7.5: count 7 is half a tick before it, count 8 half a tick after, count 9 a tick and a half after. Half a tick of asymmetry in a window with eight ticks of margin to either edge is nothing — but it is there, and it is more accurate to say “count 8 and its neighbours” than to pretend the three straddle 7.5 evenly. They do not; they cluster just past it.

That leaves the _ -> s arm of captureSample — the no-op at all twelve non-sampled counts — and its comment, -- actually unreachable. It is reached constantly in the ordinary sense: on every tick that is not a 7, 8, or 9, captureSample runs and does nothing. The “unreachable” is subtler and is the same totality point the transmitter post made about TxIdle -> s: the case must cover every Index 16 value or GHC’s exhaustiveness warning fires, so the catch-all is there to satisfy the compiler that the function is total. Whether any particular count ever flows through it is a runtime matter the type cannot see; the wildcard makes the function honest for all sixteen regardless.^[4]

One bit, its sixteen oversample ticks, and the three the receiver actually reads. The geometric center is 7.5 (sixteen is even, so no count sits exactly on it); the design nominates count 8 and brackets it with 7 and 9 — the accent band. Those three samples sit about eight ticks from both edge transitions, the maximum possible margin, where the transmitter's Moore-driven line is guaranteed flat, and where the sub-tick start-detection lag is comfortably absorbed. Why these three and no others: odd so the vote cannot tie, three because it is the smallest odd count that tolerates a glitch, tight around the center so drift never pushes a sample onto an edge, and cheap — three flip-flops and a boolean. The three feed maj, which returns the bit the majority saw.

The majority vote

The vote itself is one line, and it is pure combinational logic — no clock, no state, the CRC’s world briefly revisited inside the receiver:

maj :: Bit -> Bit -> Bit -> Bit
maj a b c = (a .&. b) .|. (a .&. c) .|. (b .&. c)

Read it as gates. .&. is bitwise AND, .|. is bitwise OR, and on three single Bits the expression is (a AND b) OR (a AND c) OR (b AND c) — high if and only if at least two of the three inputs are high. Every pair gets its own AND; if any pair is both-high, the OR fires. It is the textbook majority function, and it does exactly what the last section promised: it returns the value that at least two of the three samples agreed on, so a lone dissenter — a single glitched sample — is outvoted.

Trace the one case that matters, a clean bit corrupted by a single glitch. Say the true bit is high, so in a clean signal s7 = s8 = s9 = 1, and maj 1 1 1 = (1 AND 1) OR ... = 1 — correct. Now let one sample be glitched low, say s8: the inputs are 1 0 1, and maj 1 0 1 = (1 AND 0) OR (1 AND 1) OR (0 AND 1) = 0 OR 1 OR 0 = 1 — still correct. The pair s7 AND s9 carried the day. The same holds whichever single sample flips, and whichever way the true bit points: two good samples always contain a both-agreeing pair, and that pair drives the OR. Only a second simultaneous corruption — two of the three flipped — could swing the vote, and that is precisely the fault the design declined to guard against because the link never produces it. One glitch in, correct bit out. That property has a name in the test suite, and we will watch Hedgehog flip a sample and demand the byte survive.

In decideBit, the vote is computed once, in a where clause, and every arm reads its result:

  bit' = maj (rxS7 s) (rxS8 s) (rxS9 s)

bit' is the recovered bit for this cell — whatever the majority of the three center samples saw — and it is what the rest of decideBit acts on. Whether the cell was a start bit, a data bit, or a stop bit, the reading is the same: three samples near the center, one majority vote, one bit. The design doc calls this reusing one sampling primitive at every bit center, and it is why the code has a single maj and a single trio of sample fields rather than special-case logic per phase. The vote does not care what kind of bit it is deciding; it just decides.

The vote (s7·s8) + (s7·s9) + (s8·s9) as gates: each pair of samples meets in a two-input AND, and the three ANDs meet in one OR, so the output is high exactly when at least two of the three inputs are. The point is fault tolerance: a clean high bit reads 1 1 1 and votes 1; a single glitch flipping one sample to 0 1 1 still votes 1, because the surviving pair s8·s9 holds. Only two simultaneous corruptions could swing it — the fault the link never produces. This is the whole return on sampling three times instead of once.

`decideBit`: confirm, assemble, test

decideBit is called once per bit, at the tick that resolves the window, with the three samples already in hand. It is where the voted bit' becomes a decision, and it reads as a case over the phase — one arm each for start, data, and stop, plus the obligatory unreachable idle:

decideBit :: RxS -> (RxS, (Maybe (BitVector 8), Bool))
decideBit s = case rxState s of
  RxStart
    | bit' == low -> (s{rxState = RxData 0, rxCnt = 0}, (Nothing, False))
    | otherwise -> (s{rxState = RxIdle, rxCnt = 0}, (Nothing, False))
  RxData i ->
    let sh =
          if bit' == high
            then setBit (rxShift s) (fromEnum i)
            else clearBit (rxShift s) (fromEnum i)
        s' = s{rxShift = sh, rxCnt = 0}
     in if i == maxBound
          then (s'{rxState = RxStop}, (Nothing, False))
          else (s'{rxState = RxData (i + 1)}, (Nothing, False))
  RxStop
    | bit' == high -> (s{rxState = RxIdle, rxCnt = 0}, (Just (rxShift s), False))
    | otherwise -> (s{rxState = RxIdle, rxCnt = 0}, (Nothing, True))
  RxIdle -> (s, (Nothing, False)) -- actually unreachable
 where
  bit' = maj (rxS7 s) (rxS8 s) (rxS9 s)

Read the three live arms in order; each is one job the transmitter never had.

RxStart confirms or abandons. The receiver reached RxStart because it saw a falling edge and believed a start bit had begun. Now, at the center of that supposed start bit, it checks: is the voted bit' still low? If so, the low level held across the center of the bit — a real start bit, not a momentary dip — and the machine commits to the frame, moving to RxData 0 to read the first data bit. If instead bit' came back high, then the thing that pulled the line down was not a start bit at all — a glitch, a runt, a noise spike that tripped the edge detector — and the machine abandons it, returning to RxIdle to wait for a real edge. This is glitch rejection at the frame level, a second line of defence behind the majority vote: the edge detector is deliberately twitchy (it must catch every real start), so the start bit is confirmed half a bit later before any data is believed. The transmitter never needed this because it never doubted its own start bit; the receiver doubts everything until the center agrees.

RxData i assembles the byte. Here is the one genuinely pretty inversion of the transmitter, so it is worth slowing down. The transmitter serialised a byte out of a shift register: it held the byte in txShift, read lsb (txShift s) onto the wire, and shiftR-ed the register at each boundary so the next bit fell into the bottom position — the byte walked out the bottom, LSB first. The receiver does the mirror image, assembling a byte in — but notice it does not shift at all:

    let sh =
          if bit' == high
            then setBit (rxShift s) (fromEnum i)
            else clearBit (rxShift s) (fromEnum i)

Instead of sliding the register and always writing the bottom, the receiver writes bit number i directly — setBit to make position i high, clearBit to make it low, with fromEnum i turning the Index 8 into the plain Int position that setBit/clearBit want. At RxData 0 it writes bit 0; at RxData 7, bit 7; so bit i of the recovered rxShift is exactly the i-th data bit received, LSB first, matching the transmitter’s convention wire for wire. Where the transmitter moved the byte past a fixed read point, the receiver holds the byte still and addresses it by index. Both are LSB-first, both walk bit 0 through bit 7, but one slides and the other indexes — the same byte, the opposite direction, and the CRC and transmitter shift-register motif seen a third time, now assembling rather than emitting.^[5] After writing, if i == maxBound — bit 7, the last one, the Index 8 guaranteeing there is no bit 8 — the machine goes to RxStop; otherwise it advances to RxData (i + 1) for the next data bit. Either way rxCnt resets to begin a fresh sixteen-tick window.

RxStop delivers the verdict. At the center of the stop bit the receiver votes one last time, and this vote decides whether the whole frame was well-formed:

  RxStop
    | bit' == high -> (s{rxState = RxIdle, rxCnt = 0}, (Just (rxShift s), False))
    | otherwise -> (s{rxState = RxIdle, rxCnt = 0}, (Nothing, True))

A UART stop bit is defined to be high; the line must return to its idle level to frame the byte. So if bit' is high, the frame closed cleanly: the machine emits Just (rxShift s) — the fully assembled byte, handed up as the one-cycle strobe — with the error flag False, and returns to idle. But if bit' is low, the stop bit was missing: the line was still low where it should have lifted, which means the framing was wrong — mismatched baud, a line fault, a spurious mid-noise “frame.” The receiver refuses to hand up a byte it cannot trust. It emits (Nothing, True): no byte, framing error raised. The assembled rxShift is simply dropped, never delivered. This is the framing-error path, the third output the transmitter had no counterpart for, and it too has made a test. Both stop arms return to RxIdle, because whether the frame was good or bad, it is over.

That leaves RxIdle -> (s, (Nothing, False)), the fourth arm, tagged -- actually unreachable. As in captureSample, and as in the transmitter’s txAdvance, it exists to make the case total: GHC insists every RxState constructor be handled, so the idle arm is written even though decideBit is only ever called from a resolving tick, and idle never resolves. Returning s unchanged with no output is the honest do-nothing that keeps the function total and the compiler quiet.^[4]

The outputs are genuinely Mealy

Now for the sharpest contrast with the transmitter, and a direct callback to the longest argument in that post. The transmitter spent pages establishing that although it was lifted with the general mealy combinator, its outputs were pure Moore — line and ready were functions of the state alone, no input in sight, so the wire sat dead-steady between boundaries. We drew a whole figure of it: the Moore machine whose output reads only the state, next to the Mealy machine with an accent tap carrying the input up into the output. The transmitter, we concluded, had no such tap. Its handshake bought a same-cycle transition, but never a same-cycle output.

The receiver has the tap. Its outputs are genuinely Mealy, and you can see it in the first line of rxStep:

rxStep s (tick, line)
  | not tick = (s, (Nothing, False)) -- only move on oversample ticks
  | otherwise = ...

Read what that guard says about the output, not the state. On any cycle where tick is low — most cycles — rxStep returns the output (Nothing, False) regardless of what state s holds. On a cycle where tick is high and the state happens to be a resolving RxStop, the same machine can return (Just byte, False). So take a single fixed state — say s with rxState = RxStop and rxCnt = 9 and a winning vote — and ask what the output is. On a non-tick cycle it is (Nothing, False); on a tick cycle it is (Just byte, False). Same state, different output, and the thing that differs is the input tick. The output reads an input. That is the definition of a Mealy output, and it is exactly the accent tap the transmitter’s figure showed and the transmitter’s code lacked.

It is worth being as careful here as the transmitter post was, because the distinction is easy to fumble. The Mealy-ness is not that the next state depends on the input — that is true of every state machine, Moore included, and says nothing. The Mealy-ness is that the output depends on the input: the byte-ready and framing-error strobes are functions of tick (and, at the resolving stop tick, of the freshly-sampled line folded into the vote), not of the state alone. By the one test that separates the two machine styles — does the input reach the output within the cycle? — the transmitter’s outputs are Moore and the receiver’s are Mealy. The mealy combinator lifted both; only the receiver actually uses the generality it offers.

And this is not an accident of implementation but a difference in the nature of the two interfaces, which is the satisfying part. The transmitter’s outputs are levels: line is a level the receiver will sample, ready is a level the caller will poll, and a level wants to be Moore — steady, glitch-free, held for as long as the state holds. Levels and Moore go together. The receiver’s outputs are events: “a byte just completed,” “a frame just failed,” each true for one cycle and then gone. An event is a strobe, and a strobe is inherently Mealy — it fires in response to a condition (this tick, this resolution) and must be low every other cycle no matter what the state is. Events and Mealy go together. The transmitter drove levels, so it was Moore; the receiver raises events, so it is Mealy. The two machines wear the two halves of the Moore/Mealy distinction the way they wear the two halves of drive/read — one at each end, by the nature of the job.^[6]

One consequence to nail down, because an integrator will care: the strobes are exactly one cycle wide. Just byte appears on precisely the single cycle where tick is high and RxStop resolves at count 9, and on the very next cycle — tick or not — the machine is in RxIdle and the output is (Nothing, False) again. There is no holding, no latching, no “byte valid until you read it.” A consumer of rxByte must catch the strobe on the cycle it fires. That is the mirror of the transmitter’s rule that a caller must present Just b while ready is high — both are one-cycle contracts — and both fall straight out of the machines being built from a tick-gated mealy with no output register tacked on.

Resolving the stop bit early

There is one asymmetry in rxStep that is easy to skate past and worth a paragraph, because it is a real design decision with a real reason. Start bits and data bits are resolved at the end of their window — at rxCnt == maxBound, count 15, the sixteenth tick — but the stop bit is resolved early, at count 9, six ticks before the window would close. The two dispatch arms make the difference plain:

            RxStop ->
              let s1 = captureSample s0 line
               in if rxCnt s == 9
                    then decideBit s1
                    else (s1{rxCnt = rxCnt s + 1}, (Nothing, False))
            _ ->
              -- RxStart / RxData
              let s1 = captureSample s0 line
               in if rxCnt s == maxBound
                    then decideBit s1
                    else (s1{rxCnt = rxCnt s + 1}, (Nothing, False))

The _ arm — start and data — resolves at maxBound; the RxStop arm resolves at 9. Why not let the stop bit run out its full sixteen ticks like every other bit? Because by count 9 the receiver already has everything it needs. Its three samples were taken at 7, 8, and 9; the moment rxS9 is captured, the vote can be computed and the frame closed. Waiting out counts 10 through 15 would decide nothing new — it would just sit on a stop bit it has already read. And those six idle ticks are worth more spent elsewhere. The code comment lays out the reasoning in full:

              -- Resolve the stop bit at its center sample (count 9) rather than
              -- waiting out the whole window: returning to idle ~6 ticks early
              -- gives the falling-edge detector idle-high ticks to arm rxPrev,
              -- so a back-to-back next frame (stop immediately followed by start)
              -- still resyncs.

Think about the worst case for start detection: back-to-back frames, where a sender transmits one byte’s stop bit and immediately drives the next byte’s start bit, with no idle gap between. The stop bit is high, the next start bit is low, so there is a clean high-to-low edge right at the boundary — but the receiver can only catch that edge if it is back in RxIdle, watching, with rxPrev already primed to high, by the time the edge arrives. If the receiver were still grinding through counts 10–15 of the stop bit when the next start edge fell, it would be in the wrong state to notice, and the next frame would be missed or misaligned. Resolving at count 9 returns the machine to RxIdle roughly six ticks before the stop bit even ends, and those six ticks are high (it is a stop bit, after all), so they land on rxPrev as idle-high observations, arming the edge detector. By the time the next frame’s falling edge arrives, the receiver is idle, primed, and ready to catch it. Early resolution is not an optimisation for its own sake; it is what makes the receiver survive a sender that does not pause between bytes — and the tests lean on it, feeding lists of bytes through the loopback with no idle padding and demanding every one come back.

The whole `rxStep`, assembled

We have read rxStep in pieces — the freeze, the idle edge-detect, the early stop resolution, the general start/data resolution. Here it is whole, the transition function mealy clocks, and now every line should land:

rxStep :: RxS -> (Bool, Bit) -> (RxS, (Maybe (BitVector 8), Bool))
rxStep s (tick, line)
  | not tick = (s, (Nothing, False)) -- only move on oversample ticks
  | otherwise =
      let s0 = s{rxPrev = line} -- remember this tick's level for next tick
       in case rxState s of
            RxIdle
              | rxPrev s == high && line == low -> (s0{rxState = RxStart, rxCnt = 0}, (Nothing, False))
              | otherwise -> (s0, (Nothing, False))
            RxStop ->
              let s1 = captureSample s0 line
               in if rxCnt s == 9
                    then decideBit s1
                    else (s1{rxCnt = rxCnt s + 1}, (Nothing, False))
            _ ->
              let s1 = captureSample s0 line
               in if rxCnt s == maxBound
                    then decideBit s1
                    else (s1{rxCnt = rxCnt s + 1}, (Nothing, False))

Its type is RxS -> (Bool, Bit) -> (RxS, (Maybe (BitVector 8), Bool)) — the primer’s s -> i -> (s, o) exactly, with the receiver’s state, the receiver’s (tick, line) input, and the receiver’s (byte, error) output. Like txStep, it splits into two clean halves, though the seam runs differently.

The first half is the same freeze the transmitter had: | not tick = (s, (Nothing, False)). Off a tick — most cycles — the state is returned untouched and the output is the quiet (Nothing, False). The receiver does nothing between ticks, exactly as the transmitter did nothing; the enable gates both. (This is also, as the last section argued, where the Mealy output lives: the output is forced quiet here by the input.)

The second half, on a tick, is the receiver’s own. First s0 = s{rxPrev = line} records this tick’s line so the next tick can detect an edge against it — the one piece of bookkeeping every tick does regardless of phase. Then a three-way dispatch on the phase, and this is where the transmitter and receiver finally diverge in shape rather than just in verb. RxIdle does not count or sample at all — it only watches for the falling edge, firing RxStart on a high-to-low transition and otherwise sitting idle with rxPrev refreshed. RxStop captures its sample and resolves early at count 9. The catch-all _ — start and data — captures its sample and resolves at the window’s end, count 15. Idle hunts; stop resolves early; start and data resolve late. Three rhythms, one per kind of bit, where the transmitter had marched every phase to the identical sixteen-tick drum. The receiver has to be more supple because it is chasing a frame it did not schedule, and the suppleness is all right here, in the seams of one case.

The tests

The receiver shares Test/Uart.hs with the rest of the UART, and because it is sequential the tests drive it through Clash simulation — sampleN, bundle, fromList — rather than the pure-function style. Four of the properties are the receiver’s own, and they are the four places the design made a promise specific enough to break: it decodes a clean frame, it flags a bad one, it shrugs off a single glitch, and it samples the center and not the edge. Read them and you have read the receiver’s contract as executable claims.

They all run through one small harness, so it is worth meeting it first:

bitAt :: BitVector 8 -> Int -> Bit
bitAt b i = if testBit b i then high else low

frame :: BitVector 8 -> Bit -> [Bit]
frame b stop =
  L.replicate 16 low
    <> L.concatMap (\i -> L.replicate 16 (bitAt b i)) [0 .. 7]
    <> L.replicate 16 stop

runRx :: [Bit] -> [(Maybe (BitVector 8), Bool)]
runRx samples =
  sampleN
    (8 + L.length samples + 24)
    (bundle (uartRx (pure True) lineSig) :: Signal Dom100 (Maybe (BitVector 8), Bool))
 where
  lineSig = fromList (L.replicate 8 high <> samples <> L.repeat high)

recovered :: [(Maybe (BitVector 8), Bool)] -> [BitVector 8]
recovered xs = [b | (Just b, _) <- xs]

anyErr :: [(Maybe (BitVector 8), Bool)] -> Bool
anyErr xs = L.or [e | (_, e) <- xs]

frame b stop hand-builds the oversampled line for a byte: sixteen low samples for the start bit, then for each i from 0 to 7 sixteen copies of that byte’s i-th bit (bitAt, LSB-first — the same convention the transmitter drives and decideBit assembles), then sixteen copies of whatever stop level you pass. Sixteen samples a bit because that is the oversampling; a whole 8N1 frame is 160 samples. runRx is the driver: it sets tick = pure True so every cycle is an oversample tick — sixteen cycles to a bit, the fast cadence, no NCO needed here — prepends eight idle-high samples (giving the two-flop synchronizer time to fill and rxPrev time to arm high before any edge), pads the tail with an infinite idle-high L.repeat high, and samples the bundled (byte, error) output for enough cycles to see the frame through. recovered sifts the Just strobes out of the output stream into a list of bytes; anyErr ORs the error strobes. With that vocabulary the four properties are one or two lines each.

The same byte the transmitter sent — ASCII 'K', 0x4B = 0b0100_1011 — now arriving at the receiver. The frame is idle-high, one accent start bit, the eight data bits LSB-first (1 1 0 1 0 0 1 0), one high stop bit, then idle. Each accent dot marks a cell center, where the receiver's three samples (counts 7/8/9) are majority-voted into that cell's bit; decideBit writes each into rxShift by index and, on the stop bit's high vote, strobes out Just 0x4B. This is the transmitter's waveform figure read from the sampling end.

The first property is the whole receiver in four lines: build a clean frame for a random byte, run it in, get the byte back:

testProperty "RX decodes a clean 8N1 frame" $ property $ do
  b <- forAll genByte
  let out = runRx (frame b high)
  recovered out === [b]
  anyErr out === False

Hedgehog draws a random byte b, frame b high renders it as a clean 160-sample line with a proper high stop bit, and the assertions are exactly the contract: recovered out === [b] — one byte came back, and it was b, bit-for-bit — and anyErr out === False — no framing error along the way. Every claim we have made about the receiver has to hold at once for this to pass: the synchronizer has to pass the line through, the edge detector has to catch the start, the center sampling has to land in each cell, the vote has to read each bit, decideBit has to assemble them LSB-first, and the stop bit has to close the frame and strobe the byte out. It is the counterpart of the transmitter’s waveform test, run in the opposite direction, and it is the floor the other three build on.

The second flips the stop bit and demands the failure:

testProperty "RX flags a framing error on a low stop bit" $ property $ do
  b <- forAll genByte
  let out = runRx (frame b low)
  recovered out === []
  anyErr out === True

The only change is frame b low — the same start and data bits, but the stop bit driven low instead of high, a malformed frame. Now the assertions invert: recovered out === [] — no byte comes back, the assembled rxShift is dropped and never strobed — and anyErr out === True — the framing-error flag fired. This is the RxStop arm’s low branch, (Nothing, True), made into a property. The receiver does not quietly hand up a byte from a frame that did not close; it raises the flag and swallows the byte, and the test pins both halves of that behaviour. The framing-error path the transmitter had no counterpart for is not dead code — it has a test that fails if it ever stops working.

The third is the majority vote made honest. It corrupts exactly one sample — at a bit center — and demands the byte decode anyway:

testProperty "RX majority vote rejects a single glitch" $ property $ do
  b <- forAll genByte
  let out = runRx (flipAt (16 + 3 * 16 + 8) (frame b high))
  recovered out === [b]

The instrument is flipAt, which inverts the single sample at one index:

flipAt :: Int -> [Bit] -> [Bit]
flipAt k xs = [if j == k then complement x else x | (j, x) <- L.zip ([0 ..] :: [Int]) xs]

Everything is in the index, 16 + 3 * 16 + 8, so read it as the test author wrote it. The 16 skips the start bit’s sixteen samples. The 3 * 16 skips three whole data bits — bit 0, bit 1, bit 2. That lands us at the start of data bit 3’s window, and the + 8 steps eight samples into it — to offset 8, the dead center of the cell, where rxCnt reaches 8, the middle of the three voted samples. So flipAt (16 + 3*16 + 8) reaches into data bit 3 and flips one of the three samples the vote will read — s8, the center one. The other two, s7 and s9 at offsets 7 and 9, still carry the true value.

And that is exactly the situation the majority vote was built for. Two of the three samples of data bit 3 are correct, one is flipped; maj returns what the two agree on; bit 3 decodes correctly despite the glitch; and the whole byte comes back — recovered out === [b], with no weakened assertion, no allowance for the corruption. The test does not check “the byte is mostly right”; it checks the byte is exactly right, because the vote makes the single glitch vanish. It is also, quietly, the argument for three samples over one: had the receiver sampled the center only once, this very flip would have hit that one sample and corrupted bit 3, and the byte would have come back wrong. The test would fail against a single-sample design and passes against this one. That is decision 5 of the design — majority-of-three rejecting a glitch — locked in silicon-shaped amber.

The fourth is the cleverest, and it guards the one property the first three cannot see. Every frame the earlier tests built used constant cells — sixteen identical samples per bit — so a receiver that sampled the leading edge of each cell, or the trailing edge, or the center, would decode them all identically. Those tests cannot tell center sampling from edge sampling, because on a constant cell there is nothing to tell. This one builds a cell that is not constant:

centerCell :: Bit -> [Bit]
centerCell v = [if 6 <= j && j <= 10 then v else complement v | j <- [0 .. 15 :: Int]]

centerFrame :: BitVector 8 -> [Bit]
centerFrame b =
  L.replicate 16 low
    <> L.concatMap (centerCell . bitAt b) [0 .. 7]
    <> L.replicate 16 high

centerCell v carries the true value v only in its center — offsets 6 through 10 — and the complement of v everywhere else, at the edges. centerFrame frames a byte out of these poisoned cells. Now sampling position is everything: a receiver that reads the center (offsets 6–10, which is where counts 7, 8, 9 land) recovers v; a receiver that reads a cell boundary — say because its rxCnt were initialised half a bit early, so it sampled near offset 0 or 15 — recovers complement v, the exact opposite byte. The test demands the center reading:

testProperty "RX samples the bit center, not the edge" $ property $ do
  b <- forAll genByte
  let out = runRx (centerFrame b)
  recovered out === [b]
  anyErr out === False

recovered out === [b] — the true byte, not its complement — and no error. This is a regression guard, and a sharp one: it pins the whole center-sampling design against a plausible mistake. If someone “simplified” the alignment and started sampling near a bit boundary, every earlier test would still pass — constant cells don’t care — but this one would fail, recovering the complement of every byte. The test comment says exactly this: a half-bit-early rxCnt init recovers the complement and fails here, while the constant-cell tests above cannot tell center from edge. It is the property that makes “sample the center” a checked invariant rather than a comment, and it is the reason Figure C’s whole argument — center, not edge — is load-bearing rather than decorative.

The trap the centerFrame test sets. Each data cell (here a true bit of 1) carries its real value only in the center band, offsets 6–10, and the complement at both edges. The receiver's three samples (counts 7/8/9, accent) land squarely in the true band and read 1, so the byte decodes. A receiver that sampled near a boundary — the hollow marker, where a half-bit-early rxCnt would land — would read 0, the complement, and recover the opposite byte. Constant-cell tests cannot see this difference; this one can, which is why it pins center sampling as a checked invariant.

The keystone closes

The remaining three properties are not the receiver’s alone — they are the whole UART’s, and the transmitter post met them from its side. Read now from the receiver’s end, they are the moment the series’ long promise pays off. The baud generator closed by saying its one blunt tick-rate test was only half a keystone, and that we would meet the other half “when the receiver is built.” The receiver is built. Here is the other half.

The fast loopback wires the transmitter’s line straight into the receiver’s, sharing one tick:

fastLoop txByte = rxByte
 where
  tick = pure True
  (txLine, _txReady) = uartTx tick txByte
  (rxByte, _rxErr) = uartRx tick txLine

uartTx’s output line is uartRx’s input line — no wire, no model, no golden waveform in between, just the two halves of the UART bolted face to face. Feed a byte to the transmitter and ask the receiver what it got:

testProperty "TX->RX fast loopback recovers the byte" $ property $ do
  b <- forAll genByte
  let out = runFastLoop [Nothing, Just b] 400
  [b' | Just b' <- out] === [b]

The byte comes back, bit-for-bit. This is the test that would catch any disagreement between the two halves that a one-sided test could miss: an LSB/MSB slip, an off-by-one on the stop bit, a sampling point a tick too early. The transmitter serialises out of a right-shifting register LSB-first; the receiver assembles by indexed writes LSB-first; and the only way the byte survives the round trip is if those two conventions agree exactly. They check each other, with no third party to be wrong.

The second is the transmitter’s handshake, seen from the receiving end. The caller jams Just b at the transmitter a hundred cycles running, and the receiver counts the result:

testProperty "TX ignores input while busy (ready gating)" $ property $ do
  b <- forAll genByte
  let out = runFastLoop (Nothing : L.replicate 100 (Just b)) 400
  [b' | Just b' <- out] === [b]

Exactly one byte comes out of the receiver, not a hundred and not a garbled smear of restarted frames. From the transmitter’s side this was “a Just presented mid-transmission is ignored”; from the receiver’s side it is “I got precisely one clean frame.” The receiver is the witness that the transmitter’s no-corruption property actually holds on the wire.

The third swaps the always-true tick for the real thing:

fullLoop txByte = rxByte
 where
  (rxByte, _err, txLine, _rdy) = uart (SNat @2_000_000) rxLine txByte
  rxLine = txLine

testProperty "full UART loopback (real NCO) recovers the byte" $ property $ do
  b <- forAll genByte
  let out = runFullLoop (Nothing : L.replicate 60 (Just b)) 1200
  [b' | Just b' <- out] === [b]

fullLoop calls the umbrella uart (SNat @2_000_000) — baud generator, transmitter, and receiver all wired together — and loops the transmitter’s line back to the receiver’s. Now a bit is not sixteen cycles but fifty, tiled by sixteen NCO ticks whose gaps alternate three and four clocks, averaging the fractional 3.125 the baud generator fought so hard to keep honest. And the byte still comes back. That single passing assertion is the entire UART’s keystone: the fractional-3.125 tick spacing, the transmitter’s Moore-steady sixteen-tick bits, the synchronizer, the falling-edge start detection, the center sampling, the majority vote, the early stop resolution — every one of them has to be right at once, because the byte is recovered only if the tick lands sixteen times per bit, the transmitter holds each level flat, and the receiver samples each center. The baud generator’s lone tick-rate test measured the heartbeat; this test spends it, end to end, and gets the byte back. The keystone the baud generator opened, and the transmitter began to close, is closed here: the heartbeat carries a byte across, TX line to RX line, and it arrives whole.

What we read

Thirty-odd lines, one exported name, and the transmitter turned inside out. The skeleton was the transmitter’s — the same four-constructor RxState, the same record carried tick to tick, the same Index 16 counting sixteen ticks a bit, the same mealy at the top, the same freeze-off-tick cadence, the same LSB-first byte — so we read all of that fast, in a mirror. The post’s words went where the mirror breaks. The line is an input now, asynchronous from a pin, so a 2-flop synchronizer clocked every cycle catches it before the tick-gated logic dares look — the one part of the receiver with no transmitter analogue, because you do not synchronize a wire you drive. The start bit is hunted by its falling edge, tracked through rxPrev, so a line merely held low can never fake a frame. Each bit is decided at its center by a three-sample majority vote on counts 7, 8, 9 — odd so it cannot tie, three because that is the cheapest count that survives a glitch, tight around the center so drift never strays onto an edge, and cheap enough to be three flip-flops and a boolean — which is the actual point of oversampling sixteen times. A low stop bit raises a framing error and drops the byte. The stop bit resolves early, at count 9, so back-to-back frames resync. And the outputs are genuinely Mealy strobes — one-cycle events that read the tick input — where the transmitter’s were steady Moore levels, because levels want Moore and events want Mealy, one machine at each end.

The transmitter taught us the silhouette — find the mealy, find the step function, split it into outputs and next state, decide Moore or Mealy by whether the output reads the input. The receiver wears that silhouette and fills in the half the transmitter left blank: the input side of a UART, where you do not own the wire and must recover what someone else put on it. Between the two of them the byte-exact loopback finally closes — the heartbeat the baud generator started now carries a byte from one end to the other and back, with the real fractional tick, the two halves checking each other with no reference model in sight.

Which is the whole UART, and it is behind us. What waited on the far side of the transport — the thing the transport exists to serve — is the Engine: the stateful difficulty spike the design kept deferring, the eSPI machine the CRC was a limb of and the introduction promised. It has the same silhouette we have now read four times — a mealy, a pure step, a sum for the phase and a record for the rest — but it is bigger than a frame, and it is where the project has been heading all along. The link is up; next we start sending it something worth carrying.

Metastability is the failure a synchronous flip-flop suffers when its data input violates the setup/hold window — the small interval around the clock edge during which the input must be stable. A signal that changes inside that window can leave the flop’s output balanced between 0 and 1, at an invalid intermediate voltage, for an unbounded time before it resolves randomly to one rail or the other. It is not a bug you can code around; it is physics, the metastable point of a bistable element being a genuine (if unstable) equilibrium. You cannot prevent an asynchronous input from occasionally hitting the window — the RX line comes from a host whose clock bears no relation to Dom100, so eventually a line edge coincides with a Tamal clock edge — so instead you contain it: sample into sync1, then give it a whole clock period, untouched, to fall off the knife-edge before synced reads it. The governing figure of merit is mean time between failures, which grows roughly exponentially with the settling time you allow; one extra flip-flop turns an MTBF of seconds into one of centuries. Two flops is the industry-standard minimum for a slow-ish single-bit crossing like a UART line, which is exactly what register high rxLine twice provides. The high initial value is not about metastability but about belief: the idle line is high, so the synchronizer and rxPrev both power up assuming the world was quiet, which stops a phantom start edge on the first tick. Multi-bit crossings (a whole byte at once) need more than a 2-flop synchronizer — gray coding, or a handshake, or an asynchronous FIFO — which is one more reason the design kept the UART in a single clock domain and paid the synchronizer only on the one genuinely asynchronous bit, the incoming line. ↩ ↩2 ↩3
Edge detection on a synchronized signal is the standard idiom: register the signal, then compare the registered copy against the live one, and a difference is an edge — rxPrev s == high && line == low is precisely “the previous sample was high and this one is low,” a falling edge. Doing it on the synchronized line rather than the raw pin matters: comparing two samples of a metastable signal could see an edge that isn’t there, so the synchronizer must come first. The sub-tick latency is the price of checking only once per tick rather than continuously: the true edge can fall anywhere in a tick interval, so the observing tick lags it by up to one tick. A design that cared could halve this by sampling the edge on the fast clock instead of the tick, but the UART does not care, because the whole point of aligning to the bit center is to put eight ticks of slack between the sample and the nearest edge — far more than the sub-tick start error and the accumulated baud drift combined. The lag is real and the center makes it free. ↩ ↩2
The odd-count requirement is intrinsic to majority voting: with an even number of voters a tie is possible and “the majority” is undefined, so you either add a tie-break (complexity, and an arbitrary bias) or use an odd count and avoid the question. Among odd counts, the returns diminish fast. One sample tolerates zero faults; three tolerate one; five tolerate two; in general 2k+1 samples tolerate k. The fault being guarded against is a glitch landing on a sample at the bit center, within the three-tick window 7–9 — a rare event to begin with, since the center is the quietest part of the settled line — and the probability of two independent such glitches in the same window of the same bit is that rare event squared, which at 2 Mbaud over a short board trace is never. Three samples buy the entire realistic benefit; five would spend more flip-flops and a wider vote to guard a case that does not occur. This is decision 5 of the design, and it is a nice instance of sizing a mechanism to the actual threat rather than to the most general one imaginable — the same instinct that chose a one-way ready handshake over full backpressure in the transmitter. ↩
Both captureSample’s _ -> s and decideBit’s RxIdle -> (s, (Nothing, False)) carry the comment -- actually unreachable, and both are the same totality tax the transmitter paid for TxIdle -> s. Haskell sanctions partial functions — head, fromJust, and their kin are non-exhaustive by design — so it treats totality as an opt-in diagnostic (-Wincomplete-patterns) rather than a law, and Tamal opts in via the -Wall its cabal turns on. A case that omits a constructor is a warning; escalated with -Werror=incomplete-patterns it is a build failure. For gateware that escalation is the right call, because silicon has no PatternMatchFail to throw — an unhandled case would lower to a don’t-care, a silent wrong answer in the netlist rather than a catchable exception. So the unreachable arms are written out, returning the safe do-nothing, to keep every case total and the compiler satisfied that there are no holes even in the corners control never reaches. The word “unreachable” is a claim about the caller — captureSample is only called at counts that could be 7/8/9, decideBit only from a resolving tick — that the type cannot express, so the wildcard stands in for the proof the compiler cannot check. ↩ ↩2
The receiver’s indexed assembly and the transmitter’s shift are two ways to (de)serialise the same LSB-first byte, and it is worth seeing why the receiver picks the one it does. The transmitter shifted: it held the byte in a register, always read the bottom bit, and slid the register right each bit so the next bit fell into the read position — the byte moved past a fixed tap. The receiver instead holds the byte still and writes bit i directly with setBit/clearBit (rxShift s) (fromEnum i), addressing the register by index. Either would work for either direction; the design doc even offers both in one breath — “shift the sampled bit into the MSB and shift right, or index by i.” Indexing reads a hair more clearly on the receive side, where the phase RxData i already carries the index in hand, so writing bit i is a direct transcription of “this is data bit i.” It is the CRC’s and the transmitter’s shift-register motif a third time — the eSPI CRC shifted left, MSB-first, feeding a polynomial division; the transmitter shifted right, LSB-first, feeding the wire; the receiver indexes, LSB-first, filling the byte — the same eight bits handled three ways by three standards’ conventions, a shift or an index apart. ↩
One could make the receiver’s byte output Moore instead — hold the completed byte in a state field and expose a separate “valid for one cycle” flag, or present the byte on a register that updates only at frame end — and some UART IP does exactly that, offering a held received byte plus a separate strobe. Tamal chooses the Mealy strobe: Just byte on exactly the resolving cycle and Nothing otherwise, the byte carried inside the strobe rather than held beside it. It is cheaper (no output register, no held-byte field) and it composes cleanly with the shell’s load FSM, which will consume rxByte strobes as they fire. The cost is the one-cycle contract: a consumer must latch the byte the cycle it appears, because it is gone the next. That is a perfectly ordinary discipline in synchronous logic — it is the same shape as the transmitter’s “present Just b while ready” — and it is why the output is honestly Mealy rather than Moore: the strobe is an event, and events read the clock-enable that times them. ↩

Tamal: The transmitter

2026-07-22T09:00:00+00:00

The baud generator we read last time produces a heartbeat — a Bool that says now sixteen times a bit — and nothing else. It had no state machine at all, just a phase accumulator counting against a modulus. That was the point: the smallest possible clocked block, a register fed back through some arithmetic, so we could meet sequential logic without also meeting a finite-state machine on the same day. The post closed by promising that the next block would start spending that heartbeat. This is that block.

The transmitter takes the tick and a byte and drives a wire high and low in an 8N1 frame — and it is where mealy finally climbs to the top of a module, exactly as the primer said it would and the baud-generator post repeated on its way out. Every block so far has been a warm-up for this line:

uartTx tick mbyte = unbundle (mealy txStep initTx (bundle (tick, mbyte)))

The primer told you to read a mealy at the top of a module as “clocked state machine, its brain the pure function beside it.” Here is the module; here is the brain. But there is a twist the code’s own comment insists on, and it is a better lesson than a plain Mealy machine would have been: the thing is lifted with mealy, its transition has the textbook Mealy shape — and yet its outputs are pure Moore. Sorting out that apparent contradiction is most of what this post is for.

Like the CRC and the baud generator, the whole transmitter fits in a screenful and change.

The entire source

Minus the license header and the doc-comments, here is src/Tamal/Uart/Tx.hs in full:

module Tamal.Uart.Tx
  ( uartTx
  ) where

import Clash.Prelude

data TxState = TxIdle | TxStart | TxData (Index 8) | TxStop
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

data TxS = TxS
  { txState :: TxState
  , txShift :: BitVector 8
  , txCnt :: Index 16
  }
  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

uartTx ::
  (HiddenClockResetEnable dom) =>
  Signal dom Bool ->
  Signal dom (Maybe (BitVector 8)) ->
  (Signal dom Bit, Signal dom Bool)
uartTx tick mbyte = unbundle (mealy txStep initTx (bundle (tick, mbyte)))
 where
  initTx :: TxS
  initTx = TxS TxIdle 0 0

txStep :: TxS -> (Bool, Maybe (BitVector 8)) -> (TxS, (Bit, Bool))
txStep s (tick, mbyte) = (s', (line, ready))
 where
  ready = txState s == TxIdle
  line = case txState s of
    TxIdle -> high
    TxStart -> low
    TxData _ -> lsb (txShift s)
    TxStop -> high
  s'
    | TxIdle <- txState s = case mbyte of
        Just b -> s{txState = TxStart, txShift = b, txCnt = 0}
        Nothing -> s
    | not tick = s
    | txCnt s /= maxBound = s{txCnt = txCnt s + 1}
    | otherwise = txAdvance s

txAdvance :: TxS -> TxS
txAdvance s = case txState s of
  TxStart -> s{txState = TxData 0, txCnt = 0}
  TxData i
    | i == maxBound -> s{txState = TxStop, txCnt = 0}
    | otherwise -> s{txState = TxData (i + 1), txShift = txShift s `shiftR` 1, txCnt = 0}
  TxStop -> s{txState = TxIdle, txCnt = 0}
  TxIdle -> s

Four things, top to bottom: two data declarations that are the state machine’s memory, a five-line uartTx that is nothing but the mealy lift and its plumbing, the pure txStep that is the machine’s whole brain, and a txAdvance helper that walks the frame forward one bit at a time. We will read them roughly in that order, but the two types come first, because everything else is written in terms of them.

One exported name

The opening beat is the CRC module’s and the baud generator’s, played a third time, so I will be quick:

module Tamal.Uart.Tx
  ( uartTx
  ) where

import Clash.Prelude

module Tamal.Uart.Tx names the module after its path on disk — src/Tamal/Uart/Tx.hs, a dot per directory — and the parenthesised export list is the one door in the wall. Only uartTx leaves the file; txStep, txAdvance, TxState, and TxS are all sealed behind it, not because the list declines to mention them but because everything private is written where nothing else can name it. import Clash.Prelude is the same prelude swap the CRC post dwelt on — the line that throws out ordinary Haskell’s furniture and moves in Signal, Bit, BitVector, register, mealy, and the rest of the vocabulary that lowers to gates. I will not re-derive either; the CRC and baud-generator posts did that at length.

One thing is missing that both earlier modules had: there is no {-# LANGUAGE NumericUnderscores #-} pragma, because this file never writes a twelve-digit literal. The transmitter has no clock frequency to name — the frequency lives in the baud generator, upstream, folded into the tick this module simply consumes. That absence is worth noticing, because it is the first hint of how the UART is factored: each block owns exactly one idea, and the transmitter’s idea is not timing, it is framing.

The type: a byte in, a line out

Now the signature, which under the primer’s reading is already half the documentation:

uartTx ::
  (HiddenClockResetEnable dom) =>
  Signal dom Bool ->
  Signal dom (Maybe (BitVector 8)) ->
  (Signal dom Bit, Signal dom Bool)

Read it against the baud generator’s and the first thing you notice is what is gone. oversampleTick needed a forall, an SNat baud argument, and a KnownNat/KnownDomain pile of constraints, because it had to read a clock frequency out of the domain type and turn a baud rate into an increment. The transmitter needs none of that. It has one constraint, HiddenClockResetEnable dom — there is a clock (and reset, and enable) threaded implicitly, which is what mealy’s hidden register will draw on — and then two plain arrows in and a pair out. No numbers in the type at all. The transmitter does not know or care what the baud rate is; it knows only “a bit is sixteen ticks,” and the ticks arrive from elsewhere.

Take the two inputs in turn.

Signal dom Bool is the oversample tick — the baud generator’s output wire, plugged straight in. Under the primer’s reading it is “a Bool that may change on every clock tick,” and we spent a whole post establishing that this particular Bool is an enable, true on the cycles the UART should advance and false on the rest. The transmitter is one of the two things that enable was built to gate. Every bit-advancing decision below is downstream of this wire being True.

Signal dom (Maybe (BitVector 8)) is the send request, and the Maybe is doing exactly the job the primer gave it. There, a step returning Maybe Ring stated a hardware fact — at most one trace-RAM write happens this cycle — a write-enable promoted to a type. Here the direction is reversed but the idea is identical: Just b on some cycle means “please transmit this byte,” and Nothing means “I have nothing for you.” The absence lives in the type, out in the open; there is no sentinel byte, no separate valid line to forget to check. A send request is a byte that might not be there, and its type says so.

That leaves the result, (Signal dom Bit, Signal dom Bool) — a pair of output wires:

Signal dom Bit is line, the serial output, one Bit per cycle. It idles high and is driven low and high through a frame. This is the physical wire that, on the board, runs to the USB-UART bridge and out to the host.
Signal dom Bool is ready, a flag that is high exactly when the transmitter is idle and can accept a new byte. It is one half of a one-cycle handshake; the caller is meant to present Just b only on a cycle when ready is high.

So the whole interface is: here is a heartbeat and maybe a byte; take the wire I drive and a flag that says whether I’m listening. This is the “strobe/handshake” interface the UART design chose over full valid/ready backpressure, and it is cheap because it can afford to be — at 2 Mbaud a byte spans roughly five hundred Dom100 cycles, so a consumer draining bytes has five hundred cycles of slack and never needs to stall the line.^[1]

Two types that are the state

Everything the transmitter remembers lives in two data declarations, and they are worth reading slowly, because they are the primer’s sum-and-product story told in hardware. The user of this UART never sees either type — they are sealed behind the export list — but they are the machine.

The first is the phase:

data TxState = TxIdle | TxStart | TxData (Index 8) | TxStop

Read the | as “or”: a TxState is TxIdle or TxStart or TxData (carrying an Index 8) or TxStop, and nothing else. This is the primer’s sum type — the FSM’s state register written as a type, the same shape as the engine’s Phase from that post. Four of a UART frame’s five ideas are here by name: the line is idle, or driving the start bit, or driving one of the data bits, or driving the stop bit.

The interesting constructor is TxData (Index 8). It is a data-bearing constructor, the primer’s Circle Double pattern: the tag TxData travels with a payload, and the payload’s type is Index 8 — a number in the range 0..7 and, by construction, never 8. So TxData is not one state but eight, one per data bit, and the index that distinguishes them cannot stray out of range because the type will not let the value 8 exist in the first place. Count the inhabitants and the whole state space is exactly 1 + 1 + 8 + 1 = 11: idle, start, eight data, stop. The compiler knows that number, which is why a case over a TxState that forgets a constructor is a warning at build time — the primer’s exhaustiveness check, standing guard over the state machine, for free.^[2]

The deriving block is the primer’s incantation, and by now it should read as ordinary furniture rather than noise:

  deriving stock (Generic, Show, Eq)
  deriving anyclass (NFDataX)

Show so a failing test can print the state it choked on; Eq so txState s == TxIdle a few lines down is legal; Generic as the structural plumbing other machinery builds on; and NFDataX, the one that is really about hardware — Clash’s way of saying this type is allowed to sit in a register, its values, including “undefined at power-up,” well-defined enough to be stored in flip-flops. A TxState is going into a register in a moment, so it must earn NFDataX, and deriving anyclass is how it does.

The second type is everything the machine carries from one tick to the next:

data TxS = TxS
  { txState :: TxState
  , txShift :: BitVector 8
  , txCnt :: Index 16
  }

This is the primer’s product type — a record, a struct, a bundle that holds one field and another and another. Where the engine’s state was a big State { phase, pc, regs, ... }, the transmitter’s is a small TxS { txState, txShift, txCnt }, and the record syntax hands us three accessor functions for free: txState :: TxS -> TxState, txShift :: TxS -> BitVector 8, txCnt :: TxS -> Index 16. Each field earns its place:

txState is the phase we just met — where in the frame we are.
txShift is the latched byte, held in a BitVector 8 and shifted right as the frame progresses so its least-significant bit always presents the next bit to send. It is eight wires with no arithmetic meaning — the CRC post’s reason for BitVector over Unsigned — because we only ever shift it and read its bottom bit, never add to it.
txCnt is the position within the current bit, an Index 16 counting the sixteen oversample ticks that make one bit-time. Again the width is load-bearing: 0..15, never 16, so “have we held this bit for a full sixteen ticks?” is exactly “has txCnt reached maxBound?”

Add it up and the entire memory of the transmitter is a phase (four bits would over-cover its eleven states), a byte, and a four-bit counter — call it fifteen bits of flip-flop. That is the whole s that mealy is about to clock. Hold the shape of it in your head; the rest of the file is just the pure function that turns one TxS into the next.

The transmitter's eleven states as an FSM. Every transition but one advances on the sixteenth oversample tick of a bit (plain arrows); the lone accented transition — accepting a byte out of TxIdle on a Just b — is driven by the input and is not tick-gated, which is what lets the ready handshake resolve in a single cycle. TxData (Index 8) packs eight states into one constructor; its self-loop shifts the latched byte right (shiftR) so lsb walks it out LSB-first. The line value under each state is the Moore output: a pure function of the state, steady for the whole bit.

`mealy` climbs to the top

Here is the line the entire series has been walking toward:

uartTx tick mbyte = unbundle (mealy txStep initTx (bundle (tick, mbyte)))
 where
  initTx :: TxS
  initTx = TxS TxIdle 0 0

The primer gave us the type of mealy and asked us to hold it:

-- mealy :: (s -> i -> (s, o)) -> s -> (Signal dom i -> Signal dom o)

Read it slowly against the code. mealy takes two things — a pure step function s -> i -> (s, o) and an initial state s — and hands back a function on signals, Signal dom i -> Signal dom o. Feed it txStep (the step) and initTx (the initial state) and you get a machine that consumes a stream of inputs and produces a stream of outputs, with a real register, clocked, holding the state between cycles. That register is the baud generator’s register seen again — the primer’s line that “a Mealy machine is nothing but a register holding the state and a pure function computing the next one,” now assembled rather than used bare. initTx = TxS TxIdle 0 0 is the power-up state, the idle phase with a zeroed shift register and counter; because Dom100 carries no reset port, that value is set by the flip-flops’ initial state at configuration, exactly as the baud generator’s register 0 was.

But mealy wants a single input signal and yields a single output signal, and our transmitter has two of each — two inputs (tick and mbyte) and two outputs (line and ready). That mismatch is what bundle and unbundle are for:

bundle (tick, mbyte) takes the pair of signals (Signal dom Bool, Signal dom (Maybe (BitVector 8))) and zips them into one signal of pairs, Signal dom (Bool, Maybe (BitVector 8)) — the single Signal dom i that mealy accepts, with i = (Bool, Maybe (BitVector 8)).
unbundle does the reverse on the way out: the machine produces one Signal dom (Bit, Bool), and unbundle splits it back into the pair (Signal dom Bit, Signal dom Bool) that the signature promises.

The two are witnesses to a small, obvious isomorphism: a signal of pairs and a pair of signals carry the same information, because a bundle of wires is just several wires side by side, watched over time.^[3] They add no gates; they are pure re-pairing at the boundary, the adapters that let a two-in, two-out interface meet mealy’s one-in, one-out shape. Strip them away and the sentence is plain: run txStep as a clocked machine starting from idle.

How mealy lowers to hardware. The dashed box is exactly what mealy txStep initTx builds: a register holding the state TxS (powering up idle) wired to the pure txStep, with the next state s′ fed back through the register — the accent loop that makes this sequential rather than a combinational knot. bundle gathers the two input signals tick and mbyte into the single i the combinator consumes; unbundle splits the single output back into line and ready. The register is the baud generator's register seen again — the primer's "a Mealy machine is a register plus a pure function," assembled.

What makes this the milestone the primer promised is that mealy has finally climbed to the top of a module — it is the thing uartTx returns, the outermost structure of the block, not a helper buried inside. The CRC was a pure function; the baud generator was a register and some arithmetic in a where block. This is the first Tamal module whose very shape is “a state machine,” and every remaining block — the receiver, and the engine that is the whole point of the project — will have this same silhouette. Learn to read it here and you can read all of them: find the mealy, find the step function beside it, and the rest is detail.

`txStep`: the pure transition

txStep is the brain. It is an ordinary, pure, total function — no Signal, no clock, no simulator — and that is exactly what the introduction post meant when it said the tests run in under a second: you can hammer a function like this with thousands of inputs in milliseconds, and only once you trust it does mealy make it hardware. Here it is again, on its own:

txStep :: TxS -> (Bool, Maybe (BitVector 8)) -> (TxS, (Bit, Bool))
txStep s (tick, mbyte) = (s', (line, ready))
 where
  ready = txState s == TxIdle
  line = case txState s of
    TxIdle -> high
    TxStart -> low
    TxData _ -> lsb (txShift s)
    TxStop -> high
  s'
    | TxIdle <- txState s = case mbyte of
        Just b -> s{txState = TxStart, txShift = b, txCnt = 0}
        Nothing -> s
    | not tick = s
    | txCnt s /= maxBound = s{txCnt = txCnt s + 1}
    | otherwise = txAdvance s

Look first at the type, because it is the primer’s promise made literal:

txStep :: TxS -> (Bool, Maybe (BitVector 8)) -> (TxS, (Bit, Bool))

That is s -> i -> (s, o) exactly, with s = TxS, i = (Bool, Maybe (BitVector 8)), and o = (Bit, Bool). Current state and input on the left; next state and output on the right. This is the shape mealy demands and the shape the primer told you to look for. The whole clocked machine is this one function with a register wrapped around it, and this function is where all the behaviour lives.

The body splits cleanly into the two halves of the pair it returns: the outputs (line, ready), and the next state s'. Read them separately, because they are where the Mealy-versus-Moore question is decided.

The outputs are Moore

Both outputs are computed from s alone. ready is literally txState s == TxIdle — a comparison against the state, nothing else in sight. line is a case on txState s:

  line = case txState s of
    TxIdle -> high      -- idle line sits high
    TxStart -> low      -- start bit
    TxData _ -> lsb (txShift s)  -- current data bit, LSB-first
    TxStop -> high      -- stop bit

Idle and stop drive high, start drives low, and a data bit drives lsb (txShift s) — the least-significant bit of the latched, shifted byte. Every arm reads only the state (and txShift, which is part of the state). Neither tick nor mbyte — the inputs — appears anywhere in line or ready.

That is the definition of a Moore output: a function of the current state only.^[4] And it has a consequence you can see on a scope. Because line ignores the input and depends only on txState and txShift, and because neither of those changes except at a bit boundary, the line is rock-steady for the whole sixteen-tick bit — it cannot twitch when a byte is offered, cannot glitch when the tick fires, cannot do anything but sit at its level until the state moves. For a wire whose entire job is to be sampled dead-center by a receiver sixteen ticks later, that stability is not an accident; it is the reason to make the outputs Moore.

So where is the Mealy?

The next state, and the one place the input reaches in

The next-state block is a chain of guards — boolean tests tried top to bottom, first match wins:

  s'
    | TxIdle <- txState s = case mbyte of
        Just b -> s{txState = TxStart, txShift = b, txCnt = 0}
        Nothing -> s
    | not tick = s
    | txCnt s /= maxBound = s{txCnt = txCnt s + 1}
    | otherwise = txAdvance s

The first guard is a pattern guard: TxIdle <- txState s succeeds when the state matches TxIdle. So the whole first arm is “if we are idle.” And notice what it does — and does not do. It looks at mbyte, the input. If a byte is offered (Just b), it latches that byte into txShift, resets the counter, and moves to TxStart, all this cycle. If nothing is offered (Nothing), it stays idle. Crucially, there is no mention of tick in this arm: accepting a byte is not tick-gated. The instant a Just b arrives while idle, the machine takes it, regardless of where the oversample tick happens to be in its cadence.

That is the one place the live input reaches into the logic, and it is the whole reason the interface is a handshake. ready is high (because we are idle), the caller sees it and presents Just b, and the byte is absorbed on that very cycle rather than waiting up to sixteen ticks for the next tick edge. It is a genuine same-cycle dependence of the transition on the input — the ingredient that makes the general mealy combinator the right tool rather than its Moore-only sibling.

Here is the subtlety worth being precise about, because it is easy to overstate. A dependence of the next state on the input is not what makes a machine Mealy — a Moore machine’s next-state function takes the input too; that is how any state machine responds to anything. What distinguishes Mealy from Moore is strictly whether the output depends on the input. By that test, txStep’s outputs are Moore, full stop. What the un-tick-gated handshake buys is not a Mealy output but a same-cycle transition — the machine changes state in response to the input without waiting for its own cadence, so that the ready handshake can complete in a single cycle. The module is, honestly stated, a Moore machine lifted through the mealy combinator, with one input-driven, un-clocked-cadence transition out of idle.^[5]

The sole distinction between the two machine styles. In a Moore machine the output is a function of the state alone; the input reaches only the next-state logic inside the register. In a Mealy machine an extra path (accent) taps the input into the output too, so the output can change the moment the input does. By this test txStep's line and ready are Moore — neither reads tick or mbyte — even though the block is lifted with the general mealy combinator. What the handshake adds is a same-cycle next-state edge, not an input-driven output.

The cadence: freeze, count, advance

Once we are past the idle arm — that is, once the machine is actually transmitting — the remaining three guards are the bit-timing, and every one of them is gated on the tick:

    | not tick = s                        -- between ticks: hold everything
    | txCnt s /= maxBound = s{txCnt = txCnt s + 1}  -- within a bit: count
    | otherwise = txAdvance s             -- 16th tick of the bit: next phase

not tick = s is the freeze: on any cycle where the oversample tick is low — which is most of them, since at 2 Mbaud the baud generator fires the tick only about once every 3.125 clocks, so the machine sits frozen roughly two cycles in every three — the state is returned unchanged. The transmitter does nothing between ticks. This is the enable in action: the baud generator hands out permission to move, and off a tick the machine simply declines to.

On a tick, the next guard asks whether the bit is done. txCnt counts 0..15; while it has not yet reached maxBound (15) we increment it and stay in the same phase — another tick of the same bit. The guard order is doing quiet safety work here: txCnt s + 1 is bounded arithmetic on an Index 16, and adding one to maxBound would be an overflow, but we only reach the increment when txCnt s /= maxBound, so the + 1 can never run off the end. The type forbids the illegal value and the guard order guarantees we never ask for it — belt and suspenders, both supplied by the primer’s “numbers can live in types.”

When the tick fires and txCnt has reached 15 — the sixteenth tick of the bit — the otherwise arm calls txAdvance, which moves the frame to its next phase and resets the counter to begin a new bit. Sixteen ticks per bit, exactly, counted off by an Index 16 rolling from 0 to its maximum. That is how “hold each level for sixteen oversample ticks” is written.

Step back and the shape of the whole step is visible: two Moore outputs read straight off the state, and a next-state function that is idle-driven by the input (the handshake) and otherwise tick-driven by the counter (the cadence). One function, two clean halves.

Inside one txStep: the state register s fans out to three consumers. Two are the Moore outputs — ready, a bare comparison txState s == TxIdle, and line, a case on the state — and neither reads an input, so both are steady functions of s. The third is the next-state logic, the only place the inputs enter: tick gates the cadence (freeze off-tick, count to sixteen, then advance) and mbyte (accent) drives the un-gated idle handshake. Its result s′ is the value the register latches for the next cycle.

`txAdvance`: walking the frame

txAdvance is called on exactly the ticks that end a bit, and its job is to move the phase forward:

txAdvance :: TxS -> TxS
txAdvance s = case txState s of
  TxStart -> s{txState = TxData 0, txCnt = 0}
  TxData i
    | i == maxBound -> s{txState = TxStop, txCnt = 0}
    | otherwise -> s{txState = TxData (i + 1), txShift = txShift s `shiftR` 1, txCnt = 0}
  TxStop -> s{txState = TxIdle, txCnt = 0}
  TxIdle -> s

Trace the phases in order and it is the whole 8N1 frame:

TxStart -> TxData 0. The start bit is finished; begin the first data bit. Note what is not touched: txShift is left exactly as it was latched, so the first data bit driven is lsb of the original byte — bit 0, the least-significant bit. UART is LSB-first, and this is where that convention is set.
TxData i, when i is not maxBound. Move to TxData (i + 1) and shift the latched byte right by one: txShift = txShift s `shiftR` 1. The right shift slides the next bit down into the lsb position, so that when line reads lsb (txShift s) during the next data phase, it presents bit i + 1. The byte walks out of the bottom of the shift register, one bit per data phase, least-significant first.
TxData i, when i == maxBound. Bit 7 is done; there is no bit 8 (the Index 8 guaranteed that), so go to TxStop.
TxStop -> TxIdle. The stop bit is finished; return to idle, where ready goes high again and the next byte can be accepted.

Every arm also resets txCnt to 0, because each new phase gets its own fresh count of sixteen ticks.

Two details reward a second look. The first is that the data bits are serialised with the same txShift register the outputs read — there is no separate bit index driving a multiplexer over the byte. line reads the bottom bit; txAdvance shifts a new bottom bit into place at each boundary; between them the byte is dealt out like cards off the bottom of a deck. It is the CRC post’s shift register seen from the other direction: there the byte was shifted left, MSB-first, feeding a polynomial division; here it is shifted right, LSB-first, feeding a wire. Same primitive, opposite convention, because eSPI’s CRC is defined MSB-first and a UART frame is defined LSB-first — two standards, two directions, one shiftR/shiftL apart.^[6]

The second is that final arm, TxIdle -> s. It can never actually run: txAdvance is only ever reached from txStep’s otherwise guard, and that guard is only reached after the idle case has already been handled by the first pattern guard. If the state is TxIdle, control never gets as far as txAdvance. So why write the arm at all? Because a case over TxState that omits TxIdle is non-exhaustive, and the compiler will say so — the primer’s exhaustiveness check again, insisting that every constructor be handled even when the programmer can prove one is dead.^[7] Returning s unchanged is the honest way to satisfy it: if we somehow were idle here, doing nothing is the only safe answer. A total function has no holes, even the unreachable ones.

The line waveform for one byte — ASCII 'K', 0x4B = 0b0100_1011. The frame is idle-high, one accent start bit (low), the eight data bits least-significant first (so 0b0100_1011 leaves as 1 1 0 1 0 0 1 0), one stop bit (high), then idle. Each cell is held for sixteen oversample ticks. The accent dots mark the bit centers, where the receiver samples: because line is a Moore output it is dead-steady across the whole cell, so the sample always lands on solid ground. Note that the stop bit and the idle line sit at the same level — a frame is delimited by counting, not by a distinct symbol.

The waveform above is the entire module, seen from outside: idle high, one low start bit, eight data bits with the byte’s least-significant bit leading, one high stop bit, and back to idle. Ten frame cells, each held for sixteen ticks, walked out by the ten states from TxStart through TxStop — with TxIdle the resting level either side, held not for sixteen ticks but for however long it takes the next byte to arrive. If you overlaid the receiver’s sampling instants — one at the center of each frame cell, sixteen ticks being enough oversampling to land there reliably — every sample would fall squarely in the middle of a rock-steady level. That is the Moore output paying off: nothing moves at the sampling instant except by design.

The one-cycle handshake

We have seen both halves of the handshake now; it is worth assembling them into the protocol the caller actually follows, because it is the part most likely to bite an integrator who gets it wrong.

ready is high only when txState s == TxIdle. The moment a byte is accepted — the idle arm firing on a Just b — the state becomes TxStart, so on the very next cycle ready is already low, and it stays low through start, all eight data bits, and stop: some five hundred Dom100 cycles at 2 Mbaud. Only when txAdvance finally returns the machine to TxIdle does ready rise again. So the contract is:

Present Just b on a cycle when ready is high, and the byte is latched that cycle. Present it any other time and it is silently dropped.

That “silently dropped” is not sloppiness; it is enforced by the shape of the guards. Once the machine is out of idle, no arm of s' so much as looks at mbyte — the not tick, counting, and txAdvance arms are functions of tick and the state alone. A Just b offered mid-frame falls through every guard and changes nothing. The byte is not queued, not latched, not remembered; it simply has no effect, because there is no wire by which it could have one. That is a deliberate safety property: a caller that violates the handshake cannot corrupt a frame in flight, only fail to send. The design calls this out as its own line — “a Just presented mid-transmission is ignored (no corruption)” — and the guard structure is what makes it true by construction rather than by vigilance.

On the drain side of the real UART, this is exactly the discipline the trace-drain FSM will follow: present the next ring byte on mbyte only while ready is high, and let ready falling be the backpressure that paces the whole readout. One flag, one rule, and the transmitter can never be overrun.

The tests

The transmitter shares a test module with the rest of the UART, Test/Uart.hs, and because it is sequential the tests drive it through Clash simulation — sampleN, bundle, fromList — rather than the pure-function style the CRC used. The primer’s reading of Signal as “an endless stream, one sample per cycle” is what makes that tractable: sampleN n is take n on the stream, so “simulate four hundred cycles” is a list traversal, not a simulator invocation.

Three of the properties are the transmitter’s own. The first is the one that matters most, and it is the baud generator post’s promised keystone finally starting to close:

testProperty "TX->RX fast loopback recovers the byte" $ property $ do
  b <- forAll genByte
  let out = runFastLoop [Nothing, Just b] 400
  [b' | Just b' <- out] === [b]

runFastLoop wires the transmitter’s line straight into the receiver’s input, shares one tick between them, and — for speed — runs with the tick held permanently True, so each bit is sixteen cycles rather than the sixteen ticks the real NCO spreads over fifty. Hedgehog draws a random byte, feeds it to the transmitter as a single Just b while ready is high, and asserts that the receiver hands back that exact byte, bit-for-bit. No reference model, no golden waveform: the two halves of the UART check each other. Any disagreement about bit order, frame shape, or timing — an MSB-first slip, an off-by-one on the stop bit — shows up as a byte that comes back wrong, and Hedgehog shrinks the failing case to the smallest byte that still breaks it.

The second pins the handshake:

testProperty "TX ignores input while busy (ready gating)" $ property $ do
  b <- forAll genByte
  let out = runFastLoop (Nothing : L.replicate 100 (Just b)) 400
  [b' | Just b' <- out] === [b]

Here the caller misbehaves on purpose: after one idle cycle it jams Just b onto the input a hundred cycles in a row, straight through the transmission. If mid-frame requests were latched, the line would be a mess of restarted frames and the receiver would recover garbage or a fistful of bytes. The assertion is that exactly one byte comes back — the machine accepted the first Just b while idle and ignored the other ninety-nine while busy, precisely as the guards promise. This is the “no corruption” property, stated as a test.

The third runs the same loopback through the real baud generator rather than the always-true tick:

testProperty "full UART loopback (real NCO) recovers the byte" $ property $ do
  b <- forAll genByte
  let out = runFullLoop (Nothing : L.replicate 60 (Just b)) 1200
  [b' | Just b' <- out] === [b]

runFullLoop calls the umbrella uart (SNat @2_000_000) — baud generator, transmitter, and receiver all wired together — with the transmitter’s line looped back to the receiver’s. Now a bit really is fifty clocks wide, tiled by sixteen NCO ticks whose gaps alternate three and four clocks, and the receiver must still sample each bit dead-center. That it recovers the byte is the whole UART’s keystone: the fractional 3.125 the baud generator fought to average correctly, the sixteen-tick bits the transmitter holds, and the center-sampling the receiver performs, all have to agree at once or the byte comes back wrong. The baud-generator post said we would meet the other end of its one blunt tick-rate test “when the receiver is built”; this is that other end, and the transmitter is the piece in the middle that turns a cadence into a frame.

What we read

Eighty-odd lines, one exported name, and underneath it the first real state machine in the series: two data types that are its entire memory — a sum for the frame phase, TxData (Index 8) folding eight data-bit states into one bounded constructor, and a record for the byte and the tick counter carried alongside it — lifted into hardware by a mealy at the very top of the module, its state held in the register the baud generator showed us bare. The brain beside it, txStep, is a pure s -> i -> (s, o) you can test in milliseconds, and reading it closely settled the question the module’s own comment raised: the outputs line and ready are Moore — functions of the state alone, so the serial line never twitches between bit boundaries — while the single input-driven, un-tick-gated transition out of idle is what makes the ready handshake resolve in one cycle. txAdvance walks the phases start-to-stop and deals the latched byte out of a right-shifting register LSB-first, the CRC’s shift register run backwards. And a byte-exact loopback checks the whole thing against its own other half.

The primer promised that spotting a mealy at the top of a module would one day mean something concrete rather than looking like an incantation. This is the module where it pays off, and the silhouette we read here — find the mealy, find the step function, split it into outputs and next state, decide Moore or Mealy by whether the output looks at the input — is the one every remaining block wears. Next is the receiver: the transmitter’s mirror, where the line is an input arriving asynchronously from a pin, where a start edge has to be found rather than driven, and where the majority-vote center sampling that the loopback test quietly depends on gets built in the open. Between the two of them the UART closes, and the heartbeat the baud generator started finally carries a byte end to end.

The alternative is full valid/ready backpressure, where producer and consumer each raise a flag and a byte moves only on a cycle when both are high — the discipline you reach for when either side might stall indefinitely. A UART transmitter at 2 Mbaud inside a 100 MHz fabric is not that situation: once a byte is latched the line takes roughly five hundred cycles to clock it out, so any consumer of ready has enormous slack and a one-way ready flag suffices. The UART design records this as an explicit decision — “at 2 Mbaud a byte spans ~500 Dom100 cycles, so the consumer always keeps up — full valid/ready backpressure is overkill” — and it is a good example of sizing the mechanism to the actual timing rather than reaching for the most general handshake reflexively. ↩
Index n is the primer’s counting-in-the-type feature doing double duty. As a state, TxData (Index 8) has exactly eight inhabitants, so the compiler’s tally of TxState’s constructors is exact and its exhaustiveness warnings are trustworthy. As a value, txCnt :: Index 16 and the i inside TxData can only hold legal positions — 0..15 and 0..7 respectively — so the arithmetic txCnt s + 1 and TxData (i + 1) cannot silently produce an out-of-range count the way an Int would; an overflow is a runtime error in simulation and a wrapped value the type is designed to prevent you from reaching, which is why both increments sit behind a /= maxBound guard. The width in the type is not documentation; it is the thing that makes “sixteen ticks per bit” and “eight data bits” facts the compiler helps enforce rather than comments it cannot check. ↩
bundle and unbundle come from Clash’s Bundle class, which witnesses the isomorphism Signal dom (a, b) ≅ (Signal dom a, Signal dom b) — and more generally between a Signal of some product (a tuple, a Vec, a record) and the product of Signals. The intuition is pure hardware: a wire carrying a pair is two wires, and whether you think of “one bus of pairs over time” or “two wires over time” is a point of view, not a difference in the circuit. mealy is written to take a single input Signal and produce a single output Signal, so when your interface is several signals — as almost every real block’s is — bundle gathers them going in and unbundle scatters them coming out. They synthesise to nothing at all; they are the type-level bookkeeping that lets a one-in/one-out combinator serve a many-in/many-out world. ↩
The two machine styles are named for the engineers who formalised them a year apart. A Moore machine (Edward F. Moore, Gedanken-experiments on Sequential Machines, 1956) has outputs that are a function of the current state only: output = g(state). A Mealy machine (George H. Mealy, A Method for Synthesizing Sequential Circuits, 1955) has outputs that are a function of the current state and the current input: output = g(state, input). Both have a next-state function f(state, input) — taking the input is how either kind reacts to anything — so the sole distinction is whether the input can reach the output within the same cycle. The practical trade is latency versus stability: a Mealy output can respond in the cycle its input arrives (fewer states, quicker reaction) but inherits the input’s glitches and combinational timing; a Moore output lags by up to a state transition but is stable and glitch-free for as long as the state holds. The two are equivalent in power — any Mealy machine has a Moore equivalent, generally with more states, and vice versa — so the choice is engineering, not expressiveness. ↩
Which raises a fair question: if the outputs are Moore, why lift with mealy and not Clash’s moore, whose type moore :: (s -> i -> s) -> (s -> o) -> s -> Signal dom i -> Signal dom o splits the next-state function from a separate, state-only output function — a perfect fit for a Moore machine? You could; the module would be equivalent. mealy wins on locality: txStep computes the next state and both outputs in a single where block that shares txState s, txShift s, and a couple of cases, and returning them together as (s', (line, ready)) keeps that shared reading of the state in one place. Splitting into a moore-shaped pair would duplicate the “look at txState s” logic across two functions for the sake of a label. mealy is the more general combinator, it costs nothing to use where a Moore machine is what you have, and it keeps the brain in one piece — so the codebase uses it uniformly, here and in the engine, and lets the shape of txStep (whether its outputs happen to read the input) decide what kind of machine each block really is. ↩
The bit-ordering split between the two blocks is not arbitrary; each follows its own standard. A UART frame is transmitted least-significant-bit first — a convention inherited from the teletype and enshrined in every 8N1 implementation — so the transmitter reads lsb and shifts right, dealing bit 0, then 1, up to 7. The CRC the eSPI link uses is defined most-significant-bit first (as eSPI and SMBus require), so that module reads msb and shifts left. The pleasing thing is how little the code has to say about it: the entire difference between “LSB-first serialiser” and “MSB-first CRC” is the direction of a shift and which end you read, shiftR/lsb versus shiftL/msb. Two wire conventions from two unrelated standards, a single mirror-image apart in the source. ↩
“The compiler will say so” is worth qualifying, because how loudly it says so is a knob. Left alone, GHC is silent about a non-exhaustive case; the diagnostic is -Wincomplete-patterns, and Tamal gets it only because its cabal turns on -Wall — one of the ghc-options the introduction post flagged as load-bearing. Even then it is by default just a warning: the module compiles, and in ordinary Haskell a branch that “cannot happen” but does raises a PatternMatchFail exception at run time rather than being caught at compile time. So the check is real but toothless unless you escalate it, which you can: -Werror=incomplete-patterns (or the pair -Wincomplete-patterns -Werror), set per-module with an {-# OPTIONS_GHC #-} pragma or project-wide in ghc-options, turns a missing constructor into a hard build failure — I confirmed as much on the exact GHC this project uses, where the warning becomes error: [-Wincomplete-patterns, Werror=incomplete-patterns] and the compile stops. That is the instructive contrast with Rust, whose recollection you may share: Rust makes match exhaustiveness a type-checker requirement, so a non-exhaustive match is a compile error (E0004) out of the box, with _ the one explicit escape hatch. Haskell went the other way because it has always sanctioned partial functions — head, fromJust, and their kin are non-exhaustive by design — so it treats totality as an opt-in diagnostic layered on top of the language rather than a law baked into it. For gateware the strict setting is the easy call: silicon has no exceptions to throw, so a “dead” arm that turned out to be live would be a silent wrong answer — a don’t-care lowered into the netlist — not a catchable PatternMatchFail, which is a good argument for compiling hardware with -Werror=incomplete-patterns. Writing the TxIdle -> s arm keeps even the warning quiet, which is why it is there. ↩

Tamal: The baud generator

2026-07-21T09:00:00+00:00

The CRC unit we read last time was pure combinational logic — a truth table wearing a Haskell type, the same output for the same input, no memory, no clock. It was the gentlest possible first block precisely because time never entered into it. The primer closed by promising that the next rung up was a block with a clock inside it, where Signal stops being a footnote and becomes the whole substance of the file. That block is the UART, Tamal’s link to the host, and this is where we start cashing the promise.

The UART is not one module but three small ones — a baud generator, a transmitter, and a receiver — so the series takes them one at a time, in the order they were built and the order they lean on one another. First the baud generator: the smallest of the three, with no state machine at all, just a clocked oscillator that produces the heartbeat every other part of the UART marches to. It is also where we meet register, the lone flip-flop that mealy — the machine from the primer — is built out of. mealy itself waits for the transmitter; here we meet its atom.

Like the CRC, the whole thing fits in a screenful.

The entire source

Minus the license header and the doc-comments, here is the module in full:

{-# LANGUAGE NumericUnderscores #-}

module Tamal.Uart.BaudGen
  ( oversampleTick
  ) where

import Clash.Prelude

oversampleTick ::
  forall baud dom.
  (HiddenClockResetEnable dom, KnownDomain dom, KnownNat baud) =>
  SNat baud ->
  Signal dom Bool
oversampleTick baud = tick
 where
  periodPs :: Integer
  periodPs = snatToNum (SNat @(DomainPeriod dom))
  fClk :: Unsigned 32
  fClk = fromInteger (1_000_000_000_000 `div` periodPs)
  inc :: Unsigned 32
  inc = fromInteger (16 * snatToNum baud)
  sums :: Signal dom (Unsigned 32)
  sums = (+ inc) <$> acc
  tick :: Signal dom Bool
  tick = (>= fClk) <$> sums
  acc :: Signal dom (Unsigned 32)
  acc = register 0 acc'
  acc' :: Signal dom (Unsigned 32)
  acc' = mux tick (subtract fClk <$> sums) sums

Roughly fifteen lines of logic under a familiar frame. The frame first, then the problem it exists to solve, then the five wires that solve it.

One exported name

The top of the file is the CRC module’s opening beat, played again. module Tamal.Uart.BaudGen names the module after its path on disk — src/Tamal/Uart/BaudGen.hs, a dot per directory — and the parentheses are the export list, the one door in the wall:

module Tamal.Uart.BaudGen
  ( oversampleTick
  ) where

Only oversampleTick leaves the file — and, as in the CRC unit, the export list is only half the story of what stays private. There, the real bit-twiddling lived in step, tucked into crc8Update’s where block; here the entire mechanism — fClk, inc, sums, tick, acc, and acc' — lives the same way, nested inside oversampleTick. A where binding is not a name the export list politely declines to mention. It is a name with no existence at all outside the one function body it sits in: no other module could reach acc, or step, even if it tried, because there is no syntax with which to spell it. The export list guards the module’s one top-level door; where the work is written seals the rest by construction.

import Clash.Prelude is the same prelude swap the CRC post dwelt on — the line that throws out ordinary Haskell’s furniture and moves in the hardware vocabulary, Signal, Unsigned, register, mux, the versions of the everyday names that lower to gates. It is still the line that says compile me to hardware; I will not re-derive it here.

The one new piece of ceremony is the pragma up top:

{-# LANGUAGE NumericUnderscores #-}

That is the switch that lets you write 1_000_000_000_000 with underscores grouping the digits, the way you would write a hundred billion on paper instead of squinting at a run of twelve zeros. It is pure legibility, and you will want it the moment a clock frequency shows up as a literal.

The problem is 3.125

Everything strange about this module comes from one number, so it is worth deriving before reading a line of the body.

Tamal runs on an Arty A7 at 100 MHz; the host link runs at 2 Mbaud, eight data bits, no parity, one stop bit. Divide the two and a bit is

$$ \frac{100 \times 10^6}{2 \times 10^6} = 50 $$

exactly fifty system clocks wide. That division comes out whole, which is a small mercy and also a trap, because it tempts you to think the timing is easy. It is not, and the reason is the receiver.

A transmitter has it easy: it owns the clock, so it can hold each bit for fifty cycles and call it a day. A receiver does not. The line arriving from the host is asynchronous — its bit edges fall wherever they fall, with no relation to Tamal’s clock — and the receiver has to find the middle of a bit it never scheduled. The standard cure, the one every robust UART uses, is to oversample: sample the line many times per bit, watch for the start edge, and then read each bit at its center where it is most settled. Tamal oversamples sixteen times a bit. Sixteen samples across a fifty-clock bit means a sample every

$$ \frac{50}{16} = 3.125 $$

clocks — and there is the number. The bit period divides the clock evenly; the thing we actually need, the 16x oversample period, does not. You cannot count off 3.125 clocks on an integer counter. Some ticks have to be three clocks apart and some four, arranged so the long-run average lands exactly on 3.125. Producing that stream — an enable that fires, on average, every 3.125 clocks — is the baud generator’s entire job.

Not a divider, not a PLL

There are two obvious ways to make a 16x-oversample strobe, and the module takes neither. Both refusals are worth understanding, because the road not taken is where the design’s philosophy shows.

The first idea is a plain clock divider: a counter that rolls over every so many clocks and pulses. But a divider can only divide by whole numbers. Divide 100 MHz by three and you get 33.3 MHz; by four, 25 MHz; the target, 16 × 2 Mbaud = 32 MHz, sits between two integer divisors and no counter reaches it. You could special-case this baud, hand-alternating threes and fours, but retune the link to some other rate for signal-integrity debugging and the fraction turns uglier still. A divider is the wrong tool for a fractional ratio.

The second idea is a PLL: ask the FPGA’s clock hardware to synthesize a real 32 MHz clock and run the UART on it. This works, and it is exactly the move to resist, because it manufactures a second clock domain. The moment the UART ticks on its own clock, every byte crossing from the receiver into the 100 MHz engine has to cross a clock boundary — and clock-domain crossings are where the sneaky bugs live: two-flop synchronizers, gray-coded pointers, an asynchronous FIFO, a pile of hardware whose only purpose is to survive two clocks that do not agree. More gates, more failure modes, harder to verify, all to gain a strobe you can get for free inside the clock you already have.

So the module produces neither a divided clock nor a synthesized one. It produces an enable: a boolean, one per system cycle, that is True on the cycles the rest of the UART should advance and False on the rest. The receiver and transmitter stay clocked by the one 100 MHz clock the whole chip runs on; they simply do nothing on the cycles the enable is low.

The baud generator hands out a cadence, not a clock — a Bool that says now a few times per bit, inside the single clock the rest of the design already lives in.

Hold that distinction; it is the whole reason the return type is what it is.

The type

oversampleTick ::
  forall baud dom.
  (HiddenClockResetEnable dom, KnownDomain dom, KnownNat baud) =>
  SNat baud ->
  Signal dom Bool

Read it back to front and it confirms everything the last two sections argued. The result is Signal dom Bool — under the primer’s reading, “a Bool that may change on every clock tick in domain dom,” a wire carrying one yes-or-no per cycle. Not a Clock, not a divided Signal dom Bit masquerading as timing: an enable, stated in the type.

A Signal dom Bool returned as timing is the type of an enable — the one-domain alternative to handing back a second clock.

The single argument is SNat baud. An SNat is a singleton — the lone value that inhabits the type of a type-level number, so baud lives in the type and can be passed as an argument without losing its type-level identity.^[1] The caller writes oversampleTick (SNat @2_000_000), and the 2_000_000 travels as something the compiler can both compute with and check. This is the primer’s “numbers can live in types” seen from the other side: here a number is the input, but it is the type-level number made touchable.

The forall baud dom. in front is not decoration. It pulls the two type variables into scope inside the body, so the definitions below can mention dom and baud by name — which they must, because one of them is about to read a number straight out of the type dom.

That leaves the three constraints before the =>, each buying one capability the body spends:

HiddenClockResetEnable dom — there is a clock (and reset, and enable) for dom, threaded implicitly so the code needn’t pass it by hand. This is what register, further down, quietly draws on: a flip-flop needs a clock, and this is where it comes from.
KnownDomain dom — the domain’s static configuration, its clock period among it, is known at compile time. We are about to read that period.
KnownNat baud — the baud number is a known type-level natural, so it can be reflected down to an ordinary value with snatToNum.

Reading the clock out of the type

The first two where bindings compute a constant most designs would have made you pass in — and get wrong:

periodPs = snatToNum (SNat @(DomainPeriod dom))
fClk     = fromInteger (1_000_000_000_000 `div` periodPs)

DomainPeriod dom is a type-level number: the clock period, in picoseconds, baked into the definition of the domain itself. For Tamal’s Dom100 it is 10,000 — ten nanoseconds, a hundred megahertz. SNat @(DomainPeriod dom) conjures the singleton for that type-level number and snatToNum reflects it down to an Integer, so periodPs is 10,000 computed by the compiler, not typed by a human.

fClk then turns a period into a frequency the obvious way: there are $10^{12}$ picoseconds in a second, so the number of cycles per second is $10^{12}$ divided by the period. For Dom100, $10^{12} / 10^{4} = 10^{8}$, one hundred million — fClk = 100_000_000, the clock frequency in hertz, and the modulus the oscillator will count against.

The point is what did not happen. Nobody passed the clock frequency in as a parameter. It was read off the clock domain, at compile time, from the same type that governs the actual flip-flops. There is no second knob to keep in sync with the first, no way for a 100_000_000 in one place to drift from a Dom100 in another:

The frequency isn’t configuration you can get wrong; it’s reflected out of the domain type, so the number and the clock can never disagree.

It is the primer’s “the compiler is a wire-width checker,” pointed at time instead of width.

The third constant is the phase increment:

inc = fromInteger (16 * snatToNum baud)

snatToNum baud reflects the baud rate down to a value, and $16 \times 2{,}000{,}000 = 32{,}000{,}000$ is the target oversample rate in hertz. Both inc and fClk are ordinary Unsigned 32 — thirty-two plain wires with no arithmetic surprises — and both are fixed at compile time. All the interesting behaviour is in how they are used.

The accumulator

Five bindings remain, and together they are a numerically-controlled oscillator — the name the module’s own comment gives it.^[2] The idea is a single running total, the phase accumulator, that gains inc every clock and fires a tick whenever it laps the modulus fClk. Here it is, wire by wire:

sums = (+ inc) <$> acc
tick = (>= fClk) <$> sums
acc  = register 0 acc'
acc' = mux tick (subtract fClk <$> sums) sums

Before unpacking the operators, read those four lines with the hardware ceremony stripped away — as ordinary arithmetic on this cycle’s numbers:

sums = acc + inc
tick = sums >= fClk
acc  = acc' from the cycle before   (0 on the first cycle)
acc' = if tick then sums - fClk else sums

Line for line, that is the whole oscillator: add the increment to the running phase, flag whether the sum has reached the modulus, carry the register forward from the previous cycle, and set the next phase to either the wrapped value or the untouched sum. Only the third line is not plain arithmetic — it is the one that remembers, and its = is really a one-cycle delay rather than an equation. The Haskell computes exactly these four things; it just has to state them for every cycle at once, which is the job of the three unfamiliar operators — <$>, register, and mux. Take them in turn.

register 0 acc' is the flip-flop. register i s is Clash’s primitive memory element — a bank of D flip-flops — and it does exactly one thing: it outputs i on the first cycle, and on every cycle after that it outputs whatever s held the cycle before. A one-cycle delay with a power-up value. This is the atom the primer’s mealy is assembled from; a Mealy machine is nothing but a register holding the state and a pure function computing the next one. Here we use the register bare, with no machine wrapped around it.

register is the flip-flop itself — the single clock-cycle delay that turns a loop of wires into a circuit that remembers.

(+ inc) <$> acc is where <$> enters. <$> is fmap, and a Signal is a functor, so f <$> s applies the pure function f to every sample of the stream s. (+ inc) is a curried adder with one operand strapped to the constant increment (the primer’s partial application, made of gates), so sums reads “the accumulator plus inc, every cycle” — one adder, its output a fresh stream.

A pure function fmapped over a Signal is a combinational gate smeared across all of time: sums is one adder, re-evaluated every clock.

(>= fClk) <$> sums is the same move with a comparator: each cycle, ask whether the candidate sum has reached or passed the modulus.^[3] The result, tick, is a Signal dom Bool — and it is both the module’s output and, one line down, a control wire.

That control wire is mux. mux sel a b is the 2:1 multiplexer on signals: sample by sample, it takes a where sel is True and b where sel is False. So

acc' = mux tick (subtract fClk <$> sums) sums

reads “the next accumulator is sums with the modulus subtracted off on a tick cycle, and plain sums otherwise.” (subtract fClk is \x -> x - fClk; subtract flips its arguments, which is precisely the direction — sums minus fClk — we want.)

Now step back and notice something about how those four lines are written. sums is defined above acc, but sums uses acc; acc is defined in terms of acc', which is defined below it and in terms of sums and tick, which sit above. The definitions refer to each other in a knot, and their order on the page is irrelevant. That is because they are not steps in a procedure — they are wires in a schematic, and a schematic has no first line:

A where block of Signal equations is a netlist, not a script; the order is yours to pick because there is no order.

Trace the knot as a circuit and it is a tidy little loop: the register acc feeds the adder sums; the adder feeds the comparator tick and a subtractor; the mux chooses between the subtractor’s output and the adder’s, steered by tick; and its choice, acc', feeds back into the register. Register, adder, comparator, subtractor, mux, and a wire home — a phase accumulator with a compare-and-subtract wrap.

The same four equations as a datapath. The register holds the phase acc; every clock it is summed with the constant inc to make sums. A comparator tests sums against the modulus f_clk; that boolean is the oversample tick, and it also steers the mux. A subtractor forms the wrapped phase sums − f_clk. The mux keeps sums when there is no tick and takes the wrapped value when there is; its output acc' loops back into the register: the accent path that makes this sequential logic rather than a lone combinational knot.

The recursion is legal for the same reason the circuit is well-behaved: the loop passes through the register. acc at cycle $n$ depends on acc' at cycle $n-1$, never on itself within a cycle, because register puts a clock edge in the path. A loop of pure signal functions with no register in it would be a combinational cycle — the one thing you may not build — and the register 0 is exactly what saves it. The initial value 0 is the power-up phase; Dom100 carries no reset port, so that 0 is set by the flip-flops’ initial state rather than by a reset pulse, and the oscillator simply starts counting from zero the instant the chip comes up.

Wrap, don’t reset

One detail in acc' is the difference between a baud generator that holds its rate forever and one that slowly slides off it. On a tick, the accumulator is set to sums - fClk — the overshoot — and not to zero.

Because the accumulator climbs by inc and inc does not divide fClk, it almost never lands exactly on the modulus; it crosses it, overshooting by a little. That is why the test is >= and not ==: you are catching a crossing, not a coincidence. And the leftover above the modulus is not noise to be discarded — it is the fractional part of a bit-time that an integer counter has no other way to hold. Subtract the modulus and you carry that fraction into the next interval, where it nudges the following tick a clock earlier. Zero the accumulator instead and you would throw the fraction away every tick, and the small errors would pile up until the ticks visibly drifted.

Keeping the remainder is what makes the average exact. Over one 2 Mbaud bit — fifty clocks — the accumulator gains

$$ 50 \times 32 \times 10^6 = 1.6 \times 10^9 = 16 \times \left(100 \times 10^6\right) $$

exactly sixteen times the modulus, so it laps exactly sixteen times and fires exactly sixteen ticks. Not sixteen on average with a wandering phase — sixteen, every bit, indefinitely. The individual gaps between ticks are three clocks or four, never the fractional 3.125 any single time, but the carried remainder does the bookkeeping so their average is 3.125 to the clock.

Subtract the modulus, never zero the accumulator: the carried overshoot is the fractional bit-time the integer hardware can’t otherwise represent, kept honest from one tick to the next.

The jitter this leaves — a tick landing a single 100 MHz clock early or late, twenty nanoseconds — is nothing by the time sixteen of them tile a five-hundred-nanosecond bit and the receiver reads only the center. And one more property falls out for free: because inc is smaller than fClk ($32$ million against $100$ million), the value left after a wrap is smaller than inc, so the next cycle’s sum cannot reach the modulus a second time. A tick is therefore always a lone one-cycle pulse, never two back to back — exactly the clean single-cycle enable the transmitter and receiver want to gate on.

The baud generator as a numerically-controlled oscillator. The phase acc gains inc = 16·baud every system clock; when the candidate sum sums reaches the modulus f_clk the mux subtracts the modulus (keeping the overshoot rather than zeroing) and a one-cycle tick fires. Because the overshoot is carried, the gaps run three clocks and (one in eight) four, averaging exactly 50/16 = 3.125, so a 50-clock bit always contains sixteen ticks. It is an enable inside Dom100, not a second clock.

The one test

The CRC unit came with a small battery of tests; the baud generator gets one, because there is only one thing to check — does it tick at the right rate?

baudTicks :: Int -> [Bool]
baudTicks n = sampleN n (oversampleTick (SNat @2_000_000) :: Signal Dom100 Bool)

testCase "oversample tick rate is 16x baud (~32 MHz avg)" $
  let n = 10000
      c = L.length (L.filter id (baudTicks n))
   in assertBool ("tick count = " <> show c <> ", expected ~3200") (abs (c - 3200) <= 2)

The whole apparatus is sampleN. sampleN n sig runs the circuit for n cycles and hands back a list of its n outputs — and that is the line where all the primer’s talk about Signal being “an endless stream, one sample per cycle” pays off. A Signal really is, morally, an infinite lazy list; sampleN n is take n on it — that is, take the first n elements from the list. So “simulate ten thousand clock cycles of this oscillator” is not a call to a hardware simulator with its process handshake and its waveform dump — it is a list traversal, evaluated by plain Haskell.

Simulating ten thousand cycles is a take 10000 on a lazy list — that, and nothing more elaborate, is why the whole suite finishes before you blink.

The assertion just counts the Trues. Over ten thousand cycles the oscillator should fire $10{,}000 \times \tfrac{32}{100} = 3200$ times, and the test allows $\pm 2$ for the partial teeth at the ends of the window, where the count can miss catching a tick that straddles the boundary. It is a blunt check, but it pins the one number that matters: the tick rate is what it claims to be.

The subtler guarantee — that the ticks land evenly enough for a receiver to sample a transmitter’s bits dead-center — is not tested here in isolation. It is tested two posts from now, by the full-UART loopback, where a real fifty-clock bit must contain sixteen real ticks or the receiver reads the wrong thing. This oscillator is one end of that keystone test; we will meet the other end when the receiver is built.

What we read

Fifteen lines of logic, one exported name, and no state machine at all: a phase accumulator — a register fed back through an adder, a comparator, a subtractor, and a mux — that reads its own clock frequency out of the domain type, climbs by a compile-time increment, and wraps by subtracting the modulus so it keeps its overshoot and fires exactly sixteen ticks per bit with no long-term drift, no PLL, and no second clock domain. What it hands the rest of the UART is an enable, not a clock: a Bool that says now sixteen times a bit, inside the one 100 MHz clock the whole design already runs on.

The primer promised that Signal would stop being a footnote in the block posts, and this is the block where it does. register, <$> over a Signal, mux, and a feedback loop tied through a flip-flop are the sequential vocabulary the rest of the series is built from — the CRC’s combinational world, now with a clock edge in it.

Next we start spending the heartbeat. The transmitter takes this tick and a byte and drives a line high and low in an 8N1 frame — and it is where mealy finally climbs to the top of a module, exactly as the primer said it would, lifting a pure TxS -> … -> (TxS, …) step into a clocked machine. The oscillator counts; the transmitter is the first thing to march to it.

A singleton is the bridge between a type-level number and a value you can pass around. SNat n is a type with exactly one inhabitant, the value that stands for the type-level natural n, so writing SNat @2_000_000 hands a function a runtime token that still carries 2000000 in its type. snatToNum walks it back down to an ordinary Integer (or any Num), while the KnownNat constraint is the compiler’s proof that the number is statically known. It is the round trip the primer’s “numbers can live in types” implies but does not spell out: up into the type to be checked, back down to a wire to be used. ↩
A numerically-controlled oscillator (NCO) — the engine of direct digital synthesis (DDS) — comes from radio and signal processing, where it synthesizes an arbitrary frequency from a single reference clock by accumulating a phase word each cycle and using the high bits as an angle into a sine table. Strip away the sine lookup and keep only the accumulator and its overflow and you are left with a fractional clock divider — precisely this module. In a textbook DDS the modulus is a power of two, so the “wrap” is just the natural carry-out of a fixed-width adder and the output frequency is the tidy fraction inc / 2^N of the clock; here the modulus is fClk, an arbitrary number rather than a power of two, so the wrap is an explicit compare-and-subtract — but the principle, phase accumulates and the overflow is your tick, is the same one that clocks software-defined radios, benchtop function generators, and any FPGA that needs a frequency its PLL cannot land on exactly. ↩
(>= fClk) is an operator section — an infix operator in parentheses with one operand already supplied, standing for a function still waiting for the other. The side you fill is the side that stays put: (>= fClk) is the right section \x -> x >= fClk, “has x reached the modulus?”, whereas (fClk >=) is the left section \x -> fClk >= x, “is the modulus at least x?” — the opposite comparison, which would fire the tick on the wrong side of the threshold. Which operand you park where is load-bearing in general; the (+ inc) a line earlier got away with either order only because addition commutes, so there (+ inc) and (inc +) genuinely denote the same function. Order-sensitive operators grant no such reprieve — >=, -, and div all care about the side — which is, incidentally, why the wrap spells its subtraction subtract fClk rather than (- fClk): the latter would parse as unary negation, not “subtract fClk.” ↩

Tamal: The CRC block

2026-07-20T09:00:00+00:00

As mentioned before Tamal is an FPGA eSPI exerciser with its gateware written in Haskell and compiled to verilog with Clash.

In a previous post we presented a very short introduction on Haskell, just enough such that the code blocks below don’t look too foreign. Today we start looking at one of the simplest blocks within Tamal: its CRC8 engine.

The code is so small that it fits easily in less than one screenfull of content on a regular smartphone screen, but as we will see, it hides a good amount of interesting operations due to Haskell’s expressiveness.

The entire source

As promised, the entire source fits in a screenfull:

module Tamal.Crc
  ( crc8Update
  ) where

import Clash.Prelude

crc8Update :: BitVector 8 -> BitVector 8 -> BitVector 8
crc8Update crc byte = foldl step crc (unpack byte :: Vec 8 Bit)
 where
  step :: BitVector 8 -> Bit -> BitVector 8
  step c inBit
    | feedbackBit == high = shifted `xor` 0x07
    | otherwise = shifted
   where
    feedbackBit = msb c `xor` inBit
    shifted = c `shiftL` 1

The first thing we notice are the top three lines:

module Tamal.Crc
  ( crc8Update
  ) where

A Haskell file opens by naming itself. module Tamal.Crc declares this module’s name, and the name is not free-form: it mirrors the path on disk. Tamal.Crc lives in src/Tamal/Crc.hs, a dot for each directory separator, the same way a Rust crate::module path or a Java package tracks its folder. The compiler leans on that correspondence to find modules, so the name and the location can never quietly drift apart.

The parentheses are the more interesting part. They are the module’s export list — the complete, deliberate enumeration of what the outside world is allowed to see:

A module is a wall with a door in it, and the export list is the door.

Only crc8Update is on that list, so only crc8Update leaves the file. Everything else — and in a moment we will meet step, the helper that does the actual bit-twiddling — stays private, sealed behind the wall. Had the author written module Tamal.Crc where with no list at all, Haskell would export everything by default, step included, and the module’s public surface would sprawl to match its implementation. The explicit list is a choice to expose one name and hide the rest.

That choice buys more than tidiness. step is an internal detail of how this CRC happens to be computed; nothing outside should depend on it, name it, or test it directly. Keeping it off the export list reserves the author’s right to rewrite it — table-driven, byte-parallel, whatever comes later — without breaking a single caller. The public contract is exactly one function wide. (It is also why the tests we read at the end exercise the byte-level crc8Update and never reach for step: step is not theirs to reach.)

The prelude swap

The line under the module header looks like ceremony and is anything but:

import Clash.Prelude

Every Haskell file begins in a world someone else furnished. That furniture is the prelude: the batch of names, types, and functions that are simply there before you import anything. Ordinary Haskell hands you the standard Prelude — Int, Bool, lists, foldl, map, the familiar fittings. import Clash.Prelude throws that set out and moves a different one in.

What arrives instead is a hardware vocabulary: the Bit, BitVector, Vec, and Signal types from the primer, the high and low bit literals, msb, shiftL, xor, unpack — and versions of the everyday functions, foldl among them, that operate on Vecs and lower to gates. This one line is the difference between a program that computes and a description that becomes a circuit:

Swapping the prelude is what turns a Haskell file into a hardware description.

Clash leans on the swap so hard that it shadows the list versions of common names. That has a visible consequence we will run into in the test file: there, map and ++ would mean the Vec versions, so gluing plain lists together has to reach for a list comprehension and <> instead. File that away; for now the thing to see is that the lone foldl two lines down is one of these swapped names. It is the Vec fold, and it will unroll into wiring rather than spin a runtime loop. Nothing in the module works without this import; it is the line that says compile me to hardware.

The type, and why it has to be this one

Now the signature, which under the primer’s reading is already half the documentation:

crc8Update :: BitVector 8 -> BitVector 8 -> BitVector 8

Two arrows, so — remembering that -> associates to the right and every function takes one argument — this is “give me a BitVector 8, then another BitVector 8, and I hand back a BitVector 8.” Name the three roles and the intent appears: the first argument is the running CRC, the second is the incoming byte, and the result is the new running CRC. It is an accumulator update, one byte at a time.

The type could have been written other ways, and the two decisions behind it are both load-bearing.

The first is BitVector 8 rather than Unsigned 8 or a Word. A BitVector 8 is eight wires with no arithmetic meaning attached — the type of a thing you xor, shift, and index into, not a thing you add. Unsigned 8 would have invited +, *, and carry, arithmetic this function never performs. Choosing BitVector states plainly that a CRC is bit-manipulation, not counting, and the type system then holds the code to that promise: reach for + on a BitVector by accident and the compiler objects. It is the primer’s “wire-width checker,” applied one level up — the kind of value, not just its width, is part of the contract.

The second decision is the argument order: running CRC first, byte second. That order is chosen so the function is fold-shaped. Recall currying — crc8Update crc is a legal value on its own, a function still waiting for a byte, meaning “advance this running CRC by one more byte.” That is precisely the shape a left fold wants for its combining step, and it is exactly how the tests will run the CRC across a whole message: foldl crc8Update 0 bytes reads left to right as “start at zero, fold in each byte.” Swap the arguments and that reading falls apart. The signature is written to make the fold obvious.

One last thing the type says by saying nothing. Every BitVector 8 in, produces a definite BitVector 8 out — no missing cases, no error, no Maybe. That totality is a truth table, $f : (\text{crc}, \text{byte}) \to \text{crc}$, same inputs giving the same output every time, which is the primer’s definition of combinational logic verbatim. crc8Update is a block of gates wearing a Haskell type. But the body only makes sense once we have the one idea the whole file is a transcription of.

A CRC is a remainder

Strip the acronym away and a CRC is a remainder — the leftover from a division, carried out in a number system with exactly two digits.

Here is the whole trick. Take a stream of bits and read it as the coefficients of a polynomial: the byte 00000111 becomes $x^2 + x + 1$, a one in each place where the polynomial has a term. Bytes, messages, whole packets — all just polynomials whose coefficients are either $0$ or $1$. Arithmetic on these coefficients is done modulo two, which collapses into one startling simplification: $1 + 1 = 0$, there are no carries, and addition, subtraction, and XOR are all the same operation. That single fact is why CRC hardware is cheap — every “subtraction” below is just an xor.

The divisor in this division has a name, the generator polynomial. Tamal’s is the one the module comment spells out,

$$ G(x) = x^8 + x^2 + x + 1 $$

whose coefficients, written as bits, are 1 0000 0111 — nine bits, 0x107, degree eight. Look at the low eight of those bits: 0000 0111, 0x07, the very constant sitting in the source. The ninth bit, the $x^8$ term, is the one that will “fall off the top” of an eight-bit register in a moment; hold onto it.

To take the CRC of a message $M$ is to do one thing:

Shift the message up by eight bits, divide by $G$, and keep the remainder.

In symbols, $C = (M \cdot x^8) \bmod G$. The shift by $x^8$ — eight zero bits of headroom appended below the message — is what makes room for an eight-bit remainder to live, and it is also, quietly, the thing that will make the residue trick at the end of this post work. A well-chosen $G$ has the property that almost any corruption of the message changes the remainder, so the remainder acts as a compact fingerprint: change the packet, change the fingerprint, and the receiver notices.

The smallest possible example is worth doing by hand, because we are about to meet it again as a unit test. Let $M$ be the one-byte message 0x01, which as a polynomial is simply $1$. Shift up by $x^8$ and reduce modulo $G$:

$$ x^8 \equiv x^2 + x + 1 \pmod{G} $$

because $x^8 = G + (x^2 + x + 1)$ and $G \equiv 0$ by definition of “modulo $G$.” The remainder is $x^2 + x + 1$, which is 0000 0111, which is 0x07. Remember that number. The code is about to reproduce it out of shifts and XORs, and the two answers are going to match.

The left fold

With the division in mind, the body is short:

crc8Update crc byte = foldl step crc (unpack byte :: Vec 8 Bit)

Two moves live on that line: turn the byte into bits, then fold over them.

unpack byte :: Vec 8 Bit takes the opaque eight-wire BitVector and re-presents it as a Vec 8 Bit, a sequence of eight individual Bits you can walk one at a time. The annotation :: Vec 8 Bit is needed because unpack is polymorphic — it will produce whatever type the surrounding code asks for — so we pin the target explicitly. The ordering is a convention worth naming: index 0 of the vector is the most significant bit, so walking the vector head to tail walks the byte MSB first, which is what this CRC (and eSPI, and SMBus) require.

Then the fold. From a purely functional standpoint a left fold^[1] is the most ordinary thing in the world, and it has nothing to do with mutation:

foldl threads an accumulator through a sequence, left to right, handing the running result and the next element to a combining function, over and over.

Written out, foldl step crc [b0, b1, .. b7] is nothing but a nest of calls:

step (step (step (.. step (step crc b0) b1 ..) b6) b7)

The crc seeds the accumulator. step folds in b0 to produce a new accumulator; that value feeds into step alongside b1 to produce the next; and so on down the byte until b7 yields the result. Nothing is ever overwritten. Each step returns^[2] a fresh CRC value and the previous one is simply never referenced again. What in C is a register clobbered inside a loop is here a value handed along a chain of pure functions — the same dance, performed without a single mutation. This is the “mapping, not procedure” point from the primer made concrete: the accumulator doesn’t change, it is replaced, eight times, by eight applications of one pure function.

And because the vector has a length the compiler knows — 8, right there in Vec 8 Bit — the hardware reading is the one the primer promised:

A fold over a fixed-size Vec is a pipeline unrolled in space, not a loop unrolled in time.

Clash does not synthesize a counter and a loop. It lays down eight copies of step’s logic, the output of each feeding the next, a chain of combinational stages that transforms the whole byte within a single clock. That chain is a shift register with XOR taps — a linear-feedback shift register, the textbook circuit for a bit-serial CRC — except Clash derived it from a foldl instead of asking anyone to draw it. The accumulator is the register’s contents, step is the tap logic, and the fold is the wiring between the stages.

The CRC-8 as a Galois shift register (polynomial 0x07). Each step shifts the byte left; the MSB is XORed with the next message bit to form the feedback, which is folded back in at the x², x¹ and x⁰ taps — the set bits of 0x07. crc8Update is this circuit with the flip-flops replaced by wires: Clash unrolls the foldl into eight combinational copies, one per bit, so a whole byte is absorbed in a single clock.

`step`: one bit at a time

Which leaves the heart of the module, the private helper the export list keeps to itself:

step :: BitVector 8 -> Bit -> BitVector 8
step c inBit
  | feedbackBit == high = shifted `xor` 0x07
  | otherwise = shifted
 where
  feedbackBit = msb c `xor` inBit
  shifted = c `shiftL` 1

The type tells the whole story of what step is for. It takes a running CRC and a single Bit — not a byte, one bit — and returns the next running CRC. That is the entire kernel of the design; everything else in the file is foldl invoking this function eight times per byte. Read crc8Update and step together and the division of labour is clean: step knows how to absorb one bit, and the fold knows how to do it eight times.

Take the two where bindings first, since the guards are written in terms of them.

The binding shifted = c `shiftL` 1 slides the CRC one place toward the most significant bit: a zero enters at the bottom, and the top bit drops off the end and is gone. In the language of the previous section, shifting left by one is multiplying the polynomial by $x$. The bit that just dropped off is the coefficient that would have become the $x^8$ term — the exact term $G$ exists to cancel.

The other binding, feedbackBit = msb c `xor` inBit, takes the CRC’s current top bit (msb c reads out the most significant Bit) and XORs in the incoming message bit. This is the point where the message actually enters the division.

Now the guards. The | is a guard: a list of boolean tests, each paired with a result, where the first test that succeeds wins and otherwise is the catch-all that is always true. So the function reads: if feedbackBit == high — high being the Bit whose value is one — the answer is shifted `xor` 0x07; otherwise the answer is just shifted.

Here is why that is division and not sleight of hand. Multiplying by $x$ can push the polynomial up to degree eight, one bit wider than the register holds. When the coefficient of that overflow — feedbackBit — is one, the value has grown “too big” and must be brought back into range by subtracting $G$. Subtracting $G$ means XORing 0x107; but the $x^8$ bit already fell off the top in the shift, so the only bits left to cancel are the low eight, 0x07. When feedbackBit is zero there was no overflow and there is nothing to subtract. That is the complete rule the five lines encode:

Multiply by $x$; if the bit that fell off says so, XOR the polynomial back in to reduce modulo $G$.

We can watch it produce the very number the algebra promised. Fold step from crc = 0 across the byte 0x01, whose bits MSB-first are seven zeros and then a one:

On each of the first seven bits, msb c is 0 and inBit is 0, so feedbackBit is 0; shifted is 0 shifted, still 0. The accumulator never leaves zero.
On the final bit, inBit is 1 while msb c is still 0, so feedbackBit is 0 xor 1 = 1. shifted is 0 `shiftL` 1 = 0, the guard fires, and the result is 0 xor 0x07 = 0x07.

The fold ends at 0x07 — exactly the $x^8 \bmod G = x^2 + x + 1$ we worked out by hand. The shifts-and-XORs and the polynomial division are not two implementations that happen to agree; they are one statement written twice. Fold that per-bit rule across all eight bits and the accumulator becomes $(\text{byte} \cdot x^8) \bmod G$, the byte’s contribution to the running remainder; chain crc8Update across a whole message, seeding from 0 and feeding each result back as the next crc, and you have divided the entire message by $G$, one byte at a time.

The tests

The module is twenty-eight lines. Its test file is shorter still, and the two of them together make a quiet point worth pausing on: a claim this small can be pinned down completely, from more than one direction. The tests come in two flavours that answer two different questions.

crc8 :: [BitVector 8] -> BitVector 8
crc8 = L.foldl' crc8Update 0

tests =
  testGroup "Crc"
    [ testCase "crc8Update 0 0x01 == 0x07" $
        crc8Update 0 0x01 @?= 0x07
    , testCase "CRC-8/SMBUS check \"123456789\" == 0xF4" $
        crc8 [fromIntegral (fromEnum c) | c <- "123456789"] @?= 0xF4
    , testProperty "residue law" $ property $ do
        msg <- forAll (Gen.list (Range.linear 0 32) genByte)
        crc8 (msg <> [crc8 msg]) === 0
    ]

First the helper. crc8Update works one byte at a time, but a message is a list of bytes, so the tests define crc8 = L.foldl' crc8Update 0 — fold the per-byte update across the whole list, seeding from the initial value 0. This is the second fold in the story, and it sits one level up from the first: the source folds bits into a byte’s CRC, the test folds bytes into a message’s CRC. Same foldl idea, twice, at two scales.

A small Clash wrinkle hides in that L.. Because import Clash.Prelude shadowed the list functions with Vec ones back at the top of the module, the plain-list fold has to be summoned from Data.List under the qualifier L, hence L.foldl'. The note at the bottom of the real test file is flagging the same shadow for map and ++, which is why the message is stitched together with a list comprehension and <> rather than the names you might expect. That one import casts its shadow all the way into the tests.

The oracle tests

The first two entries are HUnit cases — plain, hand-checked assertions of the shape “this exact input yields this exact output,” where @?= reads “the actual value should equal the expected one.”

crc8Update 0 0x01 @?= 0x07 is the smallest witness in the whole project. We have now derived it twice — once as $x^8 \bmod G$ with pencil and polynomials, once by tracing the fold through eight bits — and here it is bolted to the workbench so it can never silently change. If some future refactor ever breaks the multiply-by-$x$-then-reduce rule, this one-liner is the first thing to go red.

The second case checks a number that is not the author’s at all — it is the world’s. CRC-8/SMBUS is a catalogued CRC, and every catalogued CRC ships with a standard check value: the CRC of the nine ASCII bytes "123456789". For this polynomial and these parameters that value is 0xF4, the same 0xF4 printed in reference tables and reproduced by independent implementations in every language. Asserting it turns the test suite into a cross-check against the entire ecosystem: if Tamal agrees with the catalog on "123456789", then it is computing the CRC it claims to be — the one an eSPI or SMBus partner on the other end of the wire will also be computing — and not some subtly different cousin. These two are oracle tests: known questions with known answers, one derived in-house, one borrowed from the standard.

The property test

The third entry is a different animal. Hedgehog is a property-based testing library: instead of one example, you state a law that must hold for every input, and the library manufactures hundreds of random inputs trying to break it. The law here is the one the whole block exists to satisfy:

crc8 (msg <> [crc8 msg]) === 0

Read it aloud: take any message msg, compute its CRC, append that CRC byte to the end of the message, and run the CRC over the whole extended thing — and you get zero. The line above it, forAll (Gen.list (Range.linear 0 32) genByte), is Hedgehog drawing msg as a random list of up to thirty-two random bytes, with genByte (from the shared Test.Gen) producing fully-defined bytes. Every run of the suite fires this across a fresh shower of messages. And on the day it does fail, Hedgehog does the thing that earns its keep: it shrinks the counterexample, paring a giant random failure down to the smallest message that still breaks the law, and hands you that minimal case instead of a haystack.

Why is this the right property — the single law worth elevating above all the specific numbers? For two reasons, one practical and one that finally cashes in the polynomial setup.

The practical reason is that it is exactly how Tamal uses this CRC on the bus. The introduction post’s peripheral_io_read.s ends its response phase by reading the trailing CRC byte and checking that the running residue has driven to zero — rdsr t2, CRC followed by bnez t2, bad_crc. A good packet followed by its CRC leaves a residue of zero; anything else is a corrupted packet. The property test is that runtime check, lifted out of the eSPI program and asserted directly against the pure function. It tests the law the hardware actually leans on.

The mathematical reason is the payoff for all the polynomials. Appending the CRC byte $C$ to the message $M$ builds the number $M \cdot x^8 + C$ — the message shifted up eight bits to make room, with $C$ dropped into the low byte. But $C$ was defined as the remainder of $M \cdot x^8$ divided by $G$, and adding a remainder back onto its own dividend lands you on a clean multiple of the divisor. (Adding and subtracting are the same XOR here, which is why appending $C$ and subtracting off the remainder come to the same thing.) So $M \cdot x^8 + C$ is divisible by $G$ with nothing left over — a valid codeword — and running the CRC over it is dividing a multiple of $G$ by $G$:

The residue is zero because a message-plus-CRC is, by construction, a multiple of the generator polynomial.

There is one subtlety the shift handles for free. Running the CRC over the codeword multiplies it by a further $x^8$ — the fold’s own headroom — before reducing. But that changes nothing in the direction we care about: the codeword is already a multiple of $G$, and $x^8$ times a multiple of $G$ is still a multiple of $G$, so the remainder is still zero. (The extra factor is harmless the other way too: because $G$ ends in a one — its constant term is $1$ — multiplying by $x$ is reversible modulo $G$, so the headroom can never manufacture a false zero out of a bad packet.) The property holds for every message because the algebra leaves it no other option, and Hedgehog’s hundreds of random trials stand guard over the day a careless edit breaks that algebra.

What we read

Twenty-eight lines, one exported name, and underneath it a complete CRC: a module wall with a single door, a prelude swap that turns the file into a circuit, a curried type written fold-shaped on purpose, a left fold that Clash unrolls into a linear-feedback shift register, and a five-line step that is polynomial division disguised as shift-and-XOR. Beside it, a test file that stakes the whole thing down from three sides at once — a witness we derived by hand, the world’s catalogued check value, and the residue law the eSPI engine trusts at runtime.

The primer promised that the syntax would stop standing between you and the hardware. This is the first block where that promise gets cashed: there is nothing left in these lines that is merely Haskell — every one of them is a statement about gates, or about the algebra those gates carry out. Next in the series we take on a block with a clock inside it — the UART — where Signal stops being a footnote and the mealy from the primer finally earns its perch at the top of a module.

A fold — also called reduce, accumulate, inject, or aggregate, depending on the language — is the higher-order function that collapses a whole sequence into a single value by threading an accumulator through it: start from a seed, then repeatedly apply a two-argument combining function to “the result so far” and “the next element.” It comes handed: a left fold (foldl) brackets from the left and walks front to back, a right fold (foldr) from the other end. Fold is bread-and-butter in the languages descended from the lambda calculus — Lisp and Scheme, the ML family and OCaml, Haskell — where it sits beside map, filter, scan, and zip in a shared vocabulary of combinators; the array languages (APL, J, BQN, Uiua) know it just as intimately, usually as a single-glyph primitive. Imperative languages have long had it too, under a scatter of names — Python’s functools.reduce, C++’s std::accumulate, Ruby’s inject, JavaScript’s reduce, C#’s LINQ Aggregate — but have tended to reach for an explicit loop-with-an-accumulator instead; Rust is arguably the first mainstream systems language to make fold (and reduce) a reached-for, idiomatic tool rather than a functional-programming curiosity, largely by building it into the iterator adaptors everyone already uses. ↩
Technically Haskell functions never return, rather they evaluate to a value. ↩

Enough Haskell to Read Tamal

2026-07-19T09:00:00+00:00

Tamal is an FPGA eSPI exerciser, and its gateware — the UART, the cycle engine, the ALU, the CRC unit, the loader, the trace ring — is written in Haskell and compiled straight to hardware by Clash. This is the first post in a series that opens up that gateware one block at a time and reads each one end to end.

There’s a catch, and if you’re here at all you can probably feel it coming. Approach this code from C, Rust, or Verilog — which is where most people who care about an eSPI exerciser are standing — and the source can read like line noise. ::, ->, \case, deriving stock, BitVector 32, a lone mealy perched atop a module like an incantation. None of it is hard. All of it is unfamiliar, and unfamiliar is enough to stop you at the door.

So before the series spends a whole post on the Uart or the Engine, this one pays down the syntax tax up front. Think of it as a Rosetta Stone: just enough Haskell that a Tamal signature stops being an obstacle and starts being documentation.

Two honest caveats about scope. This is not a Haskell course — there are excellent ones, and I’m not writing another — and it deliberately steers around the deep theory: no monad tutorial, no functor laws, no monoids, none of the machinery a “learn Haskell” book leads with. The goal is narrow and practical: by the end you should be able to look at a Tamal type signature, a data block, a case, and the mealy at the top of an engine and know exactly what you’re seeing — not prove theorems about it, just read it. That’s the whole job.

`f :: A -> B` is just `f : A → B`

Start with the single most important translation, because once it clicks the rest follows. In mathematics you write a function as $f : A \to B$, read aloud as “$f$ takes an $A$ and gives you a $B$.” That arrow is the entire idea.

Haskell writes the exact same statement as f :: A -> B. The -> is the arrow. The only oddity is the doubled colon: :: reads “has type.” A single : would have been the obvious choice, but it was already spoken for — in Haskell : is the list-cons operator — so the type annotation had to take the double. Read f :: A -> B as “f has type $A \to B$,” and you are reading the mathematics.

Here is the smallest honest example:

double :: Int -> Int
double n = n * 2

The first line is the type; the second the definition. And I do mean mapping, not procedure. double is not a recipe of steps that mutate something on the way to a result — it is the mathematical object that associates each Int with another, no more alive than the function $x \mapsto 2x$ on a chalkboard. Feed it 21 and you get 42, today, tomorrow, on every core, with nothing else happening anywhere. That last clause has a name: purity. Same input, same output, no side effects, no hidden state read or written.

If you build hardware you already own the mental model, and it is worth stating loudly because it is load-bearing for everything Clash does:

A block of combinational logic is a pure function of its inputs.

A truth table is literally $f : \text{inputs} \to \text{outputs}$: same inputs, same outputs, every time, no memory of what came before — that is purity, in gates instead of lambda calculus. It is the whole reason a functional language can describe a circuit at all: your design’s combinational core and a pure Haskell function are the same kind of object, and Clash is the compiler that notices.

A quick tour of categories

Once functions are arrows, the natural question is: what do you actually do with them? Strip it down and there are exactly two moves.

The first is composition. Given $f : A \to B$ and $g : B \to C$ — the target of the first matching the source of the second — you run them nose to tail and get a single arrow $A \to C$. Mathematicians write it $g \circ f$ (“$g$ after $f$”); Haskell writes it g . f, a single dot:

-- (.) :: (b -> c) -> (a -> b) -> (a -> c)
pipeline = decode . validate . receive

Read that right to left: receive, then validate, then decode. The comment is just the arrow-matching rule spelled out — give . an arrow b -> c and an arrow a -> b, and it hands back the composite a -> c. If you have ever built a datapath as a chain of stages, each feeding the next, you have built exactly this.

The second move is humbler still: the identity, a do-nothing arrow $A \to A$ that hands its input straight back. It sounds too trivial to mention, but it is the neutral element that makes composition well-behaved — the wire from a stage to itself.

Those two ingredients, plus two laws, are the entire definition of a category: some objects, arrows between them, a way to compose arrows whose ends line up, and an identity arrow on every object, subject to

$$ f \circ \mathrm{id} = f = \mathrm{id} \circ f $$

$$ (h \circ g) \circ f = h \circ (g \circ f) $$

The first law says the identity truly does nothing; the second says composition doesn’t care how you parenthesise a chain — only order matters, not grouping. That is the whole axiom set. There is no third page.

Now the part that trips people up. Sets with functions between them do form a category — objects are sets, arrows are functions, composition the ordinary $g \circ f$ — and it has a name, Set. Haskell types with functions form another. So it can sound like categories are just “sets, restated.” They are not.

Here is a category with no sets and no functions in sight. Take any preorder — a set with a $\le$ relation that is reflexive and transitive, like divisibility on the integers. Make the elements the objects, and draw one arrow $a \to b$ precisely when $a \le b$. Composition? If $a \le b$ and $b \le c$ then $a \le c$: that transitivity is the composite. The identity? $a \le a$: reflexivity. The laws hold for free, and you have a category in which an “arrow” is not a mapping of anything — it is a fact, that one thing sits below another.

That is the honest version of the “superset” story. Category theory does not contain set theory — Set is one example among many. It steps back from what the objects are made of — sets, integers, types, states — and studies only the pattern they share: things, arrows, and a law-abiding notion of composition. Forget the elements; keep the plumbing.

You need none of this to type a . into a Haskell file. But it buys the right mental model for the rest of this post:

Composition is the primary verb.

A type signature full of -> is not a scary pile of punctuation. It is a chain of arrows, and your job when reading Tamal is usually just to see where each arrow starts, where it ends, and how they snap together.

Arrows in a row: currying

If a function is one arrow from one input to one output, here is a puzzle. Why does addition have two arrows?

add :: Int -> Int -> Int
add x y = x + y

addFive :: Int -> Int
addFive = add 5

The resolution is a single rule: -> associates to the right. So Int -> Int -> Int secretly means Int -> (Int -> Int) — “give me an Int, and I hand you back a function of type Int -> Int.” add does not take two arguments at all: it takes one Int and returns a function still waiting for the second. Every Haskell function takes exactly one argument; the multi-arrow signatures everywhere are sugar for this chain. The trick has a name — currying, after Haskell Curry, who also lent the language its first name.

The payoff is that you can stop halfway. add 5 is a complete value — the function that adds five to whatever comes next. Supplying some arguments now and the rest later is partial application, and addFive is exactly that.

The hardware reading is direct, and worth holding onto:

Partial application is a circuit family parameterised by configuration.

Fix the configuration bits now; feed the data later. add 5 is the adder with one operand strapped to a constant — a specialized block carved out of a general one. You will see this shape all over Tamal: the ALU’s signature alu :: AluOp -> BitVector 32 -> BitVector 32 -> BitVector 32 reads left to right as “pick an operation, then hand me two 32-bit operands, and I’ll give you a 32-bit result.” Thanks to currying, alu Add is already meaningful on its own — the two-operand adder, carved out of the general ALU by pinning the opcode. Configuration first, data second, all the way down.

Types as data: algebraic data types

Now the syntax you will meet more than any other: data, the keyword that builds new types. Haskell’s are called algebraic data types, and the name is a promise about how they are built — from two operations you already know, even if never by these names.

Start with the simpler one, the sum type. Each | is an alternative — read it as “or”:

data Color = Red | Green | Blue

A Color is Red or Green or Blue, and nothing else. This is a C or Rust enum, and if that were all you ever used it for it would already earn its keep. Tamal’s engine lifecycle is exactly this shape — a Phase that is Idle or Preamble or Fetch or one of a handful of other named states, the FSM’s state register written as a type.

The other operation is the product type, better known as a struct or record — a bundle that holds one field and another and another:

data Point = Point { x :: Int, y :: Int }

A Point carries an x and a y, both at once. The record syntax throws in a gift: each field name is also an accessor function. Write that data and you get x :: Point -> Int for free, no boilerplate. Tamal’s engine state is one big record of this kind, a State { phase, pc, regs, ... } threaded through every step — program counter, register file, current phase, all in one value.

Constructors are allowed to carry data, which is where sum and product combine into something sharper than a C enum:

data Shape
  = Circle Double
  | Rectangle Double Double

A Shape is either a Circle carrying one Double (its radius) or a Rectangle carrying two (width and height). The tag and its payload travel together — and, as the next section shows, you cannot reach the payload without first checking the tag. A Rust programmer will recognize this immediately; it is a data-bearing enum.

So why “algebraic”? Because you are literally doing arithmetic on types. A sum adds possibilities; a product multiplies them. Count the inhabitants and the algebra is exact: $|A + B| = |A| + |B|$ for a sum, and $|A \times B| = |A| \cdot |B|$ for a product. Bool has 2 values; the pair (Bool, Bool) has $2 \cdot 2 = 4$; Either Bool Bool has $2 + 2 = 4$. That counting is no party trick — it is exactly why the compiler can tell whether you have handled every case, which matters a great deal for state machines.

One member of the family deserves special mention, because it is how Haskell abolishes the null pointer:

data Maybe a = Nothing | Just a

Maybe a has two constructors: Nothing, carrying no data, or Just, carrying an a. It is the type of “a value that might be absent” — but the absence lives in the type, out in the open. There is no null a hiding inside an ordinary a waiting to segfault you; if a value might be missing, its type says Maybe, and you can’t use it as a bare a — you have to pattern-match, and if you skip the Nothing case the build warns you, by name, before you ever run it. In Tamal a step returning a Maybe Ring states a fact about hardware: at most one trace-RAM write happens this cycle — zero or one, never a smuggled “sometimes.” A write-enable line, promoted to a type.

Taking types apart: pattern matching

If data is how you build a value, pattern matching is how you take one apart — and it is the mirror image, constructor for constructor. The tool is the case expression:

area :: Shape -> Double
area s = case s of
  Circle r      -> 3.14159 * r * r
  Rectangle w h -> w * h

Read case s of as “look at which Shape s actually is.” If it was built with Circle, the first branch fires and binds r to the radius packed inside; if Rectangle, the second binds w and h. This is the “you can’t get the payload without checking the tag” rule made concrete: the only route to r is to match Circle r, and inside that branch the compiler knows a radius is there.

When a function is nothing but one case on its final argument — which is most of the time — there is a shorthand that drops the ceremony, \case:

area' :: Shape -> Double
area' = \case
  Circle r      -> 3.14159 * r * r
  Rectangle w h -> w * h

Same behaviour, one fewer name to invent; \case is “a function that immediately pattern-matches on the argument I didn’t bother to name.” You will see it constantly in Tamal — most of the gateware’s logic is a match on some state or opcode.

Here is the part that should make a hardware engineer sit up straight. The compiler does exhaustiveness checking: if your case over a sum type leaves out a constructor, you get a warning pointing at the exact one you missed. Now recall that a Phase is a sum type and the engine’s next-state logic is a case over it. That means the question every FSM review is supposed to ask —

Did you handle every state?

— is answered by the compiler, on every build, for free. Add a new Phase and forget to wire it into the next-state logic, and the build tells you before you run a test, let alone open a waveform. It is the most boring flavour of formal-ish guarantee, and one of the most valuable: a whole category of “unhandled state” bugs surfaces at build time instead of in a waveform.

Types with behaviour: typeclasses and `deriving`

The last piece of everyday syntax is how Haskell attaches behaviour to types. A typeclass is an interface — a named set of operations a type can choose to support:

class Eq a where
  (==) :: a -> a -> Bool

This declares Eq, the class of types whose values can be compared: an Eq must supply a == taking two of its values and returning a Bool. A concrete type opts in with an instance — the actual == for Int, for Color, for whatever. If you write Rust this is a trait; in modern C++, a concept. What it is not, despite the keyword, is an object-oriented class: no fields, no constructors, no inheritance tree, no this. A typeclass is a contract a type satisfies, not a box a value lives inside.

Typeclasses exist to enable bounded polymorphism — one function that works for any type, provided it supports the operations you need. The signature carries the requirement:

elem :: Eq a => a -> [a] -> Bool

Read the => as a constraint arrow: “for any type a that is an Eq, elem takes an a and a list of a and says whether the value is in the list.” The part before => is a precondition on the caller — given that a can be compared — and the part after is the ordinary type. elem does not care whether a is Int or Color; it only asks that == exist.

Which brings us to the incantation stapled to nearly every data declaration in Tamal:

data Phase = Idle | Running | Halted
  deriving stock (Generic, Show, Eq, Enum, Bounded)
  deriving anyclass (NFDataX)

deriving is the compiler offering to write the boring instances for you, so you never hand-roll a == that just compares constructors. The list looks like noise the first time; here is what each name buys, so it stops looking like noise:

Show — the type is printable, so a failing property test can show you the exact value it choked on.
Eq — values can be compared with ==.
Enum and Bounded — “list me every constructor, in order,” which is exactly what an exhaustive test over all Phases needs.
Generic — a structural, machine-readable description of the type that other libraries build on top of; plumbing, rarely read by humans.
NFDataX — the one that is really about hardware. It is Clash’s way of saying this type is allowed to sit in a register — that its values, including “undefined at power-up,” are well-defined enough to be stored in a flip-flop.

The stock versus anyclass split is only which machinery writes the instance — a built-in strategy for the classic classes, a generics-based one for NFDataX. It is a detail you will copy more often than you think about. The takeaway: a wall of deriving atop a Tamal type is not doing anything deep — it is the compiler filling in equality, printing, enumeration, and “fits in a register,” so the author didn’t have to.

Types that count: widths in the type

Here is the feature that startles newcomers most, and delights them shortly after: in Clash, numbers can live in types.

x     :: BitVector 32   -- exactly 32 bits
lanes :: Vec 4 Bit      -- exactly 4 elements
i     :: Index 5        -- a value 0..4, and never 5

The 32, the 4, and the 5 are not runtime values or comments. They are part of the type, checked at compile time like everything else. BitVector 32 is the type of exactly-32-bit vectors — not “up to 32,” not “32 by convention,” exactly 32. Vec 4 Bit is a vector of exactly four bits. Index 5 is a number in the range 0..4 and, by construction, never 5 — the natural type for an index into something with five slots.

Because the width is in the type, the compiler enforces it. You cannot index past the end of a Vec 4, because the index type will not let the out-of-range value exist in the first place. You cannot wire a BitVector 4 into a port expecting a BitVector 8; they are different types and the mismatch is a compile error. The clean way to say what that buys you:

The compiler is a wire-width checker.

Anyone who has written RTL knows the dread here. In Verilog a width mismatch is not an error — it is a silent zero-extension or, worse, a silent truncation you discover three days later as a dropped high bit. In Clash the same mistake is a type error, reported by name, before you run a single test. Tamal leans on this everywhere: an Unsigned AW, where AW is the address width, carries the program-counter size in the type; an Index 5 pins a five-state micro-FSM step to exactly its five legal values. A whole class of off-by-one-bit bugs never makes it past the compiler — a strictly better place to catch them than a logic analyzer.

From pure functions to hardware: `Signal` and `mealy`

Everything up to now has been combinational: pure functions, inputs to outputs, no memory. But hardware has clocks, and sequential logic needs a notion of time. Clash spells time with a type called Signal:

counter :: Signal dom (Unsigned 8)

Read Signal dom a as “a value of type a that may change on every clock tick, in clock domain dom.” It is an endless stream — one sample per cycle, across all of time — which is precisely what a wire is once you stop looking at a single instant and watch it over the whole run. The dom parameter names the clock domain, so the type system can stop two clocks from crossing by accident; for reading Tamal you can mostly gloss it as “the clock.”

The bridge from the pure world to the clocked one is a single function, mealy:

-- mealy :: (s -> i -> (s, o)) -> s -> (Signal dom i -> Signal dom o)
step :: State -> Input -> (State, Output)

Look past the parameters and the shape is simple. You write an ordinary, pure step function — current state and input in, next state and output out — plus an initial state. mealy takes those two things and hands back a function on Signals: a real register holding the state, clocked, with your step function as its next-state and output logic. That is a textbook Mealy machine, which is where the name comes from, and it is the heart of the design — Tamal’s engine is, quite literally, mealy stepM initState.

This is the punchline behind the introduction post’s claim that its tests run in under a second. stepM is just a function — State and Input in, new State and Output out, pure, no clock, no simulator — so you can hammer it with thousands of property tests in milliseconds against a reference model, and only after you trust it does mealy make it hardware. The pure core is the part you test; mealy is the thin bridge to silicon. We’ll pull that thread in the block posts; for now it is enough to spot the mealy at the top of a module and read it as “clocked state machine, its brain the pure function beside it.”

Where to go next

That is the whole toolkit. Look back at what you can now read without flinching: a Tamal type signature is $f : A \to B$ with the widths written into the types; a data block is sums and products, with Maybe for the things that might be absent; a case or \case takes those values apart, exhaustively, with the compiler checking your work; the stack of deriving clauses is the compiler filling in equality, printing, enumeration, and “fits in a register”; a BitVector n or an Index n is a wire whose width the type system guards; and the mealy at the top of a module is a clocked state machine wrapped around an ordinary, testable function.

None of that is the interesting part of Tamal. It is the syntax you had to stop tripping over so the interesting part could show through. Next in the series we do exactly that: open a single block and read it end to end, top to bottom, no hand-waving. I’ll start with a gentle one — the CRC unit, or the UART, something small enough to hold whole in your head — now that the Haskell is no longer standing between you and the hardware. Bring the mental model of arrows snapping together; that is most of what you will need.

Tamal: an eSPI exerciser

2026-07-13T09:00:00+00:00

mole is an FPGA bit-cycle engine for exercising I²C and I³C — you write a little program, it drives the bus edge by edge, legal or illegal, and hands you back a structured trace of what happened. Tamal is that same idea aimed at a different, meaner bus: Intel’s Enhanced Serial Peripheral Interface (eSPI, base spec rev 1.0).

The one-line pitch, which is the vision more than the current state:

A programmable eSPI controller/target that turns compliance testing into a reproducible, fully-observable, byte-for-byte deterministic exercise.

Read that as the destination, not the odometer. Tamal is experimental — I’m keeping that adjective on it until it has withstood considerable real-world load, at which point I’ll drop it. Today it plays eSPI controller only (target role is designed but not built), at a single 20 MHz clock (all eSPI speeds are on the roadmap), and everything below the honesty line near the end of this post runs in simulation, not on silicon.

This post is what Tamal is, why it’s shaped the way it is, why the gateware is written in Haskell of all things, what I’ve learned building it — and, honestly, how early it still is. The repo is github.com/felipebalbi/tamal, public and split-licensed. Read on before you clone it expecting a finished product; it isn’t one yet.

The problem

eSPI is the bus that replaced LPC on modern platforms: a short, fast-ish serial link between a chipset/SoC and an embedded controller, flash device, or BMC. It’s more capable than it looks. A single eSPI link multiplexes four logical channels — Peripheral, Virtual Wire, OOB (tunneled SMBus), and Runtime Flash Access — over one set of pins, with command/response framing, turnaround phases, CRC, alerts, and a status register that gates who’s allowed to talk.

That density is exactly what makes it hard to test. “Does my eSPI target behave correctly?” is not one question. It’s: does it honour turnaround timing, does it respect CRC when enabled, does it track the status register, does it tolerate a WAIT STATE, does it drive alerts correctly, does it decode each channel’s packets, and — the part almost nothing can produce on demand — does it do the right thing when the other side does the wrong thing?

Producing a legal transaction is the easy 20%. Producing a specific illegal one — a deliberately short turnaround, a corrupted CRC, a truncated packet, a cycle on a channel that isn’t enabled yet — at a precise moment, reproducibly, over and over, is the 80% that a real device or a canned test fixture can’t give you. That’s the gap Tamal is built to fill: an exerciser that will drive any cycle, correct or malformed, with deterministic timing, and capture everything the bus did in response.

The name

eSPI wraps four logical channels into one serial packet stream. A tamal is a wrapped, layered dish — masa and filling folded inside a husk. The mapping wrote itself: eSPI wraps Peripheral, Virtual Wire, OOB, and Runtime Flash Access into one stream of bytes on the wire; Tamal is the thing that unwraps every layer and checks it against the spec. Naming projects is one of the few unambiguous joys of this line of work, and the mole → tamal lineage (both wrapped, both Mesoamerican, both about what’s hidden inside) was too good to pass up.

The key insight

The temptation with an FPGA bus tool is to think of it as a throughput problem — get the bytes on and off the wire fast enough. eSPI defeats that framing immediately, and in a useful way:

This is not a throughput problem. It is an external timing alignment problem.

eSPI tops out at 66 MHz. On an Artix-7 that’s slow; the fabric runs at 100 MHz and never breaks a sweat pushing bits. The danger isn’t speed. It’s that in target role — which Tamal is designed for but does not yet play — you are not the clock master: the eSPI clock is driven by the device under test, and you must respond relative to it. The parts that will actually hurt you are turnaround/tri-state timing, setup and hold against an external clock, and getting IO direction control exactly right on a shared, bidirectional data bus. None of that is about going fast. All of it is about being aligned.

Internalizing that reframed the whole design. The engine doesn’t need to be clever or quick. It needs to be precise about when it drives, when it samples, and when it lets go of the pins.

The shape: three planes

Tamal has a clean split into three planes, and almost every design decision falls out of which plane it belongs to:

Control plane (host → FPGA): load a compiled test program, select role (controller today; target is designed but not yet built), IO mode (single/dual/quad), CRC on or off, and triggers. Error injection isn’t a knob here — it lives in the program, where the test author writes the malformed cycle directly (more on that below).
Bus plane (FPGA ↔ DUT): the eSPI link itself — CS#, CLK, IO[3:0], ALERT#, RESET# — driven or sampled against the device under test.
Trace / result plane (FPGA → host): observed transactions, channel decode, captured cycles, and verdicts.

There’s one load-bearing rule that spans the planes: never block the bus on trace backpressure. If the host can’t keep up draining the trace, the bus plane does not stall waiting for it — events get dropped with an overflow marker instead. A test rig that perturbs the timing of the thing it’s measuring is worse than useless, so the trace plane is always allowed to lose data before the bus plane is allowed to hesitate.

On the FPGA, that shape is deliberately boring:

 host ──UART──► loader ──► instr BRAM ──► engine (mealy step) ──► eSPI pads
      ◄─UART──── drain  ◄──── ring BRAM ◄──────┘   (IO[3:0], CS#, SCK,
                                                     RESET#, ALERT#)

The host ships a compiled program over UART; the loader writes it into an instruction block RAM; the engine executes it as a Mealy machine, driving and sampling the eSPI pads; every transaction lands in a trace ring (another block RAM); on HALT the drainer sweeps the ring back out over the same UART.

The whole thing is one clock domain — Dom100, 100 MHz — with no clock-domain crossings and no FIFOs. The trace ring BRAM is the buffer, and UART is roughly 500× slower than the fabric, so there’s nothing to gain from a FIFO in front of it. (On the Cyclone V board a 50 MHz oscillator is multiplied up to 100 MHz by an Altera PLL, but it’s still a single design domain.) Fewer moving parts, less to get wrong, and — this matters later — a design that simulates end to end without any special-casing.

The repo

Two toolchains, cleanly separated:

crates/                 Rust host tooling (Cargo workspace)
  tamal-abi/            bytecode/ISA encoding + COBS/CRC-8 wire format + typed trace decode
  tamal-asm/            assembler: RISC-V-flavored source -> tamal bytecode
  tamal-asm-cli/        `tamal-asm` binary (clap front-end)
  tamal-loader/         host-side loader: load -> trigger -> drain over a transport
  tamal-loader-cli/     `tamal-loader` binary
hdl/                    Clash gateware + Vivado/Quartus build (self-contained)
docs/                   design specs + implementation plans

tamal-abi is the crate that matters most: it’s the ABI, the single source of truth for the bytecode encoding, the COBS/CRC-8 wire format, and the typed trace decode. Everything else — assembler, loader, gateware — agrees with tamal-abi byte for byte or it’s a bug. It is deliberately transport-agnostic: v1 speaks UART because that’s what the Arty’s FT2232 gives you (USB-UART plus JTAG, not a USB3 SuperSpeed FIFO), but the wire format doesn’t know or care, so a future EZ-USB FX3 (GPIF II slave-FIFO) shield can be bolted on as another backend without touching the ABI.

The licensing follows the crates/ ↔ hdl/ seam. The Rust host tooling is MIT. The Clash gateware is CERN-OHL-W-2.0 (CERN Open Hardware Licence v2, Weakly Reciprocal), because an open-hardware licence fits a hardware description better than a software licence does. Every .hs file under hdl/ carries a REUSE-style SPDX header to make that boundary machine-checkable.

A RISC-V-flavored ISA, and a very dumb engine

Tamal’s on-FPGA engine is programmable, and the instruction set is inspired by — but not compatible with — the RISC-V 32-bit (RV32I) ISA.

From RV32I it borrows the ergonomics: 32-bit fixed-width instructions; a 32-name register space x0..x31 with x0 hardwired to zero (v1 implements 16 physical registers, with x16..x31 aliasing their low-4 twin); the R/I/S/B/U/J instruction formats; and the ABI register names (zero, ra, sp, t0, s0, a0, …). The assembler follows the riscv-asm-manual conventions for directives, labels, and pseudo-instructions — but follows is doing real work in that sentence. What’s implemented today is the subset the examples exercise (.text, .globl, .equ, the li pseudo-instruction, symbolic labels, the branch mnemonics). The rest of the RISC-V surface I’d like to have — .align, .macro, numeric local labels (1f/1b), mv/j/call/ret/beqz and friends — is intended but not written yet. If you’ve used RISC-V assembly the current subset will read like home; just don’t assume the whole manual works.

Where it diverges is the opcode space: Tamal repurposes and extends it with bus-domain instructions for eSPI work — driving and sampling cycles, per-channel operations, deterministic timing, author-written error injection, and capture/verdict. The upshot is a hard rule: Tamal bytecode is not interchangeable with a stock RISC-V toolchain, and the project never claims otherwise. It’s RISC-V-flavored, not RISC-V.

The design decision I’m happiest with is how little the engine knows. The engine is a nearly-dumb SPI shifter with almost no eSPI knowledge. There is no “PUT_IORD” opcode and no notion of a channel. The one concession is a CRC-8 unit that runs over incoming bytes, so a program can read the residue and decide whether a packet from the link partner was valid — but even it has no idea what a “packet” is, and every outbound CRC byte is still computed by the host. The host builds every byte that goes on the wire — command, header, payload, TX CRC — and the engine just shifts them out and shifts responses back. All the eSPI semantics live in the program, in software, where they’re easy to read, easy to change, and easy to get deliberately wrong.

The shape of a program

The smallest interesting program reads one byte from an eSPI Peripheral-channel I/O port. Here’s the real peripheral_io_read.s from the repo, reading I/O port 0x64 — the classic 8042 keyboard-controller status port:

    .equ  PUT_IORD1,      0x44    # PUT_IORD_SHORT, length = 1 byte
    .equ  RSP_WAIT_STATE, 0x0F    # eSPI WAIT_STATE response code
    .equ  VERDICT_OK,     0x00    # host verdict codes (written by halt)
    .equ  VERDICT_CRC,    0x11

    .text
    .globl _start
_start:
    set_config CONTROLLER, X1, SCK20, ALERT_PIN   # controller, x1 IO, 20 MHz
    cs_assert                       # begin frame: CS# low

    # --- command phase: host-built eSPI packet ---
    put_byte PUT_IORD1              # CMD:  PUT_IORD_SHORT (1 byte)
    put_byte 0x00                   # addr [15:8]
    put_byte 0x64                   # addr [7:0]  -> I/O port 0x64
    put_byte 0x16                   # TX CRC-8 over the 3 bytes above (poly 0x07)
    tar 2                           # legal turnaround; tar 3 / tar 1 = deliberate violation

    # --- response phase: WAIT_STATE poll + RX CRC residue verdict ---
poll:
    crc_reset                       # drop any prior WAIT_STATE byte from the residue
    get_byte t0                     # response code (auto-updates RX CRC-8)
    li   t1, RSP_WAIT_STATE
    beq  t0, t1, poll               # WAIT_STATE -> keep polling
    get_byte t0                     # read data byte (port 0x64 value)
    get_byte t0                     # status [7:0]
    get_byte t0                     # status [15:8]
    get_byte t0                     # trailing CRC byte -> drives residue to 0
    rdsr t2, CRC                    # RX CRC-8 residue (0 == good packet)
    cs_deassert                     # end frame: CS# high
    bnez t2, bad_crc
    halt VERDICT_OK
bad_crc:
    halt VERDICT_CRC

Read it top to bottom and the whole model is visible. set_config picks controller role, single (x1) IO, a 20 MHz clock (SCK20 — the only rate wired up today, though the ISA reserves the field for the faster eSPI speeds still to come), and pin-based alerts. cs_assert pulls CS# low. Then a run of put_bytes spells out the eSPI command packet a byte at a time — opcode, address, and a TX CRC-8 the program computed, not the engine. tar 2 performs a legal turnaround; swapping in tar 3 or tar 1 is how you inject a deliberate turnaround violation — that’s the whole error-injection story, a test author spelling out the malformed cycle by hand, not a probabilistic “corrupt 10% of packets” knob. The response phase polls for WAIT_STATE, reads the data and status bytes, and checks that the RX CRC residue drove to zero — the eSPI-idiomatic way to validate a packet. Finally halt writes a verdict code the host reads back from the trace.

The load-bearing observation: only the command-phase put_bytes are channel-specific. The CS framing, the WAIT_STATE poll, and the CRC residue check are byte-for-byte identical across the Peripheral I/O read, the Virtual Wire example that deasserts PLTRST#, and every other per-channel program in examples/. The channel is just a different run of bytes in the middle. That’s the payoff of a dumb engine: the interesting part of each test is a handful of lines, and everything around it is boilerplate you can read once and stop thinking about.

Why Clash, why Haskell

The gateware is written in Clash — a Haskell-to-RTL compiler — and that’s the choice people ask about first. It looks exotic next to Verilog or even the SpinalHDL that drives mole. The reasons are entirely practical, and they all come back to one thing: iteration speed — how fast the edit-test loop closes. (Not to be confused with eSPI’s turnaround; this is developer seconds, not bus cycles.)

The Tamal test suite runs in under a second. Not the synthesis — the tests. Every pure leaf of the design (stepM, ringWrite, rigState, ledPattern) is a plain Haskell function, and I test them the way I’d test any Haskell function: hedgehog property tests and HUnit unit tests, each pure leaf and the engine keystone checked against a reference model. No simulator to spin up, no waveform to eyeball, no four-minute Vivado round-trip to find out I got a mux backwards. cabal test, a second later I know.

It gets better at the top. Because the whole integration is wired over plain Clash Signals — no BiSignal in the core, the tri-state only appears in the thin board shell — the entire system simulates in Haskell. There’s a whole-system cosim (Test.Top) that serializes a real LOAD_PROGRAM + TRIGGER onto a modeled UART line, runs the actual load → run → drain path, decodes the UART output, and asserts the drained trace (revision header, records, HALT terminator) and the eSPI pin activity — UART → loader → engine → eSPI → ring → drain, end to end, in one test, in the same language as the design, in milliseconds. I can refactor the engine and know within a second whether the full pipeline still behaves. That feedback loop is the single biggest force multiplier on the project.

The type system pulls its weight too. eSPI is a bidirectional, tri-state, direction-controlled bus, which is precisely where hardware bugs love to hide. Having the compiler track widths, states, and pad directions catches a whole class of “which way is this pin pointing this cycle” mistakes before simulation, let alone before silicon.

And the discipline of a single clock domain with no CDC and no FIFOs means the design is small enough to hold in your head — which is what makes the sub-second property testing tractable in the first place. Fast tests and a simple design reinforce each other.

The trade is real and worth stating: Clash is a smaller ecosystem, the error messages can be a wall of type, and the toolchain (GHC 9.10.3 + cabal + Vivado/Quartus) is more to stand up than verilator. For this project, on this bus, that sub-second feedback loop won the argument easily.

Lessons learned

A few things I didn’t know going in, in case they save you some time:

The bus is not the hard part; the pins are. I spent the early design energy worrying about eSPI’s channel matrix and almost none on tri-state timing. That was backwards. Reframing the whole thing as an external timing alignment problem — especially for the not-yet-built target role — is what made the architecture click.
A dumb engine is a feature. Every time I was tempted to teach the engine more eSPI (“just let it build the TX CRC too”, “just add a channel register”), pushing it back up into the host program made the design smaller and made illegal-cycle injection trivial. Malformed packets are free when the host builds every byte. (The one place I gave in — an RX-side CRC-8 so a program can check an inbound residue — earns its keep precisely because it stops at checking and never learns what a packet is.)
Clash’s tri-state lowering has sharp edges. Four scalar inout lanes (io0..io3) exist instead of a tidy Vec because Clash fuses a per-lane BiSignalIn/BiSignalOut pair into one inout port — but a Vec of BiSignals does not; it silently lowers to a plain input. That one cost me an afternoon.
The no-reset power-up design is deliberate. The top ties reset permanently de-asserted and relies on power-up init, so Clash emits no reset port at all — matching the sibling Clash examples. Fighting that to add a “proper” reset is a trap.
Some ghc-options are load-bearing. The common-options in tamal.cabal aren’t optional style — Clash needs them. Trimming them to tidy up breaks codegen in non-obvious ways.

What’s running today — and what isn’t

Now the honest part, because this is the whole reason for the experimental label I put on it up top.

Gateware: v1 complete, in simulation. The full pipeline exists and is tested in Clash — the RISC-V-flavored cycle engine, the instruction and trace-ring block RAMs, the COBS/CRC-8 wire format, the UART load/drain loader, the tri-state eSPI pad boundary, and the topEntity that wires it all to the Arty A7 pins. The whole-system cosim streams a program in and checks the drained trace end to end. cabal run clash -- Tamal.Board.ArtyA7 --verilog emits a synthesizable top, and cd hdl && make builds a bitstream. But v1 is controller role, single (x1) IO, one 20 MHz clock rate, UART transport, and it has not yet been brought up on real hardware. Simulation-complete is a real milestone; it is not the same as “works on the bench.”

Host tooling: v1 implemented and tested. The Rust ABI, assembler, and loader are built and mirror the gateware’s wire and bytecode contract byte for byte. The live serial path is exercised on hardware rather than in CI, and the pass/fail conformance verdict engine — the thing that would let Tamal actually render a compliance judgment — does not exist yet. Today a program ends in a HALT/TRAP with a host-defined verdict code; a real conformance catalog is a later phase.

So, plainly: Tamal is early. What it most needs next is validation against real eSPI scenarios — on real silicon, against real targets, with a logic analyzer confirming the timing the simulator promises. Until on-hardware bring-up lands, every claim in this post about what the bus does is a claim the model makes, and models are exactly the thing an exerciser exists to distrust.

The roadmap is four phases:

Link + transaction bring-up. SPI-style framing, command/response/turnaround, Get Status / Get Configuration, CRC; controller role over single IO. (This is where v1 sits — done in sim, next on hardware.)
The four channels. Peripheral, Virtual Wire, OOB (tunneled SMBus), Runtime Flash Access; the ISA, assembler, and loader path; result streaming.
Target role, alerts, dual/quad IO, faster clocks. The external-timing-alignment problem in full: responding to a clock you don’t own, and driving the higher eSPI speeds beyond today’s 20 MHz.
Determinism and verdicts. The error-injection model stays what it is today — the test author writes the malformed cycle by hand, so a program is byte-for-byte reproducible by construction — joined by the verdict engine and a conformance catalog that turn a captured trace into an actual pass/fail judgment.

Where to look

The source is on GitHub. The gateware’s story is in hdl/README.md and hdl/PLAN.md; the design specs live under docs/; AGENTS.md is the fastest orientation to how the pieces fit. The examples/ directory is the best way to get the feel of the ISA — start with smoke_halt.s, then peripheral_io_read.s, then the per-channel programs.

It’s early, it’s promising, and it’s exactly the stage where design critiques are most useful. If you know eSPI — especially its nastier corners — I’d love to hear where this is wrong before it meets silicon.

From 'it works' to 'I trust it': two torture loops on a NOR driver

2026-06-28T09:00:00+00:00

The FlexSPI NOR driver for the NXP MCXA5xx already worked. The blocking self-test was green, the examples ran, I could erase a sector, program a page, read it back, and watch the same bytes come out of the memory-mapped window. By the usual bar for “the driver works,” it worked.

That bar is too low. A driver that passes its own happy-path self-test has demonstrated exactly one thing: that it can succeed when nothing goes wrong. It has said nothing about what happens when an async operation gets cancelled half a microsecond into a command shift, or when a caller does a partial-page write at an address the controller quietly dislikes. The distance between “it works” and “I trust it” is made entirely of those questions, and you don’t answer them by running the happy path again.

You answer them by building something whose only job is to be nasty to the driver and to notice when the driver flinches. This post is about two such things — a pair of self-checking soak rigs for the embassy-mcxa FlexSPI driver — and the two bugs they caught on the way. The work landed in embassy-rs/embassy#6389, validated on an FRDM-MCXA577 with its on-board Winbond W25Q64 (8 MiB), and it builds on the register-level fixes (AHBCR, DLLCR, FLSHCR2) from #6386 — more on how those got found in a moment, because it was the same rig.

What a torture loop has to be

A soak test that only loops the happy path faster is not a soak test; it’s a slow way to confirm what you already believed. To actually buy trust, the loop has to have a few properties, and getting those properties right was most of the work.

It has to be adversarial: every round erases a fresh window, programs it with randomly-sized, randomly-placed sub-page writes and full pages, and then reads it back through two independent paths — the IP command path and the memory-mapped AHB window — asserting they agree with each other and with the pattern it wrote. A bug that lives in only one path can’t hide when the other path is watching.

It has to be reproducible: every round is driven by a logged xorshift seed, so a failure three hours in isn’t a ghost — it’s a seed I can replay from a clean boot.

It has to protect itself from itself: a torture loop that programs random addresses is one off-by-one away from scribbling on the sector it’s verifying, or wearing a single sector to death. So the window rotates by a prime stride to spread wear, a per-sector erase budget caps the damage, a wall-clock limit ends the run, and a never-erased canary sector sits off to the side. If a wild write ever lands in the canary, the canary stops matching, and I learn that the driver wrote somewhere it was never told to.

Stripped of the bookkeeping, each round looks like this:

loop {
    let seed = rng.next();          // logged, so any failure replays
    let window = next_window(seed); // prime-stride rotation, wear-spread

    erase(window)?;
    verify_erased(window)?;

    for write in random_writes(seed, window) {
        program(write.addr, write.bytes)?;
    }

    // The load-bearing assertion: two independent read paths must
    // agree with each other and with what we wrote.
    assert_eq!(read_ip(window),   expected(seed));
    assert_eq!(read_mmap(window), expected(seed));

    assert_canary_intact()?;        // nobody wrote where they shouldn't
    if elapsed() > LIMIT { break; }
}

The first time I pointed this at the driver, it didn’t get to a clean round. The IP path and the memory-mapped path disagreed, which is how the AHBCR.AFLASHBASE addressing bug surfaced — I fixed that separately in #6386 before any of the rest of this made sense. With that fixed, the rig got much further, and then found something stranger.

What it found first: the byte before the write keeps going to zero

The failure was small and specific, which is the worst kind. Most rounds were clean. But on rounds where the random writes happened to place one sub-page write starting at an address with addr % 8 of 5 or 7, and another write followed in the same page, the byte immediately before the second write’s start address came back as 0x00. Not the bytes I wrote — those were fine. The byte before them, which I hadn’t touched in that operation at all.

My first assumption was that I had a bug in the FIFO-fill loop: an off-by-one in how the driver packs the caller’s buffer into the controller’s TX FIFO. I went and read that loop very carefully, then did the thing I should have done first and diffed it, byte for byte, against NXP’s FLEXSPI_WriteBlocking in their SDK. It was identical. The driver was filling the FIFO exactly the way the vendor does.

That reframed the whole problem. If the loop is byte-identical to the reference and the reference is trusted, the corruption isn’t in the loop — it’s in the controller’s handling of an unaligned write boundary between two consecutive writes in a page. A single write of any length, at any alignment, is fine. It’s specifically the seam between two sub-page writes when the second one starts unaligned that the IP mangles. This is a controller alignment quirk, and no amount of re-reading my code was going to fix a property of the silicon.

So the fix isn’t to make the unaligned write work — it’s to make the unaligned write impossible to ask for, loudly, instead of letting it silently corrupt an adjacent byte. page_program now enforces a write-size contract: the start address and the length must both be 8-byte aligned, and the write must stay within a single page. Anything else returns an error before a single byte reaches the flash.

// The 8 is a property of the FlexSPI IP/DMA FIFO window,
// not of the flash chip. Name it so nobody "optimizes" it away.
const WRITE_GRANULARITY: usize = 8;

fn check_program(addr: u32, len: usize, flash_size: u32) -> Result<(), IoError> {
    if addr as usize % WRITE_GRANULARITY != 0 || len % WRITE_GRANULARITY != 0 {
        return Err(IoError::Misaligned);
    }
    match addr.checked_add(len as u32) {
        Some(end) if end <= flash_size => {}
        _ => return Err(IoError::OutOfBounds),
    }
    // ...plus the single-page check...
    Ok(())
}

Two things made this an easy call rather than a regression. First, it’s the exact granularity the DMA write path already required (len % 8 == 0), so the async/DMA side of the driver had always lived under this contract — I was only making the blocking side honest about it. Second, it maps cleanly onto embedded-storage’s WRITE_SIZE model, so a future trait impl falls out naturally rather than fighting the contract. The same pass also bounds-checks read, erase_sector, and program against the configured flash size, returning IoError::OutOfBounds instead of wrapping around. Both new variants went onto an already #[non_exhaustive] IoError, so none of this breaks callers — the only behavioural change is that a sub-page write now has to align to 8 bytes, where before it would silently eat the byte next door.

Partial-page writes still work. They just work at 8-byte granularity, the way the hardware can actually deliver them. I updated the bundled examples to match (a 100-byte partial write became 96; the stress example’s program sizes got rounded to multiples of 8), which was a nice forcing function for confirming the contract was livable and not just defensible.

Pushing the same idea at the async path

The blocking driver was now hardened and soaked. But the interesting half of an Embassy driver is the async half, and async brings a failure mode that blocking code simply doesn’t have: cancellation.

In async Rust, the idiomatic way to bound an operation is to wrap it in with_timeout, or race it in a select!, or cancel the task it runs in. All three do the same thing under the hood: they drop the future mid-flight. The operation was in progress, and now it isn’t, and it never got to run whatever cleanup it might have wanted to run. Any async driver that can’t survive that is a driver with a landmine in it, waiting for the first caller who puts a timeout around a flash write.

So the second rig, flexspi-cancel-soak, does that on purpose, thousands of times. It runs the same erase/program/verify integrity checks over the async + DMA path, and then it does something deliberately hostile: it takes a real operation, wraps it in with_timeout with a delay swept across a wide range — from about a microsecond (mid command-shift, the operation has barely started) out to a couple of milliseconds (mid write-in-progress, the flash is busy) — so the future gets dropped at every interesting phase of the transaction. Then it issues a fresh operation and asserts that one returns correct data.

The elegant part of testing cancel-safety is that you barely need an assertion. A driver that isn’t cancel-safe doesn’t return wrong data after a botched cancellation — it hangs the next operation forever. So the test simply reaching the next round, across thousands of in-flight cancellations, is itself the pass signal. If the rig is still counting rounds, the driver is recovering. If it stops, it wedged.

It stopped.

What it found second: a dropped future wedges the controller

The symptom was a hang, deep in prepare_ip_transfer, spinning in wait_idle() waiting for a sequence engine that was never going to become idle. The diagnosis, once I dumped the controller state at the hang, was clear: the cancelled operation had left the FlexSPI sequence engine non-idle — chip-select still asserted, the TX FIFO in underrun — and the driver had no notion that it should clean any of that up. The next operation walked in, asked the engine to be idle, and waited for a condition that the previous, cancelled operation had made permanently false. One cancelled future, and the controller was bricked until reset.

The fix is to stop trusting that the engine is idle just because the last operation “finished,” and instead make prepare_ip_transfer self-healing. On entry, if the engine isn’t idle — the fingerprint of a previously cancelled op — force it idle with a software reset before doing anything else:

fn prepare_ip_transfer(&mut self) -> Result<(), IoError> {
    // A cancelled op leaves the sequence engine non-idle: CS still
    // asserted, TX FIFO underrun. Detect that fingerprint and recover.
    //
    // One SEQIDLE sample is authoritative here: SEQIDLE only deasserts
    // on a fresh IPCMD trigger, and none is pending at this point.
    if !self.seq_idle() {
        // Force idle, de-assert CS, reset the instruction pointer,
        // flush the FIFOs. The LUT and controller config survive a
        // software reset -- the init path already relies on that.
        self.software_reset();
    }
    self.wait_idle();
    // ...load the IP command, trigger IPCMD...
    Ok(())
}

There’s a deliberate design decision hiding in what this fix doesn’t do. It does not add a timeout. The driver imposes no timeout of its own and keeps embassy-time out of its hot path entirely. Timeout policy — how long is too long, and whether to give up — belongs to the application, which already has with_timeout for exactly that. The driver’s job isn’t to decide the policy; it’s to make the policy safe. The self-healing recovery is precisely what lets a caller wrap any operation in with_timeout without fear: when their timeout elapses and drops the future, the driver un-wedges itself on the next call instead of staying broken. The cancellation that used to be a landmine is now just a thing that happens.

The payoff

With both fixes in, the two rigs ran clean:

flexspi-soak (blocking IP + memory-mapped): 384 rounds, zero mismatches between the IP and AHB paths, and every out-of-contract call — misaligned, page-crossing, out-of-range — returning the error it should.
flexspi-cancel-soak (async + DMA): 388 rounds, 5,044 in-flight cancellations, 3,880 clean recoveries, zero wedges, zero data corruption.

Those 5,044 cancellations are the number I care about most, because every one of them is a with_timeout firing at a moment that, a week earlier, would have bricked the controller until the next reset.

What I’d carry to the next driver

A few things generalize past this one chip:

A happy-path self-test proves a driver can work. It says nothing about whether you can trust it. Those are different claims, and only the second one matters once real callers show up.

Cancel-safety is a first-class property of an async driver, not an edge case. If dropping an in-flight future can leave your peripheral in a state the next operation can’t recover from, you don’t have a working async driver yet — you have one that works until someone uses a timeout. And in Embassy, someone always uses a timeout.

Make illegal states loud. The unaligned write didn’t fail — it succeeded and corrupted a neighbour. A contract that turns “silently wrong” into “loudly refused” is worth more than it costs, every time.

Seed your randomness. A fuzzing soak loop that can’t replay its own failures is a slot machine. The xorshift seed turned “it broke somewhere in three hours” into “it broke on this seed, here’s the repro.”

A note on trusting it

I trust this driver today — on this board, with this flash part, against everything the two rigs throw at it. That’s a real and specific claim, and it’s also a smaller one than “it’s correct.” Both bugs in this post were invisible until the moment a rig was nasty enough to provoke them, and the honest conclusion to draw from that is not that I’ve now found the last one. It’s that the next rig, or the next caller with a workload I didn’t imagine, may well surface something these two didn’t. Soak tests buy confidence proportional to how mean they are, and no finite amount of meanness reaches a proof. If you run this driver and it does something neither rig caught, I’d genuinely like to know — that’s the rig I haven’t built yet.

What this doesn’t cover

The usual caveats, and they’re real ones. This is one board, one flash part, one controller IP. The unaligned-write corruption is a quirk of this FlexSPI block, and I’d be unsurprised if it looked nothing like that on other silicon — the shape of the lesson (diff against the vendor reference; if your loop is identical, suspect the controller) transfers better than the specifics. The driver also doesn’t implement the embedded-storage traits yet, though the write-size contract was designed so it maps straight onto WRITE_SIZE = 8 / ERASE_SIZE = 4096 when it does.

The full set of fixes, the two soak rigs, and the hardware run logs are in embassy-rs/embassy#6389. If you’re bringing up FlexSPI on MCXA, I hope the rigs save you the half-week. If you’re doing it on something else and one of these patterns rhymes with what you’re seeing, I’d like to hear about it.

Pico de Gallo: Release Announcement

2026-06-22T09:00:00+00:00

Pico de Gallo turns an RP2350 into a USB-attached bridge that lets a host program drive real I²C, SPI, GPIO, PWM, ADC, UART, and 1-Wire from std Rust, C, or Python — so you can write and test device drivers on your laptop instead of cross-compiling for an MCU every time. Today’s release moves the whole ecosystem forward at once.

This is a lockstep release. The wire protocol in pico-de-gallo-internal went from schema 0.5 to 0.6, and under the pre-1.0 schema-versioning rule that is a breaking change. Firmware and host must be upgraded together — a 0.10 firmware will reject an older host’s RPCs, and a new host will refuse to talk to old firmware rather than silently mis-decode bytes on the wire. The upgrade notes at the bottom have the full version table.

Most of what landed here comes out of a reliability review that turned up a handful of real bugs: a GPIO wait could wedge the entire firmware dispatcher, a hung handler had no recovery path, GPIO subscriptions leaked when a host process crashed, and a bumped schema major could slip past validation and corrupt decoding silently. Each crate’s share of the fix is below.

`pico-de-gallo-internal` 0.6.0 — the wire protocol

This is the crate every other one depends on, and the breaking schema bump that drives the lockstep.

GpioWaitRequest gained a timeout_ms: u32 field, used by all five gpio/wait-* endpoints (wait-high, wait-low, wait-rising, wait-falling, wait-any). A value of 0 preserves the old wait-forever behavior; a non-zero value bounds the firmware-side wait and returns the new GpioError::Timeout on expiry. This is the wire half of the fix for the dispatcher wedge — a wait on a pin that never transitions used to block every other endpoint until you power-cycled the board.
New system/reset-subscriptions endpoint (request (), response u8 count). GPIO subscriptions are server-side state that outlives the USB transport, so a host that crashed without sending gpio/unsubscribe would strand those pins until a power cycle. This endpoint is the recovery path.

Both changes are append-only on the wire, but the schema-version bump itself is what requires the coordinated upgrade.

`pico-de-gallo-lib` 0.6.0 — the Rust host library

New gpio_wait_for_{high,low,rising_edge,falling_edge,any_edge}_with_timeout methods take a std::time::Duration and return Err(PicoDeGalloError::Endpoint(GpioError::Timeout)) on expiry. The existing two-argument methods keep waiting forever by sending timeout_ms: 0.
New system_reset_subscriptions() method returns the number of subscriptions it reset. The recommended connect sequence is now new() → validate().await? → system_reset_subscriptions().await?.
validate() now checks schema_major in addition to schema_minor. Previously a firmware reporting a bumped major with a matching minor would pass validation and the host would then mis-decode wire bytes — silent garbage out. ValidateError::SchemaMismatch now carries expected_major / actual_major, and its Display shows the full MAJOR.MINOR.x skew.
Fixed: validate() no longer mis-classifies transport, postcard-decode, and frame-size errors as ValidateError::LegacyFirmware. Only the postcard-rpc “no handler for that key” signals (UnknownKey, KeyTooSmall) map to LegacyFirmware; everything else routes to Comms, so you stop being told to upgrade firmware that is already current.
MAX_BATCH_OPS and MAX_TRANSFER_SIZE are now re-exported, so you don’t have to depend on the wire crate just to validate batch sizes.

`pico-de-gallo-hal` 0.6.0 — the `embedded-hal` layer

New Hal::new_validated() and Hal::new_validated_with_serial_number() constructors call validate() before returning, failing loudly on a disconnected device or a schema mismatch. The lazy Hal::new() still defers failures to the first RPC if that’s what you want. A standalone Hal::validate() accessor lets you check after the fact.
New Hal::system_reset_subscriptions() -> Result<u8, SystemHalError> exposes the subscription teardown that previously required dropping down to pico-de-gallo-lib. Recommended right after new_validated() in any app that uses GPIO subscriptions.
New Gpio::wait_for_*_with_timeout inherent async methods accept a Duration and return GpioError::Timeout on expiry. They’re inherent methods rather than trait methods because embedded-hal-async’s Wait trait has no notion of a timeout; the trait methods keep their wait-forever semantics.
AdcChannel, AdcConfigurationInfo, GpioDirection, GpioEdge, and GpioPull are now re-exported — driver authors no longer need pico-de-gallo-lib in their Cargo.toml just for these types.
New HalInitError and SystemHalError types, and a fix for a stale doc-comment that referenced a Hal::uart_set_config method that never existed.

`pico-de-gallo-ffi` 0.7.0 — the C bindings

New gallo_init_strict() and gallo_init_strict_with_serial_number() call validate() internally and return NULL on device-not-found, schema mismatch, or legacy firmware. Prefer these over the lazy gallo_init in production C — failures surface at construct time instead of on the first RPC.
New gallo_gpio_wait_for_{high,low,rising_edge,falling_edge,any_edge}_with_timeout_ms functions. timeout_ms == 0 keeps the wait-forever behavior; non-zero bounds it and returns Status::GpioTimeout (-70). These need firmware schema 0.6+; older firmware returns Status::SchemaMismatch.
New gallo_system_reset_subscriptions() with SystemResetSubscriptionsFailed (-69).
The high-throughput primitives gallo_spi_transfer, gallo_spi_batch, and gallo_i2c_batch are now reachable from C, via the tagged structs GalloSpiBatchOp / GalloI2cBatchOp. On a per-operation failure an optional out_failed_op receives the zero-based index of the failing op. New status codes: I2cBatchFailed (-66), SpiBatchFailed (-67), SpiTransferFailed (-68). The wire protocol is unchanged here — this is pure FFI surface over existing endpoints.
All gallo_* functions now take const PicoDeGallo * for the device handle. The ABI is unchanged, but C consumers that previously cast away const on every call can drop those casts, and headers built with -Wcast-qual stop warning. The handle remains Send + Sync and interior-mutable.

`pyco-de-gallo` 0.4.2 — the Python bindings

New pyco_de_gallo.open_strict() and open_strict_with_serial_number(serial_number) call validate() before returning the handle and raise RuntimeError on device-not-found, schema mismatch, or legacy firmware. Prefer these over the lazy open() in production Python.
New gpio_wait_for_*_with_timeout(timeout_ms: int) methods — 0 waits forever, non-zero raises RuntimeError on GpioError::Timeout. Requires firmware schema 0.6+.
New system_reset_subscriptions() returns an int.

`gallo` (CLI) 0.7.0 — the command-line tool

gallo now calls validate() at the top of every subcommand except list and version. A schema-version mismatch is reported up front with an actionable message that points at gallo version and tells you to re-flash the firmware or install a matching gallo, instead of surfacing as a confusing CommsFailed on the first RPC. list is exempt because it doesn’t touch a connected device; version is exempt because it is the diagnostic that reports schema skew.
Everything else is unchanged. The existing gpio subcommands (get, put, set-config, monitor) keep working. The CLI doesn’t expose gpio wait-for-* subcommands, so bounded waits stay available through the Rust, C, and Python libraries.

`pico-de-gallo-firmware` 0.10.0 — the device

gpio_wait_for_* handlers now honor the per-request timeout_ms. Non-zero values wrap embassy’s wait_for_*_edge() future in embassy_time::with_timeout(...) and return GpioError::Timeout on expiry; 0 keeps the pre-0.6 wait-forever behavior.
An embassy-rp watchdog is now enabled at a 2-second timeout, fed every 800 ms by a dedicated watchdog_feeder_task. It’s a separate task on purpose — a wedged handler can’t be trusted to feed a handler-based scheme — so the device recovers from any future handler hang. pause_on_debug(true) keeps debugger sessions from resetting the chip.
i2c_scan_handler now wraps each per-address probe in a 50 ms timeout, so one slow-to-NAK address no longer burns the whole scan budget.
New system/reset-subscriptions handler iterates the GPIO monitor slots, signals each live one to stop, awaits the pin back from its monitor task, and returns it to the context. It’s idempotent and cheap when nothing is subscribed — the device-side half of the subscription-leak recovery.

Together these close the dispatcher-wedge regression (a gpio_wait on a never-transitioning pin blocking every other endpoint), the no-recovery-from-a-hung-handler gap, and the worst-case impact of a flaky I²C bus on i2c_scan.

Upgrade and compatibility

Because the wire schema changed, flash the new firmware and update your host crate in the same step. Mixed versions won’t talk to each other — by design, the new validation refuses rather than mis-decodes.

Crate	Old	New
`pico-de-gallo-internal`	0.5.0	0.6.0
`pico-de-gallo-lib`	0.5.0	0.6.0
`pico-de-gallo-hal`	0.5.0	0.6.0
`pico-de-gallo-ffi`	0.6.0	0.7.0
`gallo` (CLI)	0.6.0	0.7.0
`pyco-de-gallo`	0.2.0	0.4.2
`pico-de-gallo-firmware`	0.9.0	0.10.0

After flashing, point the host at the device and confirm the schema lines up:

$ gallo version

For new code, reach for the validating entry points so a version skew or a missing board fails at construct time rather than on the first call:

Rust library: PicoDeGallo::new() → validate().await? → system_reset_subscriptions().await?
HAL: Hal::new_validated(), then system_reset_subscriptions()
C: gallo_init_strict()
Python: pyco_de_gallo.open_strict()

If you hit a schema-mismatch error after upgrading only one side, that mismatch is the new validation doing its job. Re-flash or re-install so both ends report the same schema, and you’re good.

I3C target mode on MCXA: three things the datasheet didn't warn me about

2026-06-20T09:00:00+00:00

I spent the last several weeks bringing up an I3C target driver for the NXP MCXA family (MCXA2xx and MCXA5xx share the same I3C IP) inside the embassy HAL. “Target” is what I3C calls the role I²C calls “slave”: the device that sits on the bus, responds to a controller, and can also raise an in-band interrupt (IBI) and service a directed read without anyone toggling a sideband pin. The use case was the boring one: a Rust target talking to a Rust controller, raising IBIs and returning responses for a few million iterations without panicking.

The driver landed in embassy-rs/embassy#6160 and the soak rig has now ticked past 50 million IBI-then-directed-read iterations at 16-byte payloads, bus at 1.5 MHz SDR, against an NXP SDK controller on the other end. It got there by way of three corner cases that each took longer to diagnose than to fix, and that each looked nothing like what I’d assumed they were when I started chasing them. This post is those three.

One caveat up front: this is one vendor, one HAL crate, one bring-up. I have no idea whether these gotchas generalize to other I3C silicon. The shape of how the bugs hid probably transfers; the specific register names and timing numbers don’t.

The setup

The hardware is two MCXA boards wired together over their I3C0 peripherals: one running the Rust controller, one running the Rust target, both on top of the embassy-mcxa HAL. The bus runs SDR at 1.5 MHz push-pull / 750 kHz open-drain. The exchange under test is the obvious one: controller writes a few bytes, target raises an IBI, controller responds with a directed read, target returns a pre-loaded payload, repeat. The target’s RX path is DMA-fed into a bbqueue ring so the IRQ can drain SRDATAB at line rate while the consuming task takes its time — that ring is what makes the soak loop possible at all, but it isn’t where any of these three gotchas live.

For the first few days everything worked. Then the rig started panicking after twenty thousand to a few hundred thousand iterations with InvalidStart or SdrParity on the target side, and I’d go back to staring at register dumps.

Gotcha 1: the target clock was 4× too slow, and the symptom was on the controller

The first failure mode looked like SDA contention around the IBI handshake — once every few hundred thousand iterations, the controller would see a frame with bad parity, or the target would surface SERRWARN.INVSTART on what should have been a clean repeated-Start. Not every IBI; not even most IBIs. Just enough to be unmissable in soak and unreproducible at the bench.

I lost a day re-reading the IBI sequencing code for a race that wasn’t there before I gave up and added a dump_registers() method on both sides — one defmt line each, every M* / S* register as a raw u32. Diffed against the NXP SDK’s target on the same wires, every register matched byte-for-byte except SCONFIG. I had BAMATCH=1 on the mcxa5xx example and BAMATCH=2 on mcxa2xx; the SDK had BAMATCH=11.

BAMATCH is the count, in I3C functional-clock cycles, the target waits after seeing bus-idle before declaring the bus “available.” The HAL computes it as fclk_MHz - 1 — correct, but only if fclk is in the range the I3C spec assumes. The MCXA examples were feeding I3C0 at roughly 3 MHz (mcxa5xx) and 2.8 MHz (mcxa2xx), giving bus-available times of 0.36 µs and 0.67 µs; the spec puts the minimum at 1 µs and the SDK runs at 12 MHz (0.92 µs). With BAMATCH expiring sub-microsecond, the target was declaring the bus available before the controller had finished releasing SDA, and very occasionally both ends would drive the line at the same time. That was the parity error and the INVSTART: SDA contention manifesting one full transaction downstream of the actual race.

The fix is one line in the example clock-tree setup: route I3C0_FCLK from FRO_LF (12 MHz exact) with a /1 divider, and the HAL’s math produces BAMATCH=11. SCONFIG becomes 0x140b0019 exactly, matching the SDK. The soak loop went from failing inside half a million iterations to running indefinitely clean.

The lesson: when a vendor’s reference and yours run on the same wires and only one is reliable, dump every register on both sides post-init and diff them — the difference is almost never where you’re looking. And if a peripheral’s clock contributes to a bus-timing parameter rather than just a baud rate, check that field’s spec minimum before you trust the formula the HAL uses to compute it.

Gotcha 2: raising the IBI before the FIFO was loaded

With the clocks corrected, the soak rig hit a different failure: SERRWARN.INVSTART on the target, during the IBI-payload phase itself this time. The trace was unambiguous — the controller ACK’d the IBI, issued a repeated-Start with the target’s dynamic address and the read bit, started clocking SCL — and the target’s TX FIFO was empty when the first byte was demanded. The cause was an ordering bug in dma_respond_to_read_with_ibi: arm TX DMA, set SCTRL.EVENT = Ibi, then wait for DMA to drain into the FIFO. The IBI arbitration plus the controller’s auto-IBI ACK plus the repeated-Start plus the read bit takes about 640 ns at 1.5 MHz — on a quiet executor DMA setup wins that race; under realistic Embassy load it doesn’t.

The intuitive fix is to invert the order — drain DMA synchronously, push the end-marker via SWDATABE, then raise EVENT = Ibi. This works perfectly up to the TX FIFO depth, which on this IP is 8 bytes. The moment you try a 9-byte payload it deadlocks: DMA blocks waiting for FIFO space; the FIFO won’t drain because the controller hasn’t been told there’s anything to read; the controller hasn’t been told because the IBI hasn’t gone out. The shape the fix has to take is the one the NXP SDK uses, and isn’t the one I’d have guessed: arm DMA, raise the IBI immediately, then await DMA completion while the controller drains the FIFO at the same rate DMA fills it.

// Arm DMA first so the first transfer is in flight.
self.dma_arm_tx(buf, end_marker).await?;
// Raise IBI immediately. Controller starts clocking; FIFO drains
// concurrently with DMA filling it.
self.regs.sctrl().modify(|w| w.set_event(Event::Ibi));
// Now wait for DMA. The FIFO is active throughout.
self.dma_wait_complete().await?;

The lesson I keep relearning: when “obviously correct order” and “actually correct order” disagree, the hardware is usually right. If a peripheral’s FIFO is meant to be filled concurrently with being drained, you can’t fill it sequentially before signalling the drain, however much safer that feels.

Gotcha 3: the post-IBI Stop turned my repeated-Start into a fresh frame

The third one took longer to believe than it did to find. With clocks correct and the IBI ordering fixed, Rust↔Rust soak still failed — much later — and the failure mode was that the target’s directed-read response was misaligned by a byte, or surfaced as InvalidStart immediately after a successful IBI.

The IBI itself was clean. The handshake worked. The TX FIFO was loaded correctly. The problem was that the controller side, in async_wait_for_ibi, was emitting an async_stop once the IBI completed. That turned the next async_read the caller issued into a fresh Start at the dynamic address, rather than the repeated-Start the target’s pre-loaded response was sitting there expecting. The target was set up for Sr→addr→R; the controller handed it Stop→Start→addr→R; the framing went sideways.

The fix is to delete the async_stop. After a successful IBI the bus is already in NORMACT and the controller can issue a repeated-Start directly into the directed-read. The function’s doc comment now spells out at some length why putting the Stop back would be wrong, because the temptation to “clean up after yourself” by trailing every transaction with a Stop is real.

The lesson is shorter than the bug: I3C, like I²C, distinguishes Start, repeated-Start, and Stop, and the target’s response state machine cares which one comes next. Pre-load a response for a repeated-Start, hand the target a fresh Start instead, and you don’t get a parity error — you get a perfectly framed read that returns the wrong bytes. That’s the worst kind of bug to have in soak: the symptom looks like data corruption, not a protocol violation.

What I’d do first next time

If I were starting an I3C target bring-up on this family of silicon tomorrow, in this order:

First, set the I3C functional clock to 12 MHz exactly and verify SCONFIG.BAMATCH post-init against the spec’s 1 µs bus-available minimum. The HAL’s formula is correct; whether the input clock makes it produce a legal value is on you. FRO_LF /1 gives you 12 MHz exact and matches the SDK.

Second, add a dump_registers() method to both controller and target from day one and call it after init in the examples. One defmt line each, every M* / S* register as a raw u32. The cost is trivial; the diagnostic value the first time something goes weird against a known-good reference is disproportionate. Of course, remember to remove that method prior to producing a PR. That method is easy to write and only useful when things go awry. In general, we don’t need it.

Third, mirror the vendor SDK’s ordering on anything that combines DMA, FIFO, and bus signalling even if it looks wrong: arm DMA, signal the bus, then wait for completion. Don’t drain the FIFO before raising the IBI. Don’t emit a Stop after an IBI if the next thing you expect is a directed read.

Those three would have saved me the bulk of the bring-up time.

What this doesn’t cover

One developer, one family of silicon, two boards on a bench. I have no idea how I3C target mode looks on other vendors’ IP, and I’d be surprised if specific register names, FIFO depths, or clock-tree dependencies transferred. The PR also contains a handful of smaller fixes I didn’t write up — a stale MERRWARN warning leaking across frames, a racy state == Slvreq guard in the IBI wake path, a controller-side ODHPP-vs-baud-rate calculation race — each of which fixed a real failure but wasn’t structurally interesting enough to earn a section. Read the PR if you want the full list.

If you’re bringing up I3C target mode on MCXA, I hope this saves you the half-week. If you’re doing it on something else and one of these patterns rhymes with what you’re seeing, I’d genuinely like to hear about it.

Examples that run

2026-06-15T15:58:00+00:00

Most driver crates I reach for ship an examples/ directory that I have to port before I can read it. Wrong PAC for my dev board, wrong linker script, a #[entry] macro from a runtime I don’t have checked out, a loop { wfi() } at the end I need to delete because I’m hosting the binary myself. By the time I’ve matched the example to my hardware, I’ve spent an hour and I haven’t learned anything about the chip — I’ve learned about the crate author’s bring-up preferences for the board they happened to own.

A previous post made the case for moving the bus host-side: a Pi Pico 2 acting as a USB-attached I²C/SPI/GPIO adapter, so the driver crate itself stays unchanged and runs from a std binary on your laptop. This post is the other half. Once the bus moved, the driver crate’s examples/ directory changed shape too, and the conventions that fell out are worth writing down. The worked example is tmp108 — at the time of writing, the only crate on crates.io that lists pico-de-gallo-hal as a (dev-)dependency at all. Five example files, five distinct chip behaviors, every one of them runs on a normal dev machine as soon as you have the chip on a breadboard.

What follows is what I do, and why. None of it is novel; most of it is the kind of thing that becomes obvious once the constraint “every example must be runnable, by anyone, on the actual chip” stops being aspirational.

The opening line is the chip’s pinout

Every example in tmp108/examples/ opens with the same shape. The oneshot.rs body, in full:

let hal = Hal::new();
let i2c = hal.i2c();

let mut tmp = Tmp108::new_with_a0_gnd(i2c);
let temperature = tmp.temperature().map_err(|_| anyhow!("Failed to read temperature"))?;
println!("Temperature: {temperature:.2} C");

The first two lines are the entire host-side preamble. They’re contract: ignore me, the rest of this file is only about the chip. After a few examples, the reader’s eye learns to skip past them and read the rest as if it were library prose. There’s no clock-tree setup, no peripheral init, no #[entry] decorator, no panic handler. The bus is just there, the way std::fs::File::open is just there in a Linux program.

The third line is the one that does the work. Tmp108::new_with_a0_gnd(i2c): the constructor name is the pinout. A0 tied to GND means I²C address 0x48. The TMP108 takes one of four addresses depending on the state of its A0 pin, and the driver exposes one constructor per choice — new_with_a0_gnd, new_with_a0_vplus, new_with_a0_sda, new_with_a0_scl. There is no new(addr: u8). There is no way to construct a Tmp108 whose address doesn’t correspond to a real wiring choice on the part.

The example file tells you which jumper you’re looking at by naming it in the constructor. A reader who has the chip strapped to V+ can see, without consulting the README, that this particular example assumes A0 is grounded — and that swapping _a0_gnd for _a0_vplus is the only change they need to make. The constructor name is doing documentation work that would otherwise have lived in a code comment, where I would have forgotten to update it the next time I edited the file.

One file per chip behavior, not per method

There are five files in tmp108/examples/: oneshot.rs, continuous.rs, alert_comparator.rs, alert_interrupt.rs, and sensor_trait.rs. Each one demonstrates a thing the TMP108 does — a single-shot conversion, a continuous-conversion loop, the ALERT pin in comparator mode, the ALERT pin in interrupt mode, and the cross-crate embedded-sensors-hal trait integration. Not new_with_a0_gnd.rs, new_with_a0_vplus.rs, new_with_a0_sda.rs — that would be per-constructor, which is per-API, which is library-shaped. Per-behavior is chip-shaped, which is the grain the reader is here for.

The grain of the directory matches the grain of the datasheet’s “Modes of operation” chapter, not the grain of the Rust struct’s impl block. A reader who wants to know “how do I use the ALERT pin in interrupt mode” goes to alert_interrupt.rs; a reader who wants to know “what does the public API look like” can read the docs.rs page. Two different audiences, two different artifacts, and they don’t have to compete for space in the same file.

The two ALERT examples are a good test of whether “chip behavior” is genuinely the right axis. The TMP108’s ALERT pin has two operating modes that the README’s Gotchas section spells out: in comparator mode the pin stays asserted until the temperature returns inside the hysteresis band; in interrupt mode the pin clears as soon as the configuration register is read. Two modes, two examples — not because the trait has two methods (it doesn’t; it has one wait_for_temperature_threshold), but because the chip genuinely behaves differently in the two configurations. The split exists because the reader who’s debugging “why doesn’t my ALERT line release” needs to know which mode they configured, and the example that demonstrates each mode is the most economical place to learn it.

Same file, both flavors

The TMP108 driver ships both a blocking Tmp108 and an async AsyncTmp108, gated on the async Cargo feature. The straightforward thing to do would have been oneshot_blocking.rs and oneshot_async.rs, two files, one per build configuration – one can certainly follow that model too. That isn’t what I did. The oneshot.rs file has two main() functions in it, picked between by cfg:

#[cfg(not(feature = "async"))]
fn main() -> Result<()> {
    // ... blocking body
}

#[cfg(feature = "async")]
#[tokio::main]
async fn main() -> Result<()> {
    // ... async body
}

Why one file? Because a reader who wants to learn what changes when you flip to async would, with two files, have to diff them in their head. With one file, the diff is in the file, visible to the eye, enforced by the compiler. The two preambles at the top are identical. The chip operations are nearly identical. The only things that change are the .await, the #[tokio::main] macro, and the import that picks AsyncTmp108 instead of Tmp108. The reader sees it, side by side, in the smallest unit of code that demonstrates the difference.

The trade-off is honest: the file is busier — every example that supports both flavors carries two main functions and at least one pair of #[cfg] arms. The payoff is that blocking/async parity is observable in the source, not just claimed in the README. Building with default features picks the blocking main; building with --features async picks the async one. (continuous.rs, alert_comparator.rs, and alert_interrupt.rs are async-only, because the underlying API is; their blocking main stub prints the required feature flags and exits, which is itself a form of documentation — the file refuses to build silently into nothing.)

A four-line header that tells you what you need

Every example opens with a doc-comment header that says, in the same shape every time, who the example is for and what it requires. oneshot.rs’s header in full:

//! TMP108 one-shot conversion example.
//!
//! # Hardware
//!
//! - Pico de Gallo USB-attached host adapter
//! - TMP108 on the default I2C bus, A0 → GND (address `0x48`)
//!
//! # Cargo features
//!
//! Works with default features (blocking). Building with `--features async`
//! produces the async variant.
//!
//! # Register interactions
//!
//! Single read of the temperature register at address `0x00`.

# Hardware says what pico de gallo connections the example needs: USB-attached host adapter, TMP108 on the default I²C bus, A0 strapped to GND. # Cargo features says how to flip blocking/async — default features for blocking, --features async for async. # Register interactions names exactly which TMP108 register the example touches, so the reader who is following along with the datasheet open can find the relevant chapter without guessing. For oneshot.rs, that’s a single read of the temperature register at address 0x00. For continuous.rs, it’s a five-step sequence (read config, write config with M=Continuous, read config, loop on temperature reads, restore M=Shutdown on exit). The header for each example calls out the register interactions specific to that example, in the order they happen.

This is the section the reader skims first to decide “is this the example I want?” — a six-line table of contents per file, in the place a Rust reader expects documentation to be. It costs nothing to write and removes the most common pre-run question, which is some flavor of “wait, what do I need to have plugged in for this one?” The reader doesn’t have to chase the answer through the body of the file or the README; the answer is already at the top.

What this doesn’t cover

A few honest limits before I oversell any of this.

The pattern works because pico de gallo can host an I²C bus, an SPI bus, and a handful of GPIOs from a laptop. Drivers that need a real MCU peripheral — USB device, Ethernet MAC, anything DMA-bound, anything where the chip itself drives timing the host can’t sustain — can’t run this way. The conventions in this post are opinionated about I²C/SPI/GPIO sensor and peripheral drivers; I have not tried any of this on a driver that needs more than those buses, and I would not assume any of it generalizes.

tmp108 is also one crate. At the time of writing it is the only crate on crates.io that depends on pico-de-gallo-hal — the reverse-deps page lists exactly one, and it’s a dev-dependency at that. These conventions are battle-tested on one chip^[1], with one set of bus requirements, by one author. Take them as one person’s house style, not as a recommendation that has survived contact with a population of users and other crates.

What I do think holds up, on the evidence of this one crate, is the shape: the constraint “every example must run on a normal dev machine against real silicon, with no porting step in between” forces an examples/ directory that reads like the chip’s datasheet, not like the library’s impl block — and the datasheet’s grain is the right grain for the audience the examples are written for.

That statement is not exactly true as I have used Pico de Gallo to run weekend long soak tests on MCXA I²C controller and target drivers. ↩

Waking up without a critical section

2026-06-13T21:38:00+00:00

A GPIO interrupt fires. The handler’s job is small: flip a status bit, call waker.wake(), return. The task that was parked on that pin is now ready to run, and the executor will get to it on the next poll.

Until you look at what waker.wake() actually did. On every embassy target, until very recently, that one call took out a critical section — a global interrupt disable, held for the duration of the register-or-wake operation — because the AtomicWaker in embassy-sync was a typedef-style alias for GenericAtomicWaker<CriticalSectionRawMutex>. On Cortex-M that is exactly what it sounds like: the wake path raised BASEPRI (or disabled IRQs outright on older parts), did its bookkeeping, and lowered it again. A higher-priority interrupt that arrived in the middle had to wait. One async task’s wake imposed a jitter floor on every other interrupt in the system.

embassy-rs/embassy#6111 replaces that. The new AtomicWaker is a port of futures::task::AtomicWaker — the one that has been doing this on std targets for years — adapted for no_std. The trade I made is concrete: a small atomic state machine in place of the critical section, plus one documented semantics change that Future::poll already required callers to honor. The old behavior is kept verbatim under a new name, CriticalSectionWaker, for the chips and the call sites that still want it.

What the type used to be

The pre-#6111 definition is essentially one line:

pub type AtomicWaker = GenericAtomicWaker<CriticalSectionRawMutex>;

GenericAtomicWaker<M> wraps an Option<Waker> in a Mutex<M, Cell<...>>. With M = CriticalSectionRawMutex, every register() and every wake() calls critical_section::with(...), which on Cortex-M expands to “disable interrupts, run the closure, restore the previous mask.” The closure itself is tiny — replace a cell, maybe clone, maybe call wake_by_ref — but the whole CPU is now refusing to acknowledge anything else for the duration.

That is fine when wake() is a background bookkeeping call. It is much less fine when wake() is itself a high-priority IRQ handler whose latency you care about, or when a different high-priority IRQ arrives during the wake and has to wait for an unrelated cell-swap to finish before it gets to run.

The three-state machine

The new type, in embassy-sync/src/waitqueue/atomic_waker.rs, replaces the mutex with a packed AtomicUsize and three constants:

const WAITING: usize     = 0;
const REGISTERING: usize = 0b01;
const WAKING: usize      = 0b10;

The important thing about those constants — and this came out of review, so it’s now spelled out in the source comments — is that they are flags, not exclusive states. REGISTERING | WAKING (0b11) is a legal, intentional state of the machine. It means a register() is mid-flight and a wake() arrived while it was running, and the wake has been flagged as pending. The encoding is load-bearing: only the holder of REGISTERING or WAKING (and never both at once, by virtue of the protocol) is allowed to touch the underlying waker cell, and the 0b11 state is what tells the in-flight register() that there is wake duty waiting for it on the way out.

The wake side is short and worth showing in full:

match self.state.fetch_or(WAKING, AcqRel) {
    WAITING => {
        // We own the cell. Fire the wake, release.
        unsafe {
            if let Some(w) = &*self.waker.get() {
                w.wake_by_ref();
            }
        }
        self.state.swap(WAITING, Release);
    }
    _ => {
        // Somebody else owns the cell. They'll deliver the wake.
    }
}

Two arms, and that is the whole thing. If the prior state was WAITING, we are now the sole owner of the cell via the WAKING bit; we invoke the stored waker by reference, then drop the bit. If the prior state was REGISTERING, the OR has produced REGISTERING | WAKING, and we deliberately do nothing else, because the in-flight register() will see our bit on its way out and deliver the wake itself.

Why fetch_or and not compare_exchange

This is the load-bearing decision in the whole PR, and review asked the obvious question: shouldn’t this be a compare_exchange? It’s the safer default, the one you reach for first.

It would be silently wrong here. Consider the race:

A task calls register(cx.waker()). The CAS from WAITING to REGISTERING succeeds; we now own the cell and start installing the new waker.
Mid-installation, an interrupt fires and calls wake().

If wake() did compare_exchange(WAITING, WAKING, ...), that CAS would observe REGISTERING, fail, and silently return — there is no prior value it could have CAS-ed against that would have encoded “a wake is pending.” The in-flight register() would then finish, CAS its own state cleanly back from REGISTERING to WAITING, and never learn that anything happened. The waker is installed, nobody is going to invoke it, the task is hung. The kind of bug you find at 2am after staring at the screen for an hour wondering why an interrupt that you can see on the registers isn’t producing a task wakeup.

fetch_or(WAKING, AcqRel) doesn’t have that failure mode. The wake’s contribution to the state word is unconditional and visible to whoever observes the state next. The in-flight register() tries to release with compare_exchange(REGISTERING, WAITING, ...) on its way out; that CAS will fail exactly when a wake raced it, because the observed state is now REGISTERING | WAKING, not REGISTERING. The failure branch is the handoff signal: it takes the freshly-installed waker out of the cell, clears both bits with a swap, and invokes the waker after releasing the cell — so that a user waker that re-enters register() or wake() on the same AtomicWaker from inside wake() cannot deadlock against our own state.

The wake is delivered exactly once, by whichever side observes the contention. The handoff is structural, not best-effort. fetch_or is doing more than “atomic OR” here; it is the data structure that makes the race path correct.

What changed in the contract

There is one user-visible semantic difference, and the PR owns it in the CHANGELOG: AtomicWaker::register() now wakes the previously registered waker if you replace it with a different one. This matches what WakerRegistration has always done. The pre-#6111 AtomicWaker would silently drop the old waker on the floor.

The reason this is safe is that Future::poll is already documented to require it. The relevant line in the Future::poll contract:

Note that on multiple calls to poll, only the Waker from the Context passed to the most recent call should be scheduled to receive a wakeup.

A correctly-written driver already re-registers on every poll, because the Waker it gets on the n-th poll is not guaranteed to be the one it got on the (n-1)-th. Waking the evicted predecessor formalizes that: if a different task ends up polling the same future, the displaced task gets a chance to re-register itself instead of vanishing. This was a late commit, prompted by review, and it is what the CHANGELOG entry calls out by name.

Two siblings now, on purpose

The previous behavior didn’t disappear. It moved into its own module, embassy-sync/src/waitqueue/critical_section_waker.rs, and got a name that says what it is:

pub struct CriticalSectionWaker {
    waker: GenericAtomicWaker<CriticalSectionRawMutex>,
}

This is a verbatim preservation of the old AtomicWaker body — the same wake_by_ref + restore flow, the same lack of an atomic state machine, the same critical section on the wake path. Call sites that depended on the old “replace without waking” semantics keep working with a one-word rename.

The asymmetry is deliberate, and I want to be explicit about it because it matters for anyone reading older code: the new AtomicWaker wakes evicted predecessors; GenericAtomicWaker<M> does not, and CriticalSectionWaker (being a wrapper around it) does not either. Review caught an earlier commit that tried to bring GenericAtomicWaker along to the new semantics, and I reverted it. A public type that has been in the tree for years should not change behavior under callers without a much louder migration story than this PR is in a position to write — and there’s no need for one. Callers who want the new semantics have AtomicWaker; callers who want the old have the type they were already using.

thumbv6 doesn’t have the atomics

The lockless state machine assumes you can do AtomicUsize::{compare_exchange, swap, fetch_or} on the target. Cortex-M0/M0+ (thumbv6m) can’t — no LDREX/STREX in the instruction set, so the LLVM atomics for anything past naked load/store aren’t there. The same goes for a handful of other targets in the embassy matrix (Xtensa S2, AVR, RV32I — anything missing the relevant target_has_atomic cfg).

The PR’s solution is the obvious one: gate the new type on #[cfg(target_has_atomic = "32")], and on every other target make AtomicWaker a type alias for CriticalSectionWaker. Callers see the same type name; the implementation behind it is the one the hardware can actually run. The sibling type isn’t there for nostalgia. Some chips genuinely need it.

What the wake path no longer does

The benchmark on the bench was a GPIO IRQ wake on an FRDM-MCXA266 (Cortex-M33 at 180 MHz); the lockless wake() body came out about 290 ns shorter than the critical-section one. I’m not making that the headline. The wall-clock delta is small enough to be well within run-to-run noise on a 180 MHz core; if the structural change weren’t real, I would not trust that number to mean anything.

The structural change is real, and it is what the PR is actually about. On any embassy target with AtomicUsize-class atomics — which is most of them — the wake path of AtomicWaker no longer disables interrupts. An IRQ handler that calls waker.wake() doesn’t enter a critical section, doesn’t pay the enter/exit cost on every wake, and doesn’t impose a jitter floor on whatever higher-priority interrupt would otherwise have preempted it. The worst case for a preempting IRQ is now an AtomicUsize op or two and a wake_by_ref call. On chips that can’t do the atomics, the fallback is the type that was already in the tree; nothing regresses.

None of this is novel. futures::task::AtomicWaker has been doing this on std for years, and the algorithm here is a direct port. What changes is that embassy-sync — and every embassy driver that uses AtomicWaker for IRQ-to-task wakeups — gets that property by default. A single-waiter waker can hand off the register-vs-wake race with a fetch_or-based state machine instead of a critical section, and the cost is one documented semantics change that Future::poll already required callers to honor.

What did the boot ROM just do to my RAM?

2026-06-11T09:00:00+00:00

A while back I was trying to get teleprobe to run a test suite on an RT685-EVK. Teleprobe’s trick is that it takes your test, compiled as a standalone firmware binary linked to execute directly from SRAM, loads it into the target’s RAM over the probe, and runs it from there — flash never gets touched. On every board I’d used it with before, it just worked. On the RT685, every run ended in a HardFault before the first test got a chance to do anything.

The diagnosis took longer than the bug deserved. The RT685’s boot ROM was power-cycling almost every SRAM partition on the way to user code — including the one the test binary was linked into. The instructions were being scribbled over between the load and the first fetch, so the core would dutifully jump to what had been code, hit garbage, and fault. Nothing in the reference manual said which partitions the ROM touches at startup, and the HardFault itself only told me where execution died, not why the instructions there were no longer the ones I’d loaded. I worked it out by reading whatever I could find, writing a few throwaway scripts, and squinting at probe dumps.

That experience is why I wrote rambo. It’s a small CLI whose only job is to answer the question I should have been able to look up: which parts of this chip’s RAM does the boot ROM clobber before my first instruction runs?

What rambo actually does

The core loop is short enough to describe in a paragraph. For every RAM region probe-rs knows about for a given chip, rambo writes a deterministic pattern across the whole region — each 32-bit word stores its own address. Then it issues a reset and halts the core on the vector catch, before any user firmware runs. It reads the region back and classifies every block as one of four things: SAFE (the pattern survived), ZERO (filled with 0x00000000), ONES (filled with 0xFFFFFFFF), or CHANGED (rewritten with something else — ROM scratch, stack, or working data, and sometimes just garbage from a partition the ROM power-cycled). Output is a colored heatmap, a run-length-encoded summary of contiguous regions sharing a class, and per-region totals.

It is deliberately a plain stdout program with ANSI colors. Not a TUI. Not a simulator. Not a fancy GUI. It’s something you can read in your terminal, pipe to a file, or paste into a bug report when you ask a vendor why their ROM is doing what it’s doing. The only thing it depends on at runtime is a debug probe and a chip that probe-rs supports — which, in practice, is most of the Cortex-M world.

It does not flash anything. It does not modify your firmware. It writes a pattern, resets, reads back. That’s it.

Why writing the address as data matters

The “each word stores its own address” pattern is the kind of thing that looks arbitrary until you’ve tried the alternatives. A solid bit pattern like 0xDEADBEEF repeated everywhere will tell you whether RAM was clobbered, but it won’t tell you whether the readback came from the address you think it did — if the chip aliases memory or has unmapped windows in a reserved range, you can read the same 0xDEADBEEF back from two different addresses and not notice. With addr-as-data, every location is uniquely identifiable. A SAFE word is unambiguous. A ZERO or ONES word is unambiguous. A CHANGED word that also happens to equal some other valid address is a strong hint that something is aliased. The pattern is essentially free to generate, and it carries its own coordinate system.

A small tour of the optional modes

The default survey answers the headline question. The optional modes are there for when the answer to “what is the ROM doing here?” is more interesting than “nothing” or “everything.”

--fingerprint classifies the kind of clobber inside CHANGED blocks. Is the block mostly zeros with a few non-zero words at the top? That looks like a stack frame. Is every word the same non-zero value? That’s a constant fill. Is it an ascending counter, a repeating motif, or an address-plus-offset pattern? Each of those points at a different ROM behavior — a memset, a struct initialization, a copy with a fixed offset, an uninitialized scratch buffer the ROM forgot to clear. None of these tell you exactly what the ROM is doing, but they let you skip straight past “is this even structured data” and into “this looks like a 16-byte header followed by a counter.”

--dual-pattern writes addr in one reset cycle and ~addr in a second. Both passes get classified independently and compared. If a block came back SAFE in both passes — pattern survived both times — then the ROM genuinely didn’t touch it. If a block came back CHANGED in both passes but with the same value, the ROM is actively writing there regardless of what was already in memory. This disambiguates two flavors of “the ROM didn’t touch this” that single-pass surveys can’t tell apart: undriven (the ROM left it alone) versus coincidentally the same as my pattern (extraordinarily unlikely with addr-as-data, but possible in pathological cases).

--write-readback is the opposite trick: skip the reset entirely. Write the pattern, immediately read it back, classify what comes out. On normal RAM, this is boring — everything classifies as SAFE. On reserved address ranges, on code-bus aliases of system RAM, on peripheral windows that look like memory in the chip description but aren’t, this is where you find out. Aliasing shows up as the same content at two addresses. Unmapped windows show up as bus faults or all-ones reads. It’s worth running once on any new chip just to see what its memory map actually does, as opposed to what the documentation claims.

--reset-cycles N re-runs the read after each of N resets without re-writing the pattern in between. If the ROM is deterministic — same chip, same reset, same post-ROM RAM contents every time — the classification is identical across cycles. If anything drifts, you’ve got nondeterminism worth investigating: timing-sensitive scratch, uninitialized stack frames bleeding in from whatever was happening microseconds before the reset, or RAM that hasn’t fully settled. This one is mostly useful when something should be the same every boot but isn’t, and you need evidence before you can start arguing about it.

The CI bit

The mode I’m most happy with isn’t in the survey — it’s in the two flags that turn rambo into a regression gate.

--json <path> writes a stable, schema-versioned JSON report of the entire run. Use it as a CI artifact, archive it across firmware versions, diff it when something changes.

--expectations <path> takes a small declarative file — a “RAM contract” — and evaluates each clause against the survey. Each entry names a range and one of three claims:

{
  "name": "main_sram_crash_dump_area",
  "range": { "start": "0x20030000", "end": "0x20031000" },
  "expect": "safe",
  "rationale": "Reserved for crash-dump recovery after watchdog reset."
}

The clauses are expect: <class> (every block must be that class), expect_any_of: [<class>, ...] (every block must be one of these), and expect_not: <class> (no block may be that class). Exit code is 0 if every expectation holds, 1 if any fails. Ranges are checked for alignment and bounds before any probe I/O happens, so a typo can’t brick a run.

What this gets you is a small, version-controlled answer to “the bootloader assumes these regions survive the ROM” that runs on every PR and on every new silicon rev. The next time a chip vendor patches their ROM and quietly starts touching memory they didn’t touch before, your CI tells you. It’s a tiny, boring thing. It’s also the kind of thing that would have saved me a few days on the RT685.

What rambo isn’t

A few honest limits before you reach for it.

It’s only as accurate as probe-rs’s chip database. If a chip’s memory_map omits a region, rambo can’t survey it. Most of the time this is fine; occasionally a vendor leaves a peripheral-attached SRAM out of the description and you’ll need to add it yourself (or --chip-description-path your own).

Some CMSIS-Pack descriptions list code-bus aliases of system-bus RAM as separate regions. Rambo treats every region in the map as independent, so you’ll see the same physical RAM surveyed twice under different addresses. That’s almost always what you want — the aliases sometimes behave differently — but it can look surprising the first time.

And “SAFE” only means “the ROM didn’t write here on this chip rev, with this fuse configuration, on this boot mode.” It does not mean the ROM will never write there. That gap is exactly why the contract file and CI gate exist.

Try it

cargo install rambo, or grab a pre-built binary from the releases page for Linux, macOS (Intel + Apple Silicon), or Windows. Source is on GitHub.

If you run it on a chip I haven’t tested with — so far that’s RT685, RT633, MCXA266, MCXA276, and MCXA577 — I’d genuinely like to hear what came back. Especially if it surprises you.

Writing embedded drivers without an MCU

2026-06-10T16:00:00+00:00

Let me clarify the title up front: there is an MCU. There’s a Raspberry Pi Pico 2 sitting on my desk. What I mean is that the MCU isn’t in my dev loop. I don’t flash it. I don’t reset it. I don’t attach a probe to it. I treat it like a USB peripheral that happens to speak the buses I need — I²C, SPI, UART, GPIOs, ADC, and 1-Wire — and I write all of my driver code as a normal cargo run binary that runs on my laptop, against the real sensor, over a real bus.

This post is about how that works, why it’s nice, and what you can do once your “embedded” driver is just a Rust program with std.

The loop I’m trying to escape

The traditional embedded dev loop looks something like this:

Edit a line of code.
Wait for cargo build --target=thumbv8m.main-none-eabihf to finish.
Reflash the chip (a few seconds with a probe, longer over the bootloader).
Either power-cycle the board or punch the reset button.
Squint at defmt output through a probe.
If you need to reproduce a bug, also: physically interact with the board (push a button, breathe on the sensor, jiggle a wire).
Goto 1.

On a good day with a fast build and a good probe, that’s two minutes per iteration. On a bad day — a stale build cache, a probe that disconnects, a chip in some weird stuck state — it’s five or ten.

The frustrating part isn’t the time. The frustrating part is that none of it is about the driver I’m writing. The driver is just some byte-level logic that talks to a chip over I²C. The chip doesn’t care which CPU is initiating the transactions. The chip certainly doesn’t care that I had to write a linker script and a clock-tree configuration to get there.

So: why not skip all of that, and write the protocol logic somewhere where iteration is free?

Enter Pico de Gallo

Pico de Gallo is a project I’ve been building for exactly this. It’s a small landing board that turns a Pi Pico 2 into a USB-attached protocol bridge. Plug it into your laptop, and your laptop now has an I²C bus, a SPI bus, a UART, a handful of GPIOs, two PWM channels, an ADC, and a 1-Wire master — addressable from any host-side program.

A few things it isn’t, because it gets confused with each of these:

It’s not a logic analyzer. It drives the bus; it doesn’t sniff somebody else’s.
It’s not a USB-to-I²C dongle in the FTDI sense. The chip underneath is a Pi Pico 2, the firmware speaks postcard-rpc, and the host side is a real Rust crate with proper types and async support.
It’s not a debug probe. There’s no SWD on the other end of the cable. There’s only the device you wired up.

What it actually does is let you write this:

use pico_de_gallo_hal::Hal;
use embedded_hal::i2c::I2c;

let hal = Hal::new();
let mut i2c = hal.i2c();

let mut buf = [0u8; 2];
i2c.write_read(0x48, &[0x00], &mut buf).unwrap();

…on your laptop, and have the bytes appear on a real I²C wire, addressed to a real chip, with the reply coming back into buf.

The Pico de Gallo book has the full setup — what to assemble, how to flash the firmware, the pinout, and a tour of each interface. I won’t repeat any of that here. From this point I assume you have a Pico de Gallo plugged in, a TMP108 wired to the I²C connector, and the gallo CLI installed.

Feeling the bus before writing a line of code

The first thing I do with any new chip is poke at it through the CLI. This is the equivalent of the “wiggle a probe at it” step from the hardware world, except it’s three commands.

Did the chip enumerate at the address I think it did?

$ gallo i2c scan
╭────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────╮
│    │  0 │  1 │  2 │  3 │  4 │  5 │  6 │  7 │  8 │  9 │  a │  b │  c │  d │  e │  f │
├────┼────┼────┼────┼────┼────┼────┼────┼────┼────┼────┼────┼────┼────┼────┼────┼────┤
│ 0  │ RR │ RR │ RR │ RR │ RR │ RR │ RR │ RR │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │
│ 1  │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │
│ 2  │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │
│ 3  │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │
│ 4  │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ 48 │ -- │ -- │ -- │ -- │ -- │ -- │ -- │
│ 5  │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │
│ 6  │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │
│ 7  │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ -- │ RR │ RR │ RR │ RR │ RR │ RR │ RR │ RR │
╰────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────╯

Yes. The TMP108 with its A0 pin to ground sits at 0x48, and there it is. If this had come back empty, I’d know it was wiring, not software, and I’d know it before I’d touched a Rust file.

Can I read its temperature register?

$ gallo i2c write-read --address 0x48 --bytes 0x00 --count 2
0x18 0x40

Two bytes, just as the datasheet promised. Register 0x00 is the temperature register; the top 12 bits of the returned 16 are the signed reading in 0.0625 °C/LSB. So 0x1840 → 0x184 → 388 → 388 × 0.0625 → 24.25 °C. The room I’m in is about 24 °C.

Three commands, no Rust, and I know:

My wiring works.
The address I expected is the address the chip enumerated at.
The data format matches the datasheet.

Those three facts cost me about a minute of reading effort each on a real MCU, every time something goes wrong, because they’re all entangled with everything else. Here they’re isolated and free.

Reading it from Rust

Now for the actual program. The tmp108 crate on crates.io already exists — it’s a regular embedded-hal driver, #[no_std], written for anything that implements embedded_hal::i2c::I2c. Normally you’d pull it into a firmware project, build for a Cortex-M target, and flash. We’re going to pull it into a std binary instead.

[dependencies]
pico-de-gallo-hal = "0.5"
tmp108 = "0.5"

use pico_de_gallo_hal::Hal;
use tmp108::Tmp108;

fn main() -> anyhow::Result<()> {
    let hal = Hal::new();
    let i2c = hal.i2c();

    let mut tmp = Tmp108::new_with_a0_gnd(i2c);
    let temperature = tmp.temperature()?;

    println!("Temperature: {temperature:.2} °C");
    Ok(())
}

That’s the whole program. cargo run, and the bytes go out, the reply comes back, and a number prints.

The interesting thing to notice is what isn’t there. The tmp108 crate doesn’t know that pico-de-gallo exists. It has no conditional compilation for “host” or “USB.” Its only requirement is “give me something that implements embedded_hal::i2c::I2c,” and pico-de-gallo-hal does. The exact same Tmp108::new_with_a0_gnd call, with the exact same crate, the exact same version, will run unmodified on an RP2350, an STM32, an nRF52, or any other chip that has an embedded-hal I²C implementation.

This is not emulation. It’s not mocking. It’s not simulation. The bus is real. The chip is real. The driver is real. The only thing that’s different is what’s underneath the I2c trait — and that’s the whole point of the trait existing in the first place.

One honest caveat on that portability claim: of the interfaces Pico de Gallo exposes, only I²C, SPI, GPIO, and Delay have stable, widely-adopted embedded-hal traits today. The TMP108 example above sails through because it’s I²C, and the alert examples in tmp108’s examples/ folder sail through because they only also need GPIO. A driver for, say, a 1-Wire temperature sensor or a UART-attached GPS module won’t be quite as plug-and-play — embedded-hal doesn’t have stable abstractions for those yet, so each crate tends to invent its own. The “unmodified upstream driver” story is strongest for parts whose driver only needs I²C, SPI, GPIO, and timing. For everything else, the host-side loop still works; you just may have to do a bit of shimming.

The dev loop, side by side

Here’s the same edit-and-test cycle from above, redrawn against this program:

Edit a line of code.
cargo run.

That’s it. A debug build of this program takes under a second to recompile and start. There’s no flash step, no reset, no probe to attach. If the program panics, the stack trace points at the line that panicked, in source, with debug symbols, in the same terminal I just ran it from.

Other things that just work, because it’s std:

cargo test runs against the real chip.
cargo bench measures real round-trip latency over USB.
cargo flamegraph and perf and dtrace and Instruments all work, because it’s a normal native process.
println!, dbg!, eprintln!, tracing, env_logger — any of them. Whatever you’d use in a normal Rust program.
The debugger you actually like — rust-lldb, rust-gdb, the one built into your editor — attaches the way it always does.

The obvious question at this point is what the catch is. We’ll get there.

What having `std` actually unlocks

The temperature-printing program is the warm-up. The thing that makes this approach worth talking about is what becomes easy next.

Here is a small ratatui dashboard that reads the TMP108 four times a second and plots a live sparkline of the last 60 samples alongside running min / avg / max:

The whole program is about 150 lines and uses three dependencies: pico-de-gallo-hal, tmp108, and ratatui. The interesting bits look like this:

const HISTORY: usize = 60;
const SAMPLE_INTERVAL: Duration = Duration::from_millis(250);

let hal = Hal::new();
let i2c = hal.i2c();
let mut tmp = Tmp108::new_with_a0_gnd(i2c);

let mut samples: VecDeque<f32> = VecDeque::with_capacity(HISTORY);
let mut next_sample = Instant::now();

loop {
    if Instant::now() >= next_sample {
        let t = tmp.temperature()?;
        if samples.len() == HISTORY {
            samples.pop_front();
        }
        samples.push_back(t);
        next_sample += SAMPLE_INTERVAL;
    }

    terminal.draw(|frame| draw(frame, &samples))?;
    // ...event handling: quit on 'q' or Esc
}

The draw function splits the screen vertically into a stats row and a sparkline:

fn draw(frame: &mut Frame<'_>, samples: &VecDeque<f32>) {
    let chunks = Layout::default()
        .direction(Direction::Vertical)
        .constraints([Constraint::Length(3), Constraint::Min(0)])
        .split(frame.area());

    frame.render_widget(stats(samples), chunks[0]);
    frame.render_widget(sparkline(samples), chunks[1]);
}

…and sparkline rescales the float window into the integer bars that ratatui::Sparkline wants, so even tiny drifts are visible:

fn sparkline(samples: &VecDeque<f32>) -> Sparkline<'_> {
    let bars: Vec<u64> = if samples.is_empty() {
        Vec::new()
    } else {
        let min = samples.iter().copied().fold(f32::INFINITY, f32::min);
        let max = samples.iter().copied().fold(f32::NEG_INFINITY, f32::max);
        let span = (max - min).max(0.1);
        samples
            .iter()
            .map(|t| (((t - min) / span) * 1000.0).round() as u64)
            .collect()
    };

    Sparkline::default()
        .data(bars)
        .max(1000)
        .style(Style::default().fg(Color::Yellow))
        .block(Block::bordered().title(" last 60 samples  (q to quit) "))
}

That’s it. Read in a loop, push into a ring buffer, redraw. The total code is shorter than the LCD-init sequence I’d have written the first time I tried to do this on an MCU. And because it’s a normal terminal program, Ctrl-C cleans up and exits.

Once you’re in this world, a lot of other things become “just write the program”:

Data logging. A few lines of serde + csv and every sample gets a wall-clock timestamp on disk. Post-process with whatever you like — polars, pandas, jq, a quick shell pipeline:

let mut wtr = csv::Writer::from_path("temps.csv")?;
wtr.write_record(["timestamp_ms", "temperature_c"])?;
// inside the loop:
wtr.write_record(&[
    chrono::Utc::now().timestamp_millis().to_string(),
    format!("{t:.4}"),
])?;

Bus tracing. Wrap the driver in a tracing span and you get structured records of every transaction, every reading, every error, with timestamps and process metadata. Pipe it into tracing-subscriber, tokio-console, OpenTelemetry — pick your poison.

Stress testing. Spin up a tokio runtime, share the bus through a Mutex<Bus>, and have a dozen tasks all reading and configuring the chip concurrently. See what falls over. This is something you could do on the MCU, but it’s the kind of thing you’d never set up just to find out.

A/B testing. Run two versions of the driver against the same chip back-to-back, diff their outputs sample-for-sample. Catch a regression in the new version before it makes it anywhere near a production board.

Real CI. This is the one I’m most excited about. cargo test runs on a CI runner that has a Pico de Gallo plugged into it, with real chips wired up. Every PR exercises the driver against real silicon. No simulation. No “we’ll catch it in hardware testing later.” (More on CI in the testing chapter of the book.)

Runnable examples in your crate. This one flips the framing. So far we’ve talked about Pico de Gallo as something consumers of a driver crate use. But it works just as well for the author of the crate. Cargo lets you put a examples/ folder in your library and have each file be a binary; if those binaries can target a real, running version of your chip without anyone reaching for a soldering iron, they stop being “snippets you’d have to port to your board” and start being “things a reader can cargo run after plugging in two cables.”

The tmp108 crate’s examples are exactly this. There are five of them — one-shot read, continuous read, comparator-mode ALERT, interrupt-mode ALERT, and a embedded-sensors-hal trait demo — and every single one starts with let hal = Hal::new(); let i2c = hal.i2c(); (the ALERT ones also grab a GPIO for the interrupt line). A reader who wants to understand any of the modes runs cargo run --example oneshot and gets a real temperature back from a real chip. No board-bringup chapter. No “you’ll need to adapt this for your target.” The documentation is the running program.

Each of these was technically possible before. Each one required setting up its own bespoke pipeline, often with a custom MCU build, a custom log format, and a custom analysis layer on top. With a real bus available to a real std program, they all collapse into “use the crate that already exists.”

The catch

One might ask, what’s the catch? Here is the honest list.

USB latency. Every transaction is a USB round-trip. In practice that’s about a millisecond. For polling a temperature sensor every 250 ms, that’s invisible. For a tight register-poll loop at 100 kHz trying to catch a hardware event in software — no, that does not work, and pretending it does would be a lie. Use the chip’s ALERT pin and an interrupt-driven path for that, which Pico de Gallo also supports via the GPIO Wait impl.

Timing is host-mediated. You cannot reproduce sub-millisecond interrupt-to-handler timing on a host. You can validate the protocol your interrupt handler implements, but not the latency of getting to the handler. For that you eventually need the real MCU.

Single master, single bus. The Pico de Gallo is the only master on the bus. You can’t reproduce a scenario where two different MCUs are arbitrating for the same wires.

The driver still has to be no_std. Pico de Gallo lets you exercise the logic of the driver in a comfortable environment. It does not validate that the driver compiles for your real target. You still need a one-line “build for thumbv8m.main-none-eabihf” step in CI to catch accidentally pulling in std. The tmp108 crate has exactly that job running on every push for this reason.

None of these are surprises. They’re the natural consequence of moving the dev environment off the target. The point is that for the work that is portable — and a sensor driver is essentially all portable work — you don’t have to pay the cost of the target during development.

Wrapping up

A device driver is protocol logic. Protocol logic doesn’t care what CPU is initiating the transactions. So write it where iteration is cheap, where you have a debugger and a test runner and a profiler, where you can wrap it in any visualization or analysis tool you want, and where adding “log every sample to a CSV” is two lines of code instead of two weeks of integration work.

Pico de Gallo is one way to do that. It happens to be the one I built, because nothing else existed that gave me exactly this. If you want to read more, the book covers the hardware, the firmware, the wire protocol, and a full chapter on writing a driver from scratch against a different temperature chip (TMP102). The tmp108 crate used in this post is on crates.io, and its examples/ directory is full of cargo run --example-able programs that all target a real chip through Pico de Gallo. The full ratatui dashboard code lives in a tiny standalone project that you can copy and adapt.

If you build something with it — a driver, a logger, a CI rig, a dashboard for a chip you’ve been wanting to characterize — I’d love to hear about it.

Hello, world

2026-06-10T08:00:00+00:00

This is the first post on the new version of balbi.sh. The previous incarnation was a single HTML file with one link; this one is built with Zola and styled after ef-melissa-light — a warm, legible Emacs theme by Protesilaos Stavrou. Body text is set in Aporetic Serif, headings and UI in Aporetic Sans, and code in Aporetic Sans Mono — all from the same author as the colour palette.

Why now

I want a place to keep working notes — short writeups about the things I run into while building firmware. The bar for publishing here is low on purpose. If a problem took me more than an hour to figure out, it probably deserves a post so I (or you) don’t have to figure it out again next time.

What to expect

Mostly:

Embedded Rust — Embassy, embedded-hal, async on tiny chips.
Bare-metal C — when Rust isn’t an option, which is more often than I’d like.
Tooling — probe-rs, defmt, the linker, the assembler, the things that quietly hold everything together.
Occasional rants about debugging hardware at 2am.

If you want to follow along, there’s an Atom feed.

Code, by the way

It looks like this:

#[embassy_executor::task]
async fn blinky(mut led: Output<'static>) {
    loop {
        led.toggle();
        Timer::after_millis(500).await;
    }
}

That’s all for now. More soon.

Felipe Balbi

Tamal: Everything, Wired

Six names, and the series behind them

The moment the engine gets its clock

No BiSignal, on purpose

The confluence

One line that keeps a promise

A status LED, made a truth table

The tests: the first time the whole thing runs

What we read

Tamal: Out to the Pins

Two names on the door

The line that makes it physical

A pad has two ends

Scalar, not Vec

Reading the net back

Three wires that pass straight through

The one asynchronous wire

One lane, drawn

The tests, and the knot

What we read

Tamal: The Record and the Ring

Three shapes

One encoder, laid in field rulers

The push that never tears

What we read

Tamal: Frames on the Wire

The leaf that removes every zero

Putting the zeros back

From bytes to a word, and back

The CRC, one layer up

The frame: CRC, then stuff, then delimit

The messages the frames carry

The reference-model role, made explicit

What we read

Tamal: Value and Enable

The last door

A tuple, on purpose

Four lanes, one beat

A byte, eight beats

The inverse the engine never calls

Drive once, then let go

Three drives, one field

One corner of a wider bus

The tests

What we read

rambo v0.1.2: the boring release is the point

Tamal: Add, And, and the Taken Branch

Two boxes, one kind of thing

The two-layer plan

Two import lines, two collisions

The core: eight total operations

The wrapper: resolving operand B

The comparator

The tests

What we read

Tamal: Sixteen Registers and a Hardwired Zero

The door, again

The prelude, and the only import

The bank, sealed

Power-up is sixteen zeros

A name is not a slot

readReg: the hole at x0

writeReg: the write that replaces

One invariant, one place, twice

Read-old, write-new, for free

The tests

What we read

Tamal: The Instruction Set

The word

One constructor per opcode

Encode: the easy direction

Decode, and the reserved zero

Total, both ways

A decode within the decode

The tests

What we read

Tamal: The Wire and the Record

SCK is the fabric clock, divided by five

One beat, five cycles

`readReg`: the hole at x0

`writeReg`: the write that replaces

The plumbing: `pico-de-gallo-lib` 0.7.1

The ports: `LoaderIn` and `LoaderOut`

`Lifecycle`: the three lives

`DrainPhase`: a program counter for the sweep

`LoaderSt`: eighteen fields, four records in a trench coat

`confirm`: fold, route, assemble, write through

`finalize`: the delimiter’s verdict

`feedByte`: one byte to the encoder

`leByte`: the little-endian tap