Metadata-Version: 2.4
Name: taracpu
Version: 1.1.1
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.
Bridge the simulator to actual silicon:

- **Inspect memory live** — read any region while the CPU runs, with a heatmap and
  auto-refresh.
- **Write & poke** — fill a range or change individual bytes by hand.
- **Assemble & run on hardware** — open a `.tara` file (or the program in the editor),
  and the tool assembles it, holds the CPU, streams the machine code over USB, and
  releases it — **no re-synthesis**.
- 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 a connected board 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) |
