G5 计算建模 CUBE 矩阵乘 Test Plan
逐 test case 定义输入、预期、覆盖的 spec 验收点与断言性质，可执行对应到实际 test 文件。
本 test plan 覆盖「G5-计算建模设计规格」首篇（CUBE 矩阵乘）的实现验证。核心验收：G5 计算 cycle 逐 kernel 严格等于 golden（Python 转写 TPUPerf 闭式公式），无容差。golden 与 Rust 实现是两份独立转写，靠双实现交叉 + 逐行核对 TPUPerf 源码防同源误读。
名词定义
| 名词 | 定义 |
|---|---|
| golden | Python 独立转写 TPUPerf mm2_cmd_sg2262.cc 闭式公式（tests/evaluation/g5/golden/tpuperf_mm2.py），作验收基准 |
| 严格无容差 | 断言 ==，不带任何容差；伪红进去查根因不加兜底（项目 feedback） |
| 行为断言 | 验证某行为被触发 / 某结构属性成立，非精确数值相等 |
| 转置格式 | mm2 的 nn/nt/tt，决定 cycle 公式分支 |
| block-quant | 量化矩阵乘 eu_typ 13，含 g_size 分组 + bq_cycle 项 |
测试套件总览
| 套件 | 文件 | 跑法 | 断言性质 |
|---|---|---|---|
| Rust golden 差分 | tier3/tiu.rs::test_g5_matches_golden_fixture | cd perfmodel/evaluation/g5 && cargo test --lib tier3::tiu | 严格无容差 |
| Rust 公式单测 | tier3/tiu.rs::test_mm2_nn_* 等 | 同上 | 严格无容差 |
| Rust overlap/访存边 | tier3/tiu.rs::test_overlap_* test_memory_edge_* | 同上 | 严格（浮点 ULP） |
| Rust 厂商中立/精度 | tier3/tiu.rs::test_vendor_neutral_* test_precision_scaling | 同上 | 严格无容差 |
| Python golden 锁定 | tests/evaluation/g5/test_golden_formula.py | pytest tests/evaluation/g5/test_golden_formula.py | 严格无容差 |
| Python 门控 | tests/evaluation/g5/test_slo_gate.py | pytest tests/evaluation/g5/test_slo_gate.py | 行为断言 |
| 端到端回归 | tests/evaluation/g5/test_cp_* test_adapter.py | pytest tests/evaluation/g5/ | 严格（继承既有） |
@tbl-g5cmtest-suites 测试套件总览
golden 差分 test case（核心验收，严格无容差）
test_g5_matches_golden_fixture 遍历 fixtures/mm2_golden.json（132 case），对每个 case 构造 Rust TIUCommand、调 calc_tiu_latency、断言 cycles == golden_cycle。fixture 由 generate_fixtures.py 在 shape × 精度 × 转置/量化网格上跑 golden 生成。
覆盖维度：
| 维度 | 取值 |
|---|---|
| 转置/量化 | mm2.nn, mm2.nt, mm2.tt, smm2.nn, smm2.nt, smm2.tt, block-quant |
| 精度 | INT8, BF16, FP32 |
| shape (M,N,K) | (16,8,32) 单 tile 整除；(32,16,64) 多 tile 整除；(4096,2048,5120) 大算子；(17,9,33) 全非整除；(1,1,1) 最小；(15,7,31) 不足单 tile |
| block-quant g_size | 16/32/64/128（opd2_n_str 0..3）× (4096,2048,5120)/(32,16,256) |
@tbl-g5cmtest-golden-dims golden 差分覆盖维度
代表性 case（手算可复核）：
| # | 输入 (转置, 精度, M,N,K) | 公式 | 预期 cycle | 覆盖 spec 验收点 | 断言 |
|---|---|---|---|---|---|
| G1 | mm2.nn, INT8, 16,8,32 | ceil(16/16)·ceil(8/8)·(ceil(32/32)+0)+44 | 45 | mm2.nn 逐 kernel ==TPUPerf | 严格 |
| G2 | mm2.nn, BF16, 32,16,64 | ch=16: 2·2·4+44 | 60 | 精度缩放 BF16 | 严格 |
| G3 | mm2.nt, INT8, 16,8,32 | 1·1·1·1+misc19 | 20 | mm2.nt + loop_cycle | 严格 |
| G4 | mm2.tt, INT8, 16,8,32 | 1·1·1+init47 | 48 | mm2.tt | 严格 |
| G5 | mm2.nt, FP32 无bias, 16,8,32 | ch=8: 1·1·4·2+19 | 27 | nt bias 因子=2 | 严格 |
| G6 | smm2.nn, INT8, 16,8,32 | N下界max(8,16)=16: 1·ceil(16/8)·1+44 | 46 | smm2 N 下界 | 严格 |
| G7 | block-quant ×4 g_size, INT8, 4096,2048,5120 | 含 bq_cycle，随 g_size 变 | 四值互异 | block-quant g_size 分档 | 严格（互异） |
@tbl-g5cmtest-golden-cases golden 代表性 case
删码即失败验证：任意改 tiu.rs 公式（错 init 常数 / 错 N 下界 / 漏 bank 项），该套件即报红——code review 已确认。
Rust 公式 + 边界 test case
| # | 测试 | 输入 | 预期 | 覆盖 spec 验收点 | 断言 |
|---|---|---|---|---|---|
| R1 | test_mm2_nn_basic | nn INT8 16,8,32 | cycles=45, t_comp=45ns, latency=t_comp+t_mem | mm2.nn + 访存边接入 | 严格 |
| R2 | test_mm2_nn_bf16 | nn BF16 32,16,64 | cycles=60 | 精度缩放 | 严格 |
| R3 | test_precision_scaling | nn 16,8,128 × INT8/BF16/FP32 | cycle=4+44 / 8+44 / 16+44 | 精度独立 ch（非算术缩放） | 严格 |
| R4 | test_vendor_neutral_params_change_cycle | nn 64,32,128，参数实例 A(lane16/eu8/ch32) vs B(lane32/eu16/ch64) | 108 vs 52 | 厂商中立：换参数 cycle 变、结构不变 | 严格 |
@tbl-g5cmtest-rust-formula Rust 公式 + 边界 case
overlap + 访存边 test case
| # | 测试 | 输入 | 预期 | 覆盖 spec 验收点 | 断言 |
|---|---|---|---|---|---|
| O1 | test_overlap_combine | (t_comp,t_mem,ρ) = (10,3,0)/(10,3,1)/(3,10,1)/(10,3,0.5) | 13 / 10 / 10 / 11.5 | overlap ρ=0 相加、ρ=1 max | 严格（ULP） |
| O2 | test_memory_edge_and_kernel_time | nn INT8 64,64,64，ρ=0 | t_mem=8192/2000，域=lmem_bus，latency=t_comp+t_mem | 访存边公式 + 带宽域标签 | 严格（ULP） |
| O3 | test_overlap_rho_one_takes_max | nn INT8 64,64,64，ρ=1 | latency=max(t_comp,t_mem) | overlap ρ=1 | 严格（ULP） |
@tbl-g5cmtest-overlap overlap + 访存边 case
门控 test case（行为断言）
| # | 测试 | 输入 | 预期 | 覆盖 spec 验收点 |
|---|---|---|---|---|
| D1 | test_unvalidated_gates_absolute | Aggregates(compute_unvalidated=True, ttft=12, tpot=3) | absolute_valid=False, ttft/tpot=None | 门控绝对值 |
| D2 | test_unvalidated_still_gives_relative | cur(total=80)/base(total=100) 均 unvalidated | relative ratio=0.8 | 门控下仍给相对 |
| D3 | test_validated_returns_absolute | compute_unvalidated=False | absolute_valid=True, ttft=12 | 验证后返绝对 |
| D4 | test_g5_adapter_sets_unvalidated | — | Aggregates 默认 False，G5 adapter 置 True | G5 路径默认门控 |
@tbl-g5cmtest-gate 门控 case
Python golden 锁定 test case
test_golden_formula.py 锁定 golden 转写自身（防 golden 漂移）：
| # | 测试 | 验证 | 断言 |
|---|---|---|---|
| P1 | test_round_int2_up | 向上取整边界 + 除零 raise | 严格 |
| P2 | test_mm2_nn_matches_known_tiu_values | golden(nn INT8 16,8,32)=45, (BF16)=60 | 严格 |
| P3 | test_mm2_nt_tt_hand_computed | nt=20, tt=48 手算 | 严格 |
| P4 | test_mm2_nt_bias_factor | FP32 无bias=27 / 有bias=23 | 严格 |
| P5 | test_smm2_nn_n_floor | smm2.nn N 下界=46 | 严格 |
| P6 | test_smm2_block_quant_g_size | 四 g_size 给四个不同值 | 严格（互异） |
| P7 | test_fixture_loadable | fixture 每 case 即时重算一致（防陈旧） | 严格 |
@tbl-g5cmtest-python-golden Python golden 锁定 case
端到端回归（继承既有严格断言）
test_cp_prefill_e2e.py / test_cp_decode_e2e.py / test_cp_overlap_metamorphic.py / test_adapter.py 验证计算建模改动（latency 含 t_mem）未破既有 CP 端到端：FLOPs 守恒严格 ==、total_time 相对比较、explicit==default。全 58 G5 Python 测试通过。
验收门槛与跑法
| 门槛 | 命令 | 通过标准 |
|---|---|---|
| Rust 全量 | cd perfmodel/evaluation/g5 && cargo test --lib | 460 passed |
| Rust 计算建模 | cargo test --lib tier3::tiu | 8 passed（含 golden 差分） |
| G5 Python | pytest tests/evaluation/g5/ | 58 passed |
| 共享模块回归 | pytest tests/ -k "chip or compute or math or aggregat or report" | 399 passed |
| 集成 | pytest tests/integration | 32 passed |
@tbl-g5cmtest-gates 验收门槛与跑法
改 Rust 后必须 maturin build --release + pip install wheel + 覆盖根目录 g5_rs.cp314-win_amd64.pyd（根目录副本遮蔽 site-packages）。
已知局限（test 不覆盖，spec 已声明）
- 绝对精度不验证：TPUPerf 常数未对硅、无真机锚点 → test 只验「翻译正确（==golden）」，不验「对硅正确」。绝对 TTFT/TPOT 由门控标 unvalidated。
- bank 冲突 B=0 stub：test 不覆盖真实 bank 冲突（首篇不建模，spec 已定）。
- nt/tt/smm2 端到端不打通：emitter 只发 nn；nt/tt/smm2 由 Rust 单测直接构造 TIUCommand 验证（spec 首篇边界）。
- 访存边绝对值：用峰值带宽占位（待 SRAM spec），test 验公式形态 + 带宽域标签，不验绝对访存时延。
维护信息
最后更新：2026-06-20。对应「G5-计算建模设计规格」v1.0.0 + 实现 plan 2026-06-20-G5计算建模CUBE矩阵乘.md。