Tamal: The CRC block

Felipe Balbi — Mon, 20 Jul 2026 09:00:00 +0000
As mentioned before Tamal</a> is an FPGA eSPI exerciser with its gateware written in Haskell</a> and compiled to verilog with Clash</a>.
In a previous</a> 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</h2>
As promised, the entire source fits in a screenfull:
module</span> Tamal.Crc</span></span>
  (</span> crc8Update</span></span>
  )</span> where</span></span>
</span>
import</span> Clash.Prelude</span></span>
</span>
crc8Update</span> ::</span> BitVector</span> 8</span> -></span> BitVector</span> 8</span> -></span> BitVector</span> 8</span></span>
crc8Update crc byte </span>=</span> foldl step crc </span>(</span>unpack byte </span>::</span> Vec</span> 8</span> Bit</span>)</span></span>
 where</span></span>
  step</span> ::</span> BitVector</span> 8</span> -></span> Bit</span> -></span> BitVector</span> 8</span></span>
  step c inBit</span></span>
    |</span> feedbackBit </span>==</span> high </span>=</span> shifted </span>`</span>xor</span>`</span> 0x07</span></span>
    |</span> otherwise </span>=</span> shifted</span></span>
   where</span></span>
    feedbackBit </span>=</span> msb c </span>`</span>xor</span>`</span> inBit</span></span>
    shifted </span>=</span> c </span>`</span>shiftL</span>`</span> 1</span></span></code></pre>
The first thing we notice are the top three lines:</p>
module</span> Tamal.Crc</span></span>
  (</span> crc8Update</span></span>
  )</span> where</span></span></code></pre>
A Haskell file opens by naming itself. module Tamal.Crc</code>
declares this module’s name, and the name is not free-form: it
mirrors the path on disk. Tamal.Crc</code> lives in
src/Tamal/Crc.hs</code>, a dot for each directory separator, the same
way a Rust crate::module</code> 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.</p>
The parentheses are the more interesting part. They are the
module’s export list</strong> — the complete, deliberate enumeration of
what the outside world is allowed to see:</p>

A module is a wall with a door in it, and the export list is
the door.</p>
</blockquote>
Only crc8Update</code> is on that list, so only crc8Update</code> leaves
the file. Everything else — and in a moment we will meet step</code>,
the helper that does the actual bit-twiddling — stays private,
sealed behind the wall. Had the author written
module Tamal.Crc where</code> with no list at all, Haskell would
export everything</em> by default, step</code> 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.</p>
That choice buys more than tidiness. step</code> is an internal detail
of how this</em> 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</code> and never reach for step</code>:
step</code> is not theirs to reach.)</p>
The prelude swap</h2>
The line under the module header looks like ceremony and is
anything but:</p>
import</span> Clash.Prelude</span></span></code></pre>
Every Haskell file begins in a world someone else furnished. That
furniture is the prelude</em>: the batch of names, types, and
functions that are simply there</em> before you import anything.
Ordinary Haskell hands you the standard Prelude</code> — Int</code>,
Bool</code>, lists, foldl</code>, map</code>, the familiar fittings.
import Clash.Prelude</code> throws that set out and moves a different
one in.</p>
What arrives instead is a hardware vocabulary: the Bit</code>,
BitVector</code>, Vec</code>, and Signal</code> types from the primer</a>, the
high</code> and low</code> bit literals, msb</code>, shiftL</code>, xor</code>, unpack</code> —
and versions of the everyday functions, foldl</code> among them, that
operate on Vec</code>s and lower to gates. This one line is the
difference between a program that computes and a description that
becomes a circuit:</p>

Swapping the prelude is what turns a Haskell file into a
hardware description.</p>
</blockquote>
Clash leans on the swap so hard that it shadows</em> the list
versions of common names. That has a visible consequence we will
run into in the test file: there, map</code> and ++</code> would mean the
Vec</code> versions, so gluing plain lists together has to reach for a
list comprehension and <></code> instead. File that away; for now the
thing to see is that the lone foldl</code> two lines down is one of
these swapped names. It is the Vec</code> 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</em>.</p>
The type, and why it has to be this one</h2>
Now the signature, which under the primer’s reading is already
half the documentation:</p>
crc8Update</span> ::</span> BitVector</span> 8</span> -></span> BitVector</span> 8</span> -></span> BitVector</span> 8</span></span></code></pre>
Two arrows, so — remembering that -></code> associates to the right and
every function takes one argument — this is “give me a
BitVector 8</code>, then another BitVector 8</code>, and I hand back a
BitVector 8</code>.” Name the three roles and the intent appears: the
first argument is the running CRC</strong>, the second is the
incoming byte</strong>, and the result is the new running CRC</strong>. It
is an accumulator update, one byte at a time.</p>
The type could have been written other ways, and the two decisions
behind it are both load-bearing.</p>
The first is BitVector 8</code> rather than Unsigned 8</code> or a Word</code>.
A BitVector 8</code> is eight wires with no</em> arithmetic meaning
attached — the type of a thing you xor</code>, shift, and index into,
not a thing you add. Unsigned 8</code> would have invited +</code>, *</code>, and
carry, arithmetic this function never performs. Choosing
BitVector</code> states plainly that a CRC is bit-manipulation, not
counting, and the type system then holds the code to that promise:
reach for +</code> on a BitVector</code> by accident and the compiler
objects. It is the primer’s “wire-width checker,” applied one
level up — the kind</em> of value, not just its width, is part of the
contract.</p>
The second decision is the argument order: running CRC first, byte
second. That order is chosen so the function is fold-shaped</strong>.
Recall currying — crc8Update crc</code> is a legal value on its own, a
function still waiting for a byte, meaning “advance this</em> 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</code>
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.</p>
One last thing the type says by saying nothing. Every BitVector 8</code>
in, produces a definite BitVector 8</code> out — no missing cases, no
error, no Maybe</code>. That totality is</em> 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</code> 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.</p>
A CRC is a remainder</h2>
Strip the acronym away and a CRC is a remainder</strong> — the leftover
from a division, carried out in a number system with exactly two
digits.</p>
Here is the whole trick. Take a stream of bits and read it as the
coefficients of a polynomial: the byte 00000111</code> 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</strong>.
That single fact is why CRC hardware is cheap — every
“subtraction” below is just an xor</code>.</p>
The divisor in this division has a name, the generator
polynomial</strong>. Tamal’s is the one the module comment spells out,</p>
$$ G(x) = x^8 + x^2 + x + 1 $$</p>
whose coefficients, written as bits, are 1 0000 0111</code> — nine bits,
0x107</code>, degree eight. Look at the low eight of those bits: 0000 0111</code>, 0x07</code>, 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.</p>
To take the CRC of a message $M$ is to do one thing:</p>

Shift the message up by eight bits, divide by $G$, and keep the
remainder.</p>
</blockquote>
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.</p>
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</code>, which as a polynomial is simply $1$. Shift up by
$x^8$ and reduce modulo $G$:</p>
$$ x^8 \equiv x^2 + x + 1 \pmod{G} $$</p>
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</code>,
which is 0x07</code>. Remember that number. The code is about to
reproduce it out of shifts and XORs, and the two answers are going
to match.</p>
The left fold</h2>
With the division in mind, the body is short:</p>
crc8Update crc byte </span>=</span> foldl step crc </span>(</span>unpack byte </span>::</span> Vec</span> 8</span> Bit</span>)</span></span></code></pre>
Two moves live on that line: turn the byte into bits, then fold
over them.</p>
unpack byte :: Vec 8 Bit</code> takes the opaque eight-wire BitVector</code>
and re-presents it as a Vec 8 Bit</code>, a sequence of eight
individual Bit</code>s you can walk one at a time. The annotation :: Vec 8 Bit</code> is needed because unpack</code> 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</code> of the vector is the most significant bit, so walking
the vector head to tail walks the byte MSB first</strong>, which is
what this CRC (and eSPI, and SMBus) require.</p>
Then the fold. From a purely functional standpoint a left fold1</a></sup>
is the most ordinary thing in the world, and it has nothing to do
with mutation:</p>

foldl</code> threads an accumulator through a sequence, left to
right, handing the running result and the next element to a
combining function, over and over.</p>
</blockquote>
Written out, foldl step crc [b0, b1, .. b7]</code> is nothing but a
nest of calls:</p>
step (step (step (.. step (step crc b0) b1 ..) b6) b7)</span></span></code></pre>
The crc</code> seeds the accumulator. step</code> folds in b0</code> to produce a
new</em> accumulator; that value feeds into step</code> alongside b1</code> to
produce the next; and so on down the byte until b7</code> yields the
result. Nothing is ever overwritten. Each step</code> returns</strong>2</a></sup>
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</em>, it is
replaced</em>, eight times, by eight applications of one pure function.</p>
And because the vector has a length the compiler knows — 8</code>, right
there in Vec 8 Bit</code> — the hardware reading is the one the primer
promised:</p>

A fold over a fixed-size Vec</code> is a pipeline unrolled in space,
not a loop unrolled in time.</p>
</blockquote>
Clash does not synthesize a counter and a loop. It lays down eight
copies of step</code>’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</strong>, the textbook circuit
for a bit-serial CRC — except Clash derived</em> it from a foldl</code>
instead of asking anyone to draw it. The accumulator is the
register’s contents, step</code> is the tap logic, and the fold is the
wiring between the stages.</p>