tage-trace-workflow - SKILL.md Agent Skill

name: tage-trace-workflow description: 用于编译 XiangShan RTL trace 版 emu、运行 RTL/gem5 的 TAGE trace、并对 gem5 stats/bp.db 与 RTL CondTrace 做共口径聚合比较。适用于 coremark、SPEC checkpoint slice、sjeng_22213 等单切片对拍与首轮分叉定位。

TAGE Trace Workflow

这个 skill 只做三件事：

编译能落 CondTrace_* / microTageTrace 的 RTL emu
运行 gem5 / RTL 的 trace，并固定到相同 instruction window
用脚本把 gem5 stats.txt / bp.db 和 RTL sqlite db 聚成同口径摘要

1. RTL 编译

在 XiangShan 目录下使用：

make clean
make emu \
  EMU_THREADS=8 \
  EMU_TRACE=fst \
  WITH_DRAMSIM3=1 \
  WITH_CONSTANTIN=1 \
  WITH_CHISELDB=1 \
  WITH_ROLLINGDB=1 \
  CONFIG=CHIFrontendDebugConfig \
  -j64

编完先做两个 sanity check：

rg -n "CHIFrontendDebugConfig" build/time.log
rg -n "CondTrace_0_write|BpuPredictionTrace_write|microTageTrace_write" build/chisel_db.cpp

如果 CondTrace_0_write() 仍然是空桩，就不要继续跑 trace。

2. RTL 运行

关键点：

--dump-select-db 必须是空格分隔的精确表名
优先只打 CondTrace_0..7，需要更细再加 microTageTrace
尽量先用 -I 把窗口限制住

示例：

./build/emu \
  --no-diff \
  -I 200000 \
  -i /nfs/home/share/gem5_ci/checkpoints/coremark-riscv64-xs.bin \
  --dump-db \
  --dump-select-db "CondTrace_0 CondTrace_1 CondTrace_2 CondTrace_3 CondTrace_4 CondTrace_5 CondTrace_6 CondTrace_7 microTageTrace" \
  > /tmp/coremark_tage.out 2>&1

对 .zstd GCPT slice，直接把路径传给 -i 即可。

3. gem5 运行

kmhv3.py 需要 diff 环境变量：

export GCBV_REF_SO=/nfs/home/yanyue/tools/gem5-tools/ref-h/riscv64-nemu-interpreter-so

示例：

./build/RISCV/gem5.opt \
  --outdir /tmp/debug/coremark_200k_basic \
  ./configs/example/kmhv3.py \
  -I 200000 \
  --generic-rv-cpt /nfs/home/share/gem5_ci/checkpoints/coremark-riscv64-xs.bin \
  --raw-cpt \
  --enable-bp-db tage basic

说明：

tage 会生成 TAGEMISSTRACE
basic 会额外生成 BPTRACE
先保证 gem5 和 RTL 用同一个 -I

4. 分析顺序

先看计数器，再看 trace：

gem5 stats.txt 中的 allocateNeeded / allocateSkipHighestProvider / resolveBranchHasProvider / resolveBranchUseProvider / resolveBranchHasAlt / resolveBranchUseAltTable / resolveBranchUseBaseTable / mispredictBranch*
RTL CondTrace_* 聚出来的同口径总量
再看热点 branch 的 provider/alt/useAlt/alloc

注意两个口径坑：

TAGEMISSTRACE.useAlt 表示 pred.useAlt，不等于 stats 里的 resolveBranchUseAltTable
要和 stats 对齐时，应该优先看 useAlt && altFound

5. 脚本

RTL 聚合： [scripts/aggregate_rtl_condtrace.py](scripts/aggregate_rtl_condtrace.py)
gem5/RTL 对拍： [scripts/compare_gem5_rtl_tage.py](scripts/compare_gem5_rtl_tage.py)
热点 branch 画像对拍： [scripts/compare_branch_profiles.py](scripts/compare_branch_profiles.py)
单个 branch 的顶层事件序列粗对拍： [scripts/compare_branch_event_sequences.py](scripts/compare_branch_event_sequences.py)
高表 alloc 生命周期分析： [scripts/analyze_alloc_lifecycle.py](scripts/analyze_alloc_lifecycle.py)
prediction-time PHR contributor 归类： [scripts/analyze_phist_contributor.py](scripts/analyze_phist_contributor.py)
RTL BpuTrainTrace 的 self / sibling / none block-level 贡献者归类： [scripts/analyze_rtl_train_contributor.py](scripts/analyze_rtl_train_contributor.py)

常用命令：

python3 docs/codex-skills/tage-trace-workflow/scripts/aggregate_rtl_condtrace.py \
  --rtl-db /path/to/rtl.db --top 12

python3 docs/codex-skills/tage-trace-workflow/scripts/compare_gem5_rtl_tage.py \
  --gem5-stats /tmp/debug/coremark_200k_basic/stats.txt \
  --gem5-bpdb /tmp/debug/coremark_200k_basic/bp.db \
  --gem5-top-branch-csv /tmp/debug/coremark_200k_basic/topMispredictsByBranch.csv \
  --rtl-db /nfs/home/yanyue/workspace/xs-env/XiangShan/build/2026-03-25-13-31-09.db \
  --top 12