scoreboarding

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.

i built this because the algorithm only really clicked once i could watch each hazard clear one cycle at a time.

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

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

Pipelined vs unpipelined functional units

Each FunctionalUnit declares whether its execute stage is pipelined.

• Unpipelined (pipelined=False, the classic CDC 6600 default): the unit is a structural hazard for its entire lifetime. It stays busy from Issue through Write Result, so a same-kind successor cannot issue to it until the occupying instruction has written its result. This is the original scoreboard behaviour.
• Pipelined (pipelined=True): the unit frees its issue slot as soon as the occupying instruction has read its operands and entered the execute pipeline. A same-kind successor can then issue the next cycle while the deep execute pipeline still carries the earlier result. The structural stall is shorter; RAW, WAR, and WAW hazards are unaffected.

For example, two independent back-to-back multiplies on a single latency=4 multiply unit:

The pipelined unit issues the second multiply at cycle 2 (right after the first reads operands) instead of waiting until cycle 7 for the first to write back.

How it differs from Tomasulo

See the sibling package tomasulo for the Tomasulo out-of-order scheduler with register renaming.

Install

# From source (until PyPI release):
git clone https://github.com/amaar-mc/scoreboarding
cd scoreboarding
uv pip install -e ".[dev]"

Usage

Python API

from scoreboarding import FunctionalUnit, Instruction, run, render_trace

fus = [
    FunctionalUnit(name="Load1", kind="load", latency=2,  pipelined=False),
    FunctionalUnit(name="Mult1", kind="mult", latency=10, pipelined=False),
    FunctionalUnit(name="Add1",  kind="add",  latency=2,  pipelined=False),
    FunctionalUnit(name="Div1",  kind="div",  latency=40, pipelined=False),
]

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

Per-cycle snapshots

Pass capture_snapshots=True to run() to capture scoreboard state after every cycle, then render any CycleSnapshot with render_snapshot():

from scoreboarding import render_snapshot

trace = run(program, functional_units=fus, capture_snapshots=True)
print(render_snapshot(trace.snapshots[0]))

-- Cycle 1 --
Instruction status
  #  Issue  ReadOps  ExecComp  WriteResult
  -  -----  -------  --------  -----------
  0  1      -        -         -
  1  -      -        -         -
  2  -      -        -         -
  3  -      -        -         -
  4  -      -        -         -
  5  -      -        -         -

Functional unit status
  FU     Busy  Op  Fi  Fj  Fk  Qj  Qk  Rj   Rk   ExecStart
  -----  ----  --  --  --  --  --  --  ---  ---  ---------
  Add1   no    -   -   -   -   -   -   no   no   -
  Div1   no    -   -   -   -   -   -   no   no   -
  Load1  yes   LD  F6  R2  -   -   -   yes  yes  -
  Mult1  no    -   -   -   -   -   -   no   no   -

Register result status
  Register  Producer
  --------  --------
  F6        Load1

render_trace() renders the summary timing table; render_snapshot() renders the full three-table scoreboard state for a single cycle.

CLI

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

--snapshots prints the instruction-status, functional-unit-status, and register-result-status tables after every cycle, so a stall can be traced back to the exact scoreboard entry holding it up.

Program file format:

# Comments start with #
# FU <name> <kind> <latency> [pipelined|unpipelined]   (default: unpipelined)
FU Load1 load 2
FU Mult1 mult 10 pipelined
FU Add1  add  2
FU Div1  div  40 unpipelined

LD   F6, R2
LD   F2, R3
MULT F0, F2, F4
SUB  F8, F6, F2
DIV  F10, F0, F6
ADD  F6, F8, F2

Development

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.