CANN 组织链接： https://atomgit.com/cann
oam-tools 仓库链接： https://gitcode.com/cann/oam-tools

1. 故障定位在异构计算中的复杂性

CANN 算子执行涉及用户态代码（Ascend C/Python）、CANN Runtime、驱动层以及物理 NPU 硬件的交互。故障可能源于任何一个层次，因此需要一套系统化的工具来剥离和定位问题。

1.1 错误隔离的挑战

当一个自定义算子执行失败时，需要区分错误是来源于：

1. 编译错误：Tiling 函数逻辑错误或 Ascend C 语法错误。
2. 运行时逻辑错误：算子内部的内存越界、数据未初始化，或错误的同步操作。
3. 环境/驱动错误：硬件初始化失败、驱动版本不匹配，或通信（SHMEM）配置错误。

2. OAM-TOOLS：一键式信息采集与诊断

oam-tools（Operation and Maintenance Tools）提供了一套命令行工具，用于系统性地收集和展示 CANN 环境中的关键健康指标和故障信息，极大地简化了复杂环境下的故障诊断流程。

2.1 环境健康检查与驱动校验

工具集的核心功能之一是对系统环境的快速校验，确保底层通信链路的完整性。

• 驱动版本比对：工具可以自动读取已安装的驱动版本、固件版本，并与当前 CANN Toolkit 版本进行比对，识别潜在的不兼容性。
• NPU 连通性：执行类似 npu-smi info 的操作，但通常集成在工具的子命令中，提供设备状态（如温度、功耗、PCIe 状态）的概览。

2.2 AI Core 错误码的解析与可视化

当 NPU 硬件执行发生异常时，会产生包含硬件状态信息的错误码（通常是十六进制值）。

• 错误码翻译：oam-tools 内置了错误码数据库。它可以接收原始的硬件错误码，并将其翻译成具有可操作性的文本描述。例如，将特定的内存访问异常码解析为“Local Memory 越界访问”或“Cube Unit 指令执行超时”。
• 上下文关联：高级功能可以尝试将错误码与最近执行的算子（从 Runtime 日志中捕获）相关联，指出是哪个算子执行过程中触发了错误。

3. 日志聚合与性能数据关联分析

深度诊断往往需要聚合来自多个组件的日志文件。

3.1 集中式日志收集

对于复杂的分布式训练或推理场景，需要收集来自多个 PE (Processing Element) 的日志。

• 日志文件结构解析：工具能够识别 CANN 在不同组件（如 Driver、Runtime、ACL）下生成的日志文件的命名规范和存放位置，并进行自动化收集和打包。

3.2 与 Profiler 数据的关联

硬件错误（如 Tiling 导致越界）往往需要结合 Profiler 数据才能准确定位。

• 时间戳同步：工具集可以帮助同步 Profiler 导出的时间线数据和 Runtime 日志的时间戳。通过这种关联，可以精确地确定在报告的错误发生前的微秒级时间内，哪个数据拷贝操作（CopyIn/CopyOut）被执行，从而将问题锁定到特定的 Tiling 块或数据偏移量上。

4. 开发者诊断实践：从错误到修复

使用 oam-tools 的标准流程聚焦于快速迭代和修复 Ascend C 编写的自定义算子。

1. 重现与采集：在受控环境下重现错误，并执行 oam-tools collect --task-id=XXX 命令收集所有相关信息。
2. 错误码解析：分析工具输出的错误摘要，确定错误是否为硬件异常（如 ECC 错误）还是软件逻辑错误（如 Aicore 校验失败）。
3. 代码回溯：若错误指向自定义核函数，则结合 Profiler 的时间轴分析，定位是数据准备（DMA/CopyIn）阶段耗时过长，还是计算（Compute）阶段本身执行失败。如果失败，则需修正 Ascend C 中的边界条件、Tiling 参数或内存访问偏移量。

CANN 组织链接： https://atomgit.com/cann
oam-tools 仓库链接： https://gitcode.com/cann/oam-tools