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
| Path | Purpose |
|---|---|
|
SystemVerilog source (synthesizable). Executable authority. |
|
Unit, cocotb, compliance, and formal testbenches |
|
This manual (source) plus ISA contract and history |
|
CRT, linker scripts, bare-metal examples |
|
Yosys synthesis and OpenLane feasibility flow |
|
Documentation guardrails, ISA generators |
|
Build and reporting scripts, including |
|
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-testsISA suites run against the RTL model. -
FPGA prototype means a future
hw/fpgamapping; 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:
-
rtl/SystemVerilog (the executable authority). -
Known Limitations and the facts stated in this introduction.
-
Machine-readable contracts (
docs/isa/rv64xo3.csv,tools/generators). -
Other prose in this manual.
-
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.
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.
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
| Parameter | Value | Notes |
|---|---|---|
|
64 |
RV64 datapath |
|
2 |
Superscalar width |
|
64 |
In-order retire buffer |
|
96 |
Physical registers (32 arch {rightarrow} 96 phys) |
|
8 / 4 / 4 |
Reservation stations |
|
16 |
Load-store queue |
|
|
Core default ( |
2.3. Branch prediction
-
Bimodal predictor: 256-entry branch history table of 2-bit saturating counters, indexed by PC bits, initialized weakly not taken.
-
JALis 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, andebreakretire at the ROB head only, giving precise M-mode traps (mepc/mcause/mtvalset, redirect tomtvec).
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_stallasserts 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.
| 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.
| Interface | Protocol | Notes |
|---|---|---|
IMEM master |
AXI4-Lite |
Instruction fetch, |
DMEM master |
AXI4-Lite |
LSQ spill/fill, store drain at commit |
UART bridge |
AXI4-Lite via |
Bring-up and |
4.2. Clocks, reset, and memory map
| Item | Value |
|---|---|
Clocking |
Single clock domain |
Reset |
Synchronous; core PC loads |
Privilege |
M-mode trap handling; supervisor CSR shadows and |
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.svandrtl/uart_axi.svcover the UART path. -
The
hello.cend-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).
| Extension | Status | Notes |
|---|---|---|
RV64I (incl. W-suffixed word ops) |
present |
|
M (incl. W ops) |
present |
|
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
| CSR | Address | Purpose |
|---|---|---|
|
|
Machine status |
|
|
ISA identity |
|
|
Interrupt enable / pending |
|
|
Trap vector |
|
|
Machine scratch |
|
|
Trap state |
|
|
Counters |
|
|
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
| 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
| Layer | Tools | Scope |
|---|---|---|
Unit (pytest) |
|
ALU, decoder, CSR, MulDiv, memory in isolation |
Integration (cocotb) |
|
Pipeline interaction, hazards, bus models |
Compliance |
|
Official |
Formal / SVA |
|
14 assert properties: x0, PC/mutual-exclusion, handshake liveness ( |
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 (includesma_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.pyrather 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
| Command | Effect |
|---|---|
|
Verible + Verilator lint |
|
Build the Verilator simulator binary |
|
Unit / integration tests |
|
RV64 compliance (RV32 kept as |
|
Full regression: lint + all test layers |
|
Yosys synthesis smoke |
|
OpenLane feasibility (needs PDK image) |
|
Build this manual into |
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 ( |
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.Sstartup,sw/link64.ldlink script,sw/uart.hdriver. -
Examples:
sw/hello.c(UART end-to-end),sw/test_misalign.c. -
32-bit
crt0.S/link.ldretained 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.
| Metric | Value |
|---|---|
Cycles per run |
1174 |
DMIPS/MHz |
0.48 |
IPC |
TBD (counter issue in the measured run) |
The score follows the standard definition:
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
| 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 (
pmpaddrunimplemented). -
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 simcanonical simulator target;run_tests.shdeduplicated.- 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 regressnow includes RV32 compliance andcpp-suite; previously
these were separate checks. Compliance was rerun after recipe changes.
git diff --checkand 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
- 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.
- 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.
- 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.
- 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_pairnow 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:
- 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.
- 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.
- Update target alignment and CSR reporting consistently before advertising
C in misa. Preserve original compressed bits for illegal-instruction mtval.
- 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
-
Tomato, a 32-bit computer (repository)
-
Pineapple GPU, a programmable 3D GPU on a Nexys A7
-
riscv64xO3, a 2-wide out-of-order RV64IMAC
-
MAC, a BFloat16 multiply-accumulate for SkyWater 130 nm
-
UDP/IP stack, a 100 Mbps datapath on a Nexys A7
-
ITCH parser, NASDAQ ITCH 5.0 on a Nexys A7
-
6T SRAM, a full-custom SRAM study
Software and systems
Open source
See open-source work for contributions to LibreLane, OpenROAD, Verilator, and OpenFPGA.