统计信息 API

目录

1. 通用统计信息函数
2. Stats::Group - 统计信息容器
3. 统计信息标志
4. 统计信息类
5. 附录：迁移到新的统计信息跟踪样式

通用统计信息函数

Stats::Group - 统计信息容器

通常，统计信息对象可以作为类变量放置在任何 SimObject 中。 但是，最近的更新 解决了 gem5 中 SimObject 的层次结构性质， 这反过来使对象的统计信息具有层次结构。 该更新引入了 Stats::Group 类，它是一个统计信息容器 并且了解 SimObject 的层次结构。 理想情况下，此容器应包含 SimObject 中的所有统计信息。

注意：如果您决定在 SimObject 内使用 Stats::Group 结构体， 通常有两种方法：

• 使用 Stats::Group(Stats::Group &parent, const std::string &name) 构造函数创建子组。当需要同一统计信息结构的多个实例时，这很有用。
• 使用 Stats::Group(Stats::Group &parent) 构造函数，它将当前组的统计信息合并（即添加）到父组。因此，添加到当前组的统计信息的行为就像它们被直接添加到父组一样。

Stats::Group 宏

#define ADD_STAT(n, ...) n(this, # n, __VA_ARGS__)

用于向统计信息组添加统计信息的便捷宏。

此宏用于在 Group 构造函数的初始化列表中将统计信息添加到 Stats::Group。该宏 自动将统计信息分配给当前组并为其提供 与类中相同的名称。例如：

struct MyStats : public Stats::Group
{
    Stats::Scalar scalar0;
    Stats::Scalar scalar1;

    MyStats(Stats::Group *parent)
        : Stats::Group(parent),
          ADD_STAT(scalar0, "Description of scalar0"),       // 等价于 scalar0(this, "scalar0", "Description of scalar0")，其中 scalar0 具有以下构造函数
                                                             // Stats::Scalar(Group *parent = nullptr, const char *name = nullptr, const char *desc = nullptr)
          scalar1(this, "scalar1", "Description of scalar1")
     {
     }
};

Stats::Group 函数

Group(Group *parent, const char *name = nullptr)

构造一个新的统计信息组。

构造函数接受两个参数：父组和名称。 通常应指定父组。但是，有一些 特殊情况，父组可能为 null。一个这样的 特殊情况是 SimObjects，其中 Python 代码执行 组父级的后期绑定。

如果 name 参数为 NULL，组将合并到 父组而不是创建子组。属于 合并组的统计信息的行为就像它们被直接添加到 父组一样。

virtual void regStats()

用于设置统计信息参数的回调。

此回调通常用于复杂的统计信息（例如， 分布），除了名称和 描述之外还需要参数。在统计信息对象无法在 构造函数中初始化的情况下（例如跟踪 总线主控器的统计信息，只有在整个 系统实例化后才能发现）。统计信息名称和描述应该 通常使用 ADD_STAT 宏从构造函数中设置。

virtual void resetStats()

用于重置统计信息的回调。

virtual void preDumpStats()

在转储统计信息之前的回调。这可以被 需要在统计信息框架实现的功能之外执行计算的对象覆盖。

void addStat(Stats::Info *info)

向此组注册统计信息。此方法通常在 实例化统计信息时自动调用。

const std::map<std::string, Group *> &getStatGroups() const

获取与此对象关联的所有子组。

const std::vector<Info *> &getStats() const

获取与此对象关联的所有统计信息。

void addStatGroup(const char *name, Group *block)

将统计信息块添加为此块的子项。

此方法只能从 Group 构造函数或从 regStats 调用。它通常只在从 Python 设置 SimObject 层次结构时显式调用。

const Info * resolveStat(std::string name) const

在此组中按名称解析统计信息。

此方法遍历此组和子组中的统计信息 并返回与提供的 名称匹配的统计信息的指针。输入名称必须相对于此 组的名称。

例如，如果此组是 SimObject system.bigCluster.cpus 并且我们想要统计信息 system.bigCluster.cpus.ipc，输入参数应该是 字符串 “ipc”。

统计信息标志

注意：尽管标志 Stats::init 和 Stats::display 可用，但这些标志 不允许由用户设置。

统计信息类

注意：Stats::Average 仅计算标量在模拟 tick 数上的平均值。 为了获得数量 A 相对于数量 B 的平均值，可以使用 Stats::Formula。 例如，

Stats::Scalar totalReadLatency;
Stats::Scalar numReads;
Stats::Formula averageReadLatency = totalReadLatency/numReads;

通用统计信息函数

Stats::Scalar

Storing a signed integer statistic.

Stats::Average

Storing an average of an integer quantity, supposely A, over the number of simulated ticks. The quantity A keeps the same value across all ticks after its latest update and before the next update. Note: the number of simulated ticks is reset when the user calls Stats::reset().

Stats::Value

Storing a signed integer statistic that is either an integer or an integer that is a result from calling a function or an object’s method.

Stats::Vector

Storing an array of scalar statistics where each element of the vector has function signatures similar to those of Stats::Scalar.

Stats::AverageVector

Storing an array of average statistics where each element of the vector has function signatures similar to those of Stats::Average.

Stats::Vector2d

Storing a 2-dimensional array of scalar statistics, where each element of the array has function signatures similar to those of Stats::Scalar. This data structure assumes all elements whose the same second dimension index has the same name.

Stats::Distribution

Storing a distribution of a quantity. The statistics of the distribution include,

• the smallest/largest value being sampled
• the number of values that are smaller/larger than the specified minimum and maximum
• the sum of all samples
• the mean, the geometric mean and the standard deviation of the samples
• histogram within the range of [min, max] splitted into (max-min)/bucket_size equally sized buckets, where the min/max/bucket_size are inputs to the init() function.

Stats::Histogram

Storing a histogram of a quantity given the number of buckets. All buckets are equally sized. Different from the histogram of Stats::Distribution which keeps track of the samples in a specific range, Stats::Histogram keeps track of all samples in its histogram. Also, while Stats::Distribution is parameterized by the number of values in a bucket, Stats::Histogram’s sole parameter is the number of buckets. When a new sample is outside of the current range of all all buckets, the buckets will be resized. Roughly, two consecutive buckets will be merged until the new sample is inside one of the buckets.

Other than the histogram itself, the statistics of the distribution include,

• the smallest/largest value being sampled
• the sum of all samples
• the mean, the geometric mean and the standard deviation of the samples

Stats::SparseHistogram

Storing a histogram of a quantity given a set of integral values.

Stats::StandardDeviation

Keeps track of the standard deviation of a sample.

Stats::AverageDeviation

Keeps track of the average deviation of a sample.

Stats::VectorDistribution

Storing a vector of distributions where each element of the vector has function signatures similar to those of Stats::Distribution.

Stats::VectorStandardDeviation

Storing a vector of standard deviations where each element of the vector has function signatures similar to those of Stats::StandardDeviation.

Stats::VectorAverageDeviation

Storing a vector of average deviations where each element of the vector has function signatures similar to those of Stats::AverageDeviation.

Stats::Formula

Storing a statistic that is a result of a series of arithmetic operations on Stats objects. Note that, in the following function, Temp could be any of Stats class holding statistics (including vector statistics), a formula, or a number (e.g.int, double, 1.2).

An example of using Stats::Formula,

Stats::Scalar totalReadLatency;
Stats::Scalar numReads;
Stats::Formula averageReadLatency = totalReadLatency/numReads;

附录：迁移到新的统计信息跟踪样式

新的统计信息跟踪样式

gem5 统计信息具有扁平结构，不了解 SimObject 的层次结构，而 SimObject 通常包含统计信息对象。 这导致不同统计信息具有相同名称的问题，更重要的是，操作 gem5 统计信息的结构并不简单。 此外，gem5 没有提供将统计信息对象集合分组到不同组的方法，这对于维护大量统计信息对象很重要。

最近的提交引入了 Stats::Group，这是一个旨在保存属于对象的所有统计信息的结构。 新结构提供了一种明确的方式来反映 SimObject 的层次结构性质 Stats::Group 还使维护大量应分组到不同集合的 Stats 对象更加明确和容易，因为可以在 SimObject 中创建多个 Stats::Group 并将它们合并到 SimObject，SimObject 也是一个了解其子 Stats::Group 的 Stats::Group。

总的来说，这是朝着更结构化的 Stats 格式迈出的一步，这将有助于操作 gem5 中统计信息的整体结构，例如过滤统计信息并将 Stats 生成更标准化的格式，如 JSON 和 XML，这些格式反过来在各种编程语言中都有大量支持的库。

迁移到新的统计信息跟踪样式

注意：强烈建议迁移到新样式；但是，旧样式的统计信息（即具有扁平结构的样式）仍然受支持。

本指南提供了如何迁移到 gem5 统计信息跟踪新样式的广泛概述，并指出了一些显示如何完成此操作的具体示例。

ADD_STAT

ADD_STAT 是一个定义为以下内容的宏，

#define ADD_STAT(n, ...) n(this, # n, __VA_ARGS__)

此宏旨在在 Stats::Group 构造函数中使用以初始化 Stats 对象。 换句话说，ADD_STAT 是调用 Stats 对象构造函数的别名。 例如，ADD_STAT(stat_name, stat_desc) 等同于，

  stat_name.parent = 定义 stat_name 的 `Stats::Group`
  stat_name.name = "stat_name"
  stat_name.desc = "stat_desc"

这适用于大多数 Stats 数据类型，但 Stats::Formula 例外，宏 ADD_STAT 可以处理指定公式的可选参数。 例如，ADD_STAT(ips, "Instructions per Second", n_instructions/sim_seconds)。

ADD_STAT 的示例用例（我们在本节中将此示例称为”示例 1“）。 此示例还用作构造 Stats::Group 结构体的模板。

    protected:
        // 定义统计信息组
        struct StatGroup : public Stats::Group
        {
            StatGroup(Stats::Group *parent); // 构造函数
            Stats::Histogram histogram;
            Stats::Scalar scalar;
            Stats::Formula formula;
        } stats;

    // 定义声明的构造函数
    StatGroup::StatGroup(Stats::Group *parent)
      : Stats::Group(parent),                           // 初始化基类
        ADD_STAT(histogram, "A useful histogram"),
        scalar(this, "scalar", "A number"),             // 这与 ADD_STAT(scalar, "A number") 相同
        ADD_STAT(formula, "A formula", scalar1/scalar2)
    {
        histogram
          .init(num_bins);
        scalar
          .init(0)
          .flags(condition ? 1 : 0);
    }

迁移到新样式

这些是将统计信息转换为新样式的具体示例：here、here 和 here。

将统计信息迁移到新样式涉及：

• 创建一个 Stats::Group 结构体，并将所有统计信息变量移到那里。此结构体的作用域应为 protected。统计信息变量的声明通常在头文件中。
• 摆脱 regStats()，并将统计信息变量的初始化移到 Stats::Group 构造函数，如示例 1 所示。
• 在头文件和 cpp 文件中，所有统计信息变量都应该以新创建的 Stats::Group 名称作为前缀，因为统计信息现在位于 Stats::Group 结构体下。
• 更新类构造函数以初始化 Stats::Group 变量。通常，这是将 stats(this) 添加到构造函数，假设变量名是 stats。

一些示例，

• Stats::Group 声明的示例在此处。 注意，所有以 Stats:: 开头的类型变量都已移到结构体中。
• 使用 ADD_STAT 的 Stats::Group 构造函数的示例在此处。
• 在统计信息变量需要除 name 和 description 之外的额外初始化的情况下，您可以遵循此示例。