scoreboarding 0.1.0__py3-none-any.whl

scoreboarding/__init__.py

@@ -0,0 +1,51 @@
+"""scoreboarding -- pure-Python Thornton Scoreboarding (CDC 6600) simulator.
+
+Public API::
+
+    from scoreboarding import FunctionalUnit, Instruction, run, render_trace, Trace
+
+Example::
+
+    from scoreboarding import FunctionalUnit, Instruction, run, render_trace
+
+    fus = [
+        FunctionalUnit(name="Load1", kind="load", latency=2),
+        FunctionalUnit(name="Mult1", kind="mult", latency=10),
+        FunctionalUnit(name="Add1",  kind="add",  latency=2),
+        FunctionalUnit(name="Div1",  kind="div",  latency=40),
+    ]
+    program = [
+        Instruction(op="LD",   dest="F6",  src1="R2",  src2=""),
+        Instruction(op="LD",   dest="F2",  src1="R3",  src2=""),
+        Instruction(op="MULT", 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"),
+    ]
+    trace = run(program, functional_units=fus)
+    print(render_trace(trace))
+"""
+
+from scoreboarding.engine import run
+from scoreboarding.model import (
+    CycleSnapshot,
+    FunctionalUnit,
+    FunctionalUnitStatus,
+    Instruction,
+    InstructionResult,
+    InstructionStatus,
+    Trace,
+)
+from scoreboarding.render import render_trace
+
+__all__ = [
+    "CycleSnapshot",
+    "FunctionalUnit",
+    "FunctionalUnitStatus",
+    "Instruction",
+    "InstructionResult",
+    "InstructionStatus",
+    "Trace",
+    "render_trace",
+    "run",
+]

scoreboarding/cli.py

@@ -0,0 +1,189 @@
+"""Command-line interface for the scoreboarding simulator.
+
+Program text format
+-------------------
+Lines starting with '#' or blank lines are ignored.
+
+Functional unit declarations (must come before instructions)::
+
+    FU <name> <kind> <latency>
+
+Example::
+
+    FU Load1 load 2
+    FU Mult1 mult 10
+    FU Add1  add  2
+    FU Div1  div  40
+
+Instruction lines::
+
+    <op> <dest>, <src1>, <src2>
+    <op> <dest>, <src1>          # single-source (loads etc.)
+
+Example::
+
+    LD  F6, R2
+    MULT F0, F2, F4
+    ADD  F6, F8, F2
+
+Usage::
+
+    scoreboarding program.txt
+    scoreboarding --snapshots program.txt
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from scoreboarding.engine import run as engine_run
+from scoreboarding.model import FunctionalUnit, Instruction
+from scoreboarding.render import render_trace
+
+
+def _parse_program(text: str) -> tuple[list[FunctionalUnit], list[Instruction]]:
+    """Parse program text into functional units and instructions.
+
+    Args:
+        text: Full program text with FU declarations followed by instructions.
+
+    Returns:
+        A tuple of (functional_units, instructions).
+
+    Raises:
+        ValueError: If a line cannot be parsed.
+    """
+    functional_units: list[FunctionalUnit] = []
+    instructions: list[Instruction] = []
+
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+
+        if line.upper().startswith("FU "):
+            parts = line.split()
+            if len(parts) != 4:
+                raise ValueError(
+                    f"FU declaration must be 'FU <name> <kind> <latency>', got: {line!r}"
+                )
+            try:
+                latency = int(parts[3])
+            except ValueError:
+                raise ValueError(
+                    f"FU latency must be an integer, got: {parts[3]!r}"
+                ) from None
+            functional_units.append(
+                FunctionalUnit(name=parts[1], kind=parts[2].lower(), latency=latency)
+            )
+            continue
+
+        # Instruction line: "OP DEST, SRC1" or "OP DEST, SRC1, SRC2"
+        # Split op from the rest.
+        space_idx = line.find(" ")
+        if space_idx == -1:
+            raise ValueError(f"Cannot parse instruction line: {line!r}")
+        op = line[:space_idx].strip()
+        rest = line[space_idx:].strip()
+
+        # Split operands by comma.
+        operands = [p.strip() for p in rest.split(",")]
+        if len(operands) < 2:
+            raise ValueError(
+                f"Instruction must have dest and at least one source: {line!r}"
+            )
+        dest = operands[0]
+        src1 = operands[1]
+        src2 = operands[2] if len(operands) >= 3 else ""
+        instructions.append(Instruction(op=op, dest=dest, src1=src1, src2=src2))
+
+    return functional_units, instructions
+
+
+def run(argv: list[str]) -> int:
+    """Entry point for the CLI, accepting an explicit argv list.
+
+    Args:
+        argv: Command-line arguments (excluding the program name).
+
+    Returns:
+        Exit code (0 = success, non-zero = error).
+    """
+    parser = argparse.ArgumentParser(
+        prog="scoreboarding",
+        description=(
+            "Cycle-exact Thornton Scoreboarding (CDC 6600) simulator. "
+            "Reads a program file and prints the pipeline timing table."
+        ),
+    )
+    parser.add_argument(
+        "program",
+        metavar="FILE",
+        help="Path to program text file (or '-' to read from stdin).",
+    )
+    parser.add_argument(
+        "--snapshots",
+        action="store_true",
+        default=False,
+        help="Print per-cycle state snapshots after the timing table.",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        if args.program == "-":
+            text = sys.stdin.read()
+        else:
+            with open(args.program) as fh:
+                text = fh.read()
+    except OSError as exc:
+        print(f"scoreboarding: error reading file: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        functional_units, instructions = _parse_program(text)
+    except ValueError as exc:
+        print(f"scoreboarding: parse error: {exc}", file=sys.stderr)
+        return 1
+
+    if not functional_units:
+        print(
+            "scoreboarding: no functional units declared"
+            " -- add 'FU <name> <kind> <latency>' lines.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not instructions:
+        print("scoreboarding: no instructions found.", file=sys.stderr)
+        return 1
+
+    try:
+        trace = engine_run(
+            instructions,
+            functional_units=functional_units,
+            capture_snapshots=args.snapshots,
+        )
+    except (ValueError, RuntimeError) as exc:
+        print(f"scoreboarding: simulation error: {exc}", file=sys.stderr)
+        return 1
+
+    print(render_trace(trace))
+
+    if args.snapshots and trace.snapshots:
+        print()
+        for snap in trace.snapshots:
+            print(f"-- Cycle {snap.cycle} --")
+            for i, ist in enumerate(snap.instruction_status):
+                issue_s = str(ist.issue) if ist.issue is not None else "-"
+                ro_s = str(ist.read_operands) if ist.read_operands is not None else "-"
+                ec_s = str(ist.execute_complete) if ist.execute_complete is not None else "-"
+                wr_s = str(ist.write_result) if ist.write_result is not None else "-"
+                print(f"  [{i}] Issue={issue_s} RO={ro_s} EC={ec_s} WR={wr_s}")
+
+    return 0
+
+
+def main() -> None:
+    """Entry point installed as the 'scoreboarding' console script."""
+    sys.exit(run(sys.argv[1:]))

scoreboarding/engine.py

@@ -0,0 +1,347 @@
+"""Cycle-exact Scoreboarding simulator engine.
+
+Implements Thornton's Scoreboarding algorithm as used in the CDC 6600 (1964),
+with four pipeline stages and three tracking tables.
+
+Stage checks (per Thornton):
+
+ISSUE
+  Preconditions (checked in program order -- no instruction may issue while an
+  earlier instruction is stalled):
+  1. No structural hazard: the required functional unit is not busy.
+  2. No WAW hazard: no currently-active instruction will write the same
+     destination register.
+
+READ OPERANDS
+  An instruction that has been issued waits here until BOTH source operands are
+  available. An operand is available when no earlier-issued instruction is still
+  going to write it (qj/qk = None AND rj/rk = True).  This stage resolves RAW.
+
+EXECUTE
+  The instruction occupies its functional unit for exactly `latency` cycles
+  starting the cycle after operands are read.
+
+WRITE RESULT
+  Precondition -- no WAR hazard: every earlier-issued instruction that reads
+  the destination register as a source must have already completed its READ
+  OPERANDS stage.  Once this holds, the result is written to the register file,
+  RegisterResultStatus is cleared, and the functional unit is freed.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass, field
+
+from scoreboarding.model import (
+    CycleSnapshot,
+    FunctionalUnit,
+    FunctionalUnitStatus,
+    Instruction,
+    InstructionResult,
+    InstructionStatus,
+    Trace,
+)
+
+
+@dataclass
+class _SimInstruction:
+    """Internal per-instruction mutable state."""
+
+    instruction: Instruction
+    program_index: int
+    status: InstructionStatus = field(default_factory=InstructionStatus)
+    fu_name: str = ""  # which FU was assigned at issue
+
+
+def _op_kind(op: str) -> str:
+    """Map an operation name to its functional-unit kind.
+
+    Recognises load/store, add/sub, mult/div, and falls back to op.lower().
+    """
+    op_upper = op.upper()
+    if op_upper in ("LD", "LW", "LOAD", "ST", "SW", "STORE"):
+        return "load"
+    if op_upper in ("ADD", "ADDD", "ADDI", "ADDF"):
+        return "add"
+    if op_upper in ("SUB", "SUBD", "SUBI", "SUBF"):
+        return "add"  # SUB shares the add/subtract unit by convention
+    if op_upper in ("MULT", "MUL", "MULTD", "MULF"):
+        return "mult"
+    if op_upper in ("DIV", "DIVD", "DIVF"):
+        return "div"
+    return op.lower()
+
+
+def run(
+    program: list[Instruction],
+    *,
+    functional_units: list[FunctionalUnit],
+    capture_snapshots: bool = False,
+) -> Trace:
+    """Simulate program using Thornton's Scoreboarding algorithm.
+
+    Args:
+        program: Instructions to execute, in program order.
+        functional_units: Available functional units.
+        capture_snapshots: When True, record a full CycleSnapshot each cycle.
+
+    Returns:
+        A Trace with per-instruction cycle stamps and optional snapshots.
+
+    Raises:
+        ValueError: If an instruction's operation has no matching functional unit.
+    """
+    if not program:
+        return Trace(results=[], snapshots=[], total_cycles=0)
+
+    # Validate that every instruction has a matching FU kind.
+    fu_by_kind: dict[str, list[FunctionalUnit]] = {}
+    for fu in functional_units:
+        fu_by_kind.setdefault(fu.kind, []).append(fu)
+
+    for instr in program:
+        kind = _op_kind(instr.op)
+        if kind not in fu_by_kind:
+            raise ValueError(
+                f"No functional unit of kind '{kind}' for operation '{instr.op}'"
+            )
+
+    # Build per-FU status table.
+    fu_status: dict[str, FunctionalUnitStatus] = {
+        fu.name: FunctionalUnitStatus() for fu in functional_units
+    }
+    fu_latency: dict[str, int] = {fu.name: fu.latency for fu in functional_units}
+
+    # Register-result-status table: maps register name -> FU name that will write it.
+    # None means no pending write (register holds its committed value).
+    register_result: dict[str, str | None] = {}
+
+    # Internal instruction list.
+    sim_instrs: list[_SimInstruction] = [
+        _SimInstruction(instruction=instr, program_index=i)
+        for i, instr in enumerate(program)
+    ]
+
+    # Index of the next instruction to issue (in-order issue pointer).
+    next_to_issue: int = 0
+    snapshots: list[CycleSnapshot] = []
+    cycle = 0
+
+    # Run until every instruction has a WriteResult.
+    while not _all_done(sim_instrs):
+        cycle += 1
+
+        # Determine which instructions attempt write-result, read-operands,
+        # and execute this cycle.  ISSUE is handled last because it depends on
+        # the current-cycle FU state after potential WriteResults free units.
+
+        # --- WRITE RESULT ---
+        # For each issued instruction that has completed execution and not yet
+        # written its result, check the WAR condition.
+        for si in sim_instrs:
+            if not _can_attempt_write(si):
+                continue
+            dest = si.instruction.dest
+            # WAR check: every earlier-issued instruction that lists `dest` as a
+            # source (fj or fk) must have already read its operands (rj/rk = False
+            # means it already consumed that operand; the flag is True only while
+            # waiting to read).
+            war_blocked = False
+            for other in sim_instrs:
+                if other is si:
+                    continue
+                if other.status.issue is None:
+                    continue
+                if other.status.issue >= (si.status.issue or 0):
+                    # Only earlier-issued instructions can cause WAR.
+                    continue
+                if other.status.read_operands is not None:
+                    # Already read operands; no WAR from this instruction.
+                    continue
+                fu_other = fu_status.get(other.fu_name)
+                if fu_other is None:
+                    continue
+                # Check if the other instruction is waiting to read dest.
+                if fu_other.fj == dest and fu_other.rj:
+                    war_blocked = True
+                    break
+                if fu_other.fk == dest and fu_other.rk:
+                    war_blocked = True
+                    break
+
+            if war_blocked:
+                continue
+
+            # Write result.
+            si.status.write_result = cycle
+
+            # Clear register-result-status if this FU is still the producer.
+            if register_result.get(dest) == si.fu_name:
+                register_result[dest] = None
+
+            # Update Qj/Qk of any waiting instruction that depended on this FU.
+            for other in sim_instrs:
+                if other.status.issue is None or other.status.read_operands is not None:
+                    continue
+                fu_other = fu_status.get(other.fu_name)
+                if fu_other is None:
+                    continue
+                if fu_other.qj == si.fu_name:
+                    fu_other.qj = None
+                    fu_other.rj = True
+                if fu_other.qk == si.fu_name:
+                    fu_other.qk = None
+                    fu_other.rk = True
+
+            # Free the functional unit.
+            fu_status[si.fu_name].reset()
+
+        # --- READ OPERANDS ---
+        # An instruction reads operands when both sources are ready.
+        for si in sim_instrs:
+            if si.status.issue is None or si.status.read_operands is not None:
+                continue
+            fu_st = fu_status[si.fu_name]
+            # Both operands available when qj=None,rj=True AND qk=None,rk=True.
+            # For single-source instructions src2="" has rk=True and qk=None by
+            # construction.
+            if fu_st.qj is None and fu_st.rj and fu_st.qk is None and fu_st.rk:
+                si.status.read_operands = cycle
+                # Mark operands as consumed (rj=rk=False) so WAR tracking works.
+                fu_st.rj = False
+                fu_st.rk = False
+
+        # --- EXECUTE COMPLETE ---
+        # Mark execute_complete when the latency has elapsed since execute_start.
+        for si in sim_instrs:
+            if si.status.read_operands is None or si.status.execute_complete is not None:
+                continue
+            fu_st = fu_status[si.fu_name]
+            # Start executing the cycle after read-operands.
+            if fu_st.execute_start is None and si.status.read_operands < cycle:
+                fu_st.execute_start = si.status.read_operands + 1
+            if fu_st.execute_start is not None:
+                elapsed = cycle - fu_st.execute_start + 1
+                if elapsed >= fu_latency[si.fu_name]:
+                    si.status.execute_complete = cycle
+
+        # --- ISSUE ---
+        # In-order: attempt to issue the next unissued instruction.
+        if next_to_issue < len(sim_instrs):
+            si = sim_instrs[next_to_issue]
+            instr = si.instruction
+            kind = _op_kind(instr.op)
+
+            # Find a free FU of the right kind.
+            candidate_fu: str | None = None
+            for fu in functional_units:
+                if fu.kind == kind and not fu_status[fu.name].busy:
+                    candidate_fu = fu.name
+                    break
+
+            if candidate_fu is not None:
+                # Check WAW: no active instruction may write the same destination.
+                waw_blocked = False
+                for other in sim_instrs:
+                    if other is si:
+                        continue
+                    if (
+                        other.status.issue is not None
+                        and other.status.write_result is None
+                        and other.instruction.dest == instr.dest
+                    ):
+                        waw_blocked = True
+                        break
+
+                if not waw_blocked:
+                    # Issue.
+                    si.status.issue = cycle
+                    si.fu_name = candidate_fu
+                    next_to_issue += 1
+
+                    fu_st = fu_status[candidate_fu]
+                    fu_st.busy = True
+                    fu_st.op = instr.op
+                    fu_st.fi = instr.dest
+
+                    # Source 1 (fj).
+                    fu_st.fj = instr.src1
+                    producing_fj = register_result.get(instr.src1)
+                    if producing_fj is not None:
+                        fu_st.qj = producing_fj
+                        fu_st.rj = False
+                    else:
+                        fu_st.qj = None
+                        fu_st.rj = True
+
+                    # Source 2 (fk).
+                    if instr.src2:
+                        fu_st.fk = instr.src2
+                        producing_fk = register_result.get(instr.src2)
+                        if producing_fk is not None:
+                            fu_st.qk = producing_fk
+                            fu_st.rk = False
+                        else:
+                            fu_st.qk = None
+                            fu_st.rk = True
+                    else:
+                        # No second source (e.g. single-operand load).
+                        fu_st.fk = ""
+                        fu_st.qk = None
+                        fu_st.rk = True
+
+                    # Mark this FU as the future producer of dest.
+                    register_result[instr.dest] = candidate_fu
+
+        # --- CAPTURE SNAPSHOT ---
+        if capture_snapshots:
+            snapshots.append(
+                CycleSnapshot(
+                    cycle=cycle,
+                    instruction_status=[copy.deepcopy(s.status) for s in sim_instrs],
+                    fu_status=copy.deepcopy(fu_status),
+                    register_result=dict(register_result),
+                )
+            )
+
+        # Safety valve: cap at a generous but finite cycle count.
+        max_cycles = 10 + sum(fu_latency[fu.name] for fu in functional_units) * len(
+            sim_instrs
+        )
+        if cycle > max_cycles:
+            raise RuntimeError(
+                f"Simulation did not terminate within {max_cycles} cycles -- "
+                "possible deadlock in the program or functional unit configuration."
+            )
+
+    total = max(
+        (s.status.write_result for s in sim_instrs if s.status.write_result is not None),
+        default=0,
+    )
+
+    results = [
+        InstructionResult(
+            instruction=si.instruction,
+            issue=si.status.issue or 0,
+            read_operands=si.status.read_operands or 0,
+            execute_complete=si.status.execute_complete or 0,
+            write_result=si.status.write_result or 0,
+        )
+        for si in sim_instrs
+    ]
+
+    return Trace(results=results, snapshots=snapshots, total_cycles=total)
+
+
+def _all_done(sim_instrs: list[_SimInstruction]) -> bool:
+    """Return True when every instruction has completed WriteResult."""
+    return all(si.status.write_result is not None for si in sim_instrs)
+
+
+def _can_attempt_write(si: _SimInstruction) -> bool:
+    """Return True when si is eligible to attempt WriteResult this cycle."""
+    return (
+        si.status.execute_complete is not None
+        and si.status.write_result is None
+    )

scoreboarding/model.py

@@ -0,0 +1,144 @@
+"""Data model for the Scoreboarding simulator.
+
+Three tables track simulation state:
+- InstructionStatus: per-instruction cycle stamps for each stage.
+- FunctionalUnitStatus: per-FU state (busy, operands, ready flags, etc.).
+- RegisterResultStatus: which FU will produce each register's next value.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class FunctionalUnit:
+    """Declares one physical functional unit available to the processor.
+
+    Args:
+        name: Unique identifier, e.g. "Add1", "Mult1", "Load1".
+        kind: Operation class this unit handles, e.g. "add", "mult", "load", "div".
+        latency: Number of cycles the execute stage occupies (>= 1).
+    """
+
+    name: str
+    kind: str
+    latency: int
+
+    def __post_init__(self) -> None:
+        if self.latency < 1:
+            raise ValueError(
+                f"FunctionalUnit '{self.name}': latency must be >= 1, got {self.latency}"
+            )
+
+
+@dataclass
+class Instruction:
+    """One instruction in the program.
+
+    For single-source instructions (e.g. loads), pass the base register as
+    src1 and an empty string "" as src2.
+
+    Args:
+        op: Operation name, e.g. "LD", "MULT", "ADD", "SUB", "DIV".
+        dest: Destination register, e.g. "F6".
+        src1: First source register (or base register for loads).
+        src2: Second source register; pass "" if not applicable.
+    """
+
+    op: str
+    dest: str
+    src1: str
+    src2: str
+
+
+@dataclass
+class InstructionStatus:
+    """Cycle stamps for one instruction's four pipeline stages.
+
+    A value of None means the stage has not yet occurred.
+    """
+
+    issue: int | None = None
+    read_operands: int | None = None
+    execute_complete: int | None = None
+    write_result: int | None = None
+
+
+@dataclass
+class FunctionalUnitStatus:
+    """Runtime state of one functional unit (the FU status table).
+
+    Fields mirror those in Thornton's original scoreboard description:
+    - busy: whether the unit is currently occupied.
+    - op: operation being performed.
+    - fi: destination register name.
+    - fj, fk: source register names.
+    - qj, qk: names of FUs that will produce fj/fk (None = already available).
+    - rj, rk: True when fj/fk are ready to read (operand available and not yet consumed).
+    - execute_start: cycle when execution started (None until started).
+    """
+
+    busy: bool = False
+    op: str = ""
+    fi: str = ""
+    fj: str = ""
+    fk: str = ""
+    qj: str | None = None
+    qk: str | None = None
+    rj: bool = False
+    rk: bool = False
+    execute_start: int | None = None
+
+    def reset(self) -> None:
+        """Return this FU to the idle state."""
+        self.busy = False
+        self.op = ""
+        self.fi = ""
+        self.fj = ""
+        self.fk = ""
+        self.qj = None
+        self.qk = None
+        self.rj = False
+        self.rk = False
+        self.execute_start = None
+
+
+@dataclass
+class CycleSnapshot:
+    """Full simulator state at the end of one cycle.
+
+    Useful for step-by-step educational replay.
+    """
+
+    cycle: int
+    instruction_status: list[InstructionStatus]
+    fu_status: dict[str, FunctionalUnitStatus]
+    register_result: dict[str, str | None]
+
+
+@dataclass
+class InstructionResult:
+    """Final cycle stamps for one instruction after simulation completes."""
+
+    instruction: Instruction
+    issue: int
+    read_operands: int
+    execute_complete: int
+    write_result: int
+
+
+@dataclass
+class Trace:
+    """Full simulation output.
+
+    Attributes:
+        results: Per-instruction cycle stamps in program order.
+        snapshots: Optional per-cycle state snapshots (populated when
+                   capture_snapshots=True in run()).
+        total_cycles: Cycle number of the final WriteResult.
+    """
+
+    results: list[InstructionResult]
+    snapshots: list[CycleSnapshot] = field(default_factory=list)
+    total_cycles: int = 0

scoreboarding/render.py

@@ -0,0 +1,83 @@
+"""Render a Trace as a human-readable timing table."""
+
+from __future__ import annotations
+
+from scoreboarding.model import InstructionResult, Trace
+
+
+def _result_to_row(r: InstructionResult) -> tuple[str, str, str, str, str]:
+    """Convert one InstructionResult to a tuple of string columns."""
+    src2_part = f", {r.instruction.src2}" if r.instruction.src2 else ""
+    instr_str = f"{r.instruction.op} {r.instruction.dest}, {r.instruction.src1}{src2_part}"
+    return (
+        instr_str,
+        str(r.issue),
+        str(r.read_operands),
+        str(r.execute_complete),
+        str(r.write_result),
+    )
+
+
+def render_trace(trace: Trace) -> str:
+    """Return a formatted timing table for the given Trace.
+
+    Each row shows one instruction and the four pipeline-stage cycle numbers:
+    Issue, ReadOperands, ExecuteComplete, WriteResult.
+
+    Args:
+        trace: The simulation output from run().
+
+    Returns:
+        A multi-line string suitable for printing to a terminal.
+    """
+    if not trace.results:
+        return "(empty program)"
+
+    header_instr = "Instruction"
+    header_issue = "Issue"
+    header_ro = "ReadOps"
+    header_ec = "ExecComp"
+    header_wr = "WriteResult"
+
+    rows = [_result_to_row(r) for r in trace.results]
+
+    col0_w = max(len(header_instr), *(len(row[0]) for row in rows))
+    col1_w = max(len(header_issue), *(len(row[1]) for row in rows))
+    col2_w = max(len(header_ro), *(len(row[2]) for row in rows))
+    col3_w = max(len(header_ec), *(len(row[3]) for row in rows))
+    col4_w = max(len(header_wr), *(len(row[4]) for row in rows))
+
+    sep = (
+        "+"
+        + "-" * (col0_w + 2)
+        + "+"
+        + "-" * (col1_w + 2)
+        + "+"
+        + "-" * (col2_w + 2)
+        + "+"
+        + "-" * (col3_w + 2)
+        + "+"
+        + "-" * (col4_w + 2)
+        + "+"
+    )
+
+    def fmt_row(c0: str, c1: str, c2: str, c3: str, c4: str) -> str:
+        return (
+            f"| {c0:<{col0_w}} "
+            f"| {c1:>{col1_w}} "
+            f"| {c2:>{col2_w}} "
+            f"| {c3:>{col3_w}} "
+            f"| {c4:>{col4_w}} |"
+        )
+
+    lines = [
+        sep,
+        fmt_row(header_instr, header_issue, header_ro, header_ec, header_wr),
+        sep,
+    ]
+    for row in rows:
+        lines.append(fmt_row(row[0], row[1], row[2], row[3], row[4]))
+    lines.append(sep)
+    lines.append(f"Total cycles: {trace.total_cycles}")
+
+    return "\n".join(lines)

scoreboarding-0.1.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: scoreboarding
+Version: 0.1.0
+Summary: Pure-Python cycle-exact simulator of Thornton's Scoreboarding (CDC 6600) in-order dynamic scheduling, with structural, WAR, and WAW hazard detection and per-instruction traces for computer architecture education.
+Project-URL: Homepage, https://github.com/amaar-mc/scoreboarding
+Project-URL: Repository, https://github.com/amaar-mc/scoreboarding
+Project-URL: Issues, https://github.com/amaar-mc/scoreboarding/issues
+Project-URL: Changelog, https://github.com/amaar-mc/scoreboarding/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: cdc-6600,computer-architecture,cpu-simulator,education,hazards,in-order,instruction-scheduling,pipeline,scoreboarding,simulation
+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
+
+# scoreboarding
+
+<p align="center">
+  <img src="assets/logo.png" alt="scoreboarding logo" width="160">
+</p>
+
+Pure-Python cycle-exact simulator of Thornton's **Scoreboarding** algorithm,
+as implemented in the CDC 6600 (1964). Designed for computer architecture
+education: readable source, zero runtime dependencies, and per-instruction
+cycle-number traces.
+
+> PyPI publish pending (package-upload quota). `pip install scoreboarding`
+> will work once the first release is live. Install from source in the meantime.
+
+---
+
+## What is Scoreboarding?
+
+Scoreboarding is an **in-order issue, out-of-order execution** dynamic
+scheduling technique. The processor issues instructions one at a time
+(program order), but lets them read operands and execute independently once
+their hazards clear. A central scoreboard -- three tables -- tracks every
+in-flight instruction and enforces the classic CDC 6600 hazard rules without
+any register renaming.
+
+### The Four Stages
+
+| Stage | What happens | Hazard checked |
+|---|---|---|
+| **Issue** | Assign instruction to a free FU | Structural (FU busy) + WAW (another active insn writes same dest) |
+| **Read Operands** | Read both source registers | RAW (stall until producing FU has written result) |
+| **Execute** | Occupy the FU for its full latency | -- |
+| **Write Result** | Commit result to register file, free FU | WAR (stall until every earlier reader has read its operand) |
+
+### Three Tracking Tables
+
+1. **Instruction Status** -- per-instruction cycle stamps (Issue / ReadOperands / ExecuteComplete / WriteResult).
+2. **Functional Unit Status** -- per-FU: busy flag, op, destination (Fi), sources (Fj, Fk), producing FUs (Qj, Qk), ready flags (Rj, Rk).
+3. **Register Result Status** -- which FU will next write each register (None once written).
+
+### How it differs from Tomasulo
+
+| | Scoreboarding | Tomasulo |
+|---|---|---|
+| Issue order | In order | In order |
+| Execution order | Out of order | Out of order |
+| WAW handling | Stall Issue | Register renaming (RS tags) |
+| WAR handling | Stall Write Result | Eliminated by renaming |
+| RAW handling | Stall Read Operands | Stall in RS until CDB broadcast |
+| Register renaming | No | Yes (via reservation stations) |
+| Broadcast mechanism | Central scoreboard | Common Data Bus |
+
+See the sibling package [tomasulo](https://github.com/amaar-mc/tomasulo) for the
+Tomasulo out-of-order scheduler with register renaming.
+
+---
+
+## Install
+
+```bash
+# From source (until PyPI release):
+git clone https://github.com/amaar-mc/scoreboarding
+cd scoreboarding
+uv pip install -e ".[dev]"
+```
+
+---
+
+## Usage
+
+### Python API
+
+```python
+from scoreboarding import FunctionalUnit, Instruction, run, render_trace
+
+fus = [
+    FunctionalUnit(name="Load1", kind="load", latency=2),
+    FunctionalUnit(name="Mult1", kind="mult", latency=10),
+    FunctionalUnit(name="Add1",  kind="add",  latency=2),
+    FunctionalUnit(name="Div1",  kind="div",  latency=40),
+]
+
+program = [
+    Instruction(op="LD",   dest="F6",  src1="R2", src2=""),
+    Instruction(op="LD",   dest="F2",  src1="R3", src2=""),
+    Instruction(op="MULT", 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"),
+]
+
+trace = run(program, functional_units=fus)
+print(render_trace(trace))
+```
+
+### Example timing table
+
+```
++---------------------+-------+---------+----------+-------------+
+| Instruction         | Issue | ReadOps | ExecComp | WriteResult |
++---------------------+-------+---------+----------+-------------+
+| LD F6, R2           |     1 |       1 |        2 |           3 |
+| LD F2, R3           |     3 |       3 |        4 |           5 |
+| MULT F0, F2, F4     |     4 |       5 |       14 |          15 |
+| SUB F8, F6, F2      |     4 |       5 |        6 |           7 |
+| DIV F10, F0, F6     |     5 |      15 |       54 |          55 |
+| ADD F6, F8, F2      |     8 |       8 |        9 |          16 |
++---------------------+-------+---------+----------+-------------+
+Total cycles: 16
+```
+
+### CLI
+
+```bash
+# Use the bundled example:
+scoreboarding examples/classic.txt
+
+# Enable per-cycle snapshots:
+scoreboarding --snapshots examples/classic.txt
+
+# Read from stdin:
+cat examples/classic.txt | scoreboarding -
+```
+
+Program file format:
+
+```
+# Comments start with #
+FU Load1 load 2
+FU Mult1 mult 10
+FU Add1  add  2
+FU Div1  div  40
+
+LD   F6, R2
+LD   F2, R3
+MULT F0, F2, F4
+SUB  F8, F6, F2
+DIV  F10, F0, F6
+ADD  F6, F8, F2
+```
+
+---
+
+## Development
+
+```bash
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+uv build
+```
+
+CI runs on Python 3.10, 3.11, 3.12, 3.13 via GitHub Actions.
+
+---
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

scoreboarding-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+scoreboarding/__init__.py,sha256=NNn0ApX5cldroPqduB-hI0KJ1Q6FdLBBZiRme5-VgLM,1494
+scoreboarding/cli.py,sha256=6PBtYrI3nqM4onLDPjsZT4baiMcv60oFE95aTfQvR_E,5639
+scoreboarding/engine.py,sha256=Nppk6ekyVsipvS-MsAOb-YhZdmBoYqinafvZsMn8tfE,13109
+scoreboarding/model.py,sha256=SONQ41KH-UhxGxQaS7Fl0Tbz1BRqaDBPbESx27EsKg4,3911
+scoreboarding/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scoreboarding/render.py,sha256=rjmKVIwga2frNdGKQNCfBg7kSaoy6-5BXw3D4HdY4kM,2417
+scoreboarding-0.1.0.dist-info/METADATA,sha256=NczuAVXyJlefKrnuj4qeshswfY0d-f74wu7SGixeKvA,7554
+scoreboarding-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+scoreboarding-0.1.0.dist-info/entry_points.txt,sha256=3i_fhrWHz9Z5flBtTx3mCHXFdYAByv09KM1jp9vCapg,57
+scoreboarding-0.1.0.dist-info/licenses/LICENSE,sha256=NORTVJb4x206RXQkpZt_vpj8I7aZL6Vn26BvTOq6J40,1071
+scoreboarding-0.1.0.dist-info/RECORD,,

scoreboarding-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

scoreboarding-0.1.0.dist-info/entry_points.txt

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

scoreboarding-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.