CrossRing External Adapter 设计规格
版本：1.0.0 状态：Accepted 创建日期：2026-05-24 最后更新：2026-05-24 作者：xiang.li 前置：G5通信评估观测与结果存储设计规格, 互联通信延迟数学建模
版本号规则 (SemVer):
- major (X.0.0)：架构变更、接口不兼容、公式体系重构
- minor (1.X.0)：新增算子展开模式、新增 endpoint_id_scheme、扩展回填语义类别 （向后兼容）
- patch (1.0.X)：修正笔误、补充说明、更新 Implementation Notes
变更历史
| 版本 | 日期 | 变更说明 |
|---|---|---|
| 1.0.0 | 2026-05-24 | 初版：CrossRing DCIN 接口适配器、5 集合通信原语平坦 Ring 展开、transaction log 回填 EngineResult |
@tbl-cr-01 文档变更历史
Summary
为 Tier6-Model 接入 CrossRing 仿真器，提供 cycle-level NoC + D2D 仿真精度的通信评估路径。本 spec 定义进程内 import 模式下的 adapter 接口契约：将集合通信原语（AllReduce / AllGather / ReduceScatter / AllToAll / P2P）展开为 GDMA→DDR 读写事务的 inject 字典序列，按 tick-driven 闭环驱动 CrossRing 仿真模型，再把 transaction log 的事务级字段按语义类别回填到既有 EngineResult schema。MVP 锁定 DCIN mode 与单一默认场景，路径选择由上层决定，不在本 adapter 范围内。
Motivation
现状与问题
项目当前有两条通信评估路径：
- Math 代数模型：基于 Alpha-Beta / LogP 等闭式公式，单次评估开销极低，但精度受限于公式假设（稳态、均匀链路、独立 step）。
- G5 指令级仿真：事件驱动 Rust 仿真器，建模 link 竞争、CDMA outstanding、credit 流控，覆盖 Tier 3-5（Core / NoC / 互联层）。
缺口：Tier 4（NoC）在 G5 内是抽象 link 模型，未细化到 cycle-level 的 ring station / D2D AXI 行为。对多 die chiplet 设计而言，die 内 NoC 拥塞和跨 die D2D 反压会显著影响 GDMA→DDR 读写延迟分布，Math 与 G5 均无法精确捕获。
CrossRing 仿真器是外部项目，建模 ring station 拓扑 + DCIN 多 die D2D 路径，cycle-level 精度，且提供进程内 import 接口。接入 CrossRing 可补全 NoC + D2D 维度的仿真精度。
驱动力
- MoE 模型 EP AllToAll、PD 分离场景中，跨 die 写延迟对端到端 TPOT 影响显著，需要精确模型校准 Math/G5 在该域的偏差。
- 拓扑寻优器需要 cycle-level reference 数据点验证 Pareto 候选。
- CrossRing 已具备完整 transaction log（含 retry / block_count 等反压字段），是构造 NoC 反压可观测数据的高质量来源。
Terminology
| 名词 | 定义 |
|---|---|
| 仿真模型 | CrossRing 对外暴露的仿真器对象，进程内 import，构造时接受 config dict，按 tick 接收 inject 序列并返回 completed 事务 id |
| inject 字典 | tick 输入的最小单元，含请求 id、源端 id、目标端 id、读写标志、报文类型、burst 长度等字段，描述一次 GDMA↔DDR 读或写的请求或响应 |
| endpoint_id_scheme | 端点编号方案。决定逻辑 GDMA / DDR id 与物理 node id 的映射规则 |
| KCIN | CrossRing 单 die 仿真后端，建模 ring station 内的 NoC 行为 |
| DCIN | CrossRing 多 die 仿真后端，内部 vendored KCIN 处理 intra-die，外加 D2D AXI 通道处理 inter-die |
| 频率三件套 | driver_cycle / ip / noc 三个频率参数，共同决定外部 tick 与 internal cycle 的比例 |
| GDMA | General DMA，CrossRing 中 RN（Request Node）侧 IP |
| DDR | DDR SN（Slave Node）侧 IP |
| transaction log | CrossRing 每完成一笔事务输出一行 jsonl 的日志，记录 req/rsp 两阶段时间点和资源 block 计数 |
| inject-driven | 上层主动注入请求字典推进仿真，区别于 trace-driven（重放外部 pcap/trace 文件） |
@tbl-cr-02 Terminology
Goals / Non-Goals
Goals：
- G1：定义 adapter 接口契约，输入既有
CommPrimitiveSpec，输出符合既有EngineResultschema 的结构化结果，上层无需感知 CrossRing 内部细节。 - G2：覆盖 5 个集合通信原语（AllReduce / AllGather / ReduceScatter / AllToAll / P2P）的平坦 Ring / Pairwise 展开，提供从 (msg_size, participants) → inject 字典序列的确定性映射。
- G3：将 transaction log 的事务级字段按 4 类语义（时间指标 / 资源反压 / 物理元数据 / 内部 cycle 细节）回填到 EngineResult。
- G4：提供持久化缓存能力，相同输入跳过仿真。
- G5：约束 C1-C11 提供完整的输入校验和接口契约保护。
- G6：保证输出 EngineResult schema 与既有 Math / G5 两条路径完全对齐，使上层可做三路径横向对比与一致性校准（对比与调度本身由上层完成，本 adapter 仅负责输出格式对齐，见 NG2）。
Non-Goals：
- NG1：显式 KCIN / DCIN mode 切换给上层。MVP 全 DCIN，单 die 评估通过 DCIN 退化路径完成。
- NG2：路径选择策略（Math / G5 / CrossRing 之间如何挑选）。本 adapter 是其中一条路径的实现，调度由上层决定。
- NG3：MVP 默认场景之外的 die 数 / topology / endpoint_id_scheme（列为 Future Work）。
- NG4：Hierarchical collective decomposition（Tree、Halving-Doubling、SHARP-like、Bruck 等非平坦算法）。
- NG5：外部直接注入 data flit。CrossRing 限制：外部只允许注入 req/rsp，data 由内部生成。
- NG6：在 adapter 内重新实现 CrossRing 内部行为（资源管理、retry、pcredit、D2D tracker 由 CrossRing 自身处理，adapter 不绕过）。
Background / Prior Art
业界仿真器接入对比
| 维度 | ASTRA-sim 2.0 | SimAI | NCCL/RCCL 实测 | Chakra ET | CrossRing（本 spec 后端） |
|---|---|---|---|---|---|
| 仿真粒度 | mixed analytical + flit | packet trace replay | n/a（硬件实测） | n/a（标准格式） | cycle-level NoC + D2D |
| 算子表达 | Chakra ET 节点图 | NCCL traffic 还原 trace | Ring/Tree/CollNet 内置 | (comp_node, comm_node) DAG | inject 字典序列 |
| 驱动模式 | 内部图调度 | trace-driven | 内核执行 | trace 标准（不仿真） | inject-driven 闭环 |
| 多 dim collective | 显式 hierarchical 分解 | NCCL 算法决定 | NCCL 算法决定 | 描述能力强 | 平坦展开（MVP） |
| 与本 spec 契合度 | 高（hierarchical 借鉴方向） | 中（trace-driven 模式不同） | 中（Ring 算法继承） | 高（未来扩展参考标准） | 直接接入 |
@tbl-cr-03 业界仿真器接入对比
参考链接：
- ASTRA-sim 2.0 — 详见 7.2 ASTRA-sim
- SimAI — 详见 7.3 SimAI
- Chakra Execution Trace — MLCommons 标准
- NCCL Topology and Algorithms
项目内引用
- 集合通信理论下界 — Ring 字节量公式来源
- AllReduce Ring 算法 — 算法步数和分片大小定义
- 互联通信延迟数学建模 — Math 路径，本 spec 字节量公式继承自该 spec
- G5 通信评估观测 —
EngineResultschema 来源
本路径的差异化设计
- inject-driven 而非 trace-driven：在 Python 侧 online 展开 inject 字典并按 tick 推进，避免对预录 trace 的依赖，参数扫描时直接复用既有
CommPrimitiveSpec输入。 - 平坦 Ring 而非 hierarchical：MVP 只补 NoC + D2D 单层精度，hierarchical 由 Math 路径多 tier 公式覆盖。
- GDMA→DDR 业务语义压扁：CrossRing 的最小事务单位是 RN-SN 读写，集合通信的 reduce / gather 语义在 adapter 层映射为成对读写，CrossRing 内部不感知 collective 抽象。
Guide-Level Explanation
场景：N 个参与方 Ring AllReduce
假设 adapter 已实现。上层提交 CommPrimitiveSpec（primitive="allreduce"、algorithm="ring"、msg_size_bytes=M、participants 长度为 N、chip_spec_summary），返回 EngineResult。
1. 算子展开
算法步数 $T_{\text{steps}} = 2(N-1)$（RS + AG 串联），每步 chunk 大小 $M/N$，折算 burst 数 $b = \lceil (M/N) / F \rceil$。每步 N 个并发流（参与方 $i \to (i+1) \bmod N$），每流产出一个 write inject 字典（is_read=False、packet_type="req"、burst_length=b、src_id / dst_id 由 endpoint_id_scheme 映射）。request_id 全局唯一，编码方式由实现层决定。
2. tick-driven 闭环（伪代码，不绑定具体函数名）
model = create_crossring_model(adapter_config)
for step_injections in expand_to_inject_steps(spec):
feed step_injections; drive empty ticks until req-phase completions arrive
construct rsp injections (reverse src/dst, reuse request_id) for completed reqs
feed rsp injections; drive empty ticks until rsp-phase completions arrive
3. 回填 EngineResult
Adapter 读取 transaction log，按 request_id 聚合：aggregates.total_time_us 取 rsp_completed_tick 最大值换算；bus_bw_gb_per_s 取总通信字节 / 总时间；max_chip_latency_us / straggler_ratio 按参与方聚合；trace_meta 按语义类别回填反压汇总 / 物理元数据 / cycle 细节 / 日志路径。
4. 缓存
下次相同 (spec, adapter_config) 调用命中缓存，跳过 CrossRing 仿真。
Detailed Design
概念模型
Adapter 是一层翻译器，三层职责：
| 层级 | 输入 | 输出 | 职责 |
|---|---|---|---|
| L1 算子展开 | CommPrimitiveSpec | 按 step 分组的 inject 字典序列 | 5 原语 × 算法 → 每步并发流 → inject 字典 |
| L2 闭环驱动 | inject 序列 + 仿真模型 | transaction log | tick 推进、req/rsp 两阶段编排、空 tick 等待完成 |
| L3 回填映射 | transaction log 事务字段 | EngineResult | 按语义类别映射、按参与方聚合 |
@tbl-cr-04 Adapter 层次结构
缓存层独立于上述三层，以 （spec 关键字段，adapter_config, adapter_version） 派生 cache key，命中时直接反序列化 EngineResult。
设计原理
- 全 DCIN（不暴露 KCIN/DCIN 切换）：暴露切换让配置 + 测试矩阵翻倍且易行为漂移；DCIN 在单 die 退化下与 KCIN 等价，单 die 评估通过 DCIN intra-die 完成。
- 集合通信压扁成 GDMA→DDR：CrossRing 的最小事务单位是 RN-SN 读写，不感知 collective 语义；reduce / gather 本质是多参与方相互读写片上 DDR，压扁为成对读写保留通信流量与延迟特征，且 adapter 不侵入 CrossRing 内核。
- inject-driven 而非 trace-driven：trace-driven 需预生成 NCCL trace 并管理格式版本；项目已有
CommPrimitiveSpec，inject-driven 直接复用，参数扫描时每次重新展开即可。 - rsp 是触发信号：rsp 注入触发目标 SN 内部生成 data burst，真实 data flit 由内部生成；adapter 视角下 rsp 只复用 req 的 request_id 并反向 src/dst。
- adapter 主动收紧契约：CrossRing 上游接口允许大部分字段默认值（构造
PythonNocModel()无参可工作）；本 adapter 主动要求所有 §接口参数 字段必填，原因是项目config-loading规则禁止默认值兜底（缺字段必须 raise）。"必填"是 adapter 层契约，不是 CrossRing 上游要求。
算子展开规则
5 原语 inject 模式
| 原语 | 算法 | 步数 | 每步并发流数 | 每流 chunk 字节 | inject 方向 |
|---|---|---|---|---|---|
| AllReduce | Ring | $2(N-1)$ | $N$ | $M/N$ | write |
| AllGather | Ring | $N-1$ | $N$ | $M/N$ | write |
| ReduceScatter | Ring | $N-1$ | $N$ | $M/N$ | write |
| AllToAll | Pairwise | $N-1$ | $N$ | $M/N$ | write |
| P2P | 直接 | $1$ | $1$ | $M$ | read 或 write |
@tbl-cr-05 5 原语 inject 模式
因为 CrossRing 下层 NoC 无 reduce 语义，AllReduce 的 RS + AG 串联在 adapter 层统一展开成 write 流量；AllToAll 第 $t$ 步参与方 $i \to (i+t+1) \bmod N$，每步目标不同。
step 同步语义：Ring 类算法第 $t+1$ 步的 chunk 计算依赖第 $t$ 步的传输完成（reduce/scatter 链的因果约束），adapter 必须等第 $t$ 步所有 inject 的事务最终完成（即 rsp 阶段完成，不只是 req 阶段完成）才能开始第 $t+1$ 步的 inject。CrossRing 每个事务返回两次 request_id（req 阶段 + 最终完成），step boundary 以最终完成为准；不允许跨 step pipeline overlap（如需 overlap 由 Future Work 引入新展开模式）。
字节量公式（继承）
第 $t$ 步流 $i$ 的 chunk 大小：
$$\begin{equation} M_{\text{chunk}} = \frac{M}{N} \label{eq:cr-chunk-size} \end{equation}$$其中 $M$ 为全量数据（见 互联通信延迟数学建模），$N$ 为参与方个数。
每 chunk 拆解为两步：先算 FLIT 数，再按事务 burst_length 拆事务。
step 1 — chunk 折算 FLIT 数：
$$\begin{equation} n_{\text{flits}} = \left\lceil \frac{M_{\text{chunk}}}{F} \right\rceil \label{eq:cr-flits-from-chunk} \end{equation}$$其中 $F$ 为单 FLIT 字节数（由 bw_bytes 参数指定）。
step 2 — FLIT 数按事务 burst_length 拆事务：
$$\begin{equation} n_{\text{txn}} = \left\lceil \frac{n_{\text{flits}}}{L_{\text{burst}}} \right\rceil \label{eq:cr-txn-from-flits} \end{equation}$$其中 $L_{\text{burst}}$ 为单事务 burst 长度（由 burst_length 参数指定，单位 FLIT 数）；CrossRing 一次事务最多承载 $L_{\text{burst}}$ 个 FLIT，故一个 chunk 需要 $n_{\text{txn}}$ 次 inject 才能传完。spec 不固化 $L_{\text{burst}}$ 上限，由 CrossRing 实际配置决定。
名词澄清：burst_length 是「一次事务承载的 FLIT 数」；inject 字典对应的是事务（一次事务一个 inject 字典）；同一并发流的多事务在 spec 层只描述总数 $n_{\text{txn}}$，并发流间编排由实现层决定。
总通信字节数（用于带宽计算）：
| 原语 | 总字节 |
|---|---|
| AllReduce Ring | $\frac{2(N-1)}{N} \cdot M$ |
| AllGather Ring | $\frac{N-1}{N} \cdot M$ |
| ReduceScatter Ring | $\frac{N-1}{N} \cdot M$ |
| AllToAll Pairwise | $\frac{N-1}{N} \cdot M$ |
| P2P | $M$ |
@tbl-cr-06 总通信字节数
参与方到 endpoint 的具体 id 映射由 endpoint_id_scheme 决定。实际可用的逻辑 GDMA / DDR id 范围以 CrossRing 当前配置为准。spec 对此层只要求满足约束 C5 / C6。
接口参数契约语义
Adapter 构造参数（语义描述，取值范围由 CrossRing 当前配置决定）：
| 字段 | 语义 | 必填 |
|---|---|---|
mode | 仿真后端 mode；MVP 固定为 "dcin" | 是 |
topology | ring station 拓扑形态 | 是 |
num_dies | die 数量 | 是 |
dcin_layout | DCIN 多 die 物理排布 | 是 |
endpoint_id_scheme | 端点编号方案；决定逻辑 id 到物理 node 的映射规则 | 是 |
num_initiators | 逻辑 GDMA 端点总数；必须与 scheme 一致 | 是 |
num_targets | 逻辑 DDR 端点总数；必须与 scheme 一致 | 是 |
driver_cycle_frequency_ghz | 外部 tick 频率；决定 tick → ns 换算 | 是 |
ip_frequency_ghz | IP 域内部频率 | 是 |
noc_frequency_ghz | NoC 域内部频率 | 是 |
mst_rd_outstanding | 逻辑 GDMA 读 outstanding；必须偶数（CrossRing 双 GDMA 轮询要求） | 是 |
mst_wr_outstanding | 逻辑 GDMA 写 outstanding；必须偶数 | 是 |
slv_rd_outstanding | DDR 物理级读 outstanding | 是 |
slv_wr_outstanding | DDR 物理级写 outstanding | 是 |
burst_length | 默认事务 burst 长度（单位：burst） | 是 |
bw_bytes | FLIT 字节数 | 是 |
enable_transaction_log | 必须为真，否则回填阶段无数据 | 是 |
transaction_log_path | 输出 jsonl 路径；由 adapter 按 cache key 派生 | 是 |
@tbl-cr-07 Adapter 构造参数契约
CommPrimitiveSpec 输入要求：
| 字段 | 要求 |
|---|---|
primitive | ∈ {"allreduce", "allgather", "reducescatter", "alltoall", "p2p"} |
algorithm | "ring" 或 "pairwise"（仅 alltoall）；其他算法拒绝（见 C11） |
msg_size_bytes | 正整数 |
participants | 逻辑 GDMA id 列表；元素互不重复（C5） |
dtype | 仅元数据记录，不影响展开 |
chip_spec_summary | dict；用于 cache key 与频率三件套来源 |
@tbl-cr-08 CommPrimitiveSpec 输入要求
输入翻译契约
算子展开返回值结构：按 step 分组的 inject 字典序列（外层一个 step 一项，内层为该 step 的并发流 inject 字典列表）。
inject 字典字段严格按 CrossRing 仿真模型对外接收的格式构造，含义：
| 字段 | 语义 |
|---|---|
| 请求 id | 全局唯一，且在同 step 内不重复（C6 前置） |
| 源端 id | 逻辑 GDMA id |
| 目标端 id | 逻辑 DDR id |
| 读写标志 | bool |
| 报文类型 | "req" 或 "rsp"（"data" 禁用，见 C9） |
| burst 长度 | 单事务 burst 数 |
rsp inject 由 adapter 在 req 完成后构造（反向 src/dst + 复用同 request_id），不属于算子展开返回值。
输出翻译契约
CrossRing transaction log 的事务级字段按 4 类语义回填到 EngineResult。具体 trace_meta 子键由 EngineResult schema spec 演进决定，本 spec 只锁定语义类别。
类别 1：时间指标（驱动 aggregates 主要字段）
包含 req 注入 tick、req 完成 tick、rsp 注入 tick、rsp 完成 tick。按以下公式聚合：
| 派生字段 | 计算 |
|---|---|
total_time_us | $\max_r(\text{rsp\_completed\_tick}_r) / f_{\text{driver}}$ 换算到 μs |
req_phase_us | 事务级 req 阶段总耗时（队列 + NoC 传输），由 req_completed - req_arrival 换算累加 |
rsp_phase_us | 事务级 rsp 阶段总耗时（含 D2D），由 rsp_completed - rsp_arrival 换算累加 |
max_chip_latency_us | 按参与方聚合：每个参与方上 rsp_completed 的最大值，再取所有参与方的最大 |
straggler_ratio | $\max_i T_i / \mathrm{median}_i T_i$，定义同 G5 观测 spec |
bus_bw_gb_per_s | 总通信字节数 / total_time_us（按 @tbl-cr-06 的总字节） |
total_comm_bytes | 按 @tbl-cr-06 |
algorithm_steps | $T_{\text{steps}}$ |
@tbl-cr-09 时间指标派生字段
类别 2：资源反压（汇总到 trace_meta）
包含 retry 计数、各类 block_count（RN 读阻塞 / RN 写阻塞 / RN 读写 databuffer 阻塞 / SN read-only tracker / SN share tracker / SN 写 databuffer / D2D 对应三类 SN tracker）。按事务汇总到 trace_meta 的反压语义分组，用于反压分析。
类别 3：物理元数据（事务级保留到 trace_meta）
包含源端 id、目标端 id、源 die、目标 die、读写标志、burst 长度。事务级保留供横切分析（如按 die 对统计 D2D 流量）。
类别 4：内部 cycle 细节（trace_meta 调试用）
包含 req 注入 cycle、写 data 生成 cycle、req 完成 cycle、rsp 注入 cycle、写 data 完成 cycle、rsp 完成 cycle。直接保留为调试细节。
trace_meta 中同时记录：仿真引擎标识（"crossring"）、transaction log 文件路径、参与方汇总元信息。
约束与规则
| 编号 | 约束 | 来源 |
|---|---|---|
| C1 | mode 固定为 "dcin"，其他值拒绝 | MVP 范围 |
| C2 | topology / num_dies / dcin_layout 三元组必须严格一致 | MVP 范围 |
| C3 | endpoint_id_scheme 固定为 MVP scheme；num_initiators / num_targets 必须与 scheme 一致 | MVP 范围 |
| C4 | mst_rd_outstanding / mst_wr_outstanding 必须为偶数 | CrossRing 双 GDMA 轮询要求 |
| C5 | spec.participants 元素互不重复 | 同步释放并发约束 |
| C6 | 同一 step 内所有 inject 的目标端 id 互不重复 | 接口层歧义防护 |
| C7 | 频率三件套必填，无默认值兜底 | 时间换算前提 |
| C8 | enable_transaction_log 必须为真 | 回填前提 |
| C9 | inject 报文类型只允许 "req" 或 "rsp"，禁止 "data" | CrossRing 限制 |
| C10 | rsp inject 的源/目标必须严格反向匹配原 req，且复用相同 request_id | CrossRing 契约 |
| C11 | MVP 仅支持 Ring（AR/AG/RS）和 Pairwise（AllToAll）算法 | MVP 范围 |
@tbl-cr-10 约束与规则
违反任一约束时 adapter 拒绝执行（具体错误类型与错误消息文案由实现层决定，要求附充分上下文便于排查）。
缓存策略
cache key 派生输入（语义层面）：
- adapter 构造参数（@tbl-cr-07 全部字段）
spec.primitive/spec.algorithm/spec.msg_size_bytes/spec.dtype- 参与方相关：参与方个数 + 参与方排序后列表（对称 collective 顺序无关；AllToAll 严格顺序敏感性见 Limitations）
spec.chip_spec_summary- adapter spec 版本号（用于 spec 演进时整体失效旧缓存）
key 生成方式由实现层决定，要求满足：相同语义输入产生相同 key；任一字段变化产生不同 key；序列化稳定（不依赖字段顺序）。
缓存命中：直接反序列化 EngineResult，跳过 CrossRing 调用。缓存未命中：仿真完成后写入持久化文件。缓存文件损坏自动失效并重新仿真。
与 G5 / Math 共存
本 adapter 是 Tier6 通信评估的三条路径之一（另两条为 Math 代数模型和 G5 指令级仿真）。路径选择由上层根据场景需求决定，不在本 spec 范围内。三路径产出统一遵循 EngineResult schema，trace_meta 中以引擎标识区分来源，便于上层做横向对比；上层对比工具按 (primitive, algorithm, msg_size, num_participants, topology) 五元组对齐。
Cross-cutting Concerns
| 维度 | 本 spec 的考虑 |
|---|---|
| Security | 进程内 import，无网络暴露，无敏感字段。CrossRing 项目源码由开发者自行管理可信。 |
| Privacy | 不涉及用户数据，transaction log 仅含仿真元数据。 |
| Observability | 三类输出：transaction log（事务级 jsonl）、timing log（外部 tick 开销）、runtime config dump（实际生效参数）。所有路径由 adapter 按 cache key 派生归档，EngineResult.trace_meta 记录日志文件路径供前端关联查询。 |
| Performance | 性能预算（adapter 翻译开销 / 缓存命中耗时 / 单次仿真耗时）由实现层 benchmark 确定，不在 spec 锁定数值；spec 仅要求缓存命中路径明显快于未命中路径。 |
| Reliability | CrossRing 内部异常 → adapter wrap 后抛出，附 CommPrimitiveSpec 上下文。tick 死锁（连续空 tick 无 completion 推进）超时拒绝；超时阈值由实现层配置。 |
| Compatibility | 输出复用既有 EngineResult schema 完全向后兼容。CrossRing 上游字段变更通过 spec 版本号失效旧缓存。 |
@tbl-cr-11 Cross-cutting Concerns
Alternatives Considered
A1 KCIN vs DCIN mode 选择
| 维度 | DCIN（选定） | 显式 KCIN/DCIN 切换 |
|---|---|---|
| 单 die 仿真 | DCIN 退化覆盖 | KCIN 直接覆盖 |
| 多 die 仿真 | DCIN 内部 KCIN + D2D | 必须 DCIN |
| 接口复杂度 | 单一入口 | 双入口 + mode 切换 |
| 测试矩阵 | 1 套配置 | 2 套配置 |
| 工程一致性 | 高 | 易漂移 |
否决理由：显式 KCIN/DCIN 切换会让配置矩阵翻倍且容易在两种 mode 之间出现行为漂移；DCIN 在单 die 退化场景下与 KCIN 等价。
A2 算子展开层位置
| 维度 | adapter 层展开（选定） | CrossRing 内构造 collective 抽象 | trace 文件预生成 |
|---|---|---|---|
| CrossRing 侵入度 | 0 | 高（需改 CrossRing 内部） | 0 |
| 算法演进灵活性 | 高（Python 层） | 低（双侧改动） | 中（trace 格式版本管理） |
与既有 CommPrimitiveSpec 复用 | 直接复用 | 需新抽象 | trace 格式独立 |
否决理由：CrossRing 内构造 collective 抽象侵入度高且与既有 CommPrimitiveSpec 不复用；trace 文件预生成引入格式版本管理负担。adapter 层展开零侵入且复用既有抽象。
A3 inject-driven vs trace-driven
| 维度 | inject-driven（选定） | trace-driven |
|---|---|---|
| 输入来源 | CommPrimitiveSpec online 展开 | 预生成 NCCL trace |
| trace 格式管理 | 不需要 | 需要版本管理 |
| 参数扫描 | 每次重新展开 | 每参数组合一份 trace |
| 真实负载还原度 | 算法级 | 高（重放真实 NCCL 内核行为） |
否决理由：trace-driven 需要预生成大量 trace 并管理版本，且与既有 CommPrimitiveSpec 抽象不兼容；inject-driven 牺牲少量真实负载还原度换取直接复用项目既有抽象的工程优势。
Limitations & Future Work
Limitations
| 限制 | 影响 | 缓解措施 |
|---|---|---|
| MVP 单一默认场景硬绑定 | 其他 chip / topology / die 数无法直接评估 | 路径选择层 fallback 到 G5 / Math；多场景扩展见 Future Work |
| 外部不允许注入 data | reduce 计算开销不在仿真路径内 | 不影响通信延迟主导场景；compute overlap 场景在上层 Gantt 报告中显式叠加 |
| rsp 是触发信号 | rsp 真实路径行为由 CrossRing 内部决定 | adapter 不绕过 CrossRing 资源管理 |
| 平坦 Ring 展开 | hierarchical decomposition 精度不足 | Math 路径多 tier 公式覆盖；CrossRing 路径专注 NoC + D2D 单层精度 |
| AllToAll 缓存 key 用排序后参与方 | 不同顺序的 AllToAll 共享缓存（不严格） | MVP 简化；精确 AllToAll cache 列入 Future Work |
| inject 字典展开是算法级而非 NCCL 内核级 | 与真实 NCCL 行为可能有差异 | 三路径对比验证；与硬件实测校准 |
@tbl-cr-12 Limitations
Future Work
| 方向 | 优先级 | 前置条件 |
|---|---|---|
| 多 die 数 / topology 扩展 | 高 | CrossRing 上游支持 + endpoint_id_scheme 扩展 |
| 显式 KCIN mode | 中 | 精细单 die 仿真需求出现 |
| Hierarchical collective decomposition | 中 | Tree / Halving-Doubling 算法实现 |
| 外部 data 注入支持 | 低 | CrossRing 上游放开限制 |
| Chakra ET 输入格式 | 低 | Chakra ET 标准在项目内推广 |
| AllToAll cache key 精确化 | 低 | AllToAll 评估场景增多 |
@tbl-cr-13 Future Work
Success Criteria
每条描述"必须验证什么"，数值目标由实现层 benchmark 校准后回填到 Implementation Notes。
| 验证项 | 必须验证什么 | 测试方法 |
|---|---|---|
| 5 原语展开正确性 | 每个原语在多个 $N$ 值下产出 EngineResult，algorithm_steps 与每步并发流数符合 @tbl-cr-05 | 确定性单元测试 |
| 总通信字节正确性 | 每个原语 total_comm_bytes 与 @tbl-cr-06 公式一致 | 确定性单元测试 |
| 4 类语义回填 | 时间指标驱动 aggregates / 资源反压汇总到 trace_meta / 物理元数据事务级保留 / 内部 cycle 细节保留 | mock transaction log 单元测试 |
| 缓存命中与失效 | 相同输入命中且结果一致；adapter 版本号或任一 key 输入变更后不命中 | 单元 + 集成测试 |
| 约束 C1-C11 拒绝 | 每条约束有独立测试用例覆盖违反路径 | 单元测试 |
| 跨路径一致性 | 大消息 AllReduce 场景下 CrossRing 与 G5 / Math 的 total_time_us 一致性可计算（阈值在 Implementation Notes 校准） | 集成测试 |
| tick 死锁防护 | 连续空 tick 无 completion 推进时超时拒绝 | 单元测试 |
@tbl-cr-14 Success Criteria
Implementation Notes
本节在实现完成后补充，记录 spec 与实际实现的偏差。包括但不限于：实测的性能预算数值、cross-path 一致性 RMSPE 实测值、tick 死锁超时阈值、burst_length 单事务上限的实测值与切分策略。