# openxiangshan/gem5 architecture

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

- Interactive diagram: https://gitdiagram.com/openxiangshan/gem5
- Repository: https://github.com/openxiangshan/gem5

## Overview

XS-GEM5 is a gem5-based full-system RISC-V simulator calibrated to XiangShan RTL. The principal workflow is to configure a system and workload, run the simulator, and inspect execution results and statistics; checkpoint restore and online Difftest extend that workflow. The README documents major CPU, cache, translation, and checkpoint capabilities, but most XiangShan implementation files were not included in the excerpts. Dashed, uncited edges indicate relationships that are plausible but not verified by the supplied source.

Main entry points: [`src/cpu`](https://github.com/openxiangshan/gem5/tree/xs-dev/src/cpu) (Distributed backend), [`src/sim/main.cc`](https://github.com/openxiangshan/gem5/blob/xs-dev/src/sim/main.cc) (Simulation runtime), [`configs/common/xiangshan.py`](https://github.com/openxiangshan/gem5/blob/xs-dev/configs/common/xiangshan.py) (System configuration), [`src/mem`](https://github.com/openxiangshan/gem5/tree/xs-dev/src/mem) (Cache hierarchy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Run configuration"]
  node_workload["FS workload"]
  node_configs["System configuration<br/>[xiangshan.py]"]
  node_variants["Kunminghu profiles<br/>[kmhv3.py]"]
end

subgraph group_cpu["XiangShan CPU"]
  node_cpu_front["Decoupled frontend"]
  node_predictors["Branch predictors"]
  node_cpu_backend["Distributed backend"]
  node_rvv["Vector execution"]
end

subgraph group_memory["Memory system"]
  node_cache["Cache hierarchy"]
  node_prefetch["Prefetchers"]
  node_translation["TLB and PTW"]
end

subgraph group_runtime["Simulation runtime"]
  node_runtime["Simulation runtime<br/>[main.cc]"]
  node_checkpoint["RVGCpt checkpoints"]
end

subgraph group_analysis["Results and validation"]
  node_difftest["Online Difftest"]
  node_stats["Topdown counters<br/>[storage.cc]"]
  node_results["Simulation results"]
end

node_user(("Simulator user"))

node_user -->|"configures"| node_configs
node_user -->|"provides"| node_workload
node_variants -.->|"profiles"| node_configs
node_configs -.->|"configures"| node_runtime
node_workload -->|"runs image"| node_runtime
node_runtime -.->|"simulates"| node_cpu_front
node_cpu_front -.->|"uses"| node_predictors
node_cpu_front -.->|"dispatches"| node_cpu_backend
node_cpu_backend -.->|"executes vectors"| node_rvv
node_cpu_backend -.->|"accesses"| node_cache
node_cache -.->|"coordinates"| node_prefetch
node_cpu_backend -.->|"translates"| node_translation
node_runtime -.->|"restores"| node_checkpoint
node_cpu_backend -.->|"checks execution"| node_difftest
node_runtime -.->|"records"| node_stats
node_stats -.->|"reports"| node_results
node_difftest -.->|"validates"| node_results

click node_configs "https://github.com/openxiangshan/gem5/blob/xs-dev/configs/common/xiangshan.py"
click node_variants "https://github.com/openxiangshan/gem5/blob/xs-dev/configs/example/kmhv3.py"
click node_runtime "https://github.com/openxiangshan/gem5/blob/xs-dev/src/sim/main.cc"
click node_cpu_front "https://github.com/openxiangshan/gem5/tree/xs-dev/src/cpu"
click node_predictors "https://github.com/openxiangshan/gem5/tree/xs-dev/src/cpu"
click node_cpu_backend "https://github.com/openxiangshan/gem5/tree/xs-dev/src/cpu"
click node_rvv "https://github.com/openxiangshan/gem5/tree/xs-dev/src/cpu"
click node_cache "https://github.com/openxiangshan/gem5/tree/xs-dev/src/mem"
click node_prefetch "https://github.com/openxiangshan/gem5/tree/xs-dev/src/mem"
click node_translation "https://github.com/openxiangshan/gem5/tree/xs-dev/src/arch/riscv"
click node_checkpoint "https://github.com/openxiangshan/gem5/tree/xs-dev/src/sim"
click node_difftest "https://github.com/openxiangshan/gem5/tree/xs-dev/src/cpu"
click node_stats "https://github.com/openxiangshan/gem5/blob/xs-dev/src/base/stats/storage.cc"

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_workload,node_configs,node_variants,node_user toneBlue
class node_cpu_front,node_predictors,node_cpu_backend,node_rvv toneAmber
class node_cache,node_prefetch,node_translation toneMint
class node_runtime,node_checkpoint toneRose
class node_difftest,node_stats,node_results toneIndigo
```

## Components

### Run configuration

- **FS workload**
- [System configuration](https://github.com/openxiangshan/gem5/blob/xs-dev/configs/common/xiangshan.py): `configs/common/xiangshan.py`
- [Kunminghu profiles](https://github.com/openxiangshan/gem5/blob/xs-dev/configs/example/kmhv3.py): `configs/example/kmhv3.py`

### XiangShan CPU

- [Decoupled frontend](https://github.com/openxiangshan/gem5/tree/xs-dev/src/cpu): `src/cpu`
- [Branch predictors](https://github.com/openxiangshan/gem5/tree/xs-dev/src/cpu): `src/cpu`
- [Distributed backend](https://github.com/openxiangshan/gem5/tree/xs-dev/src/cpu): `src/cpu`
- [Vector execution](https://github.com/openxiangshan/gem5/tree/xs-dev/src/cpu): `src/cpu`

### Memory system

- [Cache hierarchy](https://github.com/openxiangshan/gem5/tree/xs-dev/src/mem): `src/mem`
- [Prefetchers](https://github.com/openxiangshan/gem5/tree/xs-dev/src/mem): `src/mem`
- [TLB and PTW](https://github.com/openxiangshan/gem5/tree/xs-dev/src/arch/riscv): `src/arch/riscv`

### Simulation runtime

- [Simulation runtime](https://github.com/openxiangshan/gem5/blob/xs-dev/src/sim/main.cc): `src/sim/main.cc`
- [RVGCpt checkpoints](https://github.com/openxiangshan/gem5/tree/xs-dev/src/sim): `src/sim`

### Results and validation

- [Online Difftest](https://github.com/openxiangshan/gem5/tree/xs-dev/src/cpu): `src/cpu`
- [Topdown counters](https://github.com/openxiangshan/gem5/blob/xs-dev/src/base/stats/storage.cc): `src/base/stats/storage.cc`
- **Simulation results**

### Other components

- **Simulator user**

## Connections

- Simulator user → System configuration: configures (evidence: `README.md`)
- Simulator user → FS workload: provides (evidence: `README.md`)
- Kunminghu profiles → System configuration: profiles
- System configuration → Simulation runtime: configures
- FS workload → Simulation runtime: runs image (evidence: `README.md`)
- Simulation runtime → Decoupled frontend: simulates
- Decoupled frontend → Branch predictors: uses
- Decoupled frontend → Distributed backend: dispatches
- Distributed backend → Vector execution: executes vectors
- Distributed backend → Cache hierarchy: accesses
- Cache hierarchy → Prefetchers: coordinates
- Distributed backend → TLB and PTW: translates
- Simulation runtime → RVGCpt checkpoints: restores
- Distributed backend → Online Difftest: checks execution
- Simulation runtime → Topdown counters: records
- Topdown counters → Simulation results: reports
- Online Difftest → Simulation results: validates
