taracpu 1.0.0__py3-none-any.whl

src/__init__.py

@@ -0,0 +1 @@
+

src/assembler/__init__.py

@@ -0,0 +1 @@
+

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

src/examples/__init__.py

@@ -0,0 +1 @@
+

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

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

src/examples/progs/display_bouncing_ball.tara

@@ -0,0 +1,349 @@
+; Bouncing glyph demo for the TARA memory-mapped display.
+;
+; Display map:
+;   0x0600-0x07FF  framebuffer
+;   64x64 pixels, 1 bit per pixel, 8 horizontal pixels per byte
+;   framebuffer row stride = 8 bytes
+;
+; Glyph map:
+;   0x0400 byte  glyph width in pixels
+;   0x0401 byte  glyph height in pixels
+;   0x0402...    packed 1-bit row-major glyph bytes
+;
+; Glyph rows are stored top-to-bottom. Each row is padded to a whole
+; number of bytes: row_bytes = ceil(width / 8). This matches the image
+; import tool's "Glyph asset" format.
+;
+; Animation state:
+;   0x0580 byte  x byte-column, so x pixel = x * 8
+;   0x0581 byte  y bottom row
+;   0x0582 byte  dx, 0=left, 1=right
+;   0x0583 byte  dy, 0=down, 1=up
+;
+; The blitter is byte-aligned horizontally. Import a ball glyph at
+; 0x0400, or let this program create a default 16x16 ball there.
+
+; ---- Ensure a glyph exists at 0x0400 -------------------------------
+        LIL  R6, 0
+        LIH  R6, 4          ; R6 = 0x0400 glyph base
+        LDB  R0, 0(R6)      ; width
+        BZ   R0, init_glyph
+        JMP  init_state
+
+; Default 16x16 ball glyph. Header = width,height, then 16 rows x 2 bytes.
+init_glyph:
+        LIL  R6, 0
+        LIH  R6, 4
+        LIL  R0, 16
+        STB  R0, 0(R6)      ; width
+        STB  R0, 1(R6)      ; height
+        ADDI R6, 2
+
+        LIL  R0, 3
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 192
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 15
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 240
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 31
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 248
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 63
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 252
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 127
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 254
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 127
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 254
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 255
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 255
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 255
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 255
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 127
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 254
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 127
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 254
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 63
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 252
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 31
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 248
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 15
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 240
+        STB  R0, 0(R6)
+        ADDI R6, 1
+
+        LIL  R0, 3
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        LIL  R0, 192
+        STB  R0, 0(R6)
+
+; ---- Initial state --------------------------------------------------
+init_state:
+        LIL  R7, 128
+        LIH  R7, 5          ; R7 = 0x0580 state base
+
+        LIL  R0, 0
+        STB  R0, 0(R7)      ; x byte-column = 0
+        STB  R0, 1(R7)      ; y bottom row = 0
+
+        LIL  R0, 1
+        STB  R0, 2(R7)      ; dx = right
+        STB  R0, 3(R7)      ; dy = up
+
+; ---- Animation loop -------------------------------------------------
+main_loop:
+        LIL  R7, 128
+        LIH  R7, 5          ; state base
+
+        LDB  R1, 0(R7)      ; R1 = x byte-column
+        LDB  R2, 1(R7)      ; R2 = y bottom row
+
+; ---- Erase old glyph only ------------------------------------------
+; This is much less flickery than clearing the whole framebuffer.
+erase_setup:
+        LIL  R7, 0
+        LIH  R7, 4          ; glyph base
+        LDB  R4, 0(R7)      ; width
+        ADDI R4, 7
+        SHR  R4, 3          ; row_bytes
+        LDB  R5, 1(R7)      ; height
+
+        MOV  R6, R2
+        ADD  R6, R6, R5
+        ADDI R6, -1         ; top display row = y + height - 1
+        SHL  R6, 3          ; row * 8 bytes
+        LIL  R0, 0
+        LIH  R0, 6          ; framebuffer base
+        ADD  R6, R6, R0
+        ADD  R6, R6, R1
+        LIL  R0, 0          ; erase byte
+
+erase_row:
+        BZ   R5, reload_state
+        MOV  R3, R4         ; bytes remaining in this glyph row
+
+erase_byte:
+        BZ   R3, erase_row_done
+        STB  R0, 0(R6)
+        ADDI R6, 1
+        ADDI R3, -1
+        JMP  erase_byte
+
+erase_row_done:
+        SUB  R6, R6, R4     ; back to row start
+        ADDI R6, -8         ; next lower display row
+        ADDI R5, -1
+        JMP  erase_row
+
+reload_state:
+        LIL  R7, 128
+        LIH  R7, 5
+        LDB  R1, 0(R7)      ; R1 = x byte-column
+        LDB  R2, 1(R7)      ; R2 = y bottom row
+        LDB  R3, 2(R7)      ; R3 = dx
+        LDB  R4, 3(R7)      ; R4 = dy
+
+; ---- Move x and bounce at left/right walls -------------------------
+move_x:
+        BZ   R3, move_left
+        ADDI R1, 1
+        JMP  check_x
+
+move_left:
+        ADDI R1, -1
+
+check_x:
+        BN   R1, hit_left
+
+        LIL  R6, 0
+        LIH  R6, 4          ; glyph base
+        LDB  R5, 0(R6)      ; glyph width
+        ADDI R5, 7
+        SHR  R5, 3          ; row_bytes = ceil(width / 8)
+        LIL  R6, 8
+        SUB  R5, R6, R5     ; max x byte-column = 8 - row_bytes
+        SUB  R5, R5, R1     ; max_x - x
+        BN   R5, hit_right
+        JMP  x_done
+
+hit_left:
+        LIL  R1, 0
+        LIL  R3, 1          ; dx = right
+        JMP  x_done
+
+hit_right:
+        LIL  R6, 0
+        LIH  R6, 4
+        LDB  R1, 0(R6)
+        ADDI R1, 7
+        SHR  R1, 3          ; row_bytes
+        LIL  R5, 8
+        SUB  R1, R5, R1     ; x = max_x
+        LIL  R3, 0          ; dx = left
+
+x_done:
+
+; ---- Move y and bounce at bottom/top walls -------------------------
+        BZ   R4, move_down
+        ADDI R2, 1
+        JMP  check_y
+
+move_down:
+        ADDI R2, -1
+
+check_y:
+        BN   R2, hit_bottom
+
+        LIL  R6, 0
+        LIH  R6, 4
+        LDB  R5, 1(R6)      ; glyph height
+        LIL  R6, 64
+        SUB  R5, R6, R5     ; max y = 64 - height
+        SUB  R5, R5, R2     ; max_y - y
+        BN   R5, hit_top
+        JMP  y_done
+
+hit_bottom:
+        LIL  R2, 0
+        LIL  R4, 1          ; dy = up
+        JMP  y_done
+
+hit_top:
+        LIL  R6, 0
+        LIH  R6, 4
+        LDB  R2, 1(R6)
+        LIL  R5, 64
+        SUB  R2, R5, R2     ; y = max_y
+        LIL  R4, 0          ; dy = down
+
+y_done:
+        LIL  R7, 128
+        LIH  R7, 5
+        STB  R1, 0(R7)
+        STB  R2, 1(R7)
+        STB  R3, 2(R7)
+        STB  R4, 3(R7)
+
+; ---- Draw glyph into framebuffer -----------------------------------
+; Registers during draw:
+;   R1 = x byte-column
+;   R2 = y bottom row
+;   R4 = row_bytes
+;   R5 = rows remaining
+;   R6 = framebuffer row pointer
+;   R7 = glyph source pointer
+draw_setup:
+        LIL  R7, 0
+        LIH  R7, 4          ; glyph base
+        LDB  R4, 0(R7)      ; width
+        ADDI R4, 7
+        SHR  R4, 3          ; row_bytes
+        LDB  R5, 1(R7)      ; height
+        ADDI R7, 2          ; source points at first glyph row, top first
+
+        MOV  R6, R2
+        ADD  R6, R6, R5
+        ADDI R6, -1         ; top display row = y + height - 1
+        SHL  R6, 3          ; row * 8 bytes
+        LIL  R0, 0
+        LIH  R0, 6          ; framebuffer base
+        ADD  R6, R6, R0
+        ADD  R6, R6, R1
+
+draw_row:
+        BZ   R5, delay_setup
+        MOV  R3, R4         ; bytes remaining in this glyph row
+
+draw_byte:
+        BZ   R3, row_done
+        LDB  R0, 0(R7)
+        NOT  R0, R0
+        STB  R0, 0(R6)
+        ADDI R7, 1
+        ADDI R6, 1
+        ADDI R3, -1
+        JMP  draw_byte
+
+row_done:
+        SUB  R6, R6, R4     ; back to row start
+        ADDI R6, -8         ; next lower display row
+        ADDI R5, -1
+        JMP  draw_row
+
+; ---- Delay so motion is visible ------------------------------------
+delay_setup:
+        LIL  R6, 80
+
+delay_loop:
+        ADDI R6, -1
+        BZ   R6, main_loop
+        JMP  delay_loop