G5 指令级仿真模块 Code Review 问题清单
审查时间: 2026-04-13 审查范围:
perfmodel/evaluation/g5/(Python 层 + Rust 后端) 总计: ~9,200 行 Rust + ~450 行 Python
一、违反 config-loading 规则（禁止默认值）
impl Default 块中的硬编码默认值
所有 impl Default 块应改为从配置文件加载，不允许硬编码默认值。
| ID | 文件 | 结构体 | 硬编码参数数量 | 关键参数 |
|---|---|---|---|---|
| CL-01 | src/tier6/rc_link_tx.rs:41-56 | RcLinkTxConfig | 11 | retry_timeout_ns=50000, overcredit_limit=512 |
| CL-02 | src/tier6/rc_link_rx.rs:25-36 | RcLinkRxConfig | 6 | merge_depth=64, poll_cycle_ns=4.0 |
| CL-03 | src/tier6/rc_link_tx.rs:99-110 | DcqcnConfig | 6 | byte_threshold=150KB, timer_interval_ns=55000 |
| CL-04 | src/tier6/switch.rs:40-55 | SwitchConfig | 10 | forwarding_latency_ns=30, buffer_capacity=16MB |
| CL-05 | src/tier6/paxi_core.rs:21-30 | PaxiCoreConfig | 4 | w_ost_limit=256, mps=4096, max_payload=1344 |
const 硬编码常量
| ID | 文件 | 常量名 | 值 | 应来源 |
|---|---|---|---|---|
| CL-06 | src/tier3/tiu.rs:15 | TIU_INIT_CYCLES | 44 | Chip config |
| CL-07 | src/top/multi_chip.rs:25 | INITIAL_CREDIT | 1024 | Protocol config |
| CL-08 | src/top/multi_chip.rs:26 | ACK_WIRE_BYTES | 50 | Protocol config |
| CL-09 | src/tier6/rc_link_tx.rs:16 | DATAPATH_BYTES | 64.0 | Chip config |
| CL-10 | src/tier6/rc_link_rx.rs:52 | CNP_INTERVAL_NS | 50000.0 | Protocol config |
| CL-11 | src/collective/*.rs (4 文件) | DEFAULT_THREADS_PER_CDMA | 8 | Chip CDMA config |
| CL-12 | src/top/event_handlers.rs:288 | CNP wire bytes | 64 | Protocol config |
静默默认值
| ID | 文件 | 位置 | 问题 |
|---|---|---|---|
| CL-13 | src/input.rs:173 | c2c_ports_per_chip | 缺失时静默默认为 1，应报错 |
| CL-14 | src/input.rs:549 | parse_map_u32_u32 | 缺失时静默返回空 HashMap |
二、违反 code-style 规则（函数/文件长度与嵌套深度）
文件过长 (>300 行)
| ID | 文件 | 行数 | 建议 |
|---|---|---|---|
| CS-01 | src/tier6/rc_link_tx.rs | 901 | 拆分 DCQCN/CBFC/Slot 为独立模块 |
| CS-02 | src/input.rs | 696 | 拆分为 chip/topology/program 子模块 |
| CS-03 | src/collective/allreduce.rs | 652 | 三种算法拆为独立文件 |
| CS-04 | src/tier3/cdma.rs | 536 | |
| CS-05 | src/top/event_handlers.rs | 522 |
函数过长 (>50 行) — 前 5 严重
| ID | 文件 | 函数 | 行数 | 嵌套深度 |
|---|---|---|---|---|
| CS-06 | src/top/multi_chip.rs | simulate() | 195 | 9 |
| CS-07 | src/collective/allreduce.rs | expand_halving_doubling_allreduce() | 167 | 5 |
| CS-08 | src/top/single_chip.rs | simulate() | 132 | 6 |
| CS-09 | src/tier3/cdma.rs | try_arbitrate() | 109 | 6 |
| CS-10 | src/top/multi_chip.rs | init_components() | 92 | 7 |
三、违反 code-comments 规则（注释应以中文为主）
| ID | 文件 | 英文注释数 | 中文注释数 | 严重程度 |
|---|---|---|---|---|
| CC-01 | src/tier3/tiu.rs | 11 | 3 | 严重（几乎全英文） |
| CC-02 | src/tier6/rc_link_tx.rs | 51 | 48 | 混杂 |
| CC-03 | src/collective/allreduce.rs | 33 | 40 | 混杂 |
| CC-04 | src/input.rs | 26 | 22 | 英文偏多 |
| CC-05 | src/tier6/paxi_core.rs | 24 | 19 | 英文偏多 |
四、错误处理问题（panic 代替 Result）
| ID | 文件 | 位置 | panic 原因 | 建议 |
|---|---|---|---|---|
| EH-01 | src/tier4/bus.rs:22-26 | NoC mesh 校验 | panic!("Mesh cannot hold cores") | 返回 Result，PyO3 边界转 PyErr |
| EH-02 | src/tier3/core_subsys.rs:66 | 缺少 GDMA 配置 | unwrap_or_else(|| panic!(...)) | 同上 |
| EH-03 | src/kernel/sim_kernel.rs:99-101 | 调度过去时间 | panic! | 同上 |
| EH-04 | src/tier3/tiu.rs:41 | ch_per_cyc=0 | 除零 panic | 前置校验 |
| EH-05 | src/tier6/rc_link_tx.rs:283 | credit underflow | 仅 debug_assert! | 改为 assert! 或运行时检查 |
五、设计与正确性问题
event_handlers 字符串传递包上下文
| ID | 文件 | 问题 |
|---|---|---|
| DE-01 | src/top/event_handlers.rs:130-176 | 包元数据编码为 "src:dst:slot:psn:bytes:txn:qp:vc" 字符串，解析失败时静默 continue。应改用 PacketContext 结构体。 |
hierarchical.rs 空命令列表导致竞争条件
| ID | 文件 | 问题 |
|---|---|---|
| DE-02 | src/collective/hierarchical.rs:42 | cmds 为空时存入 u32::MAX (NO_DEP)，下一维度命令无依赖约束，可能导致执行顺序错乱。 |
Go-Back-N 粒度过粗
| ID | 文件 | 问题 |
|---|---|---|
| DE-03 | src/tier6/rc_link_tx.rs | NAK 触发时对该目标的所有 QP 执行 Go-Back-N，而非仅重传出错 QP。影响仿真精度。 |
DCQCN 未完整实现
| ID | 文件 | 问题 |
|---|---|---|
| DE-04 | src/tier6/rc_link_tx.rs | DCQCN 状态机框架已有，但速率限制未在 TX 路径实际执行（仅注释）。 |
AllReduce chunk 计算语义不清
| ID | 文件 | 问题 |
|---|---|---|
| DE-05 | src/collective/allreduce.rs:18 | chunk_bytes = data_bytes / (N * num_chunks) 在 num_chunks > 1 时语义不够清晰。 |
CDMA 与 SDMA 混淆统计
| ID | 文件 | 问题 |
|---|---|---|
| DE-06 | adapter.py:94-96 | CDMA 记录被归入 sdma_duration_ns，C2C 通信和片内 SDMA 混为一体，应单独统计。 |
六、Python 层问题
| ID | 文件 | 问题 |
|---|---|---|
| PY-01 | sim_engine.py:62-67 | simulate_multi_chip 的 program, network_graph 参数缺少类型标注 |
| PY-02 | pipeline.py:33-34 | docstring 标注 network_graph/routing_table "暂未使用"，但 sim_engine 已在用，docstring 过时 |
| PY-03 | adapter.py:107-112 | 瓶颈判断：wait_ns < 0 (overlap 场景) 未单独处理 |
七、输入校验不足
| ID | 文件 | 问题 |
|---|---|---|
| IV-01 | src/input.rs:294-299 | operand_addrs 无边界/对齐校验 |
| IV-02 | src/input.rs:361-377 | Hierarchical dimension 的 group 结构无校验（空组、重复 core_id） |
| IV-03 | src/input_parse.rs | 枚举解析方式不一致（有的用 .getattr("name")，有的直接读字符串） |
八、测试覆盖不足
| ID | 问题 |
|---|---|
| TC-01 | tests/g5/ 目录不存在，无专门 G5 测试套件 |
| TC-02 | 缺少 PyO3 序列化/反序列化 roundtrip 测试 |
| TC-03 | 缺少输入校验边界条件测试 |
| TC-04 | 缺少多芯片 PAXI 协议端到端测试 |
| TC-05 | 缺少集合通信算法正确性对比测试 |
修复状态
已修复 (2026-04-13)
- P0: EH-01~05 — panic 改为 Result/自动修正 (bus.rs, core_subsys.rs, sim_kernel.rs, tiu.rs, rc_link_tx.rs)
- P0: DE-01 — event_handlers 字符串上下文改为 PacketContext 结构体
- P0: DE-02 — hierarchical.rs 空命令列表 bug 修复 (drain 前记录 max_id)
- P0: CL-13 — c2c_ports_per_chip 缺失时报错而非静默默认
- P0: CL-14 — 缺失 map 时添加日志提示
- P1: CL-06 — TIU_INIT_CYCLES 改为从 ChipSpec.tiu_init_cycles 读取
- P1: CL-07/08 — INITIAL_CREDIT/ACK_WIRE_BYTES 改为 MultiChipSim 实例参数
- P2: PY-01 — sim_engine.py 添加类型标注
- P2: PY-02 — pipeline.py docstring 更新
- P2: PY-03 — adapter.py 瓶颈判断 overlap 场景修复
- P2: DE-06 — CDMA 独立于 SDMA 统计
- P3: CC-01~05 — 核心代码注释已中文化，协议术语保留英文
待修复
- P1: CL-01~05 — PAXI/Switch/DCQCN impl Default 块参数化 (已标注 TODO)
- P1: CL-09~12 — 其他 const 参数化 (DATAPATH_BYTES 等, 已标注 TODO)
- P1: CL-11 — DEFAULT_THREADS_PER_CDMA 参数化 (已标注 TODO)
- P2: CS-01~10 — 文件/函数过长问题 (需拆分重构)
- P3: IV-01~03 — 输入校验补充
- P4: DE-03~05 — Go-Back-N 粒度、DCQCN 完整实现、chunk 语义
- P4: TC-01~05 — 测试覆盖补充