python

Architecture Overview

The Python module is divided into two major packages: the low-level m5 infrastructure that provides PyBind11 bindings to C++ simulator objects, and the high-level gem5 standard library that offers composable board/processor/memory abstractions. Together they enable full system configuration from Python scripts.

flowchart TD
    User["User Config Script"]
    Sim["gem5.simulate.Simulator"]
    Board["gem5.components.boards"]
    Proc["gem5.components.processors"]
    Mem["gem5.components.memory"]
    Cache["gem5.components.cachehierarchies"]
    Res["gem5.resources"]
    M5["m5.SimObject"]
    Params["m5.params"]
    Simulate["m5.simulate"]
    Bind["_m5 (PyBind11 C++)"]
    CPP["C++ Simulator Core"]

    User --> Sim
    Sim --> Board
    Board --> Proc
    Board --> Mem
    Board --> Cache
    Sim --> Res
    Board --> M5
    M5 --> Params
    M5 --> Simulate
    Simulate --> Bind
    Bind --> CPP

The architecture follows a layered design: user scripts interact with Simulator, which orchestrates AbstractBoard subclasses. Boards compose processors, caches, and memory modules. At the bottom, m5.SimObject and its metaclass system create C++ objects via the _m5 PyBind11 bridge.

m5 Package — Core Bindings

The m5 package provides the foundational infrastructure that bridges Python configuration to C++ simulation objects. Key submodules:

MetaSimObject Metaclass

The MetaSimObject metaclass intercepts class creation for every SimObject subclass. It collects parameter declarations, builds parameter descriptors, resolves inheritance, and registers the class in the global SimObject type registry. This allows the declarative Python style to automatically generate C++ parameter structs.

gem5 Standard Library

The modern gem5 standard library provides a component-based API for building simulation systems without deep knowledge of m5 internals.

Key Classes

Deep Dive: SimObject System

Parameter Lifecycle

sequenceDiagram
    participant U as User Script
    participant Meta as MetaSimObject
    participant SO as SimObject
    participant Inst as m5.simulate
    participant CPP as C++ Object

    U->>Meta: class MyObj(SimObject): type='MyObj' ...
    Meta->>Meta: Collect params, build descriptors
    U->>SO: obj = MyObj(param1=val)
    SO->>SO: Store params in _values dict
    U->>Inst: instantiate(root)
    Inst->>SO: adoptOrphanParams()
    Inst->>SO: unproxyParams() (resolve Self/Parent)
    Inst->>CPP: _create_cpp_objects()
    Inst->>CPP: connectPorts()
    Inst->>CPP: init() / startup()

The instantiation sequence resolves all proxy parameters (Self.attr, Parent.attr), creates the C++ objects in dependency order, connects ports, and calls init() and startup() on each object. The configuration can be dumped in INI, JSON, or DOT format for debugging.

Parameter Types

Deep Dive: Component Model

flowchart TD
    AB["AbstractBoard"]
    AP["AbstractProcessor"]
    AM["AbstractMemorySystem"]
    AC["AbstractCacheHierarchy"]

    AB -->|"has-a"| AP
    AB -->|"has-a"| AM
    AB -->|"has-a"| AC

    AP --> SP["SimpleProcessor"]
    AP --> SWP["SwitchableProcessor"]
    AM --> SC["SingleChannelDDR4"]
    AM --> DC["DualChannelDDR4"]
    AC --> CL["ClassicCacheHierarchy"]
    AC --> RB["RubyCacheHierarchy"]

    AB --> SB["SimpleBoard"]
    AB --> X86["X86Board"]
    AB --> ARM["ArmBoard"]

The component model follows an abstract factory pattern. Each board implements _pre_instantiate() to wire components and get_memory_ranges() to define the address map. The connect_things() method links processor ports to cache hierarchy ports and cache to memory controller ports.

Simulation Flow

flowchart LR
    A["Create Board"] --> B["Set Workload"]
    B --> C["Create Simulator"]
    C --> D["simulator.run()"]
    D --> E["instantiate()"]
    E --> F["simulate()"]
    F --> G{Exit Event?}
    G -->|"handler"| H["On-exit handler"]
    H --> F
    G -->|"done"| I["Stats dump & cleanup"]

Runtime Operations

The simulation engine supports runtime control operations through the m5.simulate module:

• switchCpus() — hot-swap CPU models (e.g., atomic → O3) during simulation
• drain() — drain all SimObjects for safe state transitions
• memWriteback() — flush dirty cache lines to memory
• checkpoint() — write simulation state for later restoration
• scheduleTickExitFromCurrent() — schedule simulation exit at specific tick

Cross-Module Interactions

Directory Map

Configuration Patterns

Code Examples

Simple SE-mode Simulation

from gem5.components.boards.simple_board import SimpleBoard
from gem5.components.processors.simple_processor import SimpleProcessor
from gem5.components.memory.single_channel import SingleChannelDDR4_2400
from gem5.components.cachehierarchies.classic.private_l1_shared_l2 import (
    PrivateL1SharedL2CacheHierarchy,
)
from gem5.isas import ISA
from gem5.resources.resource import obtain_resource
from gem5.simulate.simulator import Simulator

# Build system components
processor = SimpleProcessor(cpu_type="timing", isa=ISA.X86, num_cores=1)
cache = PrivateL1SharedL2CacheHierarchy(l1d_size="32kB", l1i_size="32kB",
                                          l2_size="256kB")
memory = SingleChannelDDR4_2400(size="2GiB")

# Assemble board
board = SimpleBoard(processor=processor, cache_hierarchy=cache,
                     memory=memory, clk_freq="3GHz")
board.set_se_binary_workload(obtain_resource("x86-hello64-static"))

# Run simulation
sim = Simulator(board=board)
sim.run()

Custom SimObject Declaration

from m5.SimObject import SimObject
from m5.params import Param, VectorParam

class MyAccelerator(SimObject):
    """Custom accelerator SimObject with configurable parameters."""
    type = 'MyAccelerator'
    cxx_header = 'my_module/accelerator.hh'
    cxx_class = 'gem5::MyAccelerator'

    num_engines = Param.Int(4, "Number of compute engines")
    queue_depth = Param.Int(16, "Command queue depth")
    clock_freq = Param.Clock('1GHz', "Operating frequency")
    mem_ports = VectorRequestPort("Memory-side ports")

CPU Switching at Runtime

from gem5.components.processors.switchable_processor import SwitchableProcessor

processor = SwitchableProcessor(
    starting_core_type="atomic",
    switch_core_type="o3",
    isa=ISA.ARM,
    num_cores=4,
)

# In exit event handler:
def switch_handler():
    processor.switch()  # Drains and swaps CPU models
    yield False         # Continue simulation