# lowrisc/ibex architecture

> Architecture diagram of the GitHub repository lowrisc/ibex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lowrisc/ibex
- Repository: https://github.com/lowrisc/ibex

## Overview

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: [`rtl/ibex_core.sv`](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_core.sv) (Core pipeline), [`rtl/ibex_ex_block.sv`](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_ex_block.sv) (Execute block), [`rtl/ibex_top.sv`](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_top.sv) (Top integration), [`rtl/ibex_csr.sv`](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_csr.sv) (CSR path)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_core["Core RTL"]
  node_n_top["Top integration<br/>RTL wrapper<br/>[ibex_top.sv]"]
  node_n_core["Core pipeline<br/>CPU core<br/>[ibex_core.sv]"]
  node_n_if["Fetch stage<br/>front-end<br/>[ibex_if_stage.sv]"]
  node_n_id["Decode stage<br/>decode/issue<br/>[ibex_id_stage.sv]"]
  node_n_ex["Execute block<br/>[ibex_ex_block.sv]"]
  node_n_wb["Writeback stage<br/>pipeline stage<br/>[ibex_wb_stage.sv]"]
  node_n_ctrl["Controller<br/>control path<br/>[ibex_controller.sv]"]
  node_n_lsu["Load/store unit<br/>memory interface"]
  node_n_csr["CSR path<br/>privileged state<br/>[ibex_csr.sv]"]
  node_n_pmp["PMP<br/>security guard<br/>[ibex_pmp.sv]"]
  node_n_rf[("Register file<br/>storage variants")]
  node_n_icache["I-cache<br/>instruction cache<br/>[ibex_icache.sv]"]
  node_n_tracer["Tracing<br/>observability<br/>[ibex_tracer.sv]"]
  node_n_lockstep(("Lockstep<br/>safety check<br/>[ibex_lockstep.sv]"))
end

subgraph group_grp_verif["Verification"]
  node_n_verif["UVM bench<br/>simulation env"]
  node_n_cosim["Co-sim<br/>golden-model check"]
  node_n_formal["Formal proofs<br/>formal harness"]
  node_n_compliance["Compliance<br/>ISA tests"]
  node_n_icache_fpv["I-cache FPV<br/>formal cache proof"]
  node_n_dataind["Timing checks<br/>formal security"]
end

subgraph group_grp_bringup["Examples"]
  node_n_example["Simple system<br/>integration example"]
  node_n_sw["Bare-metal SW<br/>test programs"]
end

subgraph group_grp_impl["Implementation"]
  node_n_syn["Synthesis flow<br/>implementation flow"]
  node_n_shared["Shared RTL<br/>support RTL"]
  node_n_util["Tooling"]
end

node_n_top -->|"instantiates"| node_n_core
node_n_top -.->|"optional tracing"| node_n_tracer
node_n_core -->|"front end"| node_n_if
node_n_core -->|"decode"| node_n_id
node_n_core -->|"execute"| node_n_ex
node_n_core -.->|"writeback"| node_n_wb
node_n_if -->|"instruction supply"| node_n_icache
node_n_if -->|"stalls/flushes"| node_n_ctrl
node_n_id -->|"control"| node_n_ctrl
node_n_id -->|"register access"| node_n_rf
node_n_id -->|"operands"| node_n_ex
node_n_ex -->|"memory ops"| node_n_lsu
node_n_ex -->|"exceptions"| node_n_ctrl
node_n_lsu -->|"protection"| node_n_pmp
node_n_csr -->|"privileged events"| node_n_ctrl
node_n_csr -->|"configures"| node_n_pmp
node_n_ex -->|"system ops"| node_n_csr
node_n_lockstep -.->|"compares"| node_n_core
node_n_verif -->|"drives RTL"| node_n_top
node_n_verif -->|"co-sim support"| node_n_cosim
node_n_verif -->|"CSR tests"| node_n_csr
node_n_cosim -->|"RVFI/instruction trace"| node_n_top
node_n_formal -->|"proves"| node_n_core
node_n_formal -->|"spec coupling"| node_n_csr
node_n_icache_fpv -->|"verifies"| node_n_icache
node_n_dataind -->|"timing properties"| node_n_ex
node_n_compliance -->|"compliance DUT"| node_n_top
node_n_example -->|"integrates"| node_n_top
node_n_example -->|"platform support"| node_n_shared
node_n_sw -->|"runs on"| node_n_example
node_n_syn -->|"maps RTL"| node_n_core
node_n_syn -->|"uses primitives"| node_n_shared
node_n_util -->|"supports"| node_n_syn

click node_n_top "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_top.sv"
click node_n_core "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_core.sv"
click node_n_if "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_if_stage.sv"
click node_n_id "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_id_stage.sv"
click node_n_ex "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_ex_block.sv"
click node_n_wb "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_wb_stage.sv"
click node_n_ctrl "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_controller.sv"
click node_n_lsu "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_load_store_unit.sv"
click node_n_csr "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_csr.sv"
click node_n_pmp "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_pmp.sv"
click node_n_rf "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_register_file_ff.sv"
click node_n_icache "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_icache.sv"
click node_n_tracer "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_tracer.sv"
click node_n_lockstep "https://github.com/lowrisc/ibex/blob/master/rtl/ibex_lockstep.sv"
click node_n_verif "https://github.com/lowrisc/ibex/tree/master/dv/uvm/core_ibex"
click node_n_cosim "https://github.com/lowrisc/ibex/tree/master/dv/cosim"
click node_n_formal "https://github.com/lowrisc/ibex/tree/master/dv/formal"
click node_n_compliance "https://github.com/lowrisc/ibex/tree/master/dv/riscv_compliance"
click node_n_icache_fpv "https://github.com/lowrisc/ibex/tree/master/formal/icache"
click node_n_dataind "https://github.com/lowrisc/ibex/tree/master/formal/data_ind_timing"
click node_n_example "https://github.com/lowrisc/ibex/tree/master/examples/simple_system"
click node_n_sw "https://github.com/lowrisc/ibex/tree/master/examples/sw"
click node_n_syn "https://github.com/lowrisc/ibex/tree/master/syn"
click node_n_shared "https://github.com/lowrisc/ibex/tree/master/shared/rtl"
click node_n_util "https://github.com/lowrisc/ibex/tree/master/util"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_top,node_n_core,node_n_if,node_n_id,node_n_ex,node_n_wb,node_n_ctrl,node_n_lsu,node_n_csr,node_n_pmp,node_n_rf,node_n_icache,node_n_tracer,node_n_lockstep toneBlue
class node_n_verif,node_n_cosim,node_n_formal,node_n_compliance,node_n_icache_fpv,node_n_dataind toneAmber
class node_n_example,node_n_sw toneMint
class node_n_syn,node_n_shared,node_n_util toneRose
```

## Components

### Core RTL

Ibex CPU pipeline, control, memory, privilege, and integration RTL.

- [Top integration](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_top.sv): RTL wrapper · Top-level core integration and optional tracing wrapper. · `rtl/ibex_top.sv`
- [Core pipeline](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_core.sv): CPU core · Internal pipeline composition and feature selection. · `rtl/ibex_core.sv`
- [Fetch stage](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_if_stage.sv): front-end · Instruction fetch, buffering, and prefetch control. · `rtl/ibex_if_stage.sv`
- [Decode stage](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_id_stage.sv): decode/issue · Decode, compressed-instruction expand, and instruction dispatch. · `rtl/ibex_id_stage.sv`
- [Execute block](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_ex_block.sv): execute · ALU, mult/div, and execute-side control. · `rtl/ibex_ex_block.sv`
- [Writeback stage](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_wb_stage.sv): pipeline stage · Optional final pipeline stage for higher-performance configurations. · `rtl/ibex_wb_stage.sv`
- [Controller](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_controller.sv): control path · Stalls, flushes, exceptions, and pipeline coordination. · `rtl/ibex_controller.sv`
- [Load/store unit](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_load_store_unit.sv): memory interface · Data-memory access, alignment, exceptions, and bus boundary. · `rtl/ibex_load_store_unit.sv`
- [CSR path](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_csr.sv): privileged state · Control/status registers and privileged architectural state. · `rtl/ibex_csr.sv`
- [PMP](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_pmp.sv): security guard · Physical memory protection and access control boundary. · `rtl/ibex_pmp.sv`
- [Register file](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_register_file_ff.sv): storage variants · Flop, FPGA, and latch-based register file implementations. · `rtl/ibex_register_file_ff.sv`
- [I-cache](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_icache.sv): instruction cache · Optional instruction cache for front-end acceleration. · `rtl/ibex_icache.sv`
- [Tracing](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_tracer.sv): observability · Architectural tracing package and trace emitter. · `rtl/ibex_tracer.sv`
- [Lockstep](https://github.com/lowrisc/ibex/blob/master/rtl/ibex_lockstep.sv): safety check · Optional comparison against a companion model. · `rtl/ibex_lockstep.sv`

### Verification

Simulation, co-simulation, UVM, compliance, and formal collateral.

- [UVM bench](https://github.com/lowrisc/ibex/tree/master/dv/uvm/core_ibex): simulation env · Main UVM verification environment and test infrastructure. · `dv/uvm/core_ibex`
- [Co-sim](https://github.com/lowrisc/ibex/tree/master/dv/cosim): golden-model check · Spike-backed co-simulation and RVFI/instruction monitoring. · `dv/cosim`
- [Formal proofs](https://github.com/lowrisc/ibex/tree/master/dv/formal): formal harness · Property checking, spec coupling, and proof strategies. · `dv/formal`
- [Compliance](https://github.com/lowrisc/ibex/tree/master/dv/riscv_compliance): ISA tests · RISC-V compliance wrapper and test utilities. · `dv/riscv_compliance`
- [I-cache FPV](https://github.com/lowrisc/ibex/tree/master/formal/icache): formal cache proof · Standalone formal collateral for instruction-cache behavior. · `formal/icache`
- [Timing checks](https://github.com/lowrisc/ibex/tree/master/formal/data_ind_timing): formal security · Data-independent timing proofs for multiply/divide behavior. · `formal/data_ind_timing`

### Examples

Runnable integration example and bare-metal software bring-up.

- [Simple system](https://github.com/lowrisc/ibex/tree/master/examples/simple_system): integration example · Minimal runnable system integration for simulation and bring-up. · `examples/simple_system`
- [Bare-metal SW](https://github.com/lowrisc/ibex/tree/master/examples/sw): test programs · Hello-world, PMP, dummy instruction, DIT, and benchmark software. · `examples/sw`

### Implementation

Synthesis, shared RTL infrastructure, and repo-wide tooling.

- [Synthesis flow](https://github.com/lowrisc/ibex/tree/master/syn): implementation flow · Yosys and target-specific synthesis, mapping, and timing scripts. · `syn`
- [Shared RTL](https://github.com/lowrisc/ibex/tree/master/shared/rtl): support RTL · Reusable bus, RAM, timer, and simulator-control components. · `shared/rtl`
- [Tooling](https://github.com/lowrisc/ibex/tree/master/util): repo tooling · Configuration, tool checks, and SV2V/helper scripts. · `util`

## Connections

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