# CLT LLVM 语义映射能力盘点

> 盘点日期：2026-08-28
> 项目基线：`operator-ub-sim` 分支 `feat/operator-ub-sim-v0.1`，提交
> `612365a5ed9d8cd8d87f1deb30764a1b6dca1b25`
> CLT 基线：`third_party/collective-llvm-trace` gitlink
> `4945cf9270c0cbaeb65a6750602023c73eb6b5b8`，分支 `dev`
> 结论类型：代码和现有测试/fixture 证据盘点，不是性能或硬件准确性声明。

## 摘要

当前 CLT 不是把任意 LLVM IR 原样翻译成一个仿真格式的转换器。它是一套有边界的
LLVM 分析、绑定、具体执行和器件语义提取系统：

```text
.bc/.ll
  -> StaticKernelIR                 # 静态 CFG、SSA、类型、intrinsic、原始 IR
  -> BoundCaseIR                    # rank/block、ABI 参数、内存区域和资源绑定
  -> CoreExecutionIR[]              # 每个 core instance 的实际路径和观察
  -> CollectiveTraceIR              # 设备 action、同步、通信请求和完整依赖
       |-> SourceExecutionIR       # invocation/launch/kernel/action 归属
       `-> RequestFlowIR            # 网络请求及 issue/completion 偏序
```

CLT 因此能实现的核心能力是：在指定 chip dialect、ABI profile、kernel entry、
launch 和内存绑定下，解释受支持的 LLVM 构造，并把设备数据搬运、地址/内存归属、
同步、轮询、LDST 请求以及 C220 HCOMM URMA 队列证据形成结构化 IR。

C310 CTP 当前还有一个 CLT 内的专用 authoritative extraction 入口。它从物化的
C310 LLVM 文本中确认 `Hcomm<COMM_PROTOCOL_UBC_CTP>` 的调用和数据流，输出
`collective-llvm-trace/c310-ctp-authoritative-extraction/v2`。它是 CLT 的一个实现
路径，不应被误写成已经生成通用 `CollectiveTraceIR` 或 `RequestFlowIR`。

当前没有证据表明 CLT 能从高层 LLVM 或项目名称自动恢复完整的 HCCL collective、
MoE 路由、专家计算或 OPS 算子语义。那些语义必须有明确的 ABI、调用绑定、case 或
外部源码证据才能建立归属。

## 1. 范围和判定口径

### 1.1 正式范围

- 只分析当前 `operator-ub-sim` 工作区实际引用的 vendored CLT；相邻的
  `../collective-llvm-trace` checkout 仅作背景，不扩大本报告结论。
- 来源项目维度限定为 HCOMM、HCCL 和仓库内 `ops-transformer`。项目名、Host API、
  Python wrapper、算子定义或源码本身不是 LLVM 产物。
- 输入范围是从配置的 device kernel entry 可达的 `.bc`/`.ll`；Host 逻辑只作为
  `BoundCaseIR` 的绑定上下文。
- 只把能进入一个 CLT 目标 IR 的 handler 作为“已实现”。孤立函数、未注册 dialect、
  未接入 executor/lowerer 的代码单列为不可达或实验能力。

### 1.2 两个完整度维度

| 维度 | 判定 | 不包含 |
| --- | --- | --- |
| CLT 提取完整度 | 源语义贯通 LLVM 表现并进入 CLT 目标 IR | 下游是否消费、NS-3 是否运行 |
| 仿真链路完整度 | CLT 语义经过 operator-ub-sim 归一化/投影并进入 NS-3 输入 | NS-3 内部时序、性能和硬件准确性 |

实现状态使用 `完整映射`、`部分映射`、`仅声明/不可达`、`未发现`。验证等级使用
`实际运行`、`测试/fixture`、`静态代码追踪`、`无法验证`。

### 1.3 映射粒度

一条映射可以是单个 intrinsic，也可以是多个 LLVM 构造的组合：

```text
LLVM 构造（或构造组合）
  -> executor/dialect/lowering 规则
  -> CLT IR 语义
```

例如，C220 URMA 不是一个 intrinsic 直接产生的结果；descriptor stores、cache
maintenance、doorbell、queue-head update 和地址/长度证据由协议 recognizer 组合成
一个通信请求及其队列 action。

### 1.4 HCOMM 源码来源与证据等级

本报告把 HCOMM 相关证据分成“源码语义”“已编译/安装文件”和“CLT artifact
提取”三层，不能把三层混写成一个结论。用户指定的 `~/workspace/hcomm` 在本次
环境中不存在；实际可见的 HCOMM checkout 是相对于 `~/workspace` 的
`cann_gitcode/hcomm`，其 `master` 分支提交为
`19541b172be3f2c76692bcb9309a66d8f70365a3`，worktree clean。以下路径均相对于各自
标注的源码根目录，不使用机器绝对路径。

| 来源层 | 根目录 | 代表性相对路径 | 能证明什么 | 不能单独证明什么 |
| --- | --- | --- | --- | --- |
| HCOMM public API/数据类型 | HCOMM checkout（`~/workspace/cann_gitcode/hcomm`） | `include/hcomm_primitives.h`（`WriteNbi` 约第 327 行、`ReadNbi` 约第 379 行、`Drain` 约第 547 行）；`include/hcomm_res_defs.h`；`docs/zh/api_ref/comm_opdev/datatype_definition/CommProtocol.md` | `WriteNbi`/`ReadNbi`/`Drain` 的接口契约、`COMM_PROTOCOL_UBC_CTP` 值、endpoint/channel 描述 | 某个 LLVM artifact 是否调用了这些接口，或 CLT 是否已匹配成功 |
| HCOMM host/control-plane | 同一 HCOMM checkout | `src/base_comm/resources/endpoints/endpoint.cc`；`src/base_comm/resources/endpoint_pairs/channels/aiv/aiv_channel_helper.cc`；`src/base_comm/resources/endpoint_pairs/channels/aiv/aiv_urma_channel.cc`；`src/coll_communicator_mgr/api_c_adpt/coll_comm_res_c_adpt.cc` | CTP device/host endpoint 到 URMA endpoint 的选择、channel entity、SQ/CQ/queue-index 资源准备和 CTP channel 转换 | device kernel 中具体 SQE 字段、LLVM 行号或一次成功的 CLT extraction |
| HCOMM legacy AIV/URMA kernel source | 同一 HCOMM checkout | `src/legacy/ascend910/algorithm/base/alg_aiv_template/aiv_communication_base.h`；`src/legacy/ascend910/algorithm/base/alg_aiv_template/all_to_all/aiv_all_to_all_910b_direct_fullmesh.h`；`src/legacy/ascend910/algorithm/base/alg_aiv_template/all_to_all/CMakeLists.txt` | 旧 AIV/URMA kernel 中 raw WQE、SGE、RDMA write、cache flush、doorbell、head update，以及编译入口 | 该 kernel 一定符合当前 CLT case/profile，或 CLT 已经对它完成提取 |
| HCOMM 已生成 LLVM artifact（候选） | 同一 HCOMM checkout 的 build 目录 | `build/src/legacy/ascend910/algorithm/base/alg_aiv_template/all_to_all/hccl_aiv_all_to_all_op.bc` | 当前可见的 LLVM bitcode 候选（sha256 `aa09f6a1b60187b8f307358299c0f98c445e23051d7db88f4864c7c1b361dffa`），字符串中包含 `llvm.hivm.*` 与 C220 data-move intrinsic | 没有 entry/profile/绑定 manifest 时，不能证明它已被当前 CLT 成功提取；它也不是 C310 CTP artifact |
| HCOMM CTP device-side 模板 | 已安装 CANN（相对于 `~/workspace`：`cann/cann-9.2.0/x86_64-linux/asc`） | `include/adv_api/hcomm/hcomm.h`；`impl/adv_api/detail/hcomm/impl/platform_v310/hcomm_aiv_urma_def.h`；`impl/adv_api/detail/hcomm/impl/platform_v310/hcomm_aiv_urma.h` | C310 CTP 的 `Hcomm<COMM_PROTOCOL_UBC_CTP>`、opcode、SQE/SGE 填充、doorbell、CQ poll 和 Drain 实现路径 | 该安装包与 checkout 的构建对应关系、原始 LLVM provenance，或 CLT 对任意产物的覆盖 |
| CLT 绑定 artifact | `operator-ub-sim` case/外部 artifact | `cases/.../kernel/*.asc`、extraction manifest 和 `third_party/collective-llvm-trace/...` | 某个具体 `.bc/.ll` 是否出现可识别的调用/dataflow，并达到 CLT 的验证等级 | 仅凭 HCOMM API 名称推断 artifact 已映射 |

已安装 CANN 下的 C310 CTP device-side 语义链可以具体写成：

```text
Hcomm<COMM_PROTOCOL_UBC_CTP>::WriteNbi
  -> HcommImpl<COMM_PROTOCOL_UBC_CTP>::PostSend
  -> HcommUrmaFillSqeCtx + HcommUrmaFillSgeCtx
  -> SQE/SGE DataCopy、SQ head/wqe count 更新、SQ doorbell
  -> Drain 读取 wqe count
  -> PollCq 校验 CQE owner/status，更新 CQ/SQ tail 并 ring CQ doorbell
```

其中 `WriteNbi` 的 `dst` 是远端目标、`src` 是本地源、`len` 以字节计；默认
config 还会影响 URMA WQE control。该链路正是 C310 CTP authoritative extraction
需要在 LLVM 中寻找的语义组合。它支持“源代码中存在这条实现路径”的判断，但只有
`c310-ctp-authoritative-extraction/v2` 中的 artifact、调用关联、SQE/SGE、发布、
Drain 和 CQ evidence 同时成立时，才能声称 CLT 对该产物完成映射。

C220 需要单独标注：HCOMM checkout 中确实存在旧 AIV/URMA device kernel source，且
当前 build 目录可见一个包含 C220 data-move intrinsic 的 LLVM bitcode 候选；但它没有
随本项目提供 CLT entry/profile/绑定 manifest，本轮也没有用当前 CLT pipeline 对它重跑。
因而 C220 `hcomm_c220_urma_v1` 的“完整映射”证据仍来自 CLT recognizer、fixture/测试
和已绑定 artifact，不能把这个候选 `.bc` 自动计入已验证覆盖。也不能用 C310 的已安装
头文件反向证明 C220 artifact 已被提取。已安装的 `libhcomm.so`/`libhccl_v2.so` 只是
stripped 二进制，不作为源码或 LLVM provenance 证据。

如果在 HCOMM `build/` 元数据中看到历史路径 `~/workspace/hcomm`，应将其视为旧构建
机的路径记录；当前 checkout 的可核验位置仍是 `~/workspace/cann_gitcode/hcomm`，不能
用历史路径替换现有源码 provenance。

还要注意执行引擎差异：`src/base_comm/primitives/api_c_adpt/cpu_primitives_c_adpt.cc`
中的 CPU wrapper 只在指定设备类型上把 `WriteNbi`/`ReadNbi` 转发给 channel，
`Drain` 转发到远端 drain；`src/base_comm/primitives/api_c_adpt/aicpu_ts_primitives_c_adpt.cc`
中的 AICPU-TS `WriteNbi`/`ReadNbi` 当前返回 `HCCL_E_NOT_SUPPORT`，`Drain` 则按平台
选择 `transportLite` 或远端 drain。这些 C/C++ wrapper 说明 API 的运行时可达范围，
不能被当作 device-side LLVM intrinsic 名称，也不能自动扩大 CLT 的映射覆盖。

## 2. CLT 的可达处理链

| 阶段 | 输入 | 可以确定的内容 | 主要证据 |
| --- | --- | --- | --- |
| `StaticKernelIR` | LLVM module、entry symbol | 函数和调用图、CFG、SSA operand、类型、intrinsic histogram、原 LLVM 文本、诊断 | `src/collective_llvm_trace/artifacts/analyzer.py`；`ir/static_kernel.py`；`cpp/llvm_analyzer` |
| `BoundCaseIR` | case、chip/ABI profile、launch、memory/rma binding | rank/block 实例、入口参数、rank-owned region、地址空间和初始内存 | `ir/bound_case.py`；`execution/binding.py`；`execution/memory.py` |
| `CoreExecutionIR` | 静态 IR + 一次绑定 | 实际 basic block、branch decision、SSA 值、memory/data-move/intrinsic observation、polling wait | `execution/evaluator.py`；`ir/execution_path.py` |
| `CollectiveTraceIR` | 所有 core execution | `DeviceActionIR`、`SyncObjectIR`、`TraceEdgeIR`、`CommunicationRequestIR`、内存访问和诊断 | `lowering/actions.py`；`ir/collective_trace.py` |
| `SourceExecutionIR` | trace + 可选 source binding | invocation、launch、kernel program、fragment、instance 和 action 归属 | `exporters/source_execution.py`；`ir/source_execution.py` |
| `RequestFlowIR` | `CollectiveTraceIR` | LDST/URMA 请求、peer/remote address、issue/completion 偏序 | `request_flow/builder.py`；`request_flow/models.py` |
| NS-3 adapter | `RequestFlowIR` + topology mapping | IoDie frontdoor、node/SLLC/Jetty/TPN、数值 request ID、callback binding | `integrations/ns3_ub/adapter.py`；`integrations/ns3_ub/contract.py` |

`CollectiveTraceIR` 的 action kind 明确包含 `scalar_region`、`local_load`、
`local_store`、`local_reduce`、`barrier`、`notify_record`、`notify_wait`、
`ldst_load`、`ldst_store`、`sq_poll`、`descriptor_write`、`cache_maintenance`、
`queue_head_update`、`doorbell_write`、`urma_read`、`urma_write` 和
`unknown_device_action`。因此 CLT 的提取面明显宽于网络仿真请求。

`RequestFlowIR` 是有意的派生请求图：它保留请求和请求依赖，移除本地 action 节点，
不为普通 scalar/vector action 分配网络延迟。它不能代表设备的逐周期总时间线。

## 3. 语义映射矩阵

下表是按语义类别归并的当前可达映射。`下游`列只表示 CLT 中是否有继续派生的路径，
不是 operator-ub-sim 已经消费的承诺；后者见第二份报告。

机器可读版本见
[`clt-llvm-semantic-mapping-matrix.csv`](clt-llvm-semantic-mapping-matrix.csv)。

| 语义类别 | LLVM 表现 | CLT 结果 | 来源归属 | CLT 提取完整度 | 验证等级 | 下游 |
| --- | --- | --- | --- | --- | --- | --- |
| 静态程序结构 | 函数、basic block、`br`/`switch`、SSA、`phi`、调用边、intrinsic | `StaticKernelIR` 的 function/basic-block/instruction、CFG/SSA、原始 `ir` | 未归属，属于通用基础设施 | 完整映射 | 测试/fixture；真实 artifact 依赖 analyzer | 支撑所有后续阶段 |
| 整数和控制流求值 | `add/sub/mul`、有/无符号除余、移位、`and/or/xor`、`icmp`、`select`、`phi`、`br`、`switch` | `CoreExecutionIR` 的具体 branch、SSA 值和执行状态 | 未归属 | 完整映射（受支持 opcode） | 测试/fixture | 影响路径和地址/长度计算 |
| 类型和地址转换 | `trunc/zext/sext`、`bitcast`、`addrspacecast`、`ptrtoint`、`inttoptr` | 整数、指针或 symbolic address execution value | 未归属 | 部分映射，依赖可解析值和 address space | 测试/fixture | 影响 memory/action/request |
| GEP 地址计算 | `getelementptr` + analyzer 的 offset metadata | pointer region、owner rank、byte offset | HCOMM/HCCL 产物可共享该能力；不能据此归属具体项目 | 完整映射（仅 offset 可分解且动态值已知） | 测试/fixture | 进入 action 的 `MemoryAccessIR` 和 request address |
| launch 上下文 | `GET.BLOCK.IDX`、`GET.BLOCK.NUM`、`GET.SUBBLOCKID`、`GET.SUBBLOCKDIM`；C220 还有 `GET.COREID` | 绑定到 rank/block 的整数 observation | HCOMM/HCCL dialect | 完整映射；物理 core ID 在未绑定时保留 unknown | 测试/fixture | 影响路径、action identity 和 SourceExecution |
| 参数和系统地址 | C310 `GET.PARA.BASE`；C220/C310 `GET.SYS.VA.BASE` | parameter-table base 或 symbolic system-VA base；local alias resolution | HCCL C310 / HCOMM C220 | 完整映射（需 profile region/alias） | 测试/fixture | 影响 pointer 和 buffer address |
| CTRL/DMA 原子模式 | `GET.CTRL`、`SET.CTRL`、`SBITSET0/1`、C220/C310 dialect 约束的 loop/store config | 控制寄存器和 DMA atomic mode；local-to-GM move 可得到 `atomic_operation`/`atomic_dtype` | HCOMM/HCCL | 完整映射（C220/C310 profile 内的已声明域） | 测试/fixture | `local_reduce` 或数据搬运属性 |
| 打包设备数据搬运 | C220 `MOV.OUT.TO.UB.v220`、`MOV.UB.TO.OUT.v220.1`、`MOV.UB.TO.OUT.ALIGN.b32.V220`；C310 `MOV.OUT.TO.UB.ALIGN.V2.u8.DV`、`MOV.UB.TO.OUT.ALIGN.V2.DV` | `DataMoveObservationIR`：方向、block count/length、stride/gap、payload bytes、源前缀、原子模式；再形成 `local_load/store/reduce` 或跨 rank `ldst_load/store` | HCOMM C220、HCCL C310；具体路径由 ABI/profile 绑定 | 完整映射（descriptor 可解码且 owner 可解析） | 测试/fixture；C220/C310 E2E 在 analyzer/artifact 可用时运行 | 通用 C220/C310 请求可进入 `RequestFlowIR` |
| `MOVEV.s32` 本地写入 | C220 `llvm.hivm.MOVEV.s32` | `local_store`/`vector_local`，4 B value，并保留对后续 WQE/flag 的 data edge | HCOMM C220 | 完整映射 | 测试/fixture | 通常只作为本地依赖，不单独成为网络 request |
| pipeline barrier/event | `BARRIER`；`SET.FLAG.REG/IMM`、`WAIT.FLAG.REG/IMM` | `barrier` action、`pipeline_event`/`pipeline_barrier` sync object 和 sync edge | HCOMM C220、HCCL C310 | 完整映射（sync key/operation 可解析） | 测试/fixture | 作为依赖；不直接生成 NS-3 request |
| C310 跨 core barrier | 受参数约束的 `SET.CROSS.CORE(5,3585)`、`WAIT.FLAG.DEV.PIPE.IMM(0,14)` | launch-scope `cross_core_barrier` sync | HCCL C310 | 完整映射，仅接受 dialect 声明的具体参数 | 静态代码追踪 + fixture coverage | 依赖关系；当前无单独 NS-3 操作 |
| GM flag polling | `load` + `icmp`（或 `and` 组合）+ back-edge branch；由前序 data move 写入 | `PollingWaitObservationIR`，`notify_wait` action，producer/consumer `gm_polling_flag` 和 `remote_completion` | HCOMM/HCCL | 完整映射（循环形态和 producer 可匹配） | 测试/fixture | `RequestFlowIR` 保留 completion dependency；项目投影可生成 wait |
| 普通本地/远端内存访问 | LLVM `load/store`、region/address-space/owner binding | `MemoryObservationIR`，再形成 local action；普通远端访问会诊断为 `unknown_device_action` | HCOMM/HCCL 产物可共享；非项目特有 | 部分映射，依赖 rank-owned region | 测试/fixture | 本地 action 通常被 RequestFlow 移除 |
| C220 HCOMM URMA WQE | descriptor stores + DCCI + doorbell data move + SQ head update + queue geometry | `descriptor_write`、`cache_maintenance`、`doorbell_write`、`queue_head_update`、`urma_write`、queue credit 和 remote completion；recognizer 产出 request | HCOMM C220，`hcomm_c220_urma_v1` | 完整映射，需 synthetic/snapshot RMA、WQE 字段和队列证据完整 | 测试/fixture；外部 E2E 需真实 analyzer/artifact | `RequestFlowIR` -> URMA request；adapter -> `URMA_WRITE` |
| C310 普通 HCCL AIV/SuperKernel 通信 | C310 data-move dialect + address/flag/barrier intrinsics | `ldst_load/store`、local actions 和同步；C310 dialect 的 `protocols: []` 不会触发 C220 URMA recognizer | HCCL C310 | 完整映射（LDST/data-move 范围）；URMA 协议映射未声明 | 测试/fixture；E2E 依赖外部 artifact | `RequestFlowIR` -> LDST request |
| C310 CTP URMA authoritative extraction | `Hcomm...CommProtocolE4...WriteNbi`、`Drain`，以及 `HcommUrmaFillSqeCtx`、`HcommUrmaFillSgeCtx`、`llvm.hivm.ST.DEV.u64/u32`、`PollCq`、CQE owner/status 检查等构造组合 | `c310-ctp-authoritative-extraction/v2`：transaction、channel、source/destination/bytes、SQE/SGE、doorbell、Drain、CQ completion、buffer/channel ABI evidence | 当前 C310 case 的 Hcomm CTP device artifact；不宣称 MC2/HCCL provenance | 完整映射，仅限绑定的 CTP ABI/dataflow | 测试/fixture；正式路径要求真实 `.bc` + pinned `llvm-link`，当前 checkout 不含生成 artifact | 进入 operator-ub-sim C310 projection；不经过通用 `CollectiveTraceIR` |
| 算子/collective 高层归属 | case/workload、entry symbol、ABI profile、Host launch 或外部 API | `collective_invocation`、`SourceExecutionIR` invocation/launch 归属 | case/workload 或外部项目，不是 LLVM 单独推导 | 部分映射 | 静态代码追踪；需明确 binding | 可作为投影上下文，不能自动证明 AllToAll/MoE/MC2 |

## 4. Dialect 和可达 handler 清单

### 4.1 C220 `ascend-dav-c220-vec/v1`

规则文件：`third_party/collective-llvm-trace/dialects/dav-c220-vec/v1.yaml`。

| 组 | 当前 selector | 处理结果 |
| --- | --- | --- |
| launch/address | `GET.BLOCK.IDX`、`GET.BLOCK.NUM`、`GET.SUBBLOCKID`、`GET.SUBBLOCKDIM`、`GET.COREID`、`GET.SYS.VA.BASE` | 绑定 launch 值或 symbolic address |
| scalar/control | `GET.CTRL`、`SET.CTRL`、`SBITSET0`、`SBITSET1`、`SFF0`、`MOVEMASK` | 整数求值、CTRL 状态、观测值 |
| data move | `MOV.OUT.TO.UB.v220`、`MOV.UB.TO.OUT.v220.1`、`MOV.UB.TO.OUT.ALIGN.b32.V220` | C220 descriptor decoder `c220_normal_v1` + `DataMoveObservationIR` |
| local/sync | `MOVEV.s32`、`BARRIER`、`DCCI.*`、`SET/WAIT.FLAG.REG`、`SET/WAIT.FLAG.IMM` | local store、barrier、cache、pipeline sync |
| protocol | YAML 的 `hcomm.aiv_urma` -> `hcomm_c220_urma_v1` | 组合识别 SQ/WQE/doorbell/URMA |

### 4.2 C310 `ascend-dav-c310-vec/v1`

规则文件：`third_party/collective-llvm-trace/dialects/dav-c310-vec/v1.yaml`。

| 组 | 当前 selector | 处理结果 |
| --- | --- | --- |
| launch/address | `GET.BLOCK.IDX`、`GET.BLOCK.NUM`、`GET.SUBBLOCKID`、`GET.SUBBLOCKDIM`、`GET.PARA.BASE`、`GET.SYS.VA.BASE` | launch 值、parameter table base、symbolic address |
| scalar/control | `GET.CTRL`、`SET.CTRL`、`SBITSET0`、`SBITSET1`、`SFF0`、`GET.BUF.mode`、`RLS.BUF.mode`、受参数约束的 `MOVEMASK.V300`、`SET.LOOP.SIZE.UBTOOUT`、`SET.LOOP.SIZE.OUTTOUB`、`SET.ST.ATOMIC.CFG` | 控制状态和观测值；参数不满足时不匹配 |
| data move | `MOV.OUT.TO.UB.ALIGN.V2.u8.DV`、`MOV.UB.TO.OUT.ALIGN.V2.DV` | C310 decoder `c310_align_v2_v1` + `DataMoveObservationIR` |
| sync | `BARRIER`、受参数约束的 `SET.CROSS.CORE`、`WAIT.FLAG.DEV.PIPE.IMM` | pipeline 或 launch-scope cross-core sync |
| protocol | 当前 `protocols: []` | 不产生通用 C310 URMA recognizer |

executor handler allow-list 位于 `dialects/handler_ids.py`，实现位于
`execution/device_intrinsics.py`。可达 handler 包括 launch geometry、parameter/system
VA、packed data move、CTRL、bitset、`MOVEV.s32` 和 `find_first_zero`；声明为
`observe` 的 intrinsic 仍会形成 observation，之后由 generic lowering 处理。注册表对
未覆盖的 handler ID 在导入时失败，避免静默不可达。

## 5. HCOMM/HCCL/OPS 覆盖矩阵

### HCOMM C220

CLT workload catalog 当前有四条可选实现：

- `hcomm-c220-allgather-ldst`
- `hcomm-c220-allreduce-ldst`
- `hcomm-c220-alltoall-ldst`
- `hcomm-c220-alltoall-urma`

它们共享 `ascend-dav-c220-vec/v1` 和 `hcomm-c220-aiv/v1`，入口符号和 RMA/link
选择由 catalog 明确记录。`alltoall-urma` 才会满足 C220 protocol recognizer 的
`synthetic`/`snapshot` RMA 前提。相关证据包括：

- `workloads/catalog.py` 的 implementation rows 和 validated artifact hash；
- `tests/unit/test_hcomm_c220_urma.py` 的 recognizer、lowering、polling 和 NS-3 adapter
  单元覆盖；
- `tests/external_e2e/test_c220_alltoall_urma.py`、`test_c220_allreduce.py` 等真实
  artifact E2E 定义。

当前 vendored CLT checkout 的 `fixtures/llvm` 只有受控 fixture；真实 C220 artifact
由外部路径/环境提供。因此本盘点对 HCOMM 的默认验证等级是测试/fixture 或静态代码
追踪，而不是本轮重新运行的产品 artifact。

### HCCL C310

catalog 当前有五条实现：

- `hccl-c310-allgather`
- `hccl-c310-allreduce-oneshot`
- `hccl-c310-allreduce-twoshot`
- `hccl-c310-alltoall`
- `hccl-c310-alltoall-superkernel`

这些行明确锁定 C310 dialect、ABI profile、entry symbol、block 数、LLVM major、
rank count、link type 和 validated artifact hash。普通 AIV/SuperKernel 路径会形成
LDST/data-move trace；C310 dialect 没有通用 protocol recognizer，所以不能从这些
行推导 C220 式 URMA WQE。

C310 CTP authoritative extraction 是另一种已实现的 CLT 输入处理方式：
`extract_c310_ctp_bitcode()` 先用指定 `llvm-link` 物化 `.bc`，再由
`recognize_c310_ctp_llvm()` 校验绑定的 `WriteNbi -> Drain` 和 SQ/CQ dataflow。它的
输出包含每个 transaction 的 channel、buffer、bytes、doorbell、Drain、completion
和按 witness 作用域化的 LLVM line evidence。生产入口拒绝 fixture LLVM。

当前 checkout 不包含 C310 生成 `.bc`/`.ll`；case 中的
`c310_urma_edge.asc` 和冻结 evidence 记录了来源与 hash，但不能替代本地 artifact。
因此 C310 CTP 的正式实现证据为静态代码 + fixture tests + 已冻结 extraction lineage，
不是本轮重新构建验证。

### OPS (`ops-transformer`)

`ops-transformer` checkout 包含大量 `mc2` kernel/source 目录，例如
`mc2/moe_distribute_dispatch`、`mc2/moe_distribute_combine`、`mc2/mega_moe`、
`mc2/moe_ep_dispatch` 和 `mc2/moe_ep_combine`。它们证明仓库存在 OPS kernel
源码和编译入口，但当前 operator-ub-sim/CLT 基线没有：

- OPS 专属的 CLT workload catalog row；
- 与这些目录绑定的可定位 `.bc/.ll` artifact；
- OPS dialect/profile 或 source-to-LLVM provenance；
- 针对 OPS artifact 的 CLT extraction 测试。

结论是：**OPS-specific LLVM mapping 当前未发现，验证等级为无法验证**。如果未来
OPS 产物使用与 C220/C310 相同的 `llvm.hivm.*` 构造，通用 dialect handler 可能可以
复用，但这只能在 artifact、entry、ABI 和完整 extraction 证据到位后确认，不能从
目录名或高层算子名称外推。

## 6. 负向空间和失败边界

CLT 对负向空间采用显式诊断或 fail-closed 行为：

| 情形 | 当前行为 | 不是 |
| --- | --- | --- |
| 执行到未注册 intrinsic | `unknown_executed_device_intrinsic` + `unknown_device_action` | 静默忽略 |
| 带副作用但未支持的 LLVM opcode | `unsupported_side_effecting_opcode` | 自动猜测副作用 |
| branch/select/GEP/地址依赖 unknown | unknown value、path underdetermined 或执行错误 | 任意填默认值 |
| 远端 GM owner 无法解析 | `unresolved_gm_owner`，action 变 unknown | 猜 peer rank |
| 普通 LLVM load/store 直接访问远端 region | `ordinary_remote_memory_access` | 自动当作协议请求 |
| packed data move descriptor 不可解码 | device intrinsic fault/diagnostic | 生成近似长度 |
| C220 URMA WQE 证据不完整 | recognizer diagnostics，不能把 partial WQE 当 LDST | 协议标签兜底 |
| C310 CTP 缺少 WriteNbi/Drain/SQE/SGE/CQ 证据 | 稳定的 `missing_*_evidence` 错误 | 仅凭函数名或 case 名称通过 |
| C310 生产提取输入是 fixture | `fixture_not_authoritative` | fixture 冒充 device evidence |

这些边界意味着“未进入 RequestFlowIR”不一定是 CLT 缺陷。local scalar/vector、
barrier、cache maintenance、queue evidence 可能已经在 `CollectiveTraceIR` 中完整
存在，只是网络请求图或项目投影没有消费它们。

## 7. 代表性证据链

### C220 远端 LDST

```text
llvm.hivm.MOV.UB.TO.OUT.v220.1
  -> packed_data_move / c220_normal_v1
  -> DataMoveObservationIR(local_to_gm, payload_bytes, gaps, owner rank)
  -> CollectiveTraceIR.ldst_store + MemoryAccessIR + program/data edges
  -> RequestFlowIR(transport=ldst, verb=write, peer, remote_address, bytes)
```

`tests/unit/test_lowering.py::test_lowering_builds_ldst_request_pipeline_wait_and_remote_flag_completion`
验证了远端 rank、32 B request、pipeline event 和 GM polling flag completion。

### C220 HCOMM URMA

```text
MOVEV/descriptor stores + DCCI + doorbell data move + SQ head update
  -> hcomm_c220_urma_v1 recognizer
  -> descriptor_write/cache_maintenance/doorbell_write/
     queue_head_update/urma_write + queue/completion edges
  -> RequestFlowIR(transport=urma, verb=write)
```

`tests/unit/test_hcomm_c220_urma.py::test_lowering_emits_urma_request_queue_actions_and_remote_completion`
验证了队列 action、URMA request token 和 remote completion 关系。

### C310 CTP

```text
Hcomm<COMM_PROTOCOL_UBC_CTP>::WriteNbi
  -> SQE/SGE construction + ST.DEV publication/doorbell
  -> Drain -> PollCq -> CQE owner/status/tail checks
  -> c310-ctp-authoritative-extraction/v2
  -> project_c310_ctp_replay()  # 第二份报告
```

`tests/unit/test_c310_ctp.py` 覆盖多 request/channel association、证据作用域和缺失
证据拒绝；正式入口还要求真实 bitcode 和 pinned `llvm-link`。

## 8. 结论和缺口

### 当前能明确声称的能力

1. CLT 能在 C220/C310 dialect 和 ABI 约束下解析 LLVM 静态结构，并执行支持的
   整数、指针、CFG、内存和设备 intrinsic 语义。
2. CLT 能把受支持的 GM/UB data move、local reduction、同步、轮询和远端 owner
   关系提取为 `CollectiveTraceIR` action/evidence/dependency。
3. C220 HCOMM 路径能从一组已验证的 queue/WQE 证据组合出 URMA request；C310 普通
   HCCL 路径能提取 LDST/data-move trace。
4. C310 CTP 专用路径能对真实物化 LLVM 建立 `WriteNbi/Drain/SQ/CQ` authoritative
   evidence，但该证据模型不是通用 `CollectiveTraceIR`。

### 当前不能声称的能力

- 覆盖任意 LLVM 版本、优化结果、芯片、ABI 或等价 IR 形态；
- 从高层 API、case 名或 OPS 目录自动恢复完整 HCCL/MC2/MoE 语义；
- 从普通 C310 AIV/SuperKernel data move 推导 C310 URMA 协议；
- 对 C220/C310/OPS 的所有产品 artifact 做本地实测覆盖；
- 恢复逐周期设备时间线、硬件性能、bit-exact SQE 或 NS-3 仿真结果。

下一份报告说明这些 CLT evidence 如何被 operator-ub-sim 归一化和有损投影。

## 9. 证据索引

- CLT IR 总览：`third_party/collective-llvm-trace/docs/reference/ir.md`
- 请求流设计：`third_party/collective-llvm-trace/docs/request-flow-ns3-ub-design-and-usage.md`
- C220/C310 dialect：`third_party/collective-llvm-trace/dialects/dav-c220-vec/v1.yaml`、
  `third_party/collective-llvm-trace/dialects/dav-c310-vec/v1.yaml`
- handler allow-list：`third_party/collective-llvm-trace/src/collective_llvm_trace/dialects/handler_ids.py`
- executor：`third_party/collective-llvm-trace/src/collective_llvm_trace/execution/device_intrinsics.py`
- evaluator：`third_party/collective-llvm-trace/src/collective_llvm_trace/execution/evaluator.py`
- generic lowerer：`third_party/collective-llvm-trace/src/collective_llvm_trace/lowering/actions.py`
- C220 recognizer：`third_party/collective-llvm-trace/src/collective_llvm_trace/lowering/hcomm_c220_urma.py`
- C310 CTP extractor：`third_party/collective-llvm-trace/src/collective_llvm_trace/c310_ctp.py`
- workload catalog：`third_party/collective-llvm-trace/src/collective_llvm_trace/workloads/catalog.py`
- CLT mapping tests：`third_party/collective-llvm-trace/tests/unit/`、`tests/integration/`、
  `tests/external_e2e/`
- HCOMM API/协议（路径均相对于 HCOMM checkout）：`include/hcomm_primitives.h`、
  `include/hcomm_res_defs.h`、`docs/zh/api_ref/comm_opdev/datatype_definition/CommProtocol.md`
- HCOMM endpoint/channel 资源（相对于 HCOMM checkout）：
  `src/base_comm/resources/endpoints/endpoint.cc`、
  `src/base_comm/resources/endpoint_pairs/channels/aiv/aiv_channel_helper.cc`、
  `src/base_comm/resources/endpoint_pairs/channels/aiv/aiv_urma_channel.cc`、
  `src/coll_communicator_mgr/api_c_adpt/coll_comm_res_c_adpt.cc`
- HCOMM CTP device-side（已安装 CANN `asc/` 根目录）：
  `include/adv_api/hcomm/hcomm.h`、
  `impl/adv_api/detail/hcomm/impl/platform_v310/hcomm_aiv_urma_def.h`、
  `impl/adv_api/detail/hcomm/impl/platform_v310/hcomm_aiv_urma.h`
- HCOMM CTP legacy connection（相对于 HCOMM checkout）：
  `src/legacy/ascend950/unified_platform/resource/connection/dev_ub_connection.h`、
  `src/legacy/ascend950/unified_platform/resource/connection/dev_ub_connection.cc`、
  `src/legacy/ascend950/unified_platform/external_system/orion_adapter_hccp.h`、
  `src/legacy/ascend950/unified_platform/external_system/orion_adapter_hccp.cc`
- HCOMM AICPU-lite transport（相对于 HCOMM checkout）：
  `src/legacy/ascend950/unified_platform/resource/transport/aicpu/ub_transport_lite_impl.cc`
- HCOMM host/AICPU adapter（相对于 HCOMM checkout）：
  `src/base_comm/primitives/api_c_adpt/cpu_primitives_c_adpt.cc`、
  `src/base_comm/primitives/api_c_adpt/aicpu_ts_primitives_c_adpt.cc`
- HCOMM 旧 AIV/URMA kernel 与编译入口（相对于 HCOMM checkout）：
  `src/legacy/ascend910/algorithm/base/alg_aiv_template/aiv_communication_base.h`、
  `src/legacy/ascend910/algorithm/base/alg_aiv_template/all_to_all/aiv_all_to_all_910b_direct_fullmesh.h`、
  `src/legacy/ascend910/algorithm/base/alg_aiv_template/all_to_all/CMakeLists.txt`
- HCOMM 当前可见候选 bitcode（相对于 HCOMM checkout）：
  `build/src/legacy/ascend910/algorithm/base/alg_aiv_template/all_to_all/hccl_aiv_all_to_all_op.bc`