tomasulo 0.1.0__py3-none-any.whl

tomasulo/__init__.py

@@ -0,0 +1,24 @@
+"""Pure-Python simulator of Tomasulo's out-of-order instruction scheduling algorithm."""
+
+from .model import (
+    CycleSnapshot,
+    Instruction,
+    InstructionResult,
+    RegisterStatus,
+    StationState,
+    Trace,
+)
+from .simulator import TomasuloSim
+from .trace import render_trace
+
+__all__ = [
+    "CycleSnapshot",
+    "Instruction",
+    "InstructionResult",
+    "RegisterStatus",
+    "StationState",
+    "TomasuloSim",
+    "Trace",
+    "render_trace",
+]
+__version__ = "0.1.0"

tomasulo/cli.py

@@ -0,0 +1,210 @@
+"""Command-line interface for the Tomasulo simulator.
+
+Input format (plain text, one instruction per line):
+    OP DEST SRC1 SRC2
+
+Lines starting with '#' are comments. Blank lines are ignored.
+
+Example:
+    LOAD F6 R2 R0
+    LOAD F2 R3 R0
+    MUL  F0 F2 F4
+    SUB  F8 F6 F2
+    DIV  F10 F0 F6
+    ADD  F6 F8 F2
+"""
+
+from __future__ import annotations
+
+import sys
+
+from . import __version__
+from .model import Instruction
+from .simulator import TomasuloSim
+from .trace import render_trace
+
+_DEFAULT_STATIONS: dict[str, int] = {"add": 3, "mult": 2, "load": 3}
+_DEFAULT_LATENCIES: dict[str, int] = {
+    "ADD": 2,
+    "SUB": 2,
+    "MUL": 10,
+    "DIV": 40,
+    "LOAD": 2,
+}
+
+
+def _parse_program(text: str) -> list[Instruction]:
+    """Parse program text into a list of Instructions.
+
+    Args:
+        text: Raw program text with one instruction per non-comment line.
+
+    Returns:
+        Ordered list of Instruction objects.
+
+    Raises:
+        ValueError: If a line cannot be parsed as an instruction.
+    """
+    instructions: list[Instruction] = []
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split()
+        if len(parts) != 4:
+            raise ValueError(
+                f"line {lineno}: expected 'OP DEST SRC1 SRC2', got {line!r}"
+            )
+        op, dest, src1, src2 = parts
+        instructions.append(Instruction(op=op.upper(), dest=dest, src1=src1, src2=src2))
+    return instructions
+
+
+def run(argv: list[str]) -> int:
+    """Parse arguments, run simulation, print timing table.
+
+    Args:
+        argv: Command-line argument list (without the program name).
+
+    Returns:
+        Exit code: 0 on success, 1 on usage error.
+    """
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="tomasulo",
+        description="Simulate Tomasulo's out-of-order instruction scheduling algorithm.",
+    )
+    parser.add_argument(
+        "program",
+        nargs="?",
+        metavar="FILE",
+        help="text file containing the instruction program (reads stdin if omitted)",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"tomasulo {__version__}",
+    )
+    parser.add_argument(
+        "--add-stations",
+        type=int,
+        default=3,
+        metavar="N",
+        help="number of ADD/SUB reservation stations (default 3)",
+    )
+    parser.add_argument(
+        "--mult-stations",
+        type=int,
+        default=2,
+        metavar="N",
+        help="number of MUL/DIV reservation stations (default 2)",
+    )
+    parser.add_argument(
+        "--load-stations",
+        type=int,
+        default=3,
+        metavar="N",
+        help="number of LOAD reservation stations (default 3)",
+    )
+    parser.add_argument(
+        "--add-latency",
+        type=int,
+        default=2,
+        metavar="C",
+        help="execution cycles for ADD/SUB (default 2)",
+    )
+    parser.add_argument(
+        "--mul-latency",
+        type=int,
+        default=10,
+        metavar="C",
+        help="execution cycles for MUL (default 10)",
+    )
+    parser.add_argument(
+        "--div-latency",
+        type=int,
+        default=40,
+        metavar="C",
+        help="execution cycles for DIV (default 40)",
+    )
+    parser.add_argument(
+        "--load-latency",
+        type=int,
+        default=2,
+        metavar="C",
+        help="execution cycles for LOAD (default 2)",
+    )
+    parser.add_argument(
+        "--snapshots",
+        action="store_true",
+        help="print per-cycle reservation station snapshots after the timing table",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.program is not None:
+        try:
+            with open(args.program, encoding="utf-8") as f:
+                text = f.read()
+        except OSError as exc:
+            print(f"tomasulo: cannot open file: {exc}", file=sys.stderr)
+            return 1
+    else:
+        text = sys.stdin.read()
+
+    try:
+        program = _parse_program(text)
+    except ValueError as exc:
+        print(f"tomasulo: parse error: {exc}", file=sys.stderr)
+        return 1
+
+    if not program:
+        print("tomasulo: no instructions found", file=sys.stderr)
+        return 1
+
+    stations: dict[str, int] = {
+        "add": args.add_stations,
+        "mult": args.mult_stations,
+        "load": args.load_stations,
+    }
+    latencies: dict[str, int] = {
+        "ADD": args.add_latency,
+        "SUB": args.add_latency,
+        "MUL": args.mul_latency,
+        "DIV": args.div_latency,
+        "LOAD": args.load_latency,
+    }
+
+    sim = TomasuloSim(stations=stations, latencies=latencies)
+    trace = sim.run(program=program)
+
+    print(render_trace(trace=trace))
+
+    if args.snapshots:
+        print()
+        for snap in trace.snapshots:
+            print(f"=== Cycle {snap.cycle} ===")
+            if snap.cdb_tag is not None:
+                print(f"  CDB: {snap.cdb_tag} = {snap.cdb_value}")
+            for st in snap.stations:
+                if st.busy:
+                    qj = st.qj or "-"
+                    qk = st.qk or "-"
+                    rem = st.remaining if st.remaining is not None else "-"
+                    print(
+                        f"  [{st.tag}] {st.op}  Qj={qj} Qk={qk} rem={rem}"
+                    )
+            status_entries = [
+                f"{r}={v}" for r, v in snap.register_status.table.items() if v is not None
+            ]
+            if status_entries:
+                print(f"  RegStatus: {', '.join(status_entries)}")
+            print()
+
+    return 0
+
+
+def main() -> int:
+    """Console entry point."""
+    return run(sys.argv[1:])

tomasulo/model.py

@@ -0,0 +1,118 @@
+"""Data model dataclasses for the Tomasulo simulator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Instruction:
+    """One instruction in the program.
+
+    Args:
+        op: Opcode string -- "ADD", "SUB", "MUL", "DIV", or "LOAD".
+        dest: Destination register name, e.g. "F0".
+        src1: First source register, e.g. "F2". For LOAD, this is the base
+            address register (e.g. "R2").
+        src2: Second source register, e.g. "F4". For LOAD, this field is
+            unused by the algorithm; pass "R0" by convention.
+    """
+
+    op: str
+    dest: str
+    src1: str
+    src2: str
+
+
+@dataclass
+class InstructionResult:
+    """Timing record for one issued instruction.
+
+    Args:
+        instruction: The original instruction.
+        issue_cycle: Cycle in which the instruction was issued to a station.
+        exec_complete_cycle: Cycle in which execution finished (remaining
+            countdown reached zero).
+        write_cycle: Cycle in which the result was broadcast on the CDB and
+            written to the register file.
+    """
+
+    instruction: Instruction
+    issue_cycle: int
+    exec_complete_cycle: int
+    write_cycle: int
+
+
+@dataclass
+class StationState:
+    """Snapshot of one reservation station at the end of a cycle.
+
+    Args:
+        tag: Unique station identifier, e.g. "add1" or "mult2".
+        unit_type: Functional unit type -- "add", "mult", or "load".
+        busy: Whether the station is occupied.
+        op: Opcode currently held, or "" when not busy.
+        vj: Value of first operand when available, or None.
+        vk: Value of second operand when available, or None.
+        qj: Tag of the station producing the first operand, or None when ready.
+        qk: Tag of the station producing the second operand, or None when ready.
+        dest: This station's own tag (used as the CDB broadcast tag).
+        remaining: Execution cycles still needed, or None when not executing.
+    """
+
+    tag: str
+    unit_type: str
+    busy: bool
+    op: str
+    vj: float | None
+    vk: float | None
+    qj: str | None
+    qk: str | None
+    dest: str
+    remaining: int | None
+
+
+@dataclass
+class RegisterStatus:
+    """Snapshot of the register result-status table at the end of a cycle.
+
+    Maps each register name to the tag of the station that will write it,
+    or None if the register value is current (no pending write).
+
+    Args:
+        table: Dictionary from register name to station tag or None.
+    """
+
+    table: dict[str, str | None]
+
+
+@dataclass
+class CycleSnapshot:
+    """Complete simulator state captured at the end of one cycle.
+
+    Args:
+        cycle: The cycle number this snapshot represents.
+        stations: Snapshot of every reservation station.
+        register_status: The register result-status table.
+        cdb_tag: Tag broadcast on the CDB this cycle, or None if no write.
+        cdb_value: Value broadcast on the CDB this cycle, or None if no write.
+    """
+
+    cycle: int
+    stations: list[StationState]
+    register_status: RegisterStatus
+    cdb_tag: str | None
+    cdb_value: float | None
+
+
+@dataclass
+class Trace:
+    """Complete simulation output.
+
+    Args:
+        results: Per-instruction timing records, in program order.
+        snapshots: Per-cycle state snapshots, one per simulated cycle.
+    """
+
+    results: list[InstructionResult]
+    snapshots: list[CycleSnapshot] = field(default_factory=list)

tomasulo/simulator.py

@@ -0,0 +1,311 @@
+"""Tomasulo out-of-order instruction scheduling simulator.
+
+Stage order each cycle: WRITE, then EXECUTE, then ISSUE.
+
+Hazard handling:
+- RAW: a station records the tag (Qj/Qk) of the station that will produce a
+  missing operand. When that station broadcasts on the CDB, all waiting
+  stations pick up the value and clear the tag.
+- WAR and WAW: handled implicitly by register renaming. Each instruction
+  renames its destination register to the station tag it was issued to.
+  The register result-status table always records the LAST writer. An
+  earlier in-flight station only commits its result to the register file
+  if the status table still points at that station when it writes back.
+
+CDB structural hazard: at most one result is broadcast per cycle. If multiple
+stations finish on the same cycle the station with the lowest index (in
+declaration order) wins; others wait and try again the following cycle.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .model import (
+    CycleSnapshot,
+    Instruction,
+    InstructionResult,
+    RegisterStatus,
+    StationState,
+    Trace,
+)
+
+# Map opcode string to functional unit type.
+_UNIT_TYPE: dict[str, str] = {
+    "ADD": "add",
+    "SUB": "add",
+    "MUL": "mult",
+    "DIV": "mult",
+    "LOAD": "load",
+}
+
+
+@dataclass
+class _Station:
+    """Live reservation station (mutable internal state)."""
+
+    tag: str
+    unit_type: str
+    busy: bool = field(default=False)
+    op: str = field(default="")
+    vj: float | None = field(default=None)
+    vk: float | None = field(default=None)
+    qj: str | None = field(default=None)
+    qk: str | None = field(default=None)
+    # remaining == None  -> not executing yet (operands not ready or not set)
+    # remaining == N > 0 -> N cycles left before exec_complete
+    # remaining == 0     -> execution finished; waiting for CDB slot
+    remaining: int | None = field(default=None)
+    # Index of the program instruction currently held (for result tracking).
+    insn_index: int | None = field(default=None)
+
+    def snapshot(self) -> StationState:
+        """Return an immutable snapshot of this station."""
+        return StationState(
+            tag=self.tag,
+            unit_type=self.unit_type,
+            busy=self.busy,
+            op=self.op,
+            vj=self.vj,
+            vk=self.vk,
+            qj=self.qj,
+            qk=self.qk,
+            dest=self.tag,
+            remaining=self.remaining,
+        )
+
+    def clear(self) -> None:
+        """Reset station to idle state."""
+        self.busy = False
+        self.op = ""
+        self.vj = None
+        self.vk = None
+        self.qj = None
+        self.qk = None
+        self.remaining = None
+        self.insn_index = None
+
+
+# Default register value when a register has not been written.
+def _default_reg_value() -> float:
+    return 0.0
+
+
+class TomasuloSim:
+    """Simulate Tomasulo's algorithm on a given program.
+
+    Args:
+        stations: Mapping from unit type ("add", "mult", "load") to the number
+            of reservation stations of that type.
+        latencies: Mapping from opcode to the number of execution cycles
+            required (e.g. {"ADD": 2, "SUB": 2, "MUL": 10, "DIV": 40,
+            "LOAD": 2}).
+    """
+
+    def __init__(self, stations: dict[str, int], latencies: dict[str, int]) -> None:
+        self._station_counts = stations
+        self._latencies = latencies
+
+    def run(self, program: list[Instruction]) -> Trace:
+        """Simulate the program and return a full Trace.
+
+        Args:
+            program: List of instructions in program order.
+
+        Returns:
+            A Trace containing per-instruction timing and per-cycle snapshots.
+        """
+        if not program:
+            return Trace(results=[], snapshots=[])
+
+        # Build ordered list of all stations (order determines CDB tie-break).
+        all_stations: list[_Station] = []
+        for unit_type, count in self._station_counts.items():
+            for i in range(1, count + 1):
+                all_stations.append(_Station(tag=f"{unit_type}{i}", unit_type=unit_type))
+
+        # Register result-status table: reg -> station tag that will write it.
+        reg_status: dict[str, str | None] = {}
+
+        # Register file: reg -> current value.
+        reg_file: dict[str, float] = {}
+
+        # Per-instruction timing records (indexed by program order).
+        issue_cycle: list[int] = [0] * len(program)
+        exec_complete_cycle: list[int] = [0] * len(program)
+        write_cycle: list[int] = [0] * len(program)
+
+        # Index of next instruction to issue.
+        issue_ptr = 0
+
+        snapshots: list[CycleSnapshot] = []
+
+        cycle = 0
+
+        while True:
+            cycle += 1
+
+            cdb_tag: str | None = None
+            cdb_value: float | None = None
+
+            # ------------------------------------------------------------------
+            # STAGE 1: WRITE
+            # Find the station that finished executing and can write to the CDB.
+            # Tie-break: lowest index in all_stations wins (first in list).
+            # A station is ready to write when remaining == 0.
+            # ------------------------------------------------------------------
+            write_station: _Station | None = None
+            for st in all_stations:
+                if st.busy and st.remaining == 0:
+                    write_station = st
+                    break  # first (lowest-index) wins
+
+            if write_station is not None:
+                idx = write_station.insn_index
+                assert idx is not None  # busy station always has insn_index set
+
+                # All computed values are 0.0 in this scheduling simulator.
+                result_value = 0.0
+
+                cdb_tag = write_station.tag
+                cdb_value = result_value
+                write_cycle[idx] = cycle
+
+                # Update register file if this station is still the last writer.
+                # Iterate over a snapshot of keys to allow value mutation.
+                for reg in list(reg_status.keys()):
+                    if reg_status[reg] == write_station.tag:
+                        reg_file[reg] = result_value
+                        reg_status[reg] = None
+
+                # Forward result to every waiting station.
+                for st in all_stations:
+                    if st.busy:
+                        if st.qj == write_station.tag:
+                            st.vj = result_value
+                            st.qj = None
+                        if st.qk == write_station.tag:
+                            st.vk = result_value
+                            st.qk = None
+
+                # Free the writing station.
+                write_station.clear()
+
+            # ------------------------------------------------------------------
+            # STAGE 2: EXECUTE
+            # Count down remaining cycles for stations currently executing.
+            # "Currently executing" means remaining is not None and > 0.
+            # Stations whose operands just became available in the WRITE phase
+            # above have remaining == None and are NOT started this cycle
+            # (next-cycle rule).
+            # ------------------------------------------------------------------
+            for st in all_stations:
+                if not st.busy or st.remaining is None or st.remaining == 0:
+                    continue
+                # remaining > 0: count down one cycle.
+                st.remaining -= 1
+                if st.remaining == 0:
+                    assert st.insn_index is not None
+                    exec_complete_cycle[st.insn_index] = cycle
+
+            # After the decrement pass, start any station whose operands are
+            # now ready but had not yet begun executing (remaining is None).
+            # These stations will begin next cycle (remaining set to latency now
+            # so the decrement pass will fire next cycle).
+            for st in all_stations:
+                if st.busy and st.remaining is None and st.qj is None and st.qk is None:
+                    assert st.insn_index is not None
+                    st.remaining = self._latencies[st.op]
+
+            # ------------------------------------------------------------------
+            # STAGE 3: ISSUE
+            # Issue at most one instruction per cycle in program order.
+            # Stall if no free station of the required type is available.
+            # ------------------------------------------------------------------
+            if issue_ptr < len(program):
+                insn = program[issue_ptr]
+                unit_type = _UNIT_TYPE[insn.op]
+
+                # Find a free station of the correct type.
+                free_station: _Station | None = None
+                for st in all_stations:
+                    if st.unit_type == unit_type and not st.busy:
+                        free_station = st
+                        break
+
+                if free_station is not None:
+                    free_station.busy = True
+                    free_station.op = insn.op
+                    free_station.insn_index = issue_ptr
+                    issue_cycle[issue_ptr] = cycle
+
+                    if insn.op == "LOAD":
+                        # LOAD: src1 is the base register; src2 is unused.
+                        # Both operand slots are ready immediately (no RAW for
+                        # address computation in this model).
+                        base_val = reg_file.get(insn.src1, _default_reg_value())
+                        free_station.vj = base_val
+                        free_station.qj = None
+                        free_station.vk = 0.0
+                        free_station.qk = None
+                    else:
+                        # src1
+                        src1_producer = reg_status.get(insn.src1)
+                        if src1_producer is not None:
+                            free_station.qj = src1_producer
+                            free_station.vj = None
+                        else:
+                            free_station.vj = reg_file.get(insn.src1, _default_reg_value())
+                            free_station.qj = None
+
+                        # src2
+                        src2_producer = reg_status.get(insn.src2)
+                        if src2_producer is not None:
+                            free_station.qk = src2_producer
+                            free_station.vk = None
+                        else:
+                            free_station.vk = reg_file.get(insn.src2, _default_reg_value())
+                            free_station.qk = None
+
+                    # Register renaming: dest register now maps to this station.
+                    reg_status[insn.dest] = free_station.tag
+
+                    # If operands are already ready at issue time, arm the
+                    # countdown so execution begins next cycle.
+                    if free_station.qj is None and free_station.qk is None:
+                        free_station.remaining = self._latencies[insn.op]
+
+                    issue_ptr += 1
+
+            # ------------------------------------------------------------------
+            # Capture snapshot at the end of the cycle.
+            # ------------------------------------------------------------------
+            station_snaps = [st.snapshot() for st in all_stations]
+            reg_snap = RegisterStatus(table=dict(reg_status))
+            snapshots.append(
+                CycleSnapshot(
+                    cycle=cycle,
+                    stations=station_snaps,
+                    register_status=reg_snap,
+                    cdb_tag=cdb_tag,
+                    cdb_value=cdb_value,
+                )
+            )
+
+            # ------------------------------------------------------------------
+            # Termination: all instructions issued AND all stations idle.
+            # ------------------------------------------------------------------
+            if issue_ptr >= len(program) and all(not st.busy for st in all_stations):
+                break
+
+        results = [
+            InstructionResult(
+                instruction=program[i],
+                issue_cycle=issue_cycle[i],
+                exec_complete_cycle=exec_complete_cycle[i],
+                write_cycle=write_cycle[i],
+            )
+            for i in range(len(program))
+        ]
+
+        return Trace(results=results, snapshots=snapshots)

tomasulo/trace.py

@@ -0,0 +1,61 @@
+"""Rendering functions for Tomasulo simulation traces."""
+
+from __future__ import annotations
+
+from .model import Trace
+
+
+def render_trace(trace: Trace) -> str:
+    """Render a simulation trace as a human-readable timing table.
+
+    Each row shows one instruction with its issue, execution-complete, and
+    write-result cycle numbers.
+
+    Args:
+        trace: The Trace returned by TomasuloSim.run().
+
+    Returns:
+        A multi-line string containing the formatted timing table.
+    """
+    if not trace.results:
+        return "(no instructions)"
+
+    col_widths = {
+        "index": 4,
+        "op": 5,
+        "dest": 5,
+        "src1": 5,
+        "src2": 5,
+        "issue": 6,
+        "exec": 14,
+        "write": 6,
+    }
+
+    header = (
+        f"{'#':>{col_widths['index']}}"
+        f"  {'Op':<{col_widths['op']}}"
+        f"  {'Dest':<{col_widths['dest']}}"
+        f"  {'Src1':<{col_widths['src1']}}"
+        f"  {'Src2':<{col_widths['src2']}}"
+        f"  {'Issue':>{col_widths['issue']}}"
+        f"  {'ExecComplete':>{col_widths['exec']}}"
+        f"  {'Write':>{col_widths['write']}}"
+    )
+    separator = "-" * len(header)
+
+    lines: list[str] = [header, separator]
+    for i, r in enumerate(trace.results):
+        insn = r.instruction
+        row = (
+            f"{i + 1:>{col_widths['index']}}"
+            f"  {insn.op:<{col_widths['op']}}"
+            f"  {insn.dest:<{col_widths['dest']}}"
+            f"  {insn.src1:<{col_widths['src1']}}"
+            f"  {insn.src2:<{col_widths['src2']}}"
+            f"  {r.issue_cycle:>{col_widths['issue']}}"
+            f"  {r.exec_complete_cycle:>{col_widths['exec']}}"
+            f"  {r.write_cycle:>{col_widths['write']}}"
+        )
+        lines.append(row)
+
+    return "\n".join(lines)

tomasulo-0.1.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: tomasulo
+Version: 0.1.0
+Summary: Pure-Python simulator of Tomasulo's out-of-order instruction scheduling: reservation stations, common data bus, and register renaming, with cycle-by-cycle traces for computer architecture education.
+Project-URL: Homepage, https://github.com/amaar-mc/tomasulo
+Project-URL: Repository, https://github.com/amaar-mc/tomasulo
+Project-URL: Issues, https://github.com/amaar-mc/tomasulo/issues
+Project-URL: Changelog, https://github.com/amaar-mc/tomasulo/blob/main/CHANGELOG.md
+Author: Amaar Chughtai
+License: MIT License
+        
+        Copyright (c) 2026 Amaar Chughtai
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: common-data-bus,computer-architecture,cpu-simulator,education,instruction-scheduling,out-of-order,register-renaming,reservation-stations,simulation,tomasulo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: hatchling>=1.25; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tomasulo
+
+Pure-Python simulator of Tomasulo's out-of-order instruction scheduling algorithm. Implements reservation stations, a Common Data Bus (CDB), and register renaming for computer architecture education.
+
+Zero runtime dependencies. Requires Python 3.10+.
+
+## Installation
+
+```
+pip install tomasulo
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```
+uv pip install tomasulo
+```
+
+## Quick start
+
+```python
+from tomasulo import Instruction, TomasuloSim, render_trace
+
+program = [
+    Instruction(op="LOAD", dest="F6",  src1="R2", src2="R0"),
+    Instruction(op="LOAD", dest="F2",  src1="R3", src2="R0"),
+    Instruction(op="MUL",  dest="F0",  src1="F2", src2="F4"),
+    Instruction(op="SUB",  dest="F8",  src1="F6", src2="F2"),
+    Instruction(op="DIV",  dest="F10", src1="F0", src2="F6"),
+    Instruction(op="ADD",  dest="F6",  src1="F8", src2="F2"),
+]
+
+sim = TomasuloSim(
+    stations={"add": 3, "mult": 2, "load": 3},
+    latencies={"ADD": 2, "SUB": 2, "MUL": 10, "DIV": 40, "LOAD": 2},
+)
+trace = sim.run(program=program)
+print(render_trace(trace=trace))
+```
+
+Output:
+
+```
+   #  Op     Dest   Src1   Src2    Issue  ExecComplete   Write
+---------------------------------------------------------------------
+   1  LOAD   F6     R2     R0          1             3       4
+   2  LOAD   F2     R3     R0          2             4       5
+   3  MUL    F0     F2     F4          3            15      16
+   4  SUB    F8     F6     F2          4             6       7
+   5  DIV    F10    F0     F6          5            56      57
+   6  ADD    F6     F8     F2          6             9      10
+```
+
+## CLI
+
+```
+tomasulo examples/sample_program.txt
+tomasulo examples/sample_program.txt --snapshots
+tomasulo --help
+```
+
+Program file format -- one instruction per line:
+
+```
+# comments are ignored
+LOAD F6  R2  R0
+LOAD F2  R3  R0
+MUL  F0  F2  F4
+SUB  F8  F6  F2
+DIV  F10 F0  F6
+ADD  F6  F8  F2
+```
+
+## Public API
+
+```python
+@dataclass
+class Instruction:
+    op: str    # "ADD", "SUB", "MUL", "DIV", "LOAD"
+    dest: str  # destination register e.g. "F0"
+    src1: str  # first source register; for LOAD: base address register
+    src2: str  # second source register; for LOAD: unused, pass "R0" by convention
+
+@dataclass
+class InstructionResult:
+    instruction: Instruction
+    issue_cycle: int
+    exec_complete_cycle: int
+    write_cycle: int
+
+@dataclass
+class Trace:
+    results: list[InstructionResult]
+    snapshots: list[CycleSnapshot]
+
+class TomasuloSim:
+    def __init__(self, stations: dict[str, int], latencies: dict[str, int]) -> None: ...
+    def run(self, program: list[Instruction]) -> Trace: ...
+
+def render_trace(trace: Trace) -> str: ...
+```
+
+## Algorithm
+
+Stage order each cycle: **WRITE, then EXECUTE, then ISSUE.**
+
+Hazards handled:
+
+- **RAW**: a station waits on the tag (Qj/Qk) of the station that will produce a missing operand. When that station broadcasts on the CDB the value is forwarded and the tag is cleared.
+- **WAR and WAW**: handled by register renaming. Each issued instruction renames its destination to the station tag. Only the last writer commits to the register file.
+- **Structural**: at most one result per cycle on the CDB. Ties broken by lowest station index (declaration order).
+
+See `docs/architecture.md` for a full description.
+
+## Development
+
+```
+uv venv && uv pip install -e ".[dev]"
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+uv build
+```
+
+## License
+
+MIT. Copyright (c) 2026 Amaar Chughtai.

tomasulo-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+tomasulo/__init__.py,sha256=WQB9GYM_I0866iJsBf4t6vygRfotu5PGtBYRq6QJtDo,484
+tomasulo/cli.py,sha256=NhRdAwwwaxqlpuIezn-UzHvpiSDyk4KOEMJHCpI5jws,5678
+tomasulo/model.py,sha256=eOW8taAU709ID9iEI5bQJbv5nmLOsMb25gmmVluMI3A,3453
+tomasulo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tomasulo/simulator.py,sha256=czdhM8IAIrOZTs3Djhbh-17H9qnF7r0dVno3xlYMq_Q,12430
+tomasulo/trace.py,sha256=R8-A9a0PYWDArI-AwsQmm3JvH6KkuCOcrIPJFbeyusg,1762
+tomasulo-0.1.0.dist-info/METADATA,sha256=AfggJmdG7esNf1kwPkJgZmL2XBzwo0kbClCRGqBFXk0,6237
+tomasulo-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tomasulo-0.1.0.dist-info/entry_points.txt,sha256=GYoV39qebKhNTyIAjyf_kbIzTtuZbj039zvfQrEU3LQ,47
+tomasulo-0.1.0.dist-info/licenses/LICENSE,sha256=NORTVJb4x206RXQkpZt_vpj8I7aZL6Vn26BvTOq6J40,1071
+tomasulo-0.1.0.dist-info/RECORD,,

tomasulo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

tomasulo-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tomasulo = tomasulo.cli:main

tomasulo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amaar Chughtai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.