gem5
gem5 is a modular, event-driven computer architecture simulator combining the best features of M5 and GEMS. It models complete systems including CPUs (out-of-order, in-order, Atomic and Timing Simple CPUs — gem5 Wiki" href="cpu_doc/simple/index.html">simple), memory hierarchies (caches, DRAM, Ruby coherence), devices, and ISAs (x86, AArch32, AArch64, TrustZone security extensions, SVE/SVE2 vector processing, PMU, and hardware transactional memory." href="arch_doc/arm/index.html">ARM, RISC-V, MIPS, SPARC, Power) for microarchitectural research, teaching, and hardware/software co-design.
⚙ Event-Driven 🏭 Full-System + SE Mode 🛠 7 ISAs 📈 Research-Grade
📚 What is this & why does it exist?
gem5 is the de-facto standard open-source simulator for computer architecture research. It allows researchers and engineers to model and evaluate processor designs, memory systems, and interconnects without building physical hardware. gem5 supports both system-call emulation (SE) mode for running individual programs and full-system (FS) mode for booting entire operating systems.
💡 Real-world analogy
Think of gem5 like a high-fidelity flight simulator for chip architects. Just as pilots test maneuvers in a simulator before flying a real aircraft, chip designers use gem5 to test processor designs before spending millions on silicon fabrication. The simulator models every tick of the clock, every Cache Hierarchy | gem5 Wiki" href="mem_doc/cache/index.html">cache miss, and every branch misprediction with enough fidelity to predict real hardware performance.
System Architecture
flowchart TD
subgraph Simulation["Simulation Engine"]
SIM["sim/ - EventQueue, SimObject, System"]
BASE["base/ - Statistics, Utilities, Loaders"]
end
subgraph CPUModels["CPU Models"]
CPU["cpu/ - O3, Minor, Simple, KVM"]
PRED["cpu/pred - Branch Prediction"]
end
subgraph MemorySystem["Memory System"]
MEM["mem/ - Ports, Packets, Abstract Memory"]
CACHE["mem/cache - L1/L2/L3, Prefetch, Replacement"]
RUBY["mem/ruby - Coherence Protocols (MOESI, MESI)"]
end
subgraph ISA["ISA Definitions"]
ARCH["arch/ - x86, ARM, RISC-V, MIPS, SPARC, Power"]
end
subgraph Devices["Device Models"]
DEV["dev/ - PCI, Network, Storage, ARM GIC"]
GPU["gpu-compute/ - AMD GCN Compute Units"]
end
subgraph Infrastructure["Infrastructure"]
PY["python/ - Config, PyBind11, stdlib"]
KERN["kern/ - Linux, FreeBSD Kernel Support"]
SC["systemc/ - SystemC/TLM Bridge"]
end
SIM -->|"SimObject base"| CPU
SIM -->|"Event scheduling"| MEM
BASE -->|"Stats, Types"| SIM
CPU -->|"Memory ports"| MEM
CPU -->|"Decode, Exec"| ARCH
MEM --> CACHE
MEM --> RUBY
CACHE -->|"Coherence"| RUBY
DEV -->|"PIO/DMA ports"| MEM
GPU -->|"Memory tokens"| MEM
GPU -->|"GPU ISA"| ARCH
PY -->|"Configuration"| SIM
KERN -->|"Syscall emulation"| SIM
SC -->|"TLM bridge"| MEM
Core Simulation
cpu
Implements multiple CPU timing models: O3 (superscalar out-of-order), Minor (in-order pipelined), Simple (atomic/timing), KVM (hardware-accelerated), plus branch predictors, checker, and trace replay.
mem
Models the complete memory system: classic cache hierarchy with configurable replacement and prefetch policies, Ruby coherence protocols (MOESI/MESI), QoS policies, DRAM/NVM controllers, and the port-based interconnect fabric.
sim
The simulation core: event queue, SimObject hierarchy, System/Process/Workload management, clocked objects, serialization/checkpointing, power/thermal modeling, and probe-based instrumentation.
Architecture & ISA
arch
ISA-specific instruction decoding, register management, memory translation (TLB/MMU), interrupt handling, and page table walkers. Each ISA inherits from generic base classes, enabling ISA-independent CPU models.
dev
Simulates hardware peripherals: PCI bus and devices, Ethernet NICs and switches, IDE/disk storage, ARM GIC interrupt controllers, serial ports, VirtIO, UART, timers, and platform-specific devices.
Accelerators & Extensions
gpu-compute
Detailed GPU compute model targeting AMD GCN architecture: compute units with fetch/schedule/execute stages, wavefront management, vector/scalar register files, LDS memory, and HSA command processing.
systemc
Implements the IEEE 1666 SystemC standard and provides TLM (Transaction Level Modeling) bridges to connect SystemC models with gem5's port-based memory system for co-simulation.
Infrastructure & Utilities
base
Foundation utilities: statistics framework (Scalar/Vector/Distribution/Histogram), ELF/binary loaders, address range management, Bloom filters, trace/debug logging, VNC server, and generic data structures.
python
Python bindings via PyBind11, the SimObject configuration system (m5 module), and the gem5 standard library (stdlib) with pre-built board, processor, memory, and cache hierarchy configurations.
kern
Kernel-level support for full-system simulation: system call emulation tables, Linux/FreeBSD/Solaris-specific event handling, and OS-dependent data structure parsing.
Navigation Guide
| Level | What You'll Find | When to Use |
|---|---|---|
| 0 — Project Hub (this page) | Project overview, module map, architecture diagram | Getting started, finding the right module |
| 1 — Module Overview | Architecture diagrams, sub-module cards, narrated walkthroughs | Understanding a module's purpose and internal structure |
| 2 — Sub-Module Deep Dive | Class tables, algorithm deep-dives, config references, code examples | Implementing, debugging, or extending specific code |
How CPU & Memory Connect
The CPU and memory modules communicate through gem5's port-based interface. Every CPU core has instruction and data cache ports that connect to the cache hierarchy. On a cache miss, requests flow down through L1, L2, L3 caches to DRAM controllers or Ruby coherence network.
sequenceDiagram
participant CPU as CPU Core (O3/Minor)
participant ICACHE as L1-ICache
participant DCACHE as L1-DCache
participant L2 as L2 Cache
participant BUS as Memory Bus
participant DRAM as DRAM Controller
CPU->>ICACHE: Fetch request (PC)
ICACHE-->>CPU: Hit - return instruction
CPU->>DCACHE: Load/Store (vaddr)
Note over CPU,DCACHE: TLB translates vaddr to paddr
DCACHE->>DCACHE: Tag lookup
DCACHE-->>CPU: Hit - return data (1-3 cycles)
DCACHE->>L2: Miss - forward request
L2->>L2: Tag lookup
L2-->>DCACHE: Hit - fill line (10-20 cycles)
L2->>BUS: Miss - send to memory bus
BUS->>DRAM: DRAM read command
DRAM-->>BUS: Data response (50-200 cycles)
BUS-->>L2: Fill response
L2-->>DCACHE: Fill line
DCACHE-->>CPU: Data ready
Key insight: CPU models own the pipeline (fetch, decode, execute, commit). The memory module owns everything below the CPU's cache ports — caches, buses, DRAM controllers, and coherence. ThePortinterface inmem/port.hhis the boundary: CPU sendsPacketobjects throughRequestPort, memory responds throughResponsePort.
Directory Map
Project source tree
gem5/src/
├── arch/ ← ISA definitions (x86, ARM, RISC-V, MIPS, SPARC, Power, AMDGPU)
├── base/ ← Utility library (statistics, loaders, filters, trace)
├── cpu/ ← CPU models (O3, Minor, Simple, KVM, branch prediction)
├── dev/ ← Device models (PCI, NIC, storage, ARM GIC, VirtIO)
├── gpu-compute/ ← AMD GCN GPU compute unit model
├── kern/ ← OS kernel support (Linux, FreeBSD, Solaris)
├── mem/ ← Memory system (caches, Ruby coherence, QoS, DRAM)
├── python/ ← Python configuration system and stdlib
├── sim/ ← Simulation engine (EventQueue, SimObject, System)
├── systemc/ ← SystemC/TLM integration bridge
├── proto/ ← Protocol buffer definitions for traces
├── doc/ ← Internal documentation
└── SConscript ← Build system entry point
Build & Tech Stack
Languages
C++ (core simulation), Python (configuration & stdlib), Protocol Buffers (traces)
Build System
SCons (SConstruct + SConscript files), Kconfig for build options
Key Dependencies
PyBind11 (Python bindings), libelf (ELF loading), protobuf, zlib, HDF5 (statistics)
Simulation Modes
SE (syscall emulation) and FS (full-system) with optional KVM hardware acceleration