Out-of-order RISC-V processor

This is a processor that runs RISC-V programs. It is 64-bit, it issues two instructions per cycle, and it executes them out of order. The instruction set is RV64IMAC: the 64-bit base, integer multiply and divide, atomic memory operations, and compressed 16-bit instructions. The repository name for the design is riscv64xO3.

The processor is described in SystemVerilog, and the project checks that this description can be turned into silicon. Start with Introduction, then Architecture for how the pipeline is organized. If this prose and the SystemVerilog disagree, the SystemVerilog wins.

1. Introduction

riscv64xO3 is a 64-bit superscalar out-of-order RISC-V project and core. Target ISA: RV64IMAC + Zicsr/Zifencei. The core fetches, decodes, issues, and commits two instructions per cycle, using Tomasulo reservation stations with in-order ROB commit. Native bus: AXI4-Lite. Privilege: M-mode with precise traps.

1.1. What this manual is

This manual is the detailed technical reference. The root README.md remains the concise GitHub-facing project overview; it does not duplicate this content.

1.2. Repository map

Table 1. Repository layout. Use it to locate evidence for every claim.
Path Purpose

rtl/

SystemVerilog source (synthesizable). Executable authority.

tb/

Unit, cocotb, compliance, and formal testbenches

docs/

This manual (source) plus ISA contract and history

sw/

CRT, linker scripts, bare-metal examples

asic/

Yosys synthesis and OpenLane feasibility flow

tools/

Documentation guardrails, ISA generators

scripts/

Build and reporting scripts, including build-docs.sh

docker/

Development and CI container definitions

1.3. Canonical vocabulary

  • riscv64xO3 is the 64-bit superscalar out-of-order RISC-V project and core.

  • RTL simulation means Verilator-driven simulation of rtl/. Label its results as simulation, never silicon or board execution.

  • Compliance means the riscv-tests ISA suites run against the RTL model.

  • FPGA prototype means a future hw/fpga mapping; it does not exist yet.

  • ASIC feasibility means Yosys/OpenLane smoke reports in asic/; it is not a tapeout.

1.4. Documentation authority

When sources disagree, this order wins:

  1. rtl/ SystemVerilog (the executable authority).

  2. Known Limitations and the facts stated in this introduction.

  3. Machine-readable contracts (docs/isa/rv64xo3.csv, tools/ generators).

  4. Other prose in this manual.

  5. docs/log/ history (never authoritative for current status).

Status words are used exactly: present / in progress / planned / verified. Simulation, FPGA, and silicon claims are kept distinct.

Note
Dated engineering history lives in docs/log/. Do not cite a log entry for present status unless a current chapter confirms it.

1.5. Conventions used in this manual

mono marks file paths, signal names, and commands. Cross references look like Architecture and resolve in both the source view and the built site. Admonitions mark non-obvious obligations:

Tip
Start with this chapter and Known Limitations before trusting any number elsewhere.

2. Architecture

Target: RV64IMAC + Zicsr/Zifencei, 2-wide superscalar out-of-order, Tomasulo with in-order commit. AXI4-Lite native. M-mode precise traps.

2.1. Pipeline overview

Five programmer-visible stages: fetch, decode/rename/dispatch, issue/execute, memory, commit. Mispredicts and traps roll back to the ROB head and redirect fetch.

Pipeline stages
Figure 1. Pipeline stages and rollback path.

The commit stage retires up to two instructions per cycle and is the only point where architectural state becomes visible. See Design for stage internals and Interfaces for bus behavior.

Two-wide pathFetch parcel: 64-bit parcels. Pairs can cross an 8-byte boundary.; Decode: Four register reads and two writes per pair.; Execute: Two ALU slots. RAW and WAW serialize the pair.; Commit: In-order retire, up to two instructions per cycle.; RVC expander: Combinational RV64C decode. Not yet in fetch. Two-wide path Phase 2 closeout, plus the RVC expander 01 Fetch parcel 64-bit parcels. Pairs can cross an 8-byte boundary. 02 Decode Four register reads and two writes per pair. 03 Execute Two ALU slots. RAW and WAW serialize the pair. 04 Commit In-order retire, up to two instructions per cycle. 05 RVC expander Combinational RV64C decode. Not yet in fetch.
Figure 2. Two-wide issue path recorded in the phase log

Phase 2 closed the two-wide in-order machinery in RTL simulation. Phase 4 added a combinational RV64C expander that is not instantiated by fetch yet, so this figure keeps it off the pipeline. IPC is still TBD (unmeasured).

2.2. Top-level parameters

Table 2. Parameters from rtl/include/rv64xo3_pkg.sv.
Parameter Value Notes

XLEN

64

RV64 datapath

FETCH_WIDTH / COMMIT_WIDTH

2

Superscalar width

ROB_SZ

64

In-order retire buffer

PRF_SZ

96

Physical registers (32 arch {rightarrow} 96 phys)

RS_ALU_SZ / RS_MUL_SZ / RS_LSU_SZ

8 / 4 / 4

Reservation stations

LSQ_SZ

16

Load-store queue

RESET_PC

0x8000_0000

Core default (rv64xo3_top/rv64xo3_if parameter; the AXI system wrapper re-parameterizes it)

2.3. Branch prediction

  • Bimodal predictor: 256-entry branch history table of 2-bit saturating counters, indexed by PC bits, initialized weakly not taken.

  • JAL is always predicted taken with a computed target; conditional branches use the counter’s taken bit.

  • Updates come from the execute stage; resolution happens in execute.

  • Mispredict flushes instructions younger than the ROB branch entry and restores the rename checkpoint. Source: rtl/rv64xo3_bp.sv.

2.4. Memory and commit model

  • 16-entry LSQ (scaffolding): ready/forward ports exist, but address matching, store-set prediction, and AXI issue are TODO.

  • AXI4-Lite instruction and data masters; data misalignment is split in hardware (see Design), misaligned fetch targets trap. See Interfaces.

  • CSR, mret, ecall, and ebreak retire at the ROB head only, giving precise M-mode traps (mepc/mcause/mtval set, redirect to mtvec).

3. Design

This chapter describes the microarchitecture behind the pipeline in Architecture. All module paths are relative to the repository root.

3.1. Fetch (IF)

Sources: rtl/rv64xo3_if.sv, rtl/rv64xo3_bp.sv.

  • 2-wide fetch on a 4-byte-aligned PC with an instruction buffer for downstream stalls. The fetch path is 32-bit today; RVC expansion is planned.

  • Bimodal direction prediction as described in Architecture.

  • Instruction memory reached through the AXI4-Lite master; fetch_stall asserts on miss.

3.2. Decode, rename, dispatch (ID)

Sources: rtl/rv64xo3_id.sv, rtl/issue/rv64xo3_rename.sv, rtl/rv64xo3_decoder.sv.

  • 2-wide decode driven by docs/isa/rv64xo3.csv. Illegal encodings poison the ROB entry and raise a precise trap.

  • Rename maps 32 architectural registers onto 96 physical registers using a map table plus freelist, with a checkpoint per branch.

  • Dispatch targets ALU (x8), multiply (x4), and LSU (x4) reservation stations and allocates ROB entries in order. Dispatch stalls when RS, ROB, or LSQ is full.

Table 3. Register and queue sizing.
Structure Entries Function

ROB

64

In-order commit, precise traps

PRF

96 x 64 bit

Renamed data storage

RS ALU / MUL / LSU

8 / 4 / 4

Tomasulo wakeup and select

LSQ

16

Forwarding, ordering, commit drain

3.3. Issue and execute (IS)

Sources: rtl/issue/rv64xo3_rs.sv, rtl/rv64xo3_ex.sv, rtl/rv64xo3_alu.sv, rtl/rv64xo3_muldiv.sv.

  • One single-cycle combinational ALU plus a shared multi-cycle multiply/divide unit (compute states with an iterative divider).

  • Reservation stations expose CDB tag/valid ports; tag RAM, ready bits, oldest-ready select, and broadcast are TODO scaffolding.

  • Branch resolution in execute triggers flush and map-table restore.

The ALU operation set (from rtl/include/rv64xo3_pkg.sv):

typedef enum logic [4:0] {
  ALU_ADD, ALU_SUB, ALU_SLL, ALU_SLT, ALU_SLTU,
  ALU_XOR, ALU_SRL, ALU_SRA, ALU_OR, ALU_AND,
  ALU_ADDW, ALU_SUBW, ALU_SLLW, ALU_SRLW, ALU_SRAW
} alu_op_e;

3.4. Memory (MEM)

Sources: rtl/memory/rv64xo3_lsq.sv, rtl/rv64xo3_mem.sv.

  • The bus moves one 4-byte-aligned word per transaction. Accesses up to 8 bytes that cross the word boundary are split in hardware into at most two transactions, so data misalignment never traps.

  • No MEM exception source remains: bus faults are not modeled and the exception ports are tied off for future PMP/bus-error use.

  • The LSQ (rtl/memory/rv64xo3_lsq.sv) is scaffolding: ready/forward ports exist, address CAM, store-set prediction, and AXI issue are TODO.

Note
Data misalignment is split in hardware. Only misaligned instruction-fetch targets trap.

3.5. Commit (CM)

Source: rtl/commit/rv64xo3_rob.sv.

  • In-order retirement of up to two instructions per cycle.

  • Precise traps flush younger entries and redirect fetch to mtvec.

4. Interfaces

The core is AXI4-Lite native on both instruction and data ports. There is no Wishbone in the core path; the legacy wb_to_axi4lite bridge (rtl/wb_to_axi4lite.sv) is retained only for UART and debug bring-up.

4.1. Bus architecture

  • Separate AXI4-Lite IMEM and DMEM masters from rtl/rv64xo3_top.sv.

  • Single clock domain with explicit reset strategy.

  • External memory interface only; no internal caches or TCM in this revision.

Table 4. Core memory interfaces.
Interface Protocol Notes

IMEM master

AXI4-Lite

Instruction fetch, fetch_stall on miss

DMEM master

AXI4-Lite

LSQ spill/fill, store drain at commit

UART bridge

AXI4-Lite via wb_to_axi4lite

Bring-up and hello.c demo only

4.2. Clocks, reset, and memory map

Table 5. Reset and address behavior.
Item Value

Clocking

Single clock domain

Reset

Synchronous; core PC loads RESET_PC (default 0x8000_0000, re-parameterizable per wrapper)

Privilege

M-mode trap handling; supervisor CSR shadows and sret present

Misaligned data

Split in hardware across bus transactions, never traps

Misaligned fetch target

Precise trap

Tip
Bare-metal programs link against sw/link64.ld with the reset vector at 0x8000_0000 and enter through sw/crt0_64.S. See Implementation for the software flow.

4.3. Debug and UART

  • tb/tb_uart_axi.sv and rtl/uart_axi.sv cover the UART path.

  • The hello.c end-to-end demo exercises UART output through the bridge.

  • Handshake, mutual-exclusion, and trap-entry assertions are documented in Verification.

5. Programming Model

5.1. ISA support

Machine-readable contract: docs/isa/rv64xo3.csv (columns: opcode,funct3,funct7/instr,name,class,description).

Table 6. ISA status. RV64IM is implemented; A/C are in bring-up.
Extension Status Notes

RV64I (incl. W-suffixed word ops)

present

ADDW/SUBW/SLLW/SRLW/SRAW, LD/SD, LWU

M (incl. W ops)

present

MUL[H[SU][U]]/DIV[U]/REM[U], MULW/DIVW[D]/REMW[D]

Zicsr / Zifencei

present

CSR access, fences

A

in progress

Bring-up; see Known Limitations

C

in progress

16-bit parcels via RVC expander (bring-up)

The full opcode map covers integer computation (immediate and register-register), control transfer, loads/stores, AUIPC/LUI, system, and fence encodings. Illegal encodings trap precisely. FENCE and FENCE.I decode as NOPs (single in-order pipe, no caches).

5.2. Control and status registers

Table 7. Minimum CSR set (rtl/include/rv64xo3_pkg.sv).
CSR Address Purpose

mstatus

0x300

Machine status

misa

0x301

ISA identity

mie / mip

0x304 / 0x344

Interrupt enable / pending

mtvec

0x305

Trap vector

mscratch

0x340

Machine scratch

mepc / mcause / mtval

0x341 / 0x342 / 0x343

Trap state

cycle / instret

0xC00 / 0xC02

Counters

mvendorid / marchid / mimpid / mhartid

0xF11-0xF14

Identity

CSR instructions CSRRW/CSRRS/CSRRC and immediates are supported, including masked writes. mret restores the pre-trap PC; sret is supported alongside the supervisor CSR shadows. misa reports MXL=2 with I+M only.

5.3. Traps and exceptions

Table 8. Precise M-mode trap causes (mcause values).
Cause Meaning

0

Instruction address misaligned

1

Instruction access fault

2

Illegal instruction

3

Breakpoint

4

Load address misaligned

5

Load access fault

6

Store address misaligned

7

Store access fault

11

Environment call from M-mode

ecall, ebreak, CSR operations, and mret retire at the ROB head, so trap entry updates the PC and mret restores it atomically.

6. Verification

Multi-layered strategy: block-level unit tests, cocotb integration, and riscv-tests compliance against the RTL model, all cycle-accurate under Verilator.

6.1. Strategy

Table 9. Verification layers and entry points.
Layer Tools Scope

Unit (pytest)

tb/unit/

ALU, decoder, CSR, MulDiv, memory in isolation

Integration (cocotb)

tb/cocotb/

Pipeline interaction, hazards, bus models

Compliance

tb/compliance/Makefile.rv64

Official riscv-tests RV64 suites

Formal / SVA

rtl/rv64xo3_top.sv, rtl/rv64xo3_hazard_sva.sv

14 assert properties: x0, PC/mutual-exclusion, handshake liveness (tb/formal/ reserved, empty)

Directed tests cover corner cases (divide-by-zero, mixed signs, misaligned traps, masked CSR writes); randomized tests cover arithmetic and constrained-random instruction streams. Bus-functional models drive the AXI4-Lite interfaces.

6.2. Current results

Phase 0 baseline (docs/log/2026-10-01-phase0-foundation.md, riscv-tests submodule @ 7af6beb):

  • make compliance (RV64 default): RV64UI 54/54, RV64UM 13/13, RV64MI 15/15 (includes ma_addr, ma_fetch, misaligned family, sbreak).

  • Legacy baselines: RV32UI 37/37 + RV32UM 8/8 (make compliance-rv32), legacy asm 8/8, C++ harness suites 15/15.

  • make unit: 58 passed. make cocotb: 7 passed (ALU, decoder, CSR, memory, MulDiv, AXI IMEM+DMEM, top).

  • Line/toggle coverage is collected with Verilator and tracked toward PRD targets (>=95% line, >=80% toggle); regenerate with scripts/generate_coverage_report.py rather than quoting old figures.

Note
Numbers here describe RTL simulation only. See Known Limitations for what simulation evidence does and does not prove.

6.3. Running the suites

make lint            # Verible + Verilator lint
make unit            # pytest module tests
make cocotb-smoke    # fast integration subset
make cocotb          # full integration
make compliance      # RV64 riscv-tests via Verilator sim
make regress         # lint + unit + cocotb + compliance

Waveforms land in waves/ as .fst; view them with:

make waves   # requires GTKWave on the host

6.4. Quality gates

  • Verible and Verilator lint clean: no inferred latches, no combinational loops, all registers explicitly clocked.

  • Pre-commit hooks run the documentation guardrails (python3 tools/check_docs.py) and YAML parsing.

7. Implementation

7.1. Getting started

Two flows are supported. Docker is recommended for exact tool versions.

Option A — Docker (recommended):

make docker-build
make docker-shell
# inside the container:
make regress

Option B — local install (Linux/macOS):

brew install verilator            # macOS
# or: sudo apt install verilator  # Ubuntu
pip install -r requirements.txt
# riscv64-unknown-elf-gcc must be on PATH

Focused checks after setup:

python3 tools/check_docs.py
make lint
make unit cocotb-smoke

7.2. Build and test commands

Table 10. Canonical make targets.
Command Effect

make lint

Verible + Verilator lint

make sim

Build the Verilator simulator binary

make unit / make cocotb[-smoke]

Unit / integration tests

make compliance

RV64 compliance (RV32 kept as compliance-rv32 baseline)

make regress

Full regression: lint + all test layers

make synth

Yosys synthesis smoke

make asic-feas

OpenLane feasibility (needs PDK image)

make docs

Build this manual into build/docs/

Generated artifacts go to build/ (simulation, logs) and waves/ (waveforms). Both are gitignored and never committed.

7.3. Synthesis and ASIC feasibility

Synthesis status (Yosys, rv64xo3_top).

Aspect Status Notes

RTL synthesizability

verified

Yosys completes; no latches or combinational loops

FPGA target

Artix-7 family

Vendor run pending; LUT/FF counts estimated only

ASIC feasibility

Sky130 / OpenLane2

Flow configured (asic/); not a tapeout

Clocking

single domain

Explicit synchronous reset

make synth        # Yosys smoke (see scripts/synth/)
make asic-feas    # OpenLane feasibility (see asic/)

Estimates only, pending real runs: core area on the order of 0.1-0.3 mm^2 in Sky130, 50-150 MHz post-layout, 5-8k LUTs on Artix-7. Do not quote these as measured results.

7.4. Software flow

  • sw/crt0_64.S startup, sw/link64.ld link script, sw/uart.h driver.

  • Examples: sw/hello.c (UART end-to-end), sw/test_misalign.c.

  • 32-bit crt0.S/link.ld retained for the legacy RV32 baseline.

Tip
Rebuild software images with make -C sw; never commit generated .elf/.hex/.mem files.

8. Performance

All figures below are measured on Verilator RTL simulation unless noted. They describe the model, not silicon or a board.

8.1. Dhrystone 2.1

Config: 100 runs, GCC 15.1.0 -O2, RV64IM_Zicsr.

Table 11. Measured results.
Metric Value

Cycles per run

1174

DMIPS/MHz

0.48

IPC

TBD (counter issue in the measured run)

The score follows the standard definition:

\[\mathrm{DMIPS/MHz} = \frac{10^6 / \mathrm{cycles\_per\_run}}{1757}\]

Current performance is bounded by the absence of caches: instruction fetch and data access over AXI4-Lite cost multiple cycles per access. A dedicated instruction cache or tightly coupled memory would move IPC toward the theoretical 2-wide ceiling.

8.2. Other benchmarks

  • CoreMark: pending porting.

  • FPGA synthesis on Artix-7: pending vendor run.

  • Post-layout frequency and power: TBD after a full OpenLane run.

8.3. Resource and timing estimates

Table 12. Pending measurement; do not quote as results.
Item Estimate basis

LUTs / FFs

~5-8k / ~2-3k from RTL complexity (5-stage + OoO scaffolding)

Block RAM / DSP

Minimal / 0-2 depending on multiplier mapping

Target clock

50-100 MHz conservative (Artix-7); 50-150 MHz post-layout (Sky130)

Critical path

Likely ALU or hazard detection

9. Known Limitations

This chapter bounds what the repository proves. It outranks any optimistic reading of earlier chapters.

9.1. Status boundaries

  • Source-present: in-order 5-stage pipeline renamed to rv64xo3_*; out-of-order issue/commit scaffolding present; full Tomasulo in progress.

  • Testable without hardware: make lint unit cocotb-smoke compliance.

  • Hardware-dependent: FPGA mapping, board boot, and silicon require live evidence. Do not infer them from source or simulation.

9.2. Open items

  • A and C extensions are in bring-up, not verified.

  • No PMP unit (pmpaddr unimplemented).

  • No instruction/data caches; AXI4-Lite latency bounds IPC.

  • Misaligned data accesses are handled in hardware (split bus transactions, no trap); misaligned instruction-fetch targets still trap.

  • FPGA prototype mapping does not exist yet.

  • ASIC work is feasibility smoke (Yosys + OpenLane2), not a tapeout.

  • CoreMark and FPGA synthesis numbers are pending.

Warning
Never relabel simulation, feasibility, or estimates as silicon, board, or tapeout results.

9.3. History and policy

Dated decisions live in docs/log/ (YYYY-MM-DD-topic.md with what was run and observed). Log entries are historical and never override this chapter. The standing authority order is rtl/, then this manual’s current facts, then machine-readable contracts, then other prose, then history.

10. Engineering log

Each note below is the original project log, in chronological order. Open the arrow in the sidebar to jump to an entry.

10.1. 2026-10-01 — Phase 0 foundation: build, compliance, and scalar correctness

Date: 2026-10-01. Local run (Apple Silicon, Verilator 5.052, xpack riscv-none-elf-gcc 13.2.0). riscv-tests @ 7af6beb (submodule).

Baseline (all green)

  • make lint — Verible skipped (not installed locally), Verilator clean.
  • make unit — 58 passed.
  • make cocotb (new cocotb 2.x pytest runner) — 7 passed

(alu, decoder, csr, mem, muldiv, axi imem+dmem, top).

  • make cocotb-smoke — alu subset passes.
  • make compliance (RV64 default) — RV64UI 54/54, RV64UM 13/13,

RV64MI 15/15 (includes ma_addr, ma_fetch, misaligned family, sbreak).

  • make compliance-rv32 (legacy) — RV32UI 37/37, RV64UM 8/8.
  • C++ harness suites — 15/15. Legacy asm (scripts/run_tests.sh) — 8/8.

What was fixed to get here

  • make sim canonical simulator target; run_tests.sh deduplicated.
  • Compliance default switched to RV64 (Makefile.rv64); RV32 kept as

compliance-rv32; riscv-tests vendored as submodule with env guards.

  • C++ harness: base-relative test writes, per-test --tohost (address

moves with test size), unified I/D memory (fence.i self-modifying code), unhandled traps no longer report PASS.

  • RTL: muldiv operand latching (forwarding-mux drift) + REMUW div-by-zero;

misa (MXL=2, I+M only), sstatus/sscratch/mscratch, CSR immediate (zimm) write path; load-use stall must not flush a load while MEM is frozen; faulting MEM ops must not retire (precise traps); fetch-misaligned trap + sret; fence/fence.i as NOPs; hardware misaligned-access splitting (no more traps for data misalignment).

  • Legacy asm: linked at 0x80000000 (was 0x0, breaking la), test data

moved clear of test code (stores clobbered code), RV32-era constant assumptions fixed for RV64 (alu tests 9/18/19, muldiv test 18).

  • cocotb migrated to 2.x (tb/cocotb/cocotb_runner.py); dead

cocotb-config Makefiles removed; unit tests updated to the compliant mstatus contract (hardwired SXL/UXL=2).

Known gaps (not fixed)

  • pmpaddr (no PMP unit), C/A extensions, caches, FPGA/ASIC beyond

feasibility smoke. See ch. 9.

10.2. 2026-10-01 — Phase 1: non-blocking execute

Date: 2026-10-01. Local run (Apple Silicon, Verilator 5.052).

Result

  • MUL/MULH/MULHSU/MULHU/MULW are single-cycle combinational (1/cycle).
  • DIV iterates in the background (65 cycles); at most one outstanding,

tracked by destination in a scoreboard. Independent instructions flow; consumers and WAW writers stall; completion injects via a 1-cycle writeback stall. No whole-pipeline muldiv stall remains.

Evidence

  • test_div_overlap: 40 independent addi retire during one DIV, dependent

consumer reads the right value — 97 cycles (fully-stalling design: ~160).

  • test_mul_throughput: 8 back-to-back MULs in 27 cycles (~48 at 4/cycle).
  • Regression green: RV64UI 54/54, RV64UM 13/13, RV64MI 15/15,

RV32UI 37/37, RV32UM 8/8, unit 58/58, cocotb 7/7, C++ suites 15/15, legacy asm 8/8, lint clean.

Bugs found on the way in

  • Scoreboard freezing a VALID instruction in EX while MEM drained let its

latched operands go stale as forwards drained (fixed: flush EX like a load-use so it advances once and drains; MEM takes a bubble instead of re-capturing frozen EX).

  • Scoreboard rs2 is checked raw, so I-type ops with aliasing immediates

can stall spuriously (safe; Tomasulo makes it moot).

  • Same-rd WAW across an outstanding DIV needs a 65+ cycle bus stall plus

rd collision to mis-forward; bus SRAM acks immediately here.

10.3. 2026-10-02 — Phase 2: two-wide in-order closeout

Requested log date: 2026-10-02. Verification ran on 2026-10-01 local (America/New_York), crossing 2026-10-02 UTC. Apple Silicon, Verilator 5.052, xPack RISC-V GCC 13.2.0-2. All evidence below is RTL simulation; no FPGA or silicon result is implied.

Result

  • IF streams aligned 64-bit instruction parcels in RUN, assembles pairs

across an eight-byte boundary with two transactions, buffers stalls, and drains redirects through IDLE.

  • ID has four reads and two writes; EX has two ALU/branch slots. Pair

dispatch serializes RAW, WAW, and shared-resource conflicts; forwarding identifies both producer slots through three-bit selectors.

  • Pipeline registers carry both slots with ordered traps, CSR handling,

and the existing background DIV scoreboard. Misaligned fetch targets participate in trap_taken.

  • Wishbone test memories return full instruction parcels and sample at

the falling edge so held-strobe requests receive current-address data.

Verification

  • make compliance: RV64UI 54/54, RV64UM 13/13, RV64MI 15/15,

including ma_fetch; zero failures or skips.

  • make compliance-rv32: RV32UI 37/37, RV32UM 8/8.
  • make regress: unit 58/58, cocotb runners 7/7, C++ suites 15/15,

both compliance baselines above, and Verilator lint clean.

  • Verible is unavailable locally; its lint step explicitly skipped.

Full Verible lint/format verification remains outstanding.

  • A verbose rerun of the top cocotb runner passed its nine processor

tests plus the hello demo. The 31-ALU reduction tree completed in 19 cycles, below the <32 bound (earlier handoff reported 22).

  • bash scripts/run_tests.sh: C++ suites 15/15 and legacy assembly 8/8.
  • Compliance recipes now fail for failed tests, missing binaries,

conversion errors, or absent tohost symbols. Injected failing simulators and missing test names returned nonzero in all five ISA suites.

  • make regress now includes RV32 compliance and cpp-suite; previously

these were separate checks. Compliance was rerun after recipe changes.

  • git diff --check and documentation guardrails passed. No temporary

debug instrumentation was found in the Phase 2 diff. An untracked generated hypervisor ELF was moved from the submodule into ignored build/phase2-cleanup/; the vendored source revision is unchanged.

The host's default macOS 27 SDK failed to link with the installed linker. Commands used the installed macOS 26.5 SDK and local xPack toolchain:

export SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk
export PATH=/Users/tmarhguy/opt/xpack-riscv-none-elf-gcc-13.2.0-2/bin:$PATH
make compliance
make compliance-rv32
make regress
bash scripts/run_tests.sh

Detailed local output: build/phase2-compliance.log, build/phase2-compliance-rv32.log, build/phase2-regress.log, build/phase2-final-compliance.log, build/phase2-top.log, and build/phase2-cpp-legacy.log (ignored build artifacts).

Next phases and acceptance gates

  1. Phase 3 — branch prediction: replace the current slot-A bimodal

predictor with gshare, BTB, and RAS. Carry per-slot predicted direction and target through the pipeline; resolve the older slot first and invalidate younger work on a redirect. Check taken/not-taken recovery, target mismatches, slot-B branches, calls/returns, and redirect timing during memory stalls before measuring prediction improvement.

  1. Phase 4 — RVC: decode/expand 16-bit instructions, track actual

instruction lengths, and assemble mixed-length boundary straddlers. Cover c.j/c.jr targets and ma_fetch-style alignment behavior; adjust alignment traps for the implemented C extension.

  1. Phase 5 — A extension: implement LR/SC reservations and AMOs with

LSQ/bus atomicity. Add rv64ua compliance plus reservation invalidation, failed SC, and ordering coverage.

  1. Phase 6 — OoO: integrate rename/PRF, reservation-station issue,

ROB commit, and LSQ disambiguation with precise recovery and full two-wide retirement. Verify dependencies, speculative stores, traps, and flush recovery before claiming out-of-order execution.

Each phase requires lint, unit tests, C++ suites, cocotb, RV64 and RV32 compliance with no regressions. Extend compliance for each newly supported extension. These phases are planned work, not completed Phase 2 features.

10.4. 2026-10-02 — Phase 3: branch prediction

RTL simulation on Apple Silicon, Verilator 5.052; local date 2026-10-01, UTC date 2026-10-02. Both slots query a shared 256-entry gshare table, carry the fetch-time index for training, and use a tagged target cache for indirect jumps plus a 16-entry resolved return-address stack. Older control transfers win updates; simultaneous younger control transfers can miss training, without changing architectural execution. The RAS updates on resolved execution rather than speculative fetch.

Direction/target mismatches redirect; correctly predicted taken transfers still kill younger slot work and check target alignment. A predicted misaligned transfer initially bypassed the old redirect-based trap check; checking resolved taken targets restored ma_fetch compliance. Buffered prediction steering now drains outstanding fetch responses through IDLE.

make regress passed unit 58/58, cocotb runners 8/8, C++ 15/15, RV64UI 54/54, RV64UM 13/13, RV64MI 15/15, RV32UI 37/37, RV32UM 8/8. Verilator lint passed; Verible remains unavailable. Added predictor tests cover saved gshare indexes, BTB tags, RAS overflow/underflow and nested calls/returns. A subsequent top rerun passed all 10 processor tests and the hello demo, including slot-B loop exit and wrong-path suppression. The dual-issue tree remains 19 cycles (<32).

Also repaired literal escaped redirection/operators in the lint recipes, which could previously hide lint failures. Logs: build/phase3-regress.log, build/phase3-bp.log, build/phase3-recovery.log (ignored artifacts).

CI portability follow-up

The first post-Phase-3 CI run exposed tool compatibility issues hidden by local-only checks. Verilator rejects nonblocking reset-loop writes to the predictor tables, so table initialization now uses initial values while the history and RAS pointer retain reset behavior. Yosys 0.33 also rejects unpacked array ports, struct member selection on a function result, return statements, and an unbased literal in the register-file read function. The predictor and rename interfaces are now packed, prediction outputs use a packed function result, and helper functions use portable result assignments.

Separating ctrl.stall_if from the other control bundle assignments removed Verilator's serialize_pair combinational-loop warning. The Yosys structural synthesis smoke runs with -noabc; this avoids spending minutes mapping the combinational 64-bit multiplier while still checking RTL parsing, hierarchy, process lowering, memory handling, and technology mapping. RTL simulation regression remains the functional check.

Follow-up evidence: Verilator lint passed; Yosys 0.69 structural synthesis passed; branch-predictor cocotb passed; make regress passed unit 58/58, cocotb runners 8/8, C++ 15/15, RV64 82/82, and RV32 45/45. Verible was unavailable locally and skipped.

Verified GitHub CI repair

The earlier portability follow-up was verified locally, but did not fix the Ubuntu jobs. On 2026-10-01 local time, the remaining failures were resolved:

  • serialize_pair now reads an independent scalar decode-stall condition,

avoiding the older Verilator's packed-control dependency cycle.

  • Predictor and rename ports use flat vectors, with predictor tests updated

to access packed slots explicitly.

  • Failed synthesis prints the final 80 log lines. This exposed Yosys 0.33's

rejection of package imports at the first ALU source, before those ports. CI now pins OSS CAD Suite 2026-10-01 (Yosys 0.69+173).

  • Replaced an invalid setup-python revision with the verified v5 revision.

Cocotb 2 requires VPI methods absent in Ubuntu Verilator 5.020, so the simulation job also uses the pinned suite. Lint still exercises 5.020.

Local make regress passed: unit 58, cocotb runners 8, C++ 15, RV64UI 54, RV64UM 13, RV64MI 15, RV32UI 37, RV32UM 8; no failures. Local synthesis passed. GitHub synthesis run 36957282399 passed with the pinned suite; the old-Verilator lint job also passed. Verible remains unavailable and is explicitly skipped. Logs: build/ci-fix-regress.log and build/ci-fix-synth.log.

10.5. 2026-10-02 — Phase 4: RV64C expansion foundation

Implementation and verification: 2026-10-01 America/New_York (2026-10-02 UTC). Phase 4 is in progress; the processor does not yet execute RVC.

Added rtl/rv64xo3_rvc.sv, a combinational RV64C integer expander covering arithmetic, word operations, loads/stores, stack addressing, branches, J/JR/JALR and EBREAK. Reserved and unsupported floating-point encodings assert illegal and return zero. Integer hints retain harmless semantics. The input is a compressed halfword; ordinary 32-bit instructions must bypass this module in the future fetch integration.

Encoding reference: RISC-V C extension v2.0. The independent oracle contains 305 compressed/base instruction pairs assembled and linked with GNU binutils from xPack GCC 13.2.0-2. It covers register extremes, signed immediate boundaries, shifts through 63, RV64-specific LD/SD/ADDIW/ADDW/SUBW, and forward/backward control transfers. Regenerate tb/cocotb/rvc/vectors.json with its neighboring generate_vectors.py and riscv-none-elf-* in PATH (or set RISCV_PREFIX). Checked-in vectors let CI run without a cross toolchain. Additional tests reject reserved, FP and non-compressed inputs. The runner is part of make cocotb and the CI smoke selection; standalone lint checks the expander even though it is not yet instantiated by the processor.

make regress passed unit 58/58, cocotb runners 9/9 (including both new RVC tests), C++ 15/15, RV64UI 54/54, RV64UM 13/13, RV64MI 15/15, RV32UI 37/37 and RV32UM 8/8. Verilator lint passed; Verible unavailable. Log: build/phase4-regress.log.

Remaining Phase 4 integration:

  1. Assemble two mixed-length instructions at every halfword offset, including

32-bit instructions crossing 64-bit parcels; retain buffers across stalls and discard partial instructions on redirect.

  1. Carry original instruction, per-slot PC and length through decode/execute;

use length for sequential PC, prediction, recovery and JALR link values. In particular, expanding C.JALR must still write pc+2, not pc+4.

  1. Update target alignment and CSR reporting consistently before advertising

C in misa. Preserve original compressed bits for illegal-instruction mtval.

  1. Add mixed-length, c.j/c.jr/c.jalr, straddler and alignment-trap processor

tests and compressed compliance, then rerun every phase gate. Phase 5 atomic operations and Phase 6 OoO remain subsequent work.

About me

I’m Tyrone Marhguy, a Computer Engineering student at the University of Pennsylvania, class of 2028. This core is my 2-wide out-of-order RV64IMAC.

I grew up between Kumasi and Accra. In 2021, Achimota School denied me admission because I wear dreadlocks as an expression of my Rastafarian faith. Ghana’s High Court ordered the school to admit me; I finished secondary school there, then came to Penn on a full scholarship. BBC Pidgin and Deutsche Welle covered the case.

I design the architecture, build the boards, and write the software. Tomato is a 32-bit computer with a running FPGA implementation and discrete boards in progress. I also build systems software, including a search engine, a compiler, and a database, and I contribute fixes to open-source EDA tools such as LibreLane, OpenROAD, Verilator, and OpenFPGA. That work has included production software at Aragorn AI and battery-management hardware at Vero Electric.

Hardware

Software and systems

Open source

See open-source work for contributions to LibreLane, OpenROAD, Verilator, and OpenFPGA.