HIXL 环境类问题排查指南：RoCE 连通性、网卡状态与 FabricMem 内存诊断

HIXL 环境类问题排查指南：RoCE 连通性、网卡状态与 FabricMem 内存诊断

【免费下载链接】hixlHIXL（Huawei Xfer Library）是一个灵活、高效的昇腾单边通信库，面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl

本指南聚焦 CANN hixl（Huawei Xfer Library）运行时建链/传输失败中典型的环境类问题定位方法，覆盖三类高发场景：RoCE 网络连通性、NPU 网卡链路状态、FabricMem 模式下 HOST 内存申请 OOM。作为 hixl-troubleshoot 技能的环境检查参考，本文依据.agents/skills/hixl-troubleshoot/references/env-check.md整理，并结合仓库源码补充底层原理与验证手段。读完本文，你将能使用hccn_tool独立完成 RoCE 连通性测试与网卡状态排查，并通过numa_intersect.py量化 FabricMem 模式可用的 HOST 内存。

1. 适用范围与前置约定

环境类检查（env-check）是整个 HIXL 问题定位流程中的一个环节，使用时有严格的先后约束：

• 应先通过hixl-transfer-paths.md判定问题落在哪条传输路径（FabricMem 引擎 / ADXL 直传 / HIXL_CS），再判建链或传输阶段；
• 仅在日志已经直接支持"环境问题"这一假设后，才执行本文的最小必要检查，不得由应用层超时直接推断网络、PFC、容器或环境问题（见 differential-diagnosis.md 的证据门槛）；
• 结论等级需满足：已确认 = 关键日志来源/时间/行号 + 至少一条判别证据 + 建链问题双端日志；否则只能输出高概率假设或继续收集证据。

本文所涉及的环境检查主要服务于A2（Atlas 800T A2，对应昇腾 910B）与 A3（Atlas 800T A3，对应昇腾 910）两类硬件形态，示例命令中的网卡序号（如-i 0、-i 1）需按实际拓扑替换。

2. RoCE 连通性检查：建链失败的第一排查项

现象与假设：环境 ROCE 没有配置连通，会导致建链失败。在排除其他明显原因后，应主动检查 device IP 和 device 间的联通性。

检查方法：使用昇腾驱动自带工具hccn_tool的roce_test子命令做端到端带宽/连通性测试。下面以双卡（接收端-i 0，发送端-i 1）为例：

# 接收端 /usr/local/Ascend/driver/tools/hccn_tool -i 0 -roce_test reset /usr/local/Ascend/driver/tools/hccn_tool -i 0 -roce_test ib_send_bw -s 65536 -n 1000 -tcp # 发送端 /usr/local/Ascend/driver/tools/hccn_tool -i 1 -roce_test reset PEER_IP=$(/usr/local/Ascend/driver/tools/hccn_tool -i 0 -ip -g 2>/dev/null | sed -n 's/^ipaddr:\(.*\)/\1/p' | head -1) /usr/local/Ascend/driver/tools/hccn_tool -i 1 -roce_test ib_send_bw -s 65536 -n 1000 address "$PEER_IP" -tcp

各要素说明：

• reset：先重置 roce_test 环境，避免上一次测试残留状态干扰；
• ib_send_bw：ib_send_bw 风格的带宽/连通测试（-s 65536 表示报文大小 65536 字节，-n 1000 表示发送 1000 个报文）；
• -tcp：走 TCP 控制面协调测试两端；
• 发送端的PEER_IP通过-ip -g读取接收端 device IP，再用sed从ipaddr:字段中提取，随后通过address "$PEER_IP"指定对端地址发起测试。

若ib_send_bw无法建立连接或带宽远低于预期，即可确认 RoCE 网络连通性/配置存在环境问题，回到建链问题的时间线中作为环境类候选假设证据。

3. 网卡状态检查：当前 DOWN 与历史 DOWN

现象与假设：网卡处于DOWN时，会导致建链失败或传输失败。值得注意的是，如果当前状态是UP，但历史上曾在传输时刻处于DOWN，同样可能是根因——例如 differential-diagnosis.md 中stream sync timeout的候选假设就包含"RDMA 重传超次或网络闪断"需要网卡历史DOWN证据来证实。

当前状态查询：循环遍历 0~15 号网卡，查询实时链路状态：

for i in {0..15}; do /usr/local/Ascend/driver/tools/hccn_tool -i $i -link -g; done

历史状态查询：查询链路统计信息，确认历史上是否曾发生DOWN：

for i in {0..15}; do /usr/local/Ascend/driver/tools/hccn_tool -i $i -link_stat -g; done

两条命令分别对应实时状态与统计累积信息，建议成对执行：先确认当前状态，再核对历史统计，从而覆盖"曾经 DOWN 但现已恢复"的隐蔽场景。该检查在 HIXL 传输超时（stream sync timeout/RtStreamSynchronizeWithTimeout）类问题中尤为重要——只有当网卡历史 DOWN 与重传统计同时存在时，网络闪断假设才成立。

4. FabricMem 模式 HOST 内存 OOM：numa_intersect.py检测

4.1 问题背景与内存模型

使用 FabricMem 模式时，如果问题是申请 HOST 内存报 out of memory，可以调用python3 scripts/numa_intersect.py检测有多少 HOST 内存可申请。该脚本位于 .agents/skills/hixl-troubleshoot/scripts/numa_intersect.py。

要理解为何需要该脚本，先看 FabricMem 的 HOST 内存分配方式。在 src/hixl/fabric_mem/fabric_mem_allocator.cc 中，FabricMemAllocator::MallocMem支持MemType为 device 或 host 的 fabric 内存，物理内存通过aclrtMallocPhysical申请；其中 HOST 内存路径会按prop.location.id（NUMA 节点）申请，并打印Malloc host memory for numa:%d.；当指定 NUMA 节点申请失败时，会退回到普通 HOST 分配路径（日志Try common host allocation instead of numa:%d.），失败后统一返回Allocate physical memory failed.。可见 FabricMem 的 HOST 内存与实际物理内存区间强相关，申请失败根因常落在"目标物理地址区间内没有足够可用内存"。

结合 docs/zh/FabricMem.md 的背景：FabricMem 模式下 NPU 通过 HCCS 高速链路直接访问远程节点的 DRAM 内存，内存以aclrtMallocPhysical+aclrtReserveMemAddress+aclrtMapMem三段式管理（先申请物理内存，再预留虚拟地址，最后映射）。因此 HOST 内存 OOM 可能来自物理页不足或目标地址区间碎片化，而不是简单的"系统内存不够"。

4.2 脚本原理

numa_intersect.py的核心逻辑是：计算"NUMA 节点空闲物理内存页"与"FabricMem 目标物理地址区间"的交集大小，从而量化当前还能申请到多少 HOST 内存。具体实现要点：

• 目标区间：脚本内置了 4 个目标物理基地址RANGES（0x29580000000、0xa9580000000、0x129580000000、0x1a9580000000），每个区间大小RANGE_SIZE = 682GB；
• 空闲页判定：通过读取/proc/kpageflags中每个物理页的 flags，检查KPF_BUDDY（bit 10）位判断该页是否处于 buddy 系统空闲链表中（is_buddy）；
• NUMA 节点内存块：从/sys/devices/system/node/node<N>/memory*读取每个 node 的物理内存块（memory block），结合/sys/devices/system/memory/block_size_bytes换算 PFN 范围；
• 连续区间合并：将相邻的空闲页合并为连续 free segment（_reset_run_if_block_gap、_apply_pfn_buddy_state），再与目标区间求交集（intersect），过滤掉小于min_mb阈值的碎片后累加，输出每个交集的起始/结束物理地址与大小，以及总计可用大小。

4.3 使用方法

python3 scripts/numa_intersect.py

参数说明：

典型输出（示意，实际以机器为准）：

===== NUMA node 0 ===== FREE∩RANGE : 0x0000002958000000 - 0x000000295c1fffff size=1024.00 MB Total intersect FREE: 2048.00 MB

解读：FREE∩RANGE行的地址对表示该 NUMA 节点上、FabricMem 目标物理区间内、当前处于 buddy 空闲态的连续内存区间；Total intersect FREE即为当前可申请 HOST 内存的量化上限。当该数值小于业务申请量时，即可确认 FabricMem 模式 HOST 内存 OOM 属于物理可用内存不足的环境问题。

4.4 使用前提与限制

• 需要 root 权限读取/proc/kpageflags；
• 脚本依赖 Linux 的 buddy 页状态，只能在可访问/proc/kpageflags的宿主机/特权容器内运行；
• 结果反映的是"当前时刻"的空闲内存快照，实际可申请量会随其他进程内存占用波动，应结合申请失败时刻的内存状态综合判断；
• 脚本内置的目标物理区间与 682GB 区间大小是特定硬件形态（A2/A3 超节点 DRAM 统一编址）的配置，非该形态环境不可直接套用结论。

5. 检查结果如何进入 HIXL 问题定位流程

环境类检查的产出应作为候选假设的判别证据进入定位闭环，而不是独立结论：

1. 在 differential-diagnosis.md 的候选假设表中定位对应行：如wait socket establish timeout的"链路路径不一致"需双端LINK_ERROR_INFO、HCCL_INTRA_ROCE_ENABLE一致；503900的"device 系统内存/CQ/QP 资源不足"需要ibv_cmd_create_cq failed, ret 12等早于 HCCL 失败的证据；
2. 将本文检查结果填入该假设的"证实证据"或"反证"列：RoCE 测试通过可排除网络连通性；网卡当前及历史均为 UP 可排除链路 DOWN；
3. 若检查均正常，则继续沿 hixl-transfer-paths.md 的路径决策树（FabricMem 引擎 / ADXL 直传 / HIXL_CS）回到源码侧定位。

6. 快速自查清单

• 建链失败时，是否已先做 RoCEib_send_bw双端连通性测试（含reset前置）？
• 传输失败时，是否同时查询了网卡当前状态（-link -g）与历史状态（-link_stat -g）？
• 是否确认了历史DOWN与传输时刻的对应关系，而非只看当前UP？
• FabricMem 模式 HOST 内存 OOM 时，是否已用numa_intersect.py量化可申请量并与申请量对比？
• 环境类结论是否有直接检查证据，而非由应用层超时反推？

【免费下载链接】hixlHIXL（Huawei Xfer Library）是一个灵活、高效的昇腾单边通信库，面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl