Tessera

Tessera is a PIO and PRU hybrid protocol engine for the Tiny Tapeout IHP shuttle. It is a separate design from TPSM. TPSM explores a pure transport-triggered architecture. Tessera explores the best small multi-state-machine I/O processor for the same protocol set.

The name comes from a small tile. The design is a tile of state machines, shared memory, and shared protocol hardware.

Status

The specification is complete. The assembler, ISS, RTL core, SPI and QSPI host bus, and the base top level are implemented. UART, SPI, I2C, and PS/2 programs, reference models, and RTL tests are in place. Unit testbenches, a directed top test, and the ISS and RTL lockstep flow pass.

The cocotb host and protocol suite passes 14 tests. The v1 extensions are in place, including the I2C read and the PS/2 host-to-device receive. The USB Low-Speed program, formal, and hardening are next. 10BASE-T is out of scope. See PLAN.md and TODO.md.

Goals

• Run UART, SPI, I2C, PS/2, JTAG, SWD, CAN, and USB Low-Speed.
• Use two independent state machines so TX and RX do not block each other.
• Keep the ISA small enough to assemble by hand and verify with a simple ISS.
• Add a small ALU so counters, masks, and CRC helpers do not need bit tricks.
• Keep the host interface on SPI or QSPI.
• Fit within the Tiny Tapeout tile budget.

Architecture at a glance

• Two to four state machines, set by the SM_COUNT parameter. The base build has two.
• Shared 32 or 64 word by 24 bit instruction memory with one read port per state machine.
• Each state machine has its own PC, X and Y registers, 8-bit ALU, flags, 32-bit OSR and ISR, shift counters, delay counter, clock divider, and pin configuration.
• Four shared 32-bit FIFOs, four words deep, assignable to transmit or receive.
• Shared pin unit with per-pin direction, open-drain, input synchronizer, and sticky edge flags.
• Shared Line Coder for NRZI, bit stuffing, differential output, and CAN arbitration.
• Shared 16-bit CRC with two contexts and CRC-5, CRC-15, and CRC-16 modes.
• Host bus with 1-bit SPI and 4-bit QSPI modes.
• 50 MHz core clock. The per-state-machine divider sets slower protocol rates.

The core clock is 50 MHz. 10BASE-T is out of scope, so there is no need for a clock that is a multiple of 20 MHz.

Instruction set

Every instruction is 24 bits.

Bits	Field	Width
23:19	Opcode	5
18:15	Condition	4
14:10	Delay	5
9:0	Operand	10

The operand format depends on the opcode. The ISA includes jumps, waits, shifts, FIFO access, moves, interrupts, immediate set, ALU operations, pin operations, configuration, delay, halt, and no operation.

The WAIT instruction has separate modes for pin low, pin high, falling edge, rising edge, IRQ clear, IRQ set, FIFO not empty, FIFO not full, and shift status. A program does not need the WAIT 0 then WAIT 1 workaround.

The full ISA is in docs/isa.md.

Protocol scope

Protocol	State machines	Notes
UART 8N1	2	Full duplex
SPI master	1 or 2	Full duplex
I2C master	1	Read with repeated START, clock stretching, ACK and NACK
PS/2 device	1	Device frames, and host frames with device ACK
JTAG	1	TAP, IR, and DR scans
SWD	1	Read, write, ACK, parity
CAN 2.0	2	TX and RX monitor, CRC-15
USB Low-Speed	2	Packet engine, CRC-5 and CRC-16

The protocol plans are in docs/protocols.md.

Repository layout

Path	Contents
docs/	Architecture, ISA, protocols, verification, host, and tooling
rtl/	Synthesizable SystemVerilog
tb/	Verilator testbenches
tb/cocotb/	cocotb system and protocol tests
sw/	Assembly programs and generated hex
tools/	Assembler, ISS, protocol models, and random generator
build/	Generated output, not tracked

Build and test

The build system is a Makefile.

Target	Action
make asm	Assemble every program in sw/
make hex	Alias for make asm
make lint	Run Verible lint
make vlt-lint	Run Verilator lint
make test	Run every SystemVerilog testbench
make tools-test	Run the assembler and ISS tests
make run-<tb>	Run one testbench
make cocotb	Run the cocotb tests
make test-all	Run the tool tests, RTL tests, cocotb tests, and random lockstep
make format	Format SystemVerilog
make format-check	Fail when a file needs formatting
make area	Report synthesized cell area
make cosim	Compare the ISS with the RTL
make cosim-random	Compare random programs
make clean	Remove build/

Cocotb setup

The cocotb run uses tb/cocotb/.venv. Create it once:

cd tb/cocotb
uv venv --python 3.12
uv pip install cocotb

Dev container and LibreLane

.devcontainer/ builds the Tiny Tapeout IHP environment. It has Verilator 5.052, Verible, uv, tt-support-tools, and LibreLane 3.0.0.dev44, and it runs the hardening tools through docker-in-docker. Open the repo in VS Code and reopen it in the container. make setup runs after creation and prepares tt/ and the cocotb environment.

Target	Action
make tt-config	Write src/user_config.json and src/config_merged.json from info.yaml
make synth	Run LibreLane through Yosys synthesis only. No placement or routing. It reports the cell area in runs/synth/06-yosys-synthesis/reports/stat.rpt
make harden	Run the full RTL to GDS flow. This takes hours

src/ holds symlinks to rtl/. tools/tt_config.py replaces tt_tool.py --create-user-config because the Tiny Tapeout port check cannot parse SystemVerilog packages. src/config.json sets USE_SLANG so LibreLane reads the sources with the slang frontend.

Requirements

• Verilator 5.x.
• Icarus Verilog.
• Verible.
• Python 3.
• Yosys and SymbiYosys for formal checks.
• LibreLane for hardening and static timing analysis.

Documentation

• docs/arch.md describes the architecture.
• docs/isa.md describes the instruction set.
• docs/protocols.md describes the protocol programs.
• docs/verification.md describes the invariants and test plan.
• docs/host.md describes the host bus and config map.
• docs/tooling.md describes the assembler, ISS, and reference models.

License

Licensed under the Apache License, Version 2.0. See LICENSE.

Copyright 2026 Dragos Bajanica.