Metadata-Version: 2.4
Name: taracpu
Version: 1.2.2
Summary: TARA Studio — an integrated software suite for the TARA 16-bit teaching CPU: a desktop ISA simulator plus an FPGA memory-interfacing toolkit.
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.

```bash
pip install taracpu
taracpu          # launch TARA Studio
```

> Prefer not to install anything? A [browser version of the simulator](https://cse.iitm.ac.in/~ayon/courses/CS2300/taracpu/) is also available.

---

## Two tools, one app

TARA Studio opens with two top-level tabs:

### 1 · TARA CPU Simulator
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.

### 2 · TARA 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 both tools share the same assembler, code you develop in the simulator runs
  unchanged on the board. A **Run on FPGA** button in the Simulator tab loads and runs
  the current program on the connected FPGA USB or Simulator Memory target in one click.

---

## Install & run

```bash
pip install taracpu
taracpu
```

Dependencies (installed automatically): PyQt5, Matplotlib, and pyserial (for the FPGA
tool). Python 3.9+.

User files — machine-state saves, CSV memory dumps and UI settings — are written to
`~/.taracpu/` on first launch.

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

---

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