taracpu 1.0.2

TARA CPU Simulator — 16-bit RISC teaching architecture (CS2300 at IIT Madras)

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

License

Copyright (C) 2026 Ayon Chakraborty, IIT Madras. All rights reserved.

This project is licensed under the GNU General Public License, version 3 or later (GPL-3.0-or-later). See LICENSE.

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

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:

{
  "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

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)