How lowrisc/ibex works
1. What this repo is
- This is the Ibex RISC-V CPU core repository: a production-oriented, highly parameterized 32-bit SystemVerilog core.
- The main architectural boundary is the core itself versus everything around it: simulation examples, verification environments, formal proof collateral, synthesis flow, and utility scripts.
2. Top-level design organization
- The primary RTL lives in rtl/ and is the heart of the project.
- Configuration and composition are controlled through ibex_configs.yaml and multiple .core files, which select optional features and package dependencies.
- ibex_top.sv is the main integration wrapper for the core, while ibex_core.sv is the internal pipeline composition.
3. Core pipeline and instruction flow
- The CPU is organized around fetch, decode/issue, execute, and writeback stages.
- Key RTL blocks are split by function: ibex_if_stage.sv, ibex_id_stage.sv, ibex_ex_block.sv, and ibex_wb_stage.sv.
- Instruction flow starts in fetch, passes through decode and execute, and may optionally pass through an extra writeback stage in higher-performance configurations.
4. Instruction supply and control path
- ibex_prefetch_buffer.sv, ibex_fetch_fifo.sv, and ibex_icache.sv handle instruction delivery and buffering.
- ibex_branch_predict.sv and ibex_controller.sv manage control-flow decisions, stalls, flushes, and pipeline control.
- ibex_compressed_decoder.sv sits on the front end to expand RVC instructions before execution.
5. Execution and arithmetic subsystems
- ibex_alu.sv handles integer ALU operations.
- Multiply/divide is split into ibex_multdiv_fast.sv and ibex_multdiv_slow.sv, reflecting configuration-dependent implementation choices.
- ibex_dummy_instr.sv and ibex_counter.sv support architectural behavior and optional security/performance features.
6. Memory and load/store path
- ibex_load_store_unit.sv is the main data-memory interface.
- It connects the core’s pipeline to the external bus/memory system, and it is a major architectural boundary because memory latency, exceptions, and alignment behavior all converge here.
- Shared infrastructure in shared/rtl/ provides reusable bus and RAM models used by examples and test environments.
7. Privileged architecture, CSR, PMP, and exceptions
- ibex_csr.sv and ibex_cs_registers.sv implement control/status registers and privileged state.
- ibex_pmp.sv adds physical memory protection, which is an important security boundary.
- Exception and interrupt behavior is centralized in the controller/CSR path and is documented under doc/03_reference/exception_interrupts.rst and doc/03_reference/pmp.rst.
8. Optional observability and safety features
- ibex_lockstep.sv supports lockstep checking against a companion model.
- ibex_tracer.sv and ibex_tracer_pkg.sv implement architectural tracing.
- ibex_top_tracing.sv is a top-level variant that includes tracing support.
- These features are optional but materially affect how the core is integrated and verified.
9. Register file choices and implementation variants
- The core includes multiple register file implementations: flop-based, FPGA-oriented, and latch-based (ibex_register_file_ff.sv, ibex_register_file_fpga.sv, ibex_register_file_latch.sv).
- This is one of the main area/performance tradeoff boundaries in the design.
- The synthesis flow in syn/ and the config file set determine which implementation is used for a given target.
10. Verification architecture
- The dv/ tree is a large, separate verification subsystem with multiple styles of checking:
- dv/cosim/ for C++/DPI co-simulation,
- dv/cs_registers/ for CSR/register behavior,
- dv/riscv_compliance/ for ISA compliance,
- dv/uvm/ for UVM-based constrained-random and directed testbenches,
- dv/formal/ for formal proof harnesses.
- The verification stack uses SystemVerilog, C++, Python, DPI, and tool-specific wrappers, with Spike appearing as the golden reference model in co-simulation.
11. Formal verification and spec coupling
- formal/ and dv/formal/ hold formal collateral, including proof strategies, generated/spec-linked models, and property checkers.
- The formal environment is tightly coupled to architectural specifications such as instruction behavior, memory rules, and data-independent timing checks.
- This subsystem exists as a separate verification boundary from simulation and is used to prove specific correctness and security properties.
12. Example integration and software bring-up
- examples/simple_system/ is a minimal integration of Ibex into a runnable system for simulation.
- examples/sw/ contains bare-metal software for that environment, including hello-world, PMP smoke tests, dummy instruction tests, and CoreMark benchmarking.
- This area shows the expected external interface of the core: clock/reset, instruction/data memory, and simple system peripherals.
13. Synthesis and implementation flow
- syn/ contains the synthesis flow, timing scripts, and RTL translation helpers.
- The repo supports Yosys-based and technology-specific flows, with scripts for mapping, timing report translation, and setup.
- This is architecturally important because some RTL choices are driven by synthesis targets rather than only by functional behavior.
14. Utilities, packaging, and repo-wide tooling
- util/ contains Python helpers for configuration handling, tool checks, and SV2V-related processing.
- Makefile, .core files, and environment scripts in ci/, nix/, and check_tool_requirements.core support reproducible builds and toolchain validation.
- In an architecture diagram, these belong outside the CPU datapath but are essential for how the repo is built, verified, and integrated.
Main entry points: ibex_core.sv Core pipeline · ibex_ex_block.sv Execute block · ibex_top.sv Top integration · ibex_csr.sv CSR path
Components 25
Core RTL
Ibex CPU pipeline, control, memory, privilege, and integration RTL.
- Top integration · Top-level core integration and optional tracing wrapper.
rtl/ibex_top.sv - Core pipeline · Internal pipeline composition and feature selection.
rtl/ibex_core.sv - Fetch stage · Instruction fetch, buffering, and prefetch control.
rtl/ibex_if_stage.sv - Decode stage · Decode, compressed-instruction expand, and instruction dispatch.
rtl/ibex_id_stage.sv - Execute block · ALU, mult/div, and execute-side control.
rtl/ibex_ex_block.sv - Writeback stage · Optional final pipeline stage for higher-performance configurations.
rtl/ibex_wb_stage.sv - Controller · Stalls, flushes, exceptions, and pipeline coordination.
rtl/ibex_controller.sv - Load/store unit · Data-memory access, alignment, exceptions, and bus boundary.
rtl/ibex_load_store_unit.sv - CSR path · Control/status registers and privileged architectural state.
rtl/ibex_csr.sv - PMP · Physical memory protection and access control boundary.
rtl/ibex_pmp.sv - Register file · Flop, FPGA, and latch-based register file implementations.
rtl/ibex_register_file_ff.sv - I-cache · Optional instruction cache for front-end acceleration.
rtl/ibex_icache.sv - Tracing · Architectural tracing package and trace emitter.
rtl/ibex_tracer.sv - Lockstep · Optional comparison against a companion model.
rtl/ibex_lockstep.sv
Verification
Simulation, co-simulation, UVM, compliance, and formal collateral.
- UVM bench · Main UVM verification environment and test infrastructure.
dv/uvm/core_ibex - Co-sim · Spike-backed co-simulation and RVFI/instruction monitoring.
dv/cosim - Formal proofs · Property checking, spec coupling, and proof strategies.
dv/formal - Compliance · RISC-V compliance wrapper and test utilities.
dv/riscv_compliance - I-cache FPV · Standalone formal collateral for instruction-cache behavior.
formal/icache - Timing checks · Data-independent timing proofs for multiply/divide behavior.
formal/data_ind_timing
Examples
Runnable integration example and bare-metal software bring-up.
- Simple system · Minimal runnable system integration for simulation and bring-up.
examples/simple_system - Bare-metal SW · Hello-world, PMP, dummy instruction, DIT, and benchmark software.
examples/sw
Implementation
Synthesis, shared RTL infrastructure, and repo-wide tooling.
- Synthesis flow · Yosys and target-specific synthesis, mapping, and timing scripts.
syn - Shared RTL · Reusable bus, RAM, timer, and simulator-control components.
shared/rtl - Tooling · Configuration, tool checks, and SV2V/helper scripts.
util
Connections 33
- Top integration → Core pipeline: instantiates · Top wrapper instantiates the core composition.
- Top integration → Tracing: optional tracing · Tracing-enabled top variant wires in observability.
- Core pipeline → Fetch stage: front end · Core composition starts with instruction fetch.
- Core pipeline → Decode stage: decode · Core composition includes decode and dispatch.
- Core pipeline → Execute block: execute · Core composition includes the execute block.
- Core pipeline → Writeback stage: writeback · Optional writeback stage in higher-performance configurations.
- Fetch stage → I-cache: instruction supply · Fetch can be backed by the instruction cache.
- Fetch stage → Controller: stalls/flushes · Front-end control is coordinated by the controller.
- Decode stage → Controller: control · Decode feeds exceptions, hazards, and pipeline control.
- Decode stage → Register file: register access · Decode reads the architectural register file.
- Decode stage → Execute block: operands · Decoded instructions flow into execute.
- Execute block → Load/store unit: memory ops · Execute issues load/store requests to the LSU.
- Execute block → Controller: exceptions · Execute-side faults return to central control.
- Load/store unit → PMP: protection · Data memory accesses are checked against PMP rules.
- CSR path → Controller: privileged events · CSR state participates in traps, interrupts, and exceptions.
- CSR path → PMP: configures · CSR path configures PMP state.
- Execute block → CSR path: system ops · System instructions and status updates route through CSR logic.
- Lockstep → Core pipeline: compares · Lockstep monitor checks architectural progress against a companion.
- UVM bench → Top integration: drives RTL · UVM environment instantiates and exercises the core top.
- UVM bench → Co-sim: co-sim support · Verification environment uses Spike-backed checking infrastructure.
- UVM bench → CSR path: CSR tests · Dedicated checks target CSR and register behavior.
- Co-sim → Top integration: RVFI/instruction trace · Co-simulation observes architectural outputs from the core.
- Formal proofs → Core pipeline: proves · Formal harness targets core-level correctness properties.
- Formal proofs → CSR path: spec coupling · Formal collateral covers privileged and architectural state.
- I-cache FPV → I-cache: verifies · Standalone proof collateral focuses on the I-cache.
- Timing checks → Execute block: timing properties · Formal timing checks target execute-side arithmetic units.
- Compliance → Top integration: compliance DUT · ISA compliance wrapper instantiates the core integration.
- Simple system → Top integration: integrates · Simple system wraps the top-level core into a runnable platform.
- Simple system → Shared RTL: platform support · Example system reuses shared bus, RAM, and timer RTL.
- Bare-metal SW → Simple system: runs on · Bare-metal software targets the simple system platform.
- Synthesis flow → Core pipeline: maps RTL · Synthesis flow consumes the core RTL and variants.
- Synthesis flow → Shared RTL: uses primitives · Implementation flow reuses shared/synth helper RTL.
- Tooling → Synthesis flow: supports · Utility scripts assist configuration, tool checks, and translation.