Metadata-Version: 2.4
Name: taracpu
Version: 1.3.1
Summary: TARA Studio — a Python C compiler, assembly simulator and FPGA toolkit for the TARA 16-bit teaching CPU.
Author: Ayon Chakraborty
License-Expression: GPL-3.0-or-later
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyQt5>=5.15
Requires-Dist: matplotlib>=3.5
Requires-Dist: pyserial>=3.5
Dynamic: license-file

# 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:

```bash
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](https://cse.iitm.ac.in/~ayon/courses/CS2300/taracpu/) 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](C_PROGRAMS.md) 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:

```c
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](COMPILER_INTEGRATION.md) 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](C_PROGRAMS.md#validation-and-wasm-reference).

### 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](https://trabucayre.github.io/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:

```bash
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](CODE_GUIDE.md) and
[Compiler integration](COMPILER_INTEGRATION.md).

## Build and publish a release

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

From this folder:

```bash
./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](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](COMPILER_INTEGRATION.md#source-and-license).

---

## TARA ISA quick reference

| Format | Instructions | Encoding |
|--------|-------------|---------|
| F0 | NOP, HLT, RET | `op[15:11] 00000000000` |
| F1 | ADD, SUB, MUL, AND, OR, XOR, SLT | `op rd rsA rsB 00` |
| F2 | MOV, NOT | `op rd rs 00000` |
| F3 | LIL, LIH, ADDI, SHL, SHR | `op rd imm8` |
| F4 | LDW, STW, LDB, STB | `op rdata rbase off5` |
| F5 | BZ, BN | `op rtest rel8` |
| F6 | JMP, CALL | `op rel11` |
| F7 | PUSH, POP | `op rstk 00000000` |

### 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.

| Range | Use |
|-------|-----|
| 0x000–0x3FF | Program code |
| 0x400–0x4FF | Data / arrays |
| 0x500–0x5FE | Stack (R7) |
| 0x5FF | Live input byte: bit0=up, bit1=down, bit2=left, bit3=right, bit4=quit |
| 0x600–0x7FF | Display framebuffer — 64×64 pixels, 1 bit per pixel, 8 pixels per byte |

### Register conventions
| Reg | Convention |
|-----|-----------|
| R0–R5 | General purpose |
| R6 | Link register (CALL / RET) |
| R7 | Stack pointer (PUSH / POP) |
