# gem5/gem5 architecture

> Architecture diagram of the GitHub repository gem5/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/gem5/gem5
- Repository: https://github.com/gem5/gem5

## Overview

gem5 is a modular computer-system simulator used to evaluate hardware designs and system software. The principal workflow is to configure a simulated system, instantiate its SimObjects, and execute simulation; Python configuration and the C++ configuration manager are visible, but the standard runtime entry point was not sampled, so that connection is shown as unverified. The graph also preserves processor, GPU, memory-coherence, power-model, and optional SystemC capabilities. Relationships are limited to README statements and source-index references or excerpts; unsampled subsystems are not treated as inspected.

Main entry points: [`ext/mcpat/logic.h`](https://github.com/gem5/gem5/blob/stable/ext/mcpat/logic.h) (McPAT logic models), [`ext/systemc/src/sysc/kernel/sc_object_manager.cpp`](https://github.com/gem5/gem5/blob/stable/ext/systemc/src/sysc/kernel/sc_object_manager.cpp) (SystemC object manager), [`ext/mcpat/cacti/basic_circuit.h`](https://github.com/gem5/gem5/blob/stable/ext/mcpat/cacti/basic_circuit.h) (CACTI circuit model), [`src/sim/cxx_manager.cc`](https://github.com/gem5/gem5/blob/stable/src/sim/cxx_manager.cc) (C++ config manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_configs["Example configurations"]
  node_m5params["Parameter types<br/>[__init__.py]"]
  node_simobject["SimObject definitions<br/>[SimObject.py]"]
  node_proxy["Parameter proxies<br/>[proxy.py]"]
end

subgraph group_simulation["Simulation core"]
  node_runtime["Simulation runtime<br/>[main.cc]"]
  node_cxxconfig["C++ config runner<br/>[main.cc]"]
  node_cxxmanager["C++ config manager<br/>[cxx_manager.cc]"]
  node_stats["Statistics storage<br/>[storage.cc]"]
end

subgraph group_compute["Compute models"]
  node_minor["Minor CPU pipeline<br/>[pipeline.cc]"]
  node_gpu_global["GPU global memory"]
  node_gpu_scalar["GPU scalar memory"]
end

subgraph group_memory["Memory and I/O"]
  node_sdma["GPU SDMA engine<br/>[sdma_engine.cc]"]
  node_copyengine["PCI copy engine<br/>[copy_engine.cc]"]
  node_backdoor["Memory backdoors"]
  node_ruby_controller["Ruby controller"]
  node_tbe["Ruby TBE storage<br/>[TBEStorage.cc]"]
end

subgraph group_extensions["Analysis and integration"]
  node_mcpat_io["McPAT I/O model<br/>[iocontrollers.cc]"]
  node_mcpat_logic["McPAT logic models<br/>[logic.h]"]
  node_cacti_circuit["CACTI circuit model<br/>[basic_circuit.h]"]
  node_cacti_interface["CACTI interface<br/>[cacti_interface.h]"]
  node_cacti_const["CACTI constants<br/>[const.h]"]
  node_cacti_parameter["CACTI parameters<br/>[parameter.h]"]
  node_mcpat_components["McPAT components<br/>[basic_components.h]"]
  node_xml_parser["McPAT XML parser<br/>[xmlParser.h]"]
  node_systemc_objects["SystemC object manager"]
  node_systemc_object["SystemC objects<br/>[sc_object.h]"]
  node_systemc_process["SystemC processes<br/>[sc_process.h]"]
  node_systemc_ids["SystemC kernel IDs<br/>[sc_kernel_ids.h]"]
  node_systemc_hash["SystemC hash utility<br/>[sc_hash.h]"]
  node_systemc_embed["SystemC embedding<br/>[main.cc]"]
end

node_user(("Simulator user"))

node_user -->|"selects setup"| node_configs
node_user -.->|"runs configuration"| node_cxxconfig
node_configs -.->|"configures simulation"| node_runtime
node_m5params -->|"supports proxies"| node_proxy
node_cxxconfig -->|"constructs objects"| node_cxxmanager
node_cxxmanager -->|"configures objects"| node_simobject
node_minor -.->|"records statistics"| node_stats
node_gpu_global -.->|"coordinates memory"| node_gpu_scalar
node_sdma -->|"issues memory writes"| node_backdoor
node_ruby_controller -.->|"uses transaction storage"| node_tbe
node_mcpat_io -->|"uses components"| node_mcpat_components
node_mcpat_io -->|"uses logic models"| node_mcpat_logic
node_mcpat_logic -->|"uses circuit model"| node_cacti_circuit
node_mcpat_logic -->|"uses interface"| node_cacti_interface
node_mcpat_logic -->|"uses constants"| node_cacti_const
node_mcpat_logic -->|"uses parameters"| node_cacti_parameter
node_mcpat_logic -->|"uses parser"| node_xml_parser
node_cacti_circuit -->|"references interface"| node_cacti_interface
node_cacti_circuit -->|"references constants"| node_cacti_const
node_systemc_objects -->|"manages objects"| node_systemc_object
node_systemc_objects -->|"uses kernel IDs"| node_systemc_ids
node_systemc_objects -->|"references processes"| node_systemc_process
node_systemc_objects -->|"uses hash table"| node_systemc_hash
node_systemc_embed -->|"configures simulation"| node_cxxmanager

click node_configs "https://github.com/gem5/gem5/tree/stable/configs"
click node_m5params "https://github.com/gem5/gem5/blob/stable/src/python/m5/params/__init__.py"
click node_simobject "https://github.com/gem5/gem5/blob/stable/src/python/m5/SimObject.py"
click node_proxy "https://github.com/gem5/gem5/blob/stable/src/python/m5/proxy.py"
click node_runtime "https://github.com/gem5/gem5/blob/stable/src/sim/main.cc"
click node_cxxconfig "https://github.com/gem5/gem5/blob/stable/util/cxx_config/main.cc"
click node_cxxmanager "https://github.com/gem5/gem5/blob/stable/src/sim/cxx_manager.cc"
click node_stats "https://github.com/gem5/gem5/blob/stable/src/base/stats/storage.cc"
click node_minor "https://github.com/gem5/gem5/blob/stable/src/cpu/minor/pipeline.cc"
click node_gpu_global "https://github.com/gem5/gem5/blob/stable/src/gpu-compute/global_memory_pipeline.cc"
click node_gpu_scalar "https://github.com/gem5/gem5/blob/stable/src/gpu-compute/scalar_memory_pipeline.cc"
click node_sdma "https://github.com/gem5/gem5/blob/stable/src/dev/amdgpu/sdma_engine.cc"
click node_copyengine "https://github.com/gem5/gem5/blob/stable/src/dev/pci/copy_engine.cc"
click node_backdoor "https://github.com/gem5/gem5/blob/stable/src/mem/backdoor_manager.cc"
click node_ruby_controller "https://github.com/gem5/gem5/blob/stable/src/mem/ruby/slicc_interface/AbstractController.cc"
click node_tbe "https://github.com/gem5/gem5/blob/stable/src/mem/ruby/structures/TBEStorage.cc"
click node_mcpat_io "https://github.com/gem5/gem5/blob/stable/ext/mcpat/iocontrollers.cc"
click node_mcpat_logic "https://github.com/gem5/gem5/blob/stable/ext/mcpat/logic.h"
click node_cacti_circuit "https://github.com/gem5/gem5/blob/stable/ext/mcpat/cacti/basic_circuit.h"
click node_cacti_interface "https://github.com/gem5/gem5/blob/stable/ext/mcpat/cacti/cacti_interface.h"
click node_cacti_const "https://github.com/gem5/gem5/blob/stable/ext/mcpat/cacti/const.h"
click node_cacti_parameter "https://github.com/gem5/gem5/blob/stable/ext/mcpat/cacti/parameter.h"
click node_mcpat_components "https://github.com/gem5/gem5/blob/stable/ext/mcpat/basic_components.h"
click node_xml_parser "https://github.com/gem5/gem5/blob/stable/ext/mcpat/xmlParser.h"
click node_systemc_objects "https://github.com/gem5/gem5/blob/stable/ext/systemc/src/sysc/kernel/sc_object_manager.cpp"
click node_systemc_object "https://github.com/gem5/gem5/blob/stable/ext/systemc/src/sysc/kernel/sc_object.h"
click node_systemc_process "https://github.com/gem5/gem5/blob/stable/ext/systemc/src/sysc/kernel/sc_process.h"
click node_systemc_ids "https://github.com/gem5/gem5/blob/stable/ext/systemc/src/sysc/kernel/sc_kernel_ids.h"
click node_systemc_hash "https://github.com/gem5/gem5/blob/stable/ext/systemc/src/sysc/utils/sc_hash.h"
click node_systemc_embed "https://github.com/gem5/gem5/blob/stable/util/systemc/gem5_within_systemc/main.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_configs,node_m5params,node_simobject,node_proxy,node_user toneBlue
class node_runtime,node_cxxconfig,node_cxxmanager,node_stats toneAmber
class node_minor,node_gpu_global,node_gpu_scalar toneMint
class node_sdma,node_copyengine,node_backdoor,node_ruby_controller,node_tbe toneRose
class node_mcpat_io,node_mcpat_logic,node_cacti_circuit,node_cacti_interface,node_cacti_const,node_cacti_parameter,node_mcpat_components,node_xml_parser,node_systemc_objects,node_systemc_object,node_systemc_process,node_systemc_ids,node_systemc_hash,node_systemc_embed toneIndigo
```

## Components

### Configuration

- [Example configurations](https://github.com/gem5/gem5/tree/stable/configs): `configs`
- [Parameter types](https://github.com/gem5/gem5/blob/stable/src/python/m5/params/__init__.py): `src/python/m5/params/__init__.py`
- [SimObject definitions](https://github.com/gem5/gem5/blob/stable/src/python/m5/SimObject.py): `src/python/m5/SimObject.py`
- [Parameter proxies](https://github.com/gem5/gem5/blob/stable/src/python/m5/proxy.py): `src/python/m5/proxy.py`

### Simulation core

- [Simulation runtime](https://github.com/gem5/gem5/blob/stable/src/sim/main.cc): `src/sim/main.cc`
- [C++ config runner](https://github.com/gem5/gem5/blob/stable/util/cxx_config/main.cc): `util/cxx_config/main.cc`
- [C++ config manager](https://github.com/gem5/gem5/blob/stable/src/sim/cxx_manager.cc): `src/sim/cxx_manager.cc`
- [Statistics storage](https://github.com/gem5/gem5/blob/stable/src/base/stats/storage.cc): `src/base/stats/storage.cc`

### Compute models

- [Minor CPU pipeline](https://github.com/gem5/gem5/blob/stable/src/cpu/minor/pipeline.cc): `src/cpu/minor/pipeline.cc`
- [GPU global memory](https://github.com/gem5/gem5/blob/stable/src/gpu-compute/global_memory_pipeline.cc): `src/gpu-compute/global_memory_pipeline.cc`
- [GPU scalar memory](https://github.com/gem5/gem5/blob/stable/src/gpu-compute/scalar_memory_pipeline.cc): `src/gpu-compute/scalar_memory_pipeline.cc`

### Memory and I/O

- [GPU SDMA engine](https://github.com/gem5/gem5/blob/stable/src/dev/amdgpu/sdma_engine.cc): `src/dev/amdgpu/sdma_engine.cc`
- [PCI copy engine](https://github.com/gem5/gem5/blob/stable/src/dev/pci/copy_engine.cc): `src/dev/pci/copy_engine.cc`
- [Memory backdoors](https://github.com/gem5/gem5/blob/stable/src/mem/backdoor_manager.cc): `src/mem/backdoor_manager.cc`
- [Ruby controller](https://github.com/gem5/gem5/blob/stable/src/mem/ruby/slicc_interface/AbstractController.cc): `src/mem/ruby/slicc_interface/AbstractController.cc`
- [Ruby TBE storage](https://github.com/gem5/gem5/blob/stable/src/mem/ruby/structures/TBEStorage.cc): `src/mem/ruby/structures/TBEStorage.cc`

### Analysis and integration

- [McPAT I/O model](https://github.com/gem5/gem5/blob/stable/ext/mcpat/iocontrollers.cc): `ext/mcpat/iocontrollers.cc`
- [McPAT logic models](https://github.com/gem5/gem5/blob/stable/ext/mcpat/logic.h): `ext/mcpat/logic.h`
- [CACTI circuit model](https://github.com/gem5/gem5/blob/stable/ext/mcpat/cacti/basic_circuit.h): `ext/mcpat/cacti/basic_circuit.h`
- [CACTI interface](https://github.com/gem5/gem5/blob/stable/ext/mcpat/cacti/cacti_interface.h): `ext/mcpat/cacti/cacti_interface.h`
- [CACTI constants](https://github.com/gem5/gem5/blob/stable/ext/mcpat/cacti/const.h): `ext/mcpat/cacti/const.h`
- [CACTI parameters](https://github.com/gem5/gem5/blob/stable/ext/mcpat/cacti/parameter.h): `ext/mcpat/cacti/parameter.h`
- [McPAT components](https://github.com/gem5/gem5/blob/stable/ext/mcpat/basic_components.h): `ext/mcpat/basic_components.h`
- [McPAT XML parser](https://github.com/gem5/gem5/blob/stable/ext/mcpat/xmlParser.h): `ext/mcpat/xmlParser.h`
- [SystemC object manager](https://github.com/gem5/gem5/blob/stable/ext/systemc/src/sysc/kernel/sc_object_manager.cpp): `ext/systemc/src/sysc/kernel/sc_object_manager.cpp`
- [SystemC objects](https://github.com/gem5/gem5/blob/stable/ext/systemc/src/sysc/kernel/sc_object.h): `ext/systemc/src/sysc/kernel/sc_object.h`
- [SystemC processes](https://github.com/gem5/gem5/blob/stable/ext/systemc/src/sysc/kernel/sc_process.h): `ext/systemc/src/sysc/kernel/sc_process.h`
- [SystemC kernel IDs](https://github.com/gem5/gem5/blob/stable/ext/systemc/src/sysc/kernel/sc_kernel_ids.h): `ext/systemc/src/sysc/kernel/sc_kernel_ids.h`
- [SystemC hash utility](https://github.com/gem5/gem5/blob/stable/ext/systemc/src/sysc/utils/sc_hash.h): `ext/systemc/src/sysc/utils/sc_hash.h`
- [SystemC embedding](https://github.com/gem5/gem5/blob/stable/util/systemc/gem5_within_systemc/main.cc): `util/systemc/gem5_within_systemc/main.cc`

### Other components

- **Simulator user**

## Connections

- Simulator user → Example configurations: selects setup (evidence: `README.md`)
- Simulator user → C++ config runner: runs configuration
- Example configurations → Simulation runtime: configures simulation
- Parameter types → Parameter proxies: supports proxies (evidence: `src/python/m5/proxy.py`)
- C++ config runner → C++ config manager: constructs objects (evidence: `util/cxx_config/main.cc`)
- C++ config manager → SimObject definitions: configures objects (evidence: `src/sim/cxx_manager.cc`)
- Minor CPU pipeline → Statistics storage: records statistics
- GPU global memory → GPU scalar memory: coordinates memory
- GPU SDMA engine → Memory backdoors: issues memory writes (evidence: `src/dev/amdgpu/sdma_engine.cc`)
- Ruby controller → Ruby TBE storage: uses transaction storage
- McPAT I/O model → McPAT components: uses components
- McPAT I/O model → McPAT logic models: uses logic models (evidence: `ext/mcpat/iocontrollers.cc`)
- McPAT logic models → CACTI circuit model: uses circuit model (evidence: `ext/mcpat/logic.h`)
- McPAT logic models → CACTI interface: uses interface (evidence: `ext/mcpat/logic.h`)
- McPAT logic models → CACTI constants: uses constants (evidence: `ext/mcpat/logic.h`)
- McPAT logic models → CACTI parameters: uses parameters (evidence: `ext/mcpat/logic.h`)
- McPAT logic models → McPAT XML parser: uses parser (evidence: `ext/mcpat/logic.h`)
- CACTI circuit model → CACTI interface: references interface (evidence: `ext/mcpat/cacti/basic_circuit.h`)
- CACTI circuit model → CACTI constants: references constants (evidence: `ext/mcpat/cacti/basic_circuit.h`)
- SystemC object manager → SystemC objects: manages objects (evidence: `ext/systemc/src/sysc/kernel/sc_object_manager.cpp`)
- SystemC object manager → SystemC kernel IDs: uses kernel IDs (evidence: `ext/systemc/src/sysc/kernel/sc_object_manager.cpp`)
- SystemC object manager → SystemC processes: references processes (evidence: `ext/systemc/src/sysc/kernel/sc_object_manager.cpp`)
- SystemC object manager → SystemC hash utility: uses hash table (evidence: `ext/systemc/src/sysc/kernel/sc_object_manager.cpp`)
- SystemC embedding → C++ config manager: configures simulation (evidence: `util/systemc/gem5_within_systemc/main.cc`)
