ascendc-mssanitizer

Ascend C 算子 mssanitizer 内存检测分析

系统化检测 Ascend C 算子的内存问题，生成详细分析报告。

概述

mssanitizer（MindStudio Sanitizer）是 CANN 提供的内存正确性检测工具套件，用于检测 AscendC 算子开发中的内存问题，包括：

• 内存泄漏（Memory Leak）
• 非法内存访问（Illegal Access）
• 未初始化内存使用（Uninitialized Memory）
• 数据竞争（Data Race）
• 同步问题（Sync Issues）

触发条件

• 用户需要对 Ascend C 算子进行内存检测
• 用户请求内存泄漏检测
• 用户需要验证算子内存安全性
• 用户提到 "mssanitizer"、"内存检测"、"内存泄漏"、"非法访问" 等关键词

---

工程类型判断与检测模式选择

关键步骤：在执行检测之前，必须先判断算子工程类型，选择对应的检测模式。

判断逻辑

算子工程目录
├── 存在 op_graph/ 目录？ ─── 是 ──→ ops 算子仓 → C++ 模式
├── 存在 op_host/op_api/ 目录？ ── 是 ──→ ops 算子仓 → C++ 模式
├── 存在 examples/test_geir_*.cpp？ ── 是 ──→ ops 算子仓 → C++ 模式 (GE IR 子模式)
├── 存在 examples/test_aclnn_*.cpp？ ── 是 ──→ ops 算子仓 → C++ 模式 (aclnn 子模式)
└── 以上均无 ──→ 自定义算子仓 → Python 模式

检测模式对比

特性	Python 模式	C++ 模式 (GE IR)	C++ 模式 (aclnn)
适用工程	自定义算子仓	ops 算子仓	ops 算子仓
工程特征	无 op_graph/、无 examples/	有 op_graph/、有 test_geir_*.cpp	有 examples/、有 test_aclnn_*.cpp
测试载体	Python 脚本（torch_npu 调用）	C++ 可执行文件（GE IR 图调用）	C++ 可执行文件（aclnn API 调用）
测试脚本	gen_test_script.py 生成	examples/test_geir_*.cpp	examples/test_aclnn_*.cpp
执行脚本	run_mssanitizer.sh	run_mssanitizer_geir.sh	run_mssanitizer_geir.sh
链接库	torch_npu	ascendcl, ge_runner, graph, register	ascendcl, opapi, nnopbase
日志前缀	memcheck_device_	geir_memcheck_device_	geir_memcheck_device_
汇总报告	mssanitizer_summary_	geir_mssanitizer_summary_	geir_mssanitizer_summary_
优势	覆盖多种 shape/dtype	直接调用算子 kernel，更贴近真实执行	无需 op_graph，构建更简单
劣势	fallback 可能绕过自定义算子	需编译 C++ 可执行文件	需编译 C++ 可执行文件

注意：run_mssanitizer_geir.sh 脚本已自动支持两种 C++ 子模式，会优先查找 test_geir_*.cpp，找不到时自动回退到 test_aclnn_*.cpp。

---

工具脚本

本 skill 提供以下脚本，位于 scripts/ 目录：

脚本	用途	模式
scripts/gen_test_script.py	根据算子名称自动生成 Python 测试脚本	Python
scripts/run_mssanitizer.sh	Python 模式：执行全部 5 项检测并生成汇总报告	Python
scripts/run_mssanitizer_geir.sh	C++ 模式：自动构建+检测+生成汇总报告（支持 GE IR 和 aclnn）	C++
scripts/parse_mssanitizer_log.py	解析 memcheck 日志生成问题分析报告	通用

SKILL 根目录: /home/rcz/agent-skills/skills/ascendc-operator-mssanitizer

---

前置条件

必需的环境变量

环境变量	说明	获取方式
ASCEND_HOME_PATH	CANN 安装路径	CANN set_env.sh 设置
LD_LIBRARY_PATH	动态库路径	包含 CANN lib64

环境激活

source /root/miniconda3/bin/activate cann_env
source /root/miniconda3/envs/cann_env/Ascend/cann-8.5.0/set_env.sh

关键约束（实战经验）

1. CANN 版本锁定：容器中可能存在多套 CANN（如 cann-8.5 和 cann-9.0），set_env.sh 设置的 ASCEND_HOME_PATH 可能指向错误版本。脚本会显式覆盖为用户指定路径，确保 mssanitizer 使用正确版本。
2. --check-device-heap 与 --check-cann-heap 互斥：不能同时启用，必须分两次跑 memcheck。
3. libhccl.so 依赖：mssanitizer 修改 LD_LIBRARY_PATH 后可能丢失 libhccl.so，导致 torch_npu 导入失败。脚本已自动补全 CANN lib64 路径。
4. 容器兼容性：脚本只使用 grep（非 rg），确保 Docker 容器内可用。
5. 日志为空 = 无错误：mssanitizer 只在检测到错误时才写入日志文件。日志文件大小为 0 表示该检测项通过，不是工具未运行。

---

检测工具类型

mssanitizer 提供四种检测工具：

工具	命令参数	检测内容
内存检测	-t memcheck	非法内存访问、非法释放、内存泄漏、UB地址越界
竞争检测	-t racecheck	多核并行竞争条件、数据竞争
未初始化检测	-t initcheck	未初始化内存读取
同步检测	-t synccheck	同步错误、同步点问题

常用参数说明

参数	说明	默认值
-t <tool>	指定检测工具	memcheck
--leak-check=<yes/no>	是否检测内存泄漏	no
--check-device-heap=<yes/no>	检测 Device 接口泄漏	no
--check-cann-heap=<yes/no>	检测 AscendCL 接口泄漏（与 device-heap 互斥）	no
--log-file=<file>	日志输出文件	stdout
--log-level=<level>	日志级别（warn）	warn
--kernel-name=<name>	只检测指定名称的 kernel	all
--block-id=<id>	只检测指定 block	all blocks
--cache-size=<size>	单 block 记录缓存大小（MB）	100

---

检测流程

━━━━━━━━━━ 模式 A：Python 模式（自定义算子仓）━━━━━━━━━━

适用于无 op_graph/、无 examples/ 的自定义算子工程。

阶段 1：生成测试脚本

使用 gen_test_script.py 自动生成针对指定算子的测试脚本：

SKILL_DIR="/home/rcz/agent-skills/skills/ascendc-operator-mssanitizer"

python3 "${SKILL_DIR}/scripts/gen_test_script.py" \
    --operator <operator_name> \
    --fallback <fallback_function> \
    --dtypes float16 float32 \
    --output <project>/mssanitizer_test/<operator_name>_mssanitizer_test.py

参数说明：

• --operator：自定义算子名称（对应 torch.ops.customize.<name>）
• --fallback：torch.nn.functional 中的回退函数名（如 gelu、relu）。当自定义算子未注册时自动使用，确保 NPU 通路仍会执行并被 mssanitizer 监控
• --dtypes：要测试的数据类型列表（仅使用算子实际支持的类型）

阶段 2：执行检测

bash "${SKILL_DIR}/scripts/run_mssanitizer.sh" \
    <project>/mssanitizer_test/<operator_name>_mssanitizer_test.py \
    <cann_root>

参数说明：

• 第 1 个参数：测试脚本路径（阶段 1 生成的）
• 第 2 个参数：CANN 安装根路径（可选，默认取 $ASCEND_HOME_PATH）

该脚本自动执行：

1. memcheck (device-heap) — --check-device-heap=yes --leak-check=yes
2. memcheck (cann-heap) — --check-cann-heap=yes --leak-check=yes
3. racecheck — 数据竞争检测
4. initcheck — 未初始化内存检测
5. synccheck — 同步问题检测
6. 生成汇总报告 — mssanitizer_summary_<timestamp>.md
7. 解析 memcheck 日志 — 调用 parse_mssanitizer_log.py 生成详细分析报告

阶段 3：单独解析日志（可选）

python3 "${SKILL_DIR}/scripts/parse_mssanitizer_log.py" \
    ./mssanitizer_logs/memcheck_device_<timestamp>.log \
    --output ./mssanitizer_logs/memcheck_analysis_report.md

---

━━━━━━━━━━ 模式 B：C++ 模式（ops 算子仓）━━━━━━━━━━

适用于 ops 算子仓（如 ops-nn 仓库），工程目录包含 op_graph/、examples/、op_host/op_api/ 等目录。

特点

• 通过 C++ 可执行文件调用算子，更贴近真实执行路径
• 自动识别测试源文件类型：
  • GE IR 子模式：使用 examples/test_geir_*.cpp，链接 ascendcl + ge_runner + graph + register
  • aclnn 子模式：使用 examples/test_aclnn_*.cpp，链接 ascendcl + opapi + nnopbase
• 自动构建 C++ 可执行文件（若尚未构建）
• 日志文件以 geir_ 前缀区分

一键执行

SKILL_DIR="/home/rcz/agent-skills/skills/ascendc-operator-mssanitizer"

bash "${SKILL_DIR}/scripts/run_mssanitizer_geir.sh" \
    <project_dir> \
    <cann_root>

参数说明：

• 第 1 个参数：算子工程目录路径（如 /home/rcz/ops-nn/activation/gelu_quant）
• 第 2 个参数：CANN 安装根路径（可选，默认取 $ASCEND_HOME_PATH）

脚本自动执行：

1. 检测算子工程结构，定位 examples/test_geir_*.cpp 或 examples/test_aclnn_*.cpp
2. 自动构建测试可执行文件（若尚未构建），根据源文件类型选择 GE IR 或 aclnn 构建方式
3. 依次执行 5 项检测（memcheck_device → memcheck_cann → racecheck → initcheck → synccheck）
4. 生成汇总报告 geir_mssanitizer_summary_<timestamp>.md
5. 调用 parse_mssanitizer_log.py 生成详细分析报告

手动分步执行（可选）

如需更细粒度的控制，可手动执行：

# 1. 构建测试可执行文件（首次需要）
cd <project>/mssanitizer_test/build
cmake . && make -j$(nproc)

# 2. 逐项执行检测
MSSAN=<cann_root>/tools/mssanitizer/bin/mssanitizer
LOGDIR=<project>/mssanitizer_logs
TS=$(date +%Y%m%d_%H%M%S)

$MSSAN -t memcheck --check-device-heap=yes --leak-check=yes \
    --log-file=$LOGDIR/geir_memcheck_device_$TS.log \
    -- ./test_geir_<op_name> float

$MSSAN -t memcheck --check-cann-heap=yes --leak-check=yes \
    --log-file=$LOGDIR/geir_memcheck_cann_$TS.log \
    -- ./test_geir_<op_name> float

$MSSAN -t racecheck --log-file=$LOGDIR/geir_racecheck_$TS.log \
    -- ./test_geir_<op_name> float

$MSSAN -t initcheck --log-file=$LOGDIR/geir_initcheck_$TS.log \
    -- ./test_geir_<op_name> float

$MSSAN -t synccheck --log-file=$LOGDIR/geir_synccheck_$TS.log \
    -- ./test_geir_<op_name> float

# 3. 解析日志
python3 ${SKILL_DIR}/scripts/parse_mssanitizer_log.py \
    $LOGDIR/geir_memcheck_device_$TS.log \
    --output $LOGDIR/geir_memcheck_device_analysis_$TS.md

---

输出文件

Python 模式输出

检测完成后在 <project>/mssanitizer_logs/ 下生成：

<project>/mssanitizer_logs/
├── memcheck_device_<ts>.log           # memcheck device-heap 原始日志
├── memcheck_device_report_<ts>.json   # memcheck device-heap 测试结果
├── memcheck_device_analysis_<ts>.md   # memcheck device-heap 解析报告
├── memcheck_cann_<ts>.log             # memcheck cann-heap 原始日志
├── memcheck_cann_report_<ts>.json
├── memcheck_cann_analysis_<ts>.md
├── racecheck_<ts>.log
├── racecheck_report_<ts>.json
├── initcheck_<ts>.log
├── initcheck_report_<ts>.json
├── synccheck_<ts>.log
├── synccheck_report_<ts>.json
└── mssanitizer_summary_<ts>.md        # 汇总报告

GE IR 模式输出

检测完成后在 <project>/mssanitizer_logs/ 下生成：

<project>/mssanitizer_logs/
├── geir_memcheck_device_<ts>.log      # memcheck device-heap 原始日志
├── geir_memcheck_cann_<ts>.log        # memcheck cann-heap 原始日志
├── geir_racecheck_<ts>.log
├── geir_initcheck_<ts>.log
├── geir_synccheck_<ts>.log
└── geir_mssanitizer_summary_<ts>.md   # 汇总报告（含解析）

注意：日志文件大小为 0 表示该检测项通过，未检测到错误。mssanitizer 只在检测到错误时才写入日志内容。

---

分阶段检测策略

根据 CANN 软件栈结构，memcheck 分两阶段定位内存泄漏位置：

┌─────────────────────────────────────┐
│         用户代码（Host 侧）          │
├─────────────────────────────────────┤
│      AscendCL 接口（CANN API）       │
├─────────────────────────────────────┤
│     Device 接口（驱动层接口）         │
└─────────────────────────────────────┘

步骤 1：检测 Device 接口泄漏

mssanitizer -t memcheck --check-device-heap=yes --leak-check=yes -- python3 test.py
# 或 GE IR 模式：
mssanitizer -t memcheck --check-device-heap=yes --leak-check=yes -- ./test_geir_op float

• 无泄漏输出 → 泄漏发生在 Device 侧应用
• 有泄漏输出 → 继续步骤 2

步骤 2：检测 AscendCL 接口泄漏

mssanitizer -t memcheck --check-cann-heap=yes --leak-check=yes -- python3 test.py
# 或 GE IR 模式：
mssanitizer -t memcheck --check-cann-heap=yes --leak-check=yes -- ./test_geir_op float

---

错误类型与严重程度

严重程度分类

严重程度	错误类型	处理优先级
🔴 严重	illegal_write, illegal_read, illegal_free	立即修复
🟡 中等	memory_leak	尽快修复
🟢 轻微	未初始化内存使用	建议修复

日志关键字段说明

字段	说明	示例
at 0x... on GM	全局内存地址	0x12c000000010
in block on device N	设备和 block 信息	device 0
serialNo:N	指令序列号，用于定位代码位置	serialNo:22
size N	访问的字节数	size 8

问题定位技巧

1. 使用 serialNo 定位：serialNo 对应编译后的指令序列号，添加 -g 编译选项后可获取源码位置
2. 地址分析：GM 地址可用于分析内存布局和越界情况
3. 大小分析：访问大小可帮助判断数据类型和操作类型
4. illegal_free 关联分析：如果 illegal_free 伴随 illegal_write 出现，通常是越界写入破坏了内存管理结构，应先修复 illegal_write

---

常见问题排查清单

1. DataCopy 参数错误

症状：illegal write/read 错误

排查步骤：

1. 检查 DataCopy 的第三个参数是否正确
2. 确认元素数量计算是否正确（注意：参数是元素数量，不是字节数）
3. 检查源/目标地址是否越界

典型错误：

// 错误：乘以 sizeof(T) 或其他系数
DataCopy(xLocal, xGlobal, totalLength * sizeof(T));  // ❌
DataCopy(xLocal, xGlobal, totalLength * 2);           // ❌

// 正确：直接使用元素数量
DataCopy(xLocal, xGlobal, totalLength);               // ✓

2. 内存分配/释放不配对

症状：memory leak 错误

排查步骤：

1. 检查所有 AllocTensor 是否有对应的 FreeTensor
2. 检查 EnQue/DeQue 是否配对使用
3. 检查 pipe.InitBuffer 的缓冲区管理

典型错误：

// 错误：忘记释放
LocalTensor<T> xLocal = xQueue.AllocTensor<T>();
// ... 使用 xLocal
// 缺少 xQueue.FreeTensor(xLocal);  // ❌

// 正确：配对使用
LocalTensor<T> xLocal = xQueue.AllocTensor<T>();
// ... 使用 xLocal
xQueue.FreeTensor(xLocal);  // ✓

3. UB 缓冲区大小不足

症状：UB address out of bounds 错误

排查步骤：

1. 检查 pipe.InitBuffer 分配的大小是否足够
2. 确认数据类型大小计算是否正确
3. 检查是否需要 32 字节对齐

典型错误：

// 错误：缓冲区大小不足
pipe.InitBuffer(tmpBuffer, totalSize);  // ❌ 未考虑临时空间需求

// 正确：根据算子需求分配足够空间
pipe.InitBuffer(tmpBuffer, totalSize * sizeof(T) + EXTRA_SPACE);  // ✓

---

故障排除

问题: 未找到 mssanitizer

检查项:

• 确保 ASCEND_HOME_PATH 指向正确的 CANN 根路径
• 确保 CANN 版本支持 mssanitizer（8.0+）
• 容器中可能存在多套 CANN，需显式传入 cann_root 参数

问题: torch_npu 导入失败 (libhccl.so)

原因: mssanitizer 启动时会修改 LD_LIBRARY_PATH，导致 CANN lib64 路径丢失

解决: run_mssanitizer.sh 已自动在 LD_LIBRARY_PATH 头部补充 CANN lib64 路径。若仍失败，手动执行：

export LD_LIBRARY_PATH=<cann_root>/lib64:$LD_LIBRARY_PATH

问题: CANNOT enable both --check-device-heap and --check-cann-heap

原因: 这两个选项互斥

解决: 分两次运行 memcheck（run_mssanitizer.sh / run_mssanitizer_geir.sh 已自动处理）

问题: 日志显示 <unknown>:0

原因: 算子编译时未添加 -g 调试选项

解决: 重新编译算子添加 -g -O0 选项

问题: 日志文件大小为 0

原因: mssanitizer 只在检测到错误时才写入日志文件

解决: 日志为 0 字节表示该检测项通过，无需处理。可通过 mssanitizer 内部日志（mindstudio_sanitizer_log/）确认工具是否正常运行。

问题: C++ 模式构建失败

检查项:

• 确认 examples/ 目录下存在 test_geir_*.cpp 或 test_aclnn_*.cpp
• GE IR 模式：确认 op_graph/ 目录存在且包含算子 proto 头文件
• aclnn 模式：确认 CANN 的 lib64/ 和 aarch64-linux/lib64/ 下有 libopapi.so 和 libnnopbase.so
• 确认 CANN 环境已正确激活（ASCEND_HOME_PATH、LD_LIBRARY_PATH）
• 检查 CMake 输出中的编译错误
• 如链接 libopapi.so 失败，检查 CANN 架构子目录路径（aarch64-linux/lib64）

问题: 未检测到错误但程序失败

检查项:

• 尝试其他 mssanitizer 工具（racecheck、initcheck）
• 检查逻辑错误
• 使用其他调试工具

---

注意事项

1. 性能影响：mssanitizer 会显著降低程序运行速度（可能慢 10-100 倍），仅用于调试
2. 内存开销：检测过程需要额外内存记录分配信息，可能需要更大的内存
3. 多次运行：某些问题可能不是每次都复现，建议多次运行检测
4. 模式选择：ops 算子仓优先使用 C++ 模式（脚本自动识别 GE IR / aclnn），能直接调用算子 kernel，检测结果更准确

---

最佳实践

1. 添加调试信息: 编译时添加 -g -O0 以获取精确的代码位置
2. 执行所有检测模式: 运行全部检测模式（脚本已默认执行全部 5 项）
3. 按优先级修复: 先解决非法访问问题，再处理内存泄漏
4. 重新验证: 修复后重新运行 mssanitizer 确认问题已解决
5. 定期检测: 在算子开发完成后、修改内存相关代码后、提交代码前进行检测
6. 选择正确模式: ops 算子仓用 C++ 模式（脚本自动识别 GE IR / aclnn），自定义算子用 Python 模式

---

相关文档

• CANN 官方文档 - mssanitizer 使用指南
• MindStudio 文档 - 检测CANN软件栈的内存
• 错误类型详解
• mssanitizer 使用指南