Seastar gem5 Evaluation Interface

本仓库是基于原始 gem5 的 Seastar cache evaluation fork。原始 gem5 README 已保存在 README_gem5。

当前改动目标是为 Seastar idea 提供第一版 evaluation 接口：gem5 能在 classic cache 路径上配置一个抽象多层 D-cache，并为后续 RD predictor、prefetcher hint 和 placement policy 实验保留稳定边界。当前版本只定义接口和统计框架，不实现具体层间协议、物理互联、 coherence、真实数据搬运或最终 placement/promotion 策略。

Scope

第一版范围如下：

• 基于 gem5 classic cache。
• 面向单核 SE、D-cache 优先 evaluation。
• L1I 保持原始 gem5 cache 配置，不进入 Seastar 第一版设计。
• Seastar 暂时作为抽象多层 tag/data store 和 placement policy 边界接入 Cache。
• 复用 classic cache 现有端口、MSHR、writeback、timing 和 prefetch queue。
• Ruby/coherence、多核协议、层间网络和数据迁移协议留给后续阶段。

File Map

Seastar 相关新增或修改集中在以下位置：

• src/mem/cache/seastar.hh

  • 定义 SeastarHint。
  • 定义 RDProvider 抽象接口。
  • 提供 Request extension 的 hint 读写 helper。

• src/mem/cache/tags/Tags.py

  • 新增 SeastarTags SimObject 参数接口。

• src/mem/cache/tags/seastar.hh

• src/mem/cache/tags/seastar.cc

  • 新增 SeastarTags C++ 占位实现。
  • 目前继承 classic BaseSetAssoc 行为。
  • 暴露 Seastar layer、hint、prefetch 相关 stats。

• src/python/gem5/components/cachehierarchies/classic/caches/seastar_cache.py

  • 新增 Python SeastarCache wrapper。
  • 面向 gem5 config 层提供统一 cache 创建入口。

• src/python/gem5/seastar/configs.py

  • 新增 evaluation dataclass 配置接口。
  • 包含默认实验矩阵 A-F。

• src/mem/cache/tags/SConscript

• src/python/SConscript

  • 将新增 C++ 和 Python 模块接入 gem5 build。

Python Cache Interface

SeastarCache 是当前推荐的 Python config 入口：

from gem5.components.cachehierarchies.classic.caches.seastar_cache import (
    SeastarCache,
)

dcache = SeastarCache(
    total_size="1056KiB",
    block_size=64,
    layer_sizes=[
        "16KiB",
        "16KiB",
        "32KiB",
        "32KiB",
        "64KiB",
        "128KiB",
        "256KiB",
        "512KiB",
    ],
    layer_assoc=[4, 4, 8, 8, 8, 16, 16, 16],
    layer_latencies=[1, 2, 4, 6, 10, 16, 24, 36],
    placement_policy="rd_hint",
    replacement_policy="LRU",
    indexing_policy="set_assoc",
    rd_boundaries=[],
    enable_rd_hint=True,
    enable_prefetch_hint=True,
)

参数语义：

• layer_sizes[i]：第 i 层容量，层号越小越靠近 core。
• layer_assoc[i]：第 i 层抽象 associativity。
• layer_latencies[i]：第 i 层命中延迟，单位为 gem5 cycle 参数。
• placement_policy：预留 lru_stack、rd_hint、oracle_rd。
• replacement_policy：第一版只接受 LRU。
• indexing_policy：预留 set_assoc、hashed_set_assoc。
• rd_boundaries：RD 到 layer 的显式映射边界；为空时后续策略可按累计容量推导。
• enable_rd_hint：关闭时忽略 RD hint，用于 no-RD 形状实验。
• enable_prefetch_hint：控制 prefetch hint 是否允许被 Seastar cache 使用。

C++ Hint Interface

SeastarHint 通过 gem5 Request extension 携带，普通 classic cache 可以直接忽略：

class SeastarHint : public Extension<Request, SeastarHint>
{
  public:
    enum class Source
    {
        None,
        Predictor,
        Prefetcher,
        Oracle
    };

    bool valid = false;
    uint64_t predictedRD = InvalidRD;
    uint32_t targetLayer = InvalidLayer;
    uint8_t confidence = 0;
    Source source = Source::None;
};

语义：

• targetLayer 优先级高于 predictedRD。
• predictedRD 需要由 Seastar placement policy 映射到 layer。
• hint 不改变 memory consistency 语义，只影响 fill placement 和后续可选 promotion。
• enable_rd_hint=false 时 Seastar cache 应忽略 hint。

RD Provider Interface

RDProvider 只定义 predictor 能力边界，不绑定具体实现：

class RDProvider
{
  public:
    virtual ~RDProvider() = default;

    virtual SeastarHint predict(
        Addr pc,
        Addr paddr,
        bool is_write,
        Tick now) = 0;

    virtual void update(
        Addr pc,
        Addr paddr,
        uint64_t observed_rd,
        bool was_hit,
        uint32_t hit_layer) = 0;
};

后续可以在同一接口后接入 oracle RD、trace-driven RD 或简单 (pc, addr) tuple predictor。

Evaluation Config Interface

src/python/gem5/seastar/configs.py 提供 dataclass 化的实验配置：

from gem5.seastar.configs import (
    CacheConfig,
    EvaluationConfig,
    PrefetchConfig,
    SeastarCacheConfig,
    default_experiment_matrix,
)

matrix = default_experiment_matrix(workload="my_workload")

当前支持的 cache_model：

• classic_l1_l2
• classic_l1_l2_with_prefetch
• seastar_no_rd
• seastar_rd_hint
• seastar_oracle_rd

默认实验矩阵：

A. classic L1D+L2, no prefetch
B. classic L1D+L2, existing prefetcher
C. Seastar D-cache, lru_stack, no RD
D. Seastar D-cache, rd_hint, no prefetch
E. Seastar D-cache, rd_hint + prefetch hint
F. Seastar D-cache, oracle_rd

默认 Seastar layer shape：

[16, 16, 32, 32, 64, 128, 256, 512] KiB

Stats Boundary

SeastarTags 目前注册以下统计项，用于后续统一 evaluation 收集：

seastar.layer.accesses
seastar.layer.hits
seastar.layer.misses
seastar.layer.fills
seastar.layer.evictions
seastar.layer.occupancy
seastar.layer.avg_latency

seastar.hint.total
seastar.hint.used
seastar.hint.ignored
seastar.hint.target_layer
seastar.hint.actual_hit_layer
seastar.hint.mispredicted_layer_distance

seastar.prefetch.issued
seastar.prefetch.useful
seastar.prefetch.unused
seastar.prefetch.pollution_evictions

当前 stats 是接口占位。真实计数语义需要随着 layer lookup、fill、eviction、hint 使用和 prefetch 生命周期实现一起补齐。

Build And Smoke Tests

常规构建：

scons build/ALL/gem5.opt -j4

接口 smoke test：

build/ALL/gem5.opt -c "from m5.objects import SeastarTags; x = SeastarTags(size='64KiB', assoc=2, layer_sizes=['16KiB', '16KiB'], layer_latencies=[1, 2]); print(type(x).__name__)"

build/ALL/gem5.opt -c "from gem5.components.cachehierarchies.classic.caches.seastar_cache import SeastarCache; c = SeastarCache(); print(type(c.tags).__name__)"

预期输出均应包含：

SeastarTags

Current Limitations

当前版本没有实现：

• 真实多层 tag/data store lookup。
• RD-aware fill placement。
• layer promotion/demotion。
• prefetcher 生成 SeastarHint 的逻辑。
• oracle RD 或在线 RD predictor。
• 多核 coherence、Ruby 协议迁移或层间互联。
• microbenchmark 和自动 evaluation runner。

因此，当前代码适合继续搭建实验配置、编译验证和接口对齐；还不能作为最终 Seastar 性能 evaluation 结果来源。

Suggested Next Steps

后续实现建议按以下顺序推进：

1. 在 SeastarTags 中实现抽象 layer lookup/fill/eviction，并让 layer stats 反映真实访问。
2. 将 SeastarHint 接入 demand access 和 prefetch request 的生成路径。
3. 实现 lru_stack、rd_hint、oracle_rd 三种 placement policy。
4. 接入至少一个简单 RD provider，用于验证 hint 管线。
5. 增加顺序流、循环数组、pointer chasing、工作集 sweep microbenchmark。
6. 增加 evaluation runner，统一收集 IPC、MPKI、prefetch accuracy/coverage 和 Seastar stats。