Metadata-Version: 2.4
Name: taracpu
Version: 1.0.1
Summary: TARA CPU Simulator — 16-bit RISC teaching architecture (CS2300 at IIT Madras)
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: PyQt5>=5.15
Requires-Dist: matplotlib>=3.5

# TARA CPU Simulator (CS2300 at IIT Madras)

A full-featured desktop simulator for the **TARA (Teaching Architecture for RISC Assembly)** ISA from CS2300 taught at IIT Madras, refer https://cse.iitm.ac.in/~ayon/courses/CS2300/CS2300.html

## Features
- **Syntax-highlighted assembly editor** with line numbers and 6 built-in example programs
- **One-click assembler** with error reporting
- **Machine code listing** with hex + colored binary fields, synchronized to PC
- **Register file view** — 8 registers in a 4x2 visual bank, with change highlighting
- **Memory viewer** — browse all 2 KB of byte-addressable memory, with optional Matplotlib colormap heatmap
- **Display panel** — 64x64 memory-mapped raster with 1-bit packed pixels and directional input byte
- **Instruction decode panel** — shows format, fields, and human-readable effect
- **Execution log** — per-instruction trace with register changes
- **Step / Run / Stop / Reset** controls
- **Save Machine State / Boot State** controls for pausing and continuing later
- **Variable clock** — 1 Hz to max speed via presets or custom frequency, adjustable while running

## How to Run

```bash
pip install PyQt5 matplotlib
python3 run_sim.py
# or as a package:
python3 -m src.run_sim
```

## Classroom Font Settings

The editor, machine-code listing, memory heatmap matrix, and register file use larger classroom-friendly defaults. You can also edit `config/ui_settings.json` before starting the simulator:

```json
{
  "base_font_size": 14,
  "editor_font_size": 15,
  "listing_font_size": 12,
  "memory_font_size": 12,
  "register_font_size": 16
}
```

The editor, listing, and memory matrix also have `A-` / `A+` controls in the UI; those changes are saved back to the config file.

## Project Layout

```text
src/
  assembler/      TARA assembler
  simulation/     CPU core and ISA behavior
  ui/             PyQt application, panels, theme, dialogs
  examples/       bundled example programs
  assets/logo/    application logos
config/
  memory/         memory CSV dumps
  cpu_state/      machine-state JSON dumps
```

## Workflow

1. Write or load assembly code in the **editor** (left panel)
2. Click **⚙ Assemble & Load** — errors appear below the editor
3. Use **⏭ Step** to execute one instruction at a time
4. Or click **▶ Run** with a chosen clock frequency
5. Watch registers, memory, listing highlight, and the decode panel update in real time
6. Click **💾 Save Machine State** to write registers, PC, memory, counters, and source to JSON
7. Later click **⤴ Boot State** to restore the JSON state and continue computation
8. Click **↺ Reset** to reload the program and start over

## 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 | Display keyboard byte: bit0=left, bit1=right, bit2=up, bit3=down |
| 0x600–0x7FF | Display framebuffer, 64x64 pixels, 1 bit per pixel, 8 pixels per byte. Pixel values: 0 off, 1 on. |

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