librelane playground

No. 27 / project of 147 on the ladder

RV32I machine-mode traps and CSRs

introduces — Machine-mode CSR file, trap entry, and mret return path

harden statelast run2026-05-01
signoff
  • DRCPASS
  • LVSPASS
  • antennaPASS
artifacts

P27 is the first system-core rung after the ACT4 base-integer milestone. It keeps the P17 external-memory shell shape but teaches the core how to enter machine-mode traps, expose basic machine CSRs, and return with mret.

Status: Hardened logic-only shell. Directed CSR/trap tests pass, the scoped ACT4/Sail rv32i/I set passes on P27, and official privileged tests are still NOT RUN.

The Result

Run it:

make -C projects/27_rv32i_machine_traps/test

Result: PASS

testresult
CSR read/write and immediate setPASS
ecall trap and mret resumePASS
illegal-instruction trap and mret resumePASS
ebreak trap and mret resumePASS
misaligned load trapPASS
misaligned store trapPASS

ACT4/Sail rv32i/I: PASS=39 FAIL=0 NOT RUN=0

Harden status: PASS

Hardened Shell

Run it:

scripts/run_librelane.sh projects/27_rv32i_machine_traps
checkresult
Run directoryprojects/27_rv32i_machine_traps/librelane/runs/RUN_2026-05-01_08-07-22
Final GDSprojects/27_rv32i_machine_traps/librelane/runs/RUN_2026-05-01_08-07-22/final/gds/top.gds
Metricsprojects/27_rv32i_machine_traps/librelane/runs/RUN_2026-05-01_08-07-22/final/metrics.json
Standard cells22710
Standard-cell area150303
Route DRCPASS (0)
Magic DRCPASS (0)
KLayout DRCPASS (0)
LVSPASS (0)
AntennaPASS (0)
Setup timingPASS
Hold timingPASS
Max slew checkerPARTIAL (4132 warnings)
Max capacitance checkerPARTIAL (52 warnings)

The final run has clean RTL lint and passes DRC/LVS/antenna. The slew and capacitance warnings are still real backend cleanup work.

What Changed

The core now supports these SYSTEM instructions:

CSRRW, CSRRS, CSRRC, CSRRWI, CSRRSI, CSRRCI, ECALL, EBREAK, and MRET.

Implemented CSRs:

CSRbehavior
mstatuswritable storage, no real privilege-stack side effects yet
misaread-only RV32I marker
mtvecwritable direct-mode trap base
mepcsaved trap PC
mcausesaved trap cause
mtvalsaved trap value
marchid, mimpid, mhartidsimple read-only IDs

Trap entry writes mepc, mcause, and mtval, then jumps to {mtvec[31:2], 2'b00}. mret jumps back to mepc.

What This Proves

P26 proved a strong base-integer instruction milestone through ACT4/Sail. P27 reruns that same scoped rv32i/I directory on the modified core and keeps the result at PASS=39 FAIL=0 NOT RUN=0.

P27 also proves a different thing: the core can now hand control to software when something exceptional happens.

That means a handler can:

  1. read mcause;
  2. read mepc and mtval;
  3. advance mepc past the trapped instruction;
  4. return with mret.

That path works for ecall, ebreak, illegal instruction, misaligned load, and misaligned store in directed RTL simulation.

Scope

Still unsupported: supervisor mode, interrupts, timer CSRs, delegation CSRs, satp, an MMU, vectored mtvec, precise mstatus privilege-stack behavior, and official privileged architecture tests.

So the honest label is narrow: PASS for directed machine-mode CSR/trap RTL tests, PASS for scoped ACT4/Sail rv32i/I, PASS for hardening signoff checks, and NOT RUN for official privileged compliance.