sim — Simulation Engine

Architecture Overview

The sim module forms the foundation of gem5's discrete-event simulation framework. It provides three pillars: SimObject — the universal base class for all simulated components, EventQueue — the priority-driven scheduling engine, and System — the top-level container binding CPUs, memory, and workloads together.

graph TB
    SimObject["SimObject\n(base class)"]
    ClockedObject["ClockedObject\n(clock domain aware)"]
    System["System\n(top-level container)"]
    Process["Process\n(SE mode)"]
    EventQueue["EventQueue\n(scheduling)"]
    Event["Event\n(scheduled action)"]
    Workload["Workload\n(FS/SE)"]
    PowerState["PowerState"]
    VoltageDomain["VoltageDomain"]

    SimObject --> ClockedObject
    SimObject --> Workload
    SimObject --> Process
    ClockedObject --> System
    Workload --> KernelWorkload["KernelWorkload"]
    Workload --> SEWorkload["SEWorkload"]
    EventQueue --> Event
    System --> VoltageDomain
    ClockedObject --> PowerState
    

SimObject Hierarchy

Every component in gem5 — CPUs, caches, buses, memories — inherits from SimObject. This base class provides a uniform interface for construction (via Python-generated Params), initialization, serialization (checkpointing), and statistics registration.

SimObject Lifecycle

SimObjects follow a strict initialization protocol:

1. Construction — Python creates Params structs, C++ constructors receive them
2. init() — Post-construction setup, resolve cross-object references
3. regStats() — Register statistics counters
4. regProbePoints() — Register probe points for instrumentation
5. startup() — Schedule initial events, final setup

class SimObject : public EventManager, public Serializable, public Drainable, public statistics::Group
{
  public:
    typedef SimObjectParams Params;
    const Params &params() const;

    SimObject(const Params &p);
    virtual ~SimObject();

    virtual void init();
    virtual void startup();
    virtual void regStats();
    virtual void regProbePoints();
    virtual void regProbeListeners();

    // Serialization for checkpointing
    void serializeSection(CheckpointOut &cp, const char *name) const;
    void unserializeSection(CheckpointIn &cp, const char *name);

    // Find SimObject by name
    static SimObject *find(const char *name);
};

ClockedObject

ClockedObject extends SimObject with clock domain awareness. It associates each object with a ClockDomain, enabling cycle-accurate timing. Components use clockEdge() to align operations to clock boundaries and cyclesToTicks() for time conversion.

class ClockedObject : public SimObject
{
    ClockDomain &clockDomain;
    Tick tick;
    Cycles cycle;

  public:
    Tick clockEdge(Cycles cycles = Cycles(0)) const;
    Tick cyclesToTicks(Cycles c) const;
    Tick clockPeriod() const;
    double voltage() const;
    Cycles ticksToCycles(Tick t) const;
    PowerState *powerState;
};

Event System

gem5 uses a discrete-event simulation model where the EventQueue maintains a time-ordered queue of Event objects. The simulation loop repeatedly dequeues the earliest event, advances simulation time, and invokes the event's process() method.

sequenceDiagram
    participant Main as simulate()
    participant EQ as EventQueue
    participant Ev as Event
    participant Obj as SimObject

    Main->>EQ: serviceOne()
    EQ->>EQ: dequeue head event
    EQ->>Ev: process()
    Ev->>Obj: execute action
    Obj->>EQ: schedule(newEvent, when)
    EQ->>EQ: insert sorted by time+priority
    Main->>EQ: serviceOne() [next iteration]
    

Event Priorities

Events at the same tick are ordered by priority. gem5 defines several standard priorities to ensure correct execution order within a single simulation tick:

Event Class

class Event : public Serializable
{
  public:
    typedef int8_t Priority;

    Event(Priority p = Default_Pri, Flags f = AutoDelete);
    virtual ~Event();

    virtual void process() = 0;  // Override to define action
    virtual const char *description() const;

    bool scheduled() const;
    Tick when() const;
    Priority priority() const;

    void squash() { flags.set(Squashed); }
    bool squashed() const { return flags.isSet(Squashed); }
};

System and Workloads

The System class is the top-level container that binds all components together. It manages the physical memory address map, tracks all CPUs, provides access to the workload, and coordinates full-system vs. syscall-emulation modes.

System Class

class System : public SimObject
{
  public:
    std::vector<BaseRemoteGDB *> remoteGDB;
    std::vector<ThreadContext *> threads;

    Workload *workload;
    PhysicalMemory physmem;

    Enums::MemoryMode memoryMode;
    AddrRangeList shadowRomRanges;

    // Memory access
    bool isMemAddr(Addr addr) const;
    PortProxy &getPhysMem();
    Addr memSize() const;

    // Thread context management
    void registerThreadContext(ThreadContext *tc);
    int numContexts() const;
    ThreadContext *threads[int id];
};

Workload Hierarchy

The workload abstraction decouples the simulated system from the software being run:

• Workload — Abstract base managing object files, symbol tables, entry points
• KernelWorkload — Loads kernel images for full-system simulation, handles kernel symbols and command lines
• SEWorkload — Manages syscall-emulation processes, maps system calls to host OS

Process & Syscall Emulation

The Process class models a user-space process in syscall emulation (SE) mode. It provides virtual memory (MemState), file descriptor tracking (FDArray), and system call dispatching without requiring a full OS kernel.

class Process : public SimObject
{
  public:
    System *system;
    std::shared_ptr<MemState> memState;
    std::shared_ptr<FDArray> fds;

    Addr brk_point;      // Current brk() address
    Addr stack_base;     // Stack base address
    Addr mmap_end;       // mmap region boundary

    ObjectFile *objFile; // Loaded binary
    SymbolTable *symtab; // Symbol table

    virtual void initState();
    virtual void syscall(ThreadContext *tc);

    // VMA management
    void allocateMem(Addr vaddr, int64_t size, bool clobber = false);
    bool mmapGrowsDown() const;
};

Simulation Control

The simulate() function is the main simulation loop entry point. It processes events from the EventQueue until a simulation exit event fires or the maximum tick count is reached.

// Core simulation entry — returns when exit event is triggered
GlobalSimLoopExitEvent *simulate(Tick num_cycles = MaxTick);

// Exit events for terminating simulation
class GlobalSimLoopExitEvent : public GlobalEvent
{
    std::string cause;
    int code;
  public:
    const std::string getCause() const { return cause; }
    int getCode() const { return code; }
};

Key Components Reference

Sub-Modules

Cross-Module Connections

graph LR
    sim["sim\n(SimObject, EventQueue)"]
    base["base\n(types, stats, debug)"]
    cpu["cpu\n(BaseCPU)"]
    mem["mem\n(MemObject)"]
    arch["arch\n(ISA)"]
    dev["dev\n(devices)"]

    base -->|"Tick, Addr types"| sim
    sim -->|"SimObject base"| cpu
    sim -->|"SimObject base"| mem
    sim -->|"SimObject base"| dev
    sim -->|"System, Workload"| arch
    

Glossary