Tomato

A 32-bit computer architecture built from copper to browser.

Physical ALU slice · FPGA Tomato OS recording (4× preview)

The animation is a sped-up preview of the complete FPGA machine.

Tomato is one architecture expressed at several layers:

• a fabricated and soldered 8-bit 74xx Dual-LUT ALU slice;
• a complete FPGA Tomato on the Nexys A7-100T that boots the assembly-written Tomato OS;
• TOMATO OS v3.0, written in Tomato assembly, with 14 menu entries;
• a functional Virtual Tomato ISA emulator in the browser;
• editable Digital schematics, KiCad boards, RTL, an assembler, and focused verification.

The complete discrete computer remains a goal. The assembled ALU slice is real hardware, but it is not a complete discrete machine. The complete running computer in this repository is the FPGA implementation.

Explore: architecture · current status · Tomato OS · ISA · compute · documentation index · project site

Architecture at a glance

These curated diagrams explain the system; the interactive GitDiagram provides a zoomable, generated map of the public repository's default branch.

Visual entry points: interactive repository map · architecture guide · web architecture · ISA reference · run Virtual Tomato

One architecture, several realizations

The four realization boxes are deliberately separate. The assembled discrete hardware proves the ALU slice; the FPGA is the complete machine; Icarus runs the RTL locally; and the browser is a functional ISA emulator. Diagram source.

From source files to runnable artifacts

The generated FPGA burn and browser image share the same OS and control data. They do not share an execution engine: the FPGA and Icarus execute Verilog, while tomato-cpu.js mirrors the ISA-level behavior in JavaScript. Diagram source.

Inside FPGA Tomato

The board harness owns clocks, pins, keypad debounce, glyph rendering, DVI, and seven-segment output. The machine core exposes those facilities as ports and memory-mapped windows, keeping board-specific wiring outside the CPU RTL. Diagram source.

Authority and state boundaries

• Edit: Digital schematics, ISA CSVs, assembly sources, and FPGA/browser implementation source.
• Regenerate: .mem images, rtl/burn/*.vh, tomato-os.bin, and bitstreams. These are derived artifacts, not design authorities.
• Runtime state: FPGA RAM, registers, framebuffer, compiler, radio mailbox, and the browser machine are volatile. Reset or reload restores the compiled image; this repository has no application database.
• External systems: Envelop clients, durable queues, hosted services, and the nearby bridge belong to the separate Envelop project.

What runs now

Layer	Current, repository-backed statement
Architecture	32-bit datapath and instruction word
ALU	Custom three-source Dual-LUT ALU: two LUT3 functions feed an adder, f(a,b,c) + g(a,b,c) + carry
ISA	91 instructions plus NOP, 92 burned rows in a 512-row control ROM
Register array	Discrete (primary): 32,768 × 32-bit. FPGA: 256 × 32-bit, addressed as 3 bank bits plus a 5-bit register field; r0 is hardwired to zero — no space for more on that implementation
FPGA	100 MHz board input; 6.25 MHz default CPU and 25 MHz pixel clocks; 90 MHz is only the nextpnr timing target
OS	The complete FPGA computer boots assembly-written TOMATO OS v3.0, with 14 menu entries including Envelop
Browser	Functional ISA-level emulation; not cycle-accurate RTL or physical execution
Hardware compiler	Counter FSM searches all 65,536 LUT pairs for one fixed A/B/C/carry/output example; a hit verifies that example, not a general function
ALU verification	A 130-billion-vector 32-bit ALU run is recorded and its harness is reproducible; the full run log is not checked in

The architectural register count is 32,768, because discrete is the superior design constraint. FPGA implementation remains 256 × 32-bit because there is no space for a larger file; its 3-read/1-write array maps to distributed RAM. Discrete uses external SRAM plus a seven-bit superbank and SETBANK2. Neither the superbank nor that instruction exists in the current FPGA RTL and burned ISA.

For evidence paths and the distinction between source-complete, hardware-dependent, and deployed behavior, use docs/status.md. Historical journal entries can describe earlier designs and counts; they do not override current sources.

See it, run it, inspect it

Browser

Open the Tomato site and choose the Virtual Tomato experience. Its checked-in OS image is generated from the assembly and control data in this repository. Results there must be labeled virtual.

Play with Virtual Tomato →
Functional ISA emulation with simulated peripherals—not FPGA or discrete-hardware execution.

Local RTL simulation

Icarus Verilog can boot the OS and print its framebuffer without an FPGA:

make -C hardware/fpga/core os

Run the focused core regression:

make -C hardware/fpga/core test

These commands prove simulation behavior, not a currently programmed board.

Assemble a Tomato program

python3 software/assembler.py software/asm/counter.s \
  -o /tmp/counter.mem --list
python3 software/assembler.py --selftest

The assembler reads the burned ISA and pseudo-instruction CSVs rather than carrying a private opcode table.

FPGA build

The default flow is Yosys → nextpnr-xilinx → Project X-Ray. An optional Linux Vivado batch target is also provided. Building a bitstream does not prove that a board is currently programmed.

make fpga-setup
make fpga

Programming is intentionally a separate, hardware-changing action; see hardware/fpga/README.md.

Proof across the stack

• Physical scope: hardware/kicad/boards/07_alu/
• Editable logic: hardware/digital/
• Complete FPGA machine: hardware/fpga/core/
• Machine software: software/
• Verification: verification/
• Evidence and asset provenance: docs/assets.md

Envelop and compute

Envelop is a separate messaging project. Its Tomato-side client and bounded compute executor are linked into Tomato OS; its user clients, backend, and nearby bridge live outside this repository.

The intended hardware message path is:

person → Envelop web app → backend queue → nearby verified bridge → Envelop in Tomato OS → Tomato CPU → labeled reply

Source in a repository is not evidence that a bridge is active or that a reply ran on hardware. Bridge software is available in the separate Envelop project, but a nearby authenticated bridge and completed FPGA job require live evidence. Virtual previews are explicit, separate, and labeled. See docs/compute.md for the current boundary. Diagram source.

Repository map

Path	Purpose
docs/	Canonical guides, ISA contracts, and historical journal
hardware/digital/	Editable architecture schematics
hardware/kicad/	PCB designs and assembly records
hardware/fpga/	Complete machine, board harness, and simulation
software/	Assembler, programs, and Tomato OS
microcode/	Control-ROM packaging
verification/	ALU and implementation checks
web/	Project site and browser emulator

Documentation and history

Start with docs/README.md. It separates current canonical guidance from the dated docs/log/ engineering record. The journal preserves decisions, wrong turns, and superseded designs as history; use the current journal index to navigate it.

Documentation authority and terminology are defined in docs/documentation-policy.md. When prose and executable sources disagree, that policy determines which source wins.

License and author

Tomato is licensed under the Solderpad Hardware License 2.1. Architecture and project by Tyrone Marhguy, Computer Engineering ’28, University of Pennsylvania.

Contributing · security · citation · third-party notices