TARA Studio

An integrated software suite for the TARA 16-bit teaching CPU.

TARA (Teaching Architecture for RISC Assembly) is a small, 16-bit RISC ISA designed to reveal how the simplest of computers actually works — from assembly, down through the datapath and microcode, all the way to pixels on a screen. TARA Studio bundles everything you need to learn it, write for it, and run it on real hardware in one desktop application.

From this folder, install the local version and launch it:

python3 -m pip install -e .
python3 run_sim.py

The installed taracpu command launches the same application.

Prefer not to install anything? A browser version of the simulator is also available.

Three tools, one app

TARA Studio opens with these tabs, in order: TARA16 Compiler, TARA16 Assembly, and TARA16 FPGA Tool. The compiler is bundled inside Studio and works without another compiler installation, a native build, or the original compiler folder.

1 · TARA16 Compiler

Write C for the TARA16 CPU, inspect the generated assembly, then send it directly to the simulator and existing FPGA workflow.

• The header shows the bundled C compiler v0.1.0, read directly from the compiler package. This is independent of the Studio distribution version.
• 27 C programs, grouped as Basic (5), Intermediate (6), Advanced (6), Display (6), and Games (4), matching the web compiler library.
• The C program guide documents each example's purpose, inputs, expected results, memory locations, and controls.
• Dark C editor with New, Open, Save, and Save As, bold syntax colours, clean whitespace, and independent font zoom.
• Compile the current editor text, including unsaved changes, with -O0, -O1, or -O2 and a hardware MUL option. Compilation runs in the background.
• Inspect outputs: Studio assembly (.tara), compiler assembly (.s), machine-code image (.hex), listing (.lst), symbols (.sym), and diagnostics.
• Copy build messages with the Build Messages Copy button, which includes the status and all diagnostics, or select text and press Cmd/Ctrl+C.
• Send to Assembly loads and assembles the generated program so you can inspect registers, Step, or Run. Initialized globals are preserved.
• Export the selected output using the compact button at the right of the output pane. Compiling alone does not overwrite the source file or create output files beside it.
• Bundled headers include tara16.h for the display and input byte. Quoted local headers can be resolved from the directory of an opened or saved C file.

For a first run, enter:

int main(void) {
    return 7 * 6;
}

Click Compile C, then Send to Assembly, then Run. When the program halts, R0 contains 42 (0x002A). Connect a target in the FPGA tab to use the existing Run on FPGA action from the Assembly tab.

This is a compact 16-bit C dialect, not a host C environment: int and pointers are 16 bits; long, floating point, and a general C standard library are not available. Code, data, and stack share the limited memory below the input byte and framebuffer. See Compiler integration for the workflow, output formats, memory limits, and maintenance instructions.

All 27 library programs are checked at -O2 with hardware multiplication and software multiplication: 54 builds match the actual WebAssembly compiler, and 54 configurations pass Studio CPU execution checks. Interactive programs use controlled input, framebuffer checks, and quit handling; they are not expected to halt without input. The compiler sources and runtime are identical to the web compiler bundle. Details and reproduction commands are in C program validation.

2 · TARA16 Assembly

A full software simulator of the TARA processor — write a program and watch it run, one instruction at a time, with every register and memory byte in view.

• Syntax-highlighted assembly editor with line numbers and a library of bundled example programs (Basic → Intermediate → Advanced, plus Display demos and playable games like snake, ping pong and flappy bird).
• One-click assembler with inline error reporting.
• Machine-code listing — address, hex encoding, colour-coded binary fields and mnemonic, synchronised to the program counter.
• Register file view — R0–R7 as live cards, with change highlighting.
• Memory viewer — browse all 2 KB of byte-addressable memory, in hex or decimal, with an optional Matplotlib colour-map heatmap.
• Display panel — the 64×64 memory-mapped framebuffer rendered as a pixel raster, with image import.
• Execution log — a per-instruction trace of register and memory changes.
• Step / Run / Stop / Reset / Back, plus Save and Boot of the full machine state, and a variable clock from 1 Hz to full speed (adjustable while running).
• Built-in ISA reference dialog.

3 · TARA16 FPGA Tool

A host-side toolkit that talks to a real TARA processor running on an FPGA (e.g. a Digilent Basys 3) over the board's USB-UART — the same cable that programs it. It can also attach to the local simulator's memory when hardware is unavailable. Bridge the simulator to actual silicon, or debug the same workflow virtually:

• Program the board — without Vivado. After a cold boot the FPGA fabric is blank. Open Board Setup, point it at the synthesised .bit, and press Program FPGA to configure the board over JTAG, then carry on as normal — no Xilinx toolchain, and no licence, on the machine running the demo. Choose FPGA SRAM (a couple of seconds, cleared at the next power cycle) or SPI flash (the board then boots TARA by itself every time it is switched on). Uses openFPGALoader; the first run offers to install it for you.
• Inspect memory live — read any region while the CPU runs, with a heatmap and auto-refresh. Use Connect Memory to choose FPGA USB or Simulator Memory.
• Write & poke — fill a range or change individual bytes by hand.
• Assemble & run on the selected target — open a .tara file (or the program in the editor), and the tool assembles it, loads the machine code, and starts the FPGA or simulator-memory target — no re-synthesis for hardware.
• Because Assembly and FPGA use the same assembler, code you develop in the simulator runs unchanged on the board. A Run on FPGA button in the Assembly tab loads and runs the current program on the connected FPGA USB or Simulator Memory target in one click.

Install & run

Python 3.9+ is required. From a terminal in the Studio folder:

python3 -m pip install -e .
python3 run_sim.py

For a regular local installation, use python3 -m pip install . and then taracpu. PyQt5, Matplotlib, and pyserial are installed automatically. The bundled Python compiler adds no third-party dependency.

Machine-state saves, CSV memory dumps, and UI settings use local/config/ when run from source, or ~/.taracpu/ for a regular installed package. C source files and exported compiler outputs use the locations selected in the file dialogs.

Developer documentation: Code guide and Compiler integration.

Build and publish a release

The current Studio package version is 1.3.0 in pyproject.toml. Version 1.2.2 was already published, so another wheel with its filename is rejected by PyPI. Increase [project].version for each new release.

From this folder:

./upload_to_pip.sh --build     # build and validate without uploading
./upload_to_pip.sh            # rebuild, check PyPI, then upload

The script builds a fresh wheel and source archive, checks their metadata and README with Twine, and rejects an existing release before starting an upload. It also stops if the public version check cannot complete. --test targets TestPyPI; --verbose includes the upload server's response if troubleshooting is needed. Use your existing Twine keyring or .pypirc token configuration.

Set TARA_PYTHON to an interpreter path to choose a Python environment, for example TARA_PYTHON=/path/to/python ./upload_to_pip.sh --build. The default is python3. Build isolation installs the backend required by pyproject.toml; --no-isolation instead uses dependencies already installed in that environment. Build and Twine are installed if missing. No API token is needed for --build or the public release check.

The source archive includes this script, its version-check helper, tests, and documentation. After a partial upload, use a new version for a rebuilt release; the script does not silently skip files or replace published content.

Author & license

Developed by Ayon Chakraborty.

Copyright (C) 2026 Ayon Chakraborty. Licensed under the GNU General Public License, version 3 or later (GPL-3.0-or-later). See LICENSE. The bundled Python compiler is also by Ayon Chakraborty and licensed GPL-3.0-or-later; its parser and preprocessor follow the structure of Rui Ueyama's MIT-licensed chibicc. See compiler provenance.

TARA ISA quick reference

Memory map

The following is the usual layout for handwritten assembly examples. Compiler output packs its code and globals according to the linker, rather than fixing globals at 0x400; inspect the generated listing and symbols for their addresses.

Register conventions