taracpu 1.0.0__tar.gz

taracpu-1.0.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: taracpu
+Version: 1.0.0
+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) |

taracpu-1.0.0/README.md

@@ -0,0 +1,95 @@
+# 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) |

taracpu-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "taracpu"
+version = "1.0.0"
+description = "TARA CPU Simulator — 16-bit RISC teaching architecture (CS2300 at IIT Madras)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+dependencies = [
+    "PyQt5>=5.15",
+    "matplotlib>=3.5",
+]
+
+[project.scripts]
+taracpu = "taracpu:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["src*", "taracpu*"]
+
+[tool.setuptools.package-data]
+"src" = [
+    "assets/*",
+    "assets/logo/*",
+    "examples/progs/*.tara",
+]

taracpu-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

taracpu-1.0.0/src/__init__.py

@@ -0,0 +1 @@
+

taracpu-1.0.0/src/assembler/__init__.py

@@ -0,0 +1 @@
+

taracpu-1.0.0/src/assembler/asm.py

@@ -0,0 +1,241 @@
+"""
+TARA Assembler
+Converts TARA assembly text into 16-bit machine words.
+Supports labels, comments (;), and all instruction formats.
+"""
+
+import re
+from src.simulation.cpu import OP, FMT, sext
+
+class AssemblerError(Exception):
+    def __init__(self, msg, line=None):
+        self.msg = msg
+        self.line = line
+        super().__init__(msg)
+
+    def __str__(self):
+        return f"Line {self.line}: {self.msg}" if self.line else self.msg
+
+
+def parse_reg(tok):
+    """Parse Rn or rn → integer 0-7."""
+    tok = tok.strip().upper()
+    if tok.startswith('R') and tok[1:].isdigit():
+        n = int(tok[1:])
+        if 0 <= n <= 7:
+            return n
+    raise AssemblerError(f"Invalid register '{tok}'")
+
+
+def parse_int(tok, label_map=None, pc=None):
+    """Parse a literal integer or label reference."""
+    tok = tok.strip()
+    if tok.startswith('0x') or tok.startswith('0X'):
+        return int(tok, 16)
+    if tok.startswith('0b') or tok.startswith('0B'):
+        return int(tok, 2)
+    if tok.lstrip('-').isdigit():
+        return int(tok)
+    if label_map is not None and tok in label_map:
+        return label_map[tok]
+    raise AssemblerError(f"Cannot parse value '{tok}'")
+
+
+def parse_mem(tok):
+    """Parse off(Rbase) → (offset_str, reg_str)."""
+    m = re.match(r'^(-?\d+|0x[0-9a-fA-F]+)\(([Rr]\d)\)$', tok.strip())
+    if not m:
+        raise AssemblerError(f"Invalid memory operand '{tok}'")
+    return m.group(1), m.group(2)
+
+
+OPERAND_COUNTS = {
+    'NOP': 0, 'HLT': 0, 'RET': 0,
+    'ADD': 3, 'SUB': 3, 'MUL': 3, 'AND': 3, 'OR': 3, 'XOR': 3, 'SLT': 3,
+    'MOV': 2, 'NOT': 2,
+    'LIL': 2, 'LIH': 2, 'ADDI': 2, 'SHL': 2, 'SHR': 2,
+    'LDW': 2, 'LDB': 2, 'STW': 2, 'STB': 2,
+    'BZ': 2, 'BN': 2,
+    'JMP': 1, 'CALL': 1,
+    'PUSH': 1, 'POP': 1,
+}
+
+
+def _parse_operands(ops_str, mnem):
+    operands = [o.strip() for o in ops_str.split(',') if o.strip()]
+    expected = OPERAND_COUNTS[mnem]
+    if len(operands) != expected:
+        suffix = "" if expected == 1 else "s"
+        raise AssemblerError(
+            f"{mnem} expects {expected} operand{suffix}, got {len(operands)}"
+        )
+    return operands
+
+
+def _label_rel(target_s, iaddr, label_map):
+    """Resolve a branch/jump target to a signed word-offset relative to iaddr+2."""
+    if target_s in label_map:
+        return (label_map[target_s] - (iaddr + 2)) // 2
+    return parse_int(target_s, label_map)
+
+
+def _encode_f0(op):
+    return (op << 11)
+
+def _encode_f1(op, rd, rA, rB):
+    return (op << 11) | (rd << 8) | (rA << 5) | (rB << 2)
+
+def _encode_f2(op, rd, rs):
+    return (op << 11) | (rd << 8) | (rs << 5)
+
+def _encode_f3(op, rd, imm8):
+    imm8 = imm8 & 0xFF
+    return (op << 11) | (rd << 8) | imm8
+
+def _encode_f4(op, rdata, rbase, off5):
+    off5 = off5 & 0x1F
+    return (op << 11) | (rdata << 8) | (rbase << 5) | off5
+
+def _encode_f5(op, rtest, rel8):
+    rel8 = rel8 & 0xFF
+    return (op << 11) | (rtest << 8) | rel8
+
+def _encode_f6(op, rel11):
+    rel11 = rel11 & 0x7FF
+    return (op << 11) | rel11
+
+def _encode_f7(op, rstk):
+    return (op << 11) | (rstk << 8)
+
+
+def assemble(source):
+    """
+    Assemble source text → (words, listing, errors)
+      words  : list of (byte_addr, 16-bit int)
+      listing: list of dict per assembled instruction
+      errors : list of AssemblerError
+    """
+    lines = source.splitlines()
+    errors = []
+    label_map = {}        # label → byte address
+    parsed = []           # list of (lineno, addr, mnemonic, operands_str, original)
+
+    # ── Pass 1: strip comments, collect labels, count addresses ───────────────
+    addr = 0
+    for lineno, raw in enumerate(lines, 1):
+        line = raw.split(';')[0].strip()
+        if not line:
+            continue
+
+        # Extract label(s)
+        while ':' in line:
+            colon = line.index(':')
+            label = line[:colon].strip()
+            if label:
+                label_map[label] = addr
+            line = line[colon+1:].strip()
+
+        if not line:
+            continue
+
+        parts = line.split(None, 1)
+        mnem = parts[0].upper()
+        ops  = parts[1].strip() if len(parts) > 1 else ''
+
+        if mnem not in OP:
+            errors.append(AssemblerError(f"Unknown mnemonic '{mnem}'", lineno))
+            continue
+
+        parsed.append((lineno, addr, mnem, ops, raw.rstrip()))
+        addr += 2
+
+    # ── Pass 2: encode instructions ───────────────────────────────────────────
+    words   = []
+    listing = []
+
+    for (lineno, iaddr, mnem, ops_str, original) in parsed:
+        opcode = OP[mnem]
+        word = 0
+        err = None
+
+        try:
+            operands = _parse_operands(ops_str, mnem)
+            if mnem in ('NOP', 'HLT', 'RET'):
+                word = _encode_f0(opcode)
+
+            elif mnem in ('ADD', 'SUB', 'MUL', 'AND', 'OR', 'XOR', 'SLT'):
+                # rd, rA, rB
+                rd = parse_reg(operands[0])
+                rA = parse_reg(operands[1])
+                rB = parse_reg(operands[2])
+                word = _encode_f1(opcode, rd, rA, rB)
+
+            elif mnem in ('MOV', 'NOT'):
+                # rd, rs
+                rd = parse_reg(operands[0])
+                rs = parse_reg(operands[1])
+                word = _encode_f2(opcode, rd, rs)
+
+            elif mnem in ('LIL', 'LIH', 'ADDI'):
+                rd = parse_reg(operands[0])
+                imm = parse_int(operands[1], label_map)
+                word = _encode_f3(opcode, rd, imm)
+
+            elif mnem in ('SHL', 'SHR'):
+                # rd, shamt
+                rd = parse_reg(operands[0])
+                shamt = parse_int(operands[1], label_map)
+                word = _encode_f3(opcode, rd, shamt)
+
+            elif mnem in ('LDW', 'LDB'):
+                # rd, off(rbase)
+                rd = parse_reg(operands[0])
+                off_s, base_s = parse_mem(operands[1])
+                off = parse_int(off_s, label_map)
+                rbase = parse_reg(base_s)
+                word = _encode_f4(opcode, rd, rbase, off)
+
+            elif mnem in ('STW', 'STB'):
+                # rs, off(rbase)
+                rs = parse_reg(operands[0])
+                off_s, base_s = parse_mem(operands[1])
+                off = parse_int(off_s, label_map)
+                rbase = parse_reg(base_s)
+                word = _encode_f4(opcode, rs, rbase, off)
+
+            elif mnem in ('BZ', 'BN'):
+                rtest = parse_reg(operands[0])
+                rel = _label_rel(operands[1], iaddr, label_map)
+                word = _encode_f5(opcode, rtest, rel)
+
+            elif mnem in ('JMP', 'CALL'):
+                rel = _label_rel(operands[0], iaddr, label_map)
+                word = _encode_f6(opcode, rel)
+
+            elif mnem in ('PUSH', 'POP'):
+                rs = parse_reg(operands[0])
+                word = _encode_f7(opcode, rs)
+
+            else:
+                raise AssemblerError(f"Unhandled mnemonic '{mnem}'")
+
+        except (AssemblerError, ValueError, IndexError) as e:
+            if not isinstance(e, AssemblerError):
+                e = AssemblerError(str(e))
+            e.line = lineno
+            errors.append(e)
+            err = e
+            word = 0xDEAD
+
+        words.append((iaddr, word))
+        listing.append({
+            'lineno': lineno,
+            'addr': iaddr,
+            'word': word,
+            'mnem': mnem,
+            'ops': ops_str,
+            'original': original,
+            'error': bool(err),
+        })
+
+    return words, listing, errors, label_map

taracpu-1.0.0/src/examples/__init__.py

@@ -0,0 +1 @@
+

taracpu-1.0.0/src/examples/examples.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+
+from src.paths import PROGS_DIR
+
+
+def _display_name(path):
+    return path.stem.replace('_', ' ').title()
+
+
+def load_examples():
+    examples = {}
+    progs = Path(PROGS_DIR)
+    if not progs.exists():
+        return examples
+    for path in sorted(progs.glob('*.tara')):
+        examples[_display_name(path)] = path.read_text(encoding='utf-8', errors='replace')
+    return examples

taracpu-1.0.0/src/examples/progs/binary_search.tara

@@ -0,0 +1,71 @@
+; Binary search for a sorted byte array.
+;
+; Interface at label "search":
+;   R0 = starting byte address of sorted array
+;   R1 = number of elements
+;   R2 = search key
+;
+; Return value:
+;   R3 = index of matching element, or 0xFFFF if not found
+;
+; The demo setup below searches for 7 in [1,3,5,7,9,11] at 0x0400.
+; After HLT, R3 contains 3.
+
+; ---- Demo setup -----------------------------------------------------
+        LIL  R0, 0
+        LIH  R0, 4          ; R0 = 0x0400
+        LIL  R1, 6          ; N = 6 byte elements
+        LIL  R2, 7          ; key = 7
+
+        LIL  R3, 1
+        STB  R3, 0(R0)
+        LIL  R3, 3
+        STB  R3, 1(R0)
+        LIL  R3, 5
+        STB  R3, 2(R0)
+        LIL  R3, 7
+        STB  R3, 3(R0)
+        LIL  R3, 9
+        STB  R3, 4(R0)
+        LIL  R3, 11
+        STB  R3, 5(R0)
+
+; ---- Binary search --------------------------------------------------
+; R3 = result index
+; R4 = low index
+; R5 = high index
+; R6 = mid index
+; R7 = scratch / loaded array value
+
+search: LIL  R3, 255
+        LIH  R3, 255        ; default result = 0xFFFF (not found)
+        LIL  R4, 0          ; low = 0
+        MOV  R5, R1
+        ADDI R5, -1         ; high = N - 1
+
+loop:   SUB  R7, R5, R4
+        BN   R7, done       ; high < low
+
+        MOV  R6, R4
+        ADD  R6, R6, R5
+        SHR  R6, 1          ; mid = (low + high) / 2
+
+        ADD  R7, R0, R6
+        LDB  R7, 0(R7)      ; R7 = A[mid]
+        SUB  R7, R7, R2     ; compare A[mid] - key
+
+        BZ   R7, found
+        BN   R7, go_right   ; A[mid] < key
+
+        MOV  R5, R6         ; A[mid] > key, high = mid - 1
+        ADDI R5, -1
+        JMP  loop
+
+go_right:
+        MOV  R4, R6         ; low = mid + 1
+        ADDI R4, 1
+        JMP  loop
+
+found:  MOV  R3, R6
+
+done:   HLT