stats — Statistics Framework

Architecture Overview

The statistics framework is organized around Group objects that own collections of Info-backed statistics. Since SimObject inherits from statistics::Group, every simulated component automatically participates in the stats hierarchy.

graph TB
    Group["statistics::Group\n(owns stats)"]
    SimObject["SimObject\n(inherits Group)"]
    Info["statistics::Info\n(metadata base)"]
    Scalar["Scalar\n(single counter)"]
    Vector["Vector\n(indexed counters)"]
    Dist["Distribution\n(histogram)"]
    Formula["Formula\n(derived expression)"]
    Histogram["Histogram\n(auto-binning)"]
    Output["Output\n(text, JSON, HDF5)"]

    Group --> SimObject
    Group --> Info
    Info --> Scalar
    Info --> Vector
    Info --> Dist
    Info --> Formula
    Info --> Histogram
    Group -->|"dump()"| Output
    

Statistic Types

Scalar

The simplest statistic — a single numeric counter. Used for counting events (instructions committed, cache misses, etc.).

namespace statistics {

class Scalar : public DataWrap<Scalar, ScalarInfo>
{
    Counter data;

  public:
    void operator++();
    void operator++(int);
    void operator--();
    void operator--(int);
    void operator+=(Counter v);
    void operator-=(Counter v);
    Counter value() const { return data; }

    // Chain initialization
    Scalar &name(const std::string &n);
    Scalar &desc(const std::string &d);
    Scalar &precision(int p);
    Scalar &flags(Flags f);
};

} // namespace statistics

Vector

An indexed array of counters. Used for per-thread, per-bank, or per-category counting.

class Vector : public DataWrap<Vector, VectorInfo>
{
    std::vector<Counter> data;

  public:
    // Resize and access
    Vector &init(size_t size);
    ScalarProxy operator[](size_t index);

    // Naming sub-stats
    Vector &subname(size_t i, const std::string &name);
    Vector &subdesc(size_t i, const std::string &desc);

    size_t size() const;
};

// Usage:
// stats.memAccess.init(4)
//   .subname(0, "read").subname(1, "write")
//   .subname(2, "ifetch").subname(3, "prefetch");

Distribution

Tracks the distribution of sampled values across fixed-width bins. Essential for latency distributions, queue depth analysis, and similar metrics.

class Distribution : public DataWrap<Distribution, DistInfo>
{
  public:
    // Initialize with min, max, bucket_size
    Distribution &init(Counter min, Counter max, Counter bkt);

    void sample(Counter val, int number = 1);

    Counter min_val;
    Counter max_val;
    Counter bucket_size;
    Counter underflow;
    Counter overflow;
    std::vector<Counter> cvec;  // Bucket counts
};

// Example: track memory access latency
// latencyDist.init(0, 1000, 10) — 0-1000 cycles, 10-cycle buckets

Histogram

Similar to Distribution but uses logarithmically-scaled or automatically-sized bins. Better for data with unknown range.

class Histogram : public DataWrap<Histogram, HistInfo>
{
  public:
    Histogram &init(size_t buckets);  // Number of buckets
    void sample(Counter val, int number = 1);

    // Auto-grows: doubles bucket width when all buckets filled
    void grow_up();
    void grow_out();

    size_t logs;  // Log base for bucket sizes
};

Formula

Computed statistics derived from other stats using arithmetic expressions. Evaluated at dump time, not during simulation.

class Formula : public DataWrap<Formula, FormulaInfo>
{
  public:
    // Build from expression tree
    Formula &operator=(const Temp &r);
    const Formula &operator+=(const Temp &r);

    // Compute current value
    Result total() const;
    VResult result() const;
};

// Usage in regStats():
// ipc.name("ipc").desc("Instructions per cycle")
//     = committedInsts / simCycles;

Vector2d

A 2D matrix of counters. Used for cross-product statistics like per-thread-per-type event counts.

class Vector2d : public DataWrap<Vector2d, Vector2dInfo>
{
  public:
    Vector2d &init(size_t x, size_t y);
    ScalarProxy operator()(size_t x, size_t y);

    Vector2d &ysubname(size_t i, const std::string &name);
};

Statistics Group

The Group class organizes statistics hierarchically. Each System & Standard Library · gem5 Wiki" class="xref">SimObject is a Group, and Groups can contain sub-Groups for modular organization.

class Group
{
  public:
    Group(Group *parent, const char *name = nullptr);

    // Register a child group
    void addStatGroup(const char *name, Group *group);

    // Called during initialization
    virtual void regStats();
    virtual void resetStats();

    // Merge another group's stats
    void mergeStatGroup(Group *group);

    // Stat registration (called by stat constructors)
    void addStat(Info *info);
};

// SimObject inherits from Group:
// class SimObject : public ... , public statistics::Group

Statistics Lifecycle

sequenceDiagram
    participant Py as Python Config
    participant SO as SimObject
    participant Stats as Stats System
    participant Out as Output Backend

    Py->>SO: instantiate()
    SO->>Stats: regStats()
    Stats->>Stats: Register all Info objects
    Note over Stats: Simulation runs...
    SO->>Stats: Increment/sample stats
    Py->>Stats: dump()
    Stats->>Out: Visit all registered stats
    Out->>Out: Format and write (stats.txt)
    Py->>Stats: reset()
    Stats->>Stats: Zero all counters
    Note over Stats: Continue simulation...
    Py->>Stats: dump()
    Stats->>Out: Write delta stats
    

Output Backends

Pipeline — gem5 Wiki" class="xref">Statistics can be output in multiple formats simultaneously:

Text Output Example

---------- Begin Simulation Statistics ----------
system.cpu.committedInsts                     1000000
system.cpu.committedOps                       1523847
system.cpu.numCycles                          2500000
system.cpu.ipc                                0.400000
system.cpu.cpi                                2.500000
system.l2cache.overallMissRate::total         0.032456
system.l2cache.overallAvgMissLatency::total   185.234
---------- End Simulation Statistics   ----------

Statistic Flags

Complete Usage Example

class MyCache : public ClockedObject
{
    struct MyCacheStats : public statistics::Group
    {
        MyCacheStats(MyCache *cache);

        statistics::Scalar hits;
        statistics::Scalar misses;
        statistics::Formula missRate;
        statistics::Vector accessesByType;
        statistics::Distribution hitLatency;
    } stats;

  public:
    MyCache(const Params &p)
        : ClockedObject(p), stats(this) {}
};

MyCache::MyCacheStats::MyCacheStats(MyCache *cache)
    : statistics::Group(cache, "cache_stats")
{
    hits.name("hits").desc("Number of cache hits");
    misses.name("misses").desc("Number of cache misses");
    missRate.name("missRate").desc("Cache miss rate")
        = misses / (hits + misses);

    accessesByType.init(3)
        .name("accessesByType")
        .subname(0, "read")
        .subname(1, "write")
        .subname(2, "prefetch");

    hitLatency.init(0, 100, 5)
        .name("hitLatency")
        .desc("Hit latency distribution (cycles)")
        .flags(statistics::pdf | statistics::cdf);
}

Key Components Reference

Glossary