# ultraembedded/biriscv architecture

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

- Interactive diagram: https://gitdiagram.com/ultraembedded/biriscv
- Repository: https://github.com/ultraembedded/biriscv

## Overview

#### Purpose and integration surface
biRISC-V is synthesizable Verilog-2001 RTL for a configurable RV32IMZicsr dual-issue, in-order CPU. It supports user/supervisor/machine privilege, basic MMU operation, branch prediction, cache-backed AXI memory, or tightly coupled memory (TCM) integration. Primary system entry points are `src/top/riscv_top.v` (AXI/cache-oriented wrapper) and `src/top/riscv_tcm_top.v` (TCM-oriented wrapper).

#### Core composition
`src/core/riscv_core.v` composes the CPU datapath and exposes instruction/data memory-side interfaces. Shared architectural definitions and configurability live in `src/core/biriscv_defs.v`. The design is parameterized for dual issue, privilege/MMU, multiply/divide, bypass paths, decode depth, predictor resources, and cacheable address range.

#### Frontend, prediction, and fetch
`src/core/biriscv_frontend.v` manages PC-facing frontend behavior; `src/core/biriscv_fetch.v` performs 64-bit instruction fetch and instruction stream handling; `src/core/biriscv_npc.v` calculates next-PC behavior. This boundary consumes instruction memory responses and produces fetched instructions plus predicted control flow. Branch-target/history/return prediction is implemented within the frontend path and is configurable through core parameters.

#### Decode, dependency control, and issue
`src/core/biriscv_decoder.v` and `src/core/biriscv_decode.v` translate fetched RV32 instructions into execution controls and operand requirements. `src/core/biriscv_issue.v` selects up to two independent instructions per cycle for the in-order pipeline. `src/core/biriscv_pipe_ctrl.v` coordinates stalls, flushes, hazards, forwarding, and redirect recovery, forming the central control boundary between speculative frontend state and committed execution progress.

#### Execution and architectural state
`src/core/biriscv_exec.v` drives execution lanes, with arithmetic and branch operations in `src/core/biriscv_alu.v`; multiply and out-of-pipeline divide use `src/core/biriscv_multiplier.v` and `src/core/biriscv_divider.v`. Integer register state is held by `src/core/biriscv_regfile.v` (with FPGA-oriented alternative `src/core/biriscv_xilinx_2r1w.v`). CSR and privilege state are handled by `src/core/biriscv_csr.v` and `src/core/biriscv_csr_regfile.v`.

#### Load/store, translation, and memory boundary
`src/core/biriscv_lsu.v` serializes the single load/store execution resource and interfaces data accesses to the memory subsystem. `src/core/biriscv_mmu.v` provides the basic translation/privilege-aware memory path needed for Linux-capable configurations. The memory boundary distinguishes cacheable ranges from direct or tightly coupled accesses according to core/top-level parameters.

#### Cache and TCM subsystem options
The instruction cache is rooted at `src/icache/icache.v`, with separate tag/data RAM modules. The data-cache hierarchy begins at `src/dcache/dcache.v`; `src/dcache/dcache_axi.v` bridges cached data traffic toward AXI, while `src/dcache/dcache_mux.v` routes cache and non-cache paths. TCM deployments use `src/tcm/tcm_mem.v` and `src/tcm/dport_axi.v`, providing local memory and AXI-facing access routing.

#### Verification runtimes
A lightweight Icarus RTL bench enters through `tb/tb_core_icarus/tb_top.v`. Full-system wrapper simulations are supported by C++/SystemC-style harnesses around `src/top/riscv_top.v` and `src/top/riscv_tcm_top.v`, respectively under `tb/tb_top/` and `tb/tb_tcm/`; these load ELF images and model AXI or memory behavior. The project also cites RISCV-DV random instruction generation and external ExactStep ISA-model cosimulation as verification infrastructure.

Main entry points: [`src/core/biriscv_exec.v`](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_exec.v) (Execution lanes), [`src/core/biriscv_frontend.v`](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_frontend.v) (Frontend & prediction), [`src/core/riscv_core.v`](https://github.com/ultraembedded/biriscv/blob/master/src/core/riscv_core.v) (CPU datapath), [`src/top/riscv_top.v`](https://github.com/ultraembedded/biriscv/blob/master/src/top/riscv_top.v) (AXI/cache top)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["CPU core"]
  node_core_defs["Core definitions<br/>parameters<br/>[biriscv_defs.v]"]
  node_core["CPU datapath<br/>core integration<br/>[riscv_core.v]"]
  node_frontend["Frontend &amp; prediction<br/>[biriscv_frontend.v]"]
  node_fetch["Instruction fetch<br/>[biriscv_fetch.v]"]
  node_npc["Next-PC<br/>control<br/>[biriscv_npc.v]"]
  node_decode["Decode<br/>[biriscv_decode.v]"]
  node_issue["Dual issue<br/>[biriscv_issue.v]"]
  node_pipe_ctrl{{"Pipeline control<br/>hazard control"}}
  node_exec["Execution lanes<br/>execute<br/>[biriscv_exec.v]"]
  node_alu["ALU &amp; branches<br/>execution unit<br/>[biriscv_alu.v]"]
  node_muldiv["Multiply/divide<br/>execution units"]
  node_regfile[("Integer registers<br/>architectural state<br/>[biriscv_regfile.v]")]
  node_csr[("CSR &amp; privilege<br/>architectural state<br/>[biriscv_csr.v]")]
  node_lsu["Load/store unit<br/>memory execution<br/>[biriscv_lsu.v]"]
  node_mmu["MMU<br/>translation<br/>[biriscv_mmu.v]"]
end

subgraph group_memory["Memory integrations"]
  node_axi_top["AXI/cache top<br/>top wrapper<br/>[riscv_top.v]"]
  node_tcm_top["TCM top<br/>top wrapper<br/>[riscv_tcm_top.v]"]
  node_icache[("Instruction cache<br/>[icache.v]")]
  node_dcache[("Data cache hierarchy<br/>cache and AXI bridge<br/>[dcache.v]")]
  node_tcm[("TCM memory<br/>local memory<br/>[tcm_mem.v]")]
end

subgraph group_verification["Verification"]
  node_icarus_tb["Icarus RTL bench<br/>RTL testbench<br/>[tb_top.v]"]
  node_full_system["Full-system harnesses<br/>C++/SystemC simulation"]
end

node_axi_top -->|"instantiates"| node_core
node_tcm_top -->|"instantiates"| node_core
node_core_defs -.->|"configures"| node_core
node_core -->|"instruction path"| node_frontend
node_frontend -->|"fetch control"| node_fetch
node_frontend -->|"next-PC prediction"| node_npc
node_fetch -->|"fetched instructions"| node_decode
node_decode -->|"decoded operations"| node_issue
node_issue -->|"up to two issued ops"| node_exec
node_pipe_ctrl -->|"flush and redirect"| node_frontend
node_pipe_ctrl -->|"stall and hazard control"| node_issue
node_exec -->|"arithmetic and branches"| node_alu
node_exec -->|"M-extension operations"| node_muldiv
node_exec -->|"reads and writes"| node_regfile
node_exec -->|"CSR operations"| node_csr
node_exec -->|"load/store operations"| node_lsu
node_lsu -->|"translated data accesses"| node_mmu
node_frontend -->|"instruction memory requests"| node_icache
node_mmu -->|"cache/direct data path"| node_dcache
node_axi_top -->|"cache integration"| node_icache
node_axi_top -->|"AXI data integration"| node_dcache
node_tcm_top -->|"local memory integration"| node_tcm
node_icarus_tb -.->|"simulates"| node_core
node_full_system -.->|"simulates"| node_axi_top
node_full_system -.->|"simulates"| node_tcm_top

click node_axi_top "https://github.com/ultraembedded/biriscv/blob/master/src/top/riscv_top.v"
click node_tcm_top "https://github.com/ultraembedded/biriscv/blob/master/src/top/riscv_tcm_top.v"
click node_core_defs "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_defs.v"
click node_core "https://github.com/ultraembedded/biriscv/blob/master/src/core/riscv_core.v"
click node_frontend "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_frontend.v"
click node_fetch "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_fetch.v"
click node_npc "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_npc.v"
click node_decode "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_decode.v"
click node_issue "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_issue.v"
click node_pipe_ctrl "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_pipe_ctrl.v"
click node_exec "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_exec.v"
click node_alu "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_alu.v"
click node_muldiv "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_multiplier.v"
click node_regfile "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_regfile.v"
click node_csr "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_csr.v"
click node_lsu "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_lsu.v"
click node_mmu "https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_mmu.v"
click node_icache "https://github.com/ultraembedded/biriscv/blob/master/src/icache/icache.v"
click node_dcache "https://github.com/ultraembedded/biriscv/blob/master/src/dcache/dcache.v"
click node_tcm "https://github.com/ultraembedded/biriscv/blob/master/src/tcm/tcm_mem.v"
click node_icarus_tb "https://github.com/ultraembedded/biriscv/blob/master/tb/tb_core_icarus/tb_top.v"

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_core_defs,node_core,node_frontend,node_fetch,node_npc,node_decode,node_issue,node_pipe_ctrl,node_exec,node_alu,node_muldiv,node_regfile,node_csr,node_lsu,node_mmu toneBlue
class node_axi_top,node_tcm_top,node_icache,node_dcache,node_tcm toneAmber
class node_icarus_tb,node_full_system toneMint
```

## Components

### CPU core

Dual-issue in-order RV32IMZicsr pipeline.

- [Core definitions](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_defs.v): parameters · Architecture features and memory-range configuration. · `src/core/biriscv_defs.v`
- [CPU datapath](https://github.com/ultraembedded/biriscv/blob/master/src/core/riscv_core.v): core integration · Exposes instruction and data memory-side interfaces. · `src/core/riscv_core.v`
- [Frontend & prediction](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_frontend.v): frontend · PC control, prediction, and instruction-stream handling. · `src/core/biriscv_frontend.v`
- [Instruction fetch](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_fetch.v): fetch · Fetches and assembles 64-bit instruction data. · `src/core/biriscv_fetch.v`
- [Next-PC](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_npc.v): control · `src/core/biriscv_npc.v`
- [Decode](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_decode.v): decode · Instruction decoding and operand requirements. · `src/core/biriscv_decode.v`
- [Dual issue](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_issue.v): issue · Selects up to two independent instructions per cycle. · `src/core/biriscv_issue.v`
- [Pipeline control](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_pipe_ctrl.v): hazard control · Stalls, flushes, forwarding, hazards, and redirects. · `src/core/biriscv_pipe_ctrl.v`
- [Execution lanes](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_exec.v): execute · `src/core/biriscv_exec.v`
- [ALU & branches](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_alu.v): execution unit · `src/core/biriscv_alu.v`
- [Multiply/divide](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_multiplier.v): execution units · Multiply is pipelined; divide operates out of pipeline. · `src/core/biriscv_multiplier.v`
- [Integer registers](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_regfile.v): architectural state · `src/core/biriscv_regfile.v`
- [CSR & privilege](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_csr.v): architectural state · `src/core/biriscv_csr.v`
- [Load/store unit](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_lsu.v): memory execution · Serializes the single load/store resource. · `src/core/biriscv_lsu.v`
- [MMU](https://github.com/ultraembedded/biriscv/blob/master/src/core/biriscv_mmu.v): translation · Privilege-aware translation for Linux-capable configurations. · `src/core/biriscv_mmu.v`

### Memory integrations

Selectable cache/AXI or TCM memory systems.

- [AXI/cache top](https://github.com/ultraembedded/biriscv/blob/master/src/top/riscv_top.v): top wrapper · `src/top/riscv_top.v`
- [TCM top](https://github.com/ultraembedded/biriscv/blob/master/src/top/riscv_tcm_top.v): top wrapper · `src/top/riscv_tcm_top.v`
- [Instruction cache](https://github.com/ultraembedded/biriscv/blob/master/src/icache/icache.v): cache · `src/icache/icache.v`
- [Data cache hierarchy](https://github.com/ultraembedded/biriscv/blob/master/src/dcache/dcache.v): cache and AXI bridge · Caches data and routes cacheable versus direct traffic. · `src/dcache/dcache.v`
- [TCM memory](https://github.com/ultraembedded/biriscv/blob/master/src/tcm/tcm_mem.v): local memory · Local tightly coupled memory with AXI-facing routing. · `src/tcm/tcm_mem.v`

### Verification

RTL and full-system simulation entry points.

- [Icarus RTL bench](https://github.com/ultraembedded/biriscv/blob/master/tb/tb_core_icarus/tb_top.v): RTL testbench · `tb/tb_core_icarus/tb_top.v`
- **Full-system harnesses**: C++/SystemC simulation · Loads ELF images and models AXI or memory behavior.

## Connections

- AXI/cache top → CPU datapath: instantiates
- TCM top → CPU datapath: instantiates
- Core definitions → CPU datapath: configures
- CPU datapath → Frontend & prediction: instruction path
- Frontend & prediction → Instruction fetch: fetch control
- Frontend & prediction → Next-PC: next-PC prediction
- Instruction fetch → Decode: fetched instructions
- Decode → Dual issue: decoded operations
- Dual issue → Execution lanes: up to two issued ops
- Pipeline control → Frontend & prediction: flush and redirect
- Pipeline control → Dual issue: stall and hazard control
- Execution lanes → ALU & branches: arithmetic and branches
- Execution lanes → Multiply/divide: M-extension operations
- Execution lanes → Integer registers: reads and writes
- Execution lanes → CSR & privilege: CSR operations
- Execution lanes → Load/store unit: load/store operations
- Load/store unit → MMU: translated data accesses
- Frontend & prediction → Instruction cache: instruction memory requests
- MMU → Data cache hierarchy: cache/direct data path
- AXI/cache top → Instruction cache: cache integration
- AXI/cache top → Data cache hierarchy: AXI data integration
- TCM top → TCM memory: local memory integration
- Icarus RTL bench → CPU datapath: simulates
- Full-system harnesses → AXI/cache top: simulates
- Full-system harnesses → TCM top: simulates
