前言

在大规模 AI 集群部署中，硬件抽象层（HAL）与驱动模块的稳定性直接决定了上层应用的可靠性。CANN 开源项目中的 driver 仓库（https://atomgit.com/cann/driver）作为底层资源管理与调度的核心组件，其运行状态直接影响整个计算栈的健壮性。然而，当设备异常、任务崩溃或性能骤降发生时，传统人工排查方式效率低下且易遗漏关键线索。

1. 故障诊断的挑战与 CANN driver 的可观测性设计

1.1 驱动层故障的典型表现

根据 driver 仓库的 Issue 记录（如 #24 中描述的芯片复位失败、#11 中的设备共享异常），常见故障包括：

• 设备状态变为 UNHEALTHY 或离线
• AI Core 执行非法指令导致硬件异常
• 共享虚拟内存（SVM）访问越界
• 任务调度器（TS）死锁或超时
• 容器环境下设备节点权限或映射错误

这些故障往往伴随内核日志（dmesg）、用户态 core dump、寄存器快照等多源异构数据，人工关联分析成本极高。

1.2 driver 仓库内置的可观测机制

CANN driver 在架构设计之初即嵌入了可观测性支持，主要体现在以下模块：

• bbox（Black Box）：位于 src/ascend_hal/bbox/，用于在系统临终（panic/crash）时自动保存关键寄存器、内存镜像和执行上下文。
• fms（Fault Manage System）：位于 src/sdk_driver/fms/，提供用户态故障上报接口，支持与上层 runtime 协同触发诊断流程。
• logdrv：位于 src/ascend_hal/dmc/logdrv/，统一日志输出通道，支持分级（DEBUG/INFO/WARN/ERROR）与模块过滤。
• msnpureport：位于 src/ascend_hal/msnpureport/，用于导出设备侧维测信息（如 ECC 错误计数、温度告警）。

✅ 关键设计：driver 通过 uda（Unified Device Access）和 urd（User Request Distribute）模块，将内核态异常事件以标准化格式传递至用户态，为 oam-tools 提供结构化输入。

---

2. oam-tools 与 driver 的协同架构

oam-tools 并非孤立工具，而是与 driver 深度集成的诊断代理。其整体协同架构如下：

该架构中，driver 负责“现场保全”，oam-tools 负责“智能分析”，二者通过标准文件路径与事件接口解耦，确保高内聚低耦合。

---

3. 自动化故障捕获：从 driver 异常到现场冻结

3.1 黑匣子（BBox）机制详解

当内核检测到严重错误（如 PCIe fatal error），driver 的 bbox 模块会触发以下流程：

1. 冻结当前 NPU 上下文（PC、寄存器、L2 Cache）
2. 将关键内存区域（如 task control block） dump 至 /var/log/npu/bbox/
3. 更新设备状态为 CRITICAL

相关代码位于 src/ascend_hal/bbox/bbox_core.c：

// bbox_core.c (简化示意)
void bbox_save_context(struct npu_device *dev) {
    // 1. 保存 PC 和通用寄存器
    write_register_snapshot(dev->core_id, &dev->regs);
    
    // 2. Dump L2 Cache 关键行（仅保留脏数据）
    cache_dump_selective(dev->l2_cache, DIRTY_ONLY);
    
    // 3. 记录时间戳与错误码
    struct bbox_header hdr = {
        .magic = BBOX_MAGIC,
        .timestamp = ktime_get_ns(),
        .error_code = dev->last_error
    };
    bbox_write_header(&hdr);
    
    // 4. 触发用户态通知（通过 sysfs 或 netlink）
    notify_userspace_fault(dev->id);
}

💡 此机制确保即使系统重启，故障现场仍可被 oam-tools 后续分析。

3.2 用户态故障上报（FMS）

对于非致命错误（如算子校验失败），driver 通过 fms 模块主动上报：

// src/sdk_driver/fms/fms_report.c
int fms_report_error(enum fms_error_type type, const char *msg) {
    struct fms_event evt = {
        .type = type,
        .timestamp = get_current_time(),
        .message = msg
    };
    
    // 写入环形缓冲区，避免阻塞
    ring_buffer_push(g_fms_rb, &evt);
    
    // 若为严重错误，触发 oam-tools hook
    if (type >= FMS_ERROR_CRITICAL) {
        exec_user_hook("/usr/local/Ascend/oam-tools/bin/msaicerr-trigger");
    }
    return 0;
}

该设计使得 oam-tools 可在错误发生的第一时间介入，而非被动等待巡检。

---

4. 根因分析自动化：oam-tools 的核心能力实践

4.1 asys：集群健康状态一键评估

asys 工具通过读取 driver 暴露的 sysfs 接口（如 /sys/class/hisi-npu/device0/health）获取设备状态：

# 查询设备健康度
asys device info -i 0 --detail

# 输出关键字段：
# Health: OK
# Temperature: 68°C
# Power: 295W
# ECC Correctable Errors: 0
# ECC Uncorrectable Errors: 0
# Device Share Status: True  # 来自 PR !35 的新特性

若发现 ECC Uncorrectable Errors > 0，asys 可自动关联 bbox 日志：

asys health-check --auto-analyze --output ./diagnosis_$(date +%s).tar.gz

该命令内部调用逻辑如下（伪代码）：

def auto_analyze():
    if get_ecc_uncorrectable() > 0:
        collect_bbox_logs()
        run_msaicerr_on_latest_dump()
        generate_timeline_with_msprof()

4.2 msaicerr：AI Core Error 深度解析

当 bbox 生成 core_*.dump 文件后，msaicerr 可解析其内容：

msaicerr analyze --dump /var/log/npu/bbox/core_12345.dump \
                 --symbol /path/to/model.so \
                 --output ./root_cause.json

输出 JSON 包含：

{
  "error_type": "ILLEGAL_INSTRUCTION",
  "faulty_address": "0x7f8a1b2c3d4e",
  "disassembled_insn": "vadd.s32 v0, v1, v2",
  "possible_cause": "Operand alignment violation in custom kernel",
  "suggested_fix": "Check tensor stride in CustomConv2D implementation"
}

📌 技术细节：msaicerr 利用 driver 提供的 queryfeature 模块（src/ascend_hal/queryfeature/）获取芯片指令集版本，确保反汇编准确性。

4.3 msprof：性能异常关联分析

若故障表现为性能下降（非崩溃），msprof 可采集 timeline：

# 在复现脚本中注入 profiling
export PROFILING_MODE=on
python reproduce_issue.py

# 分析结果
msprof analyze --input ./profiling_data --format summary

输出将显示异常耗时的算子，结合 fms 日志可判断是否因 driver 调度延迟导致。

---

5. 构建端到端自动化诊断流水线

将上述能力整合为 CI/CD 中的诊断流水线：

# .gitlab-ci.yml 示例
stages:
  - test
  - diagnose

run_ai_test:
  stage: test
  script:
    - python test_model.py || echo "TEST_FAILED" > /tmp/status

postmortem_analysis:
  stage: diagnose
  when: on_failure
  script:
    - if [ -f /tmp/status ]; then
          asys health-check --auto-analyze --output ./postmortem.tar.gz;
          curl -F "file=@./postmortem.tar.gz" http://diagnosis-server/upload;
      fi

该流水线确保每次测试失败后，自动生成包含 driver 日志 + bbox dump + 性能 trace 的完整诊断包，极大提升问题复现与修复效率。

---

6. 未来演进：向预测性维护迈进

当前 oam-tools + driver 的组合已实现“故障后诊断”，下一步将向 预测性维护 演进：

• 利用 dsmi（Device System Manage Interface）模块持续采集设备健康指标
• 通过机器学习模型预测 ECC 错误增长趋势
• 在故障发生前触发预防性迁移或告警

driver 仓库中的 src/ascend_hal/dmc/device_monitor/ 模块已预留此能力接口。

---

结语

CANN driver 与 oam-tools 的深度协同，构建了一套从内核态到用户态、从现场保全到根因定位的完整故障诊断闭环。通过利用 driver 内置的 bbox、fms、logdrv 等可观测模块，结合 oam-tools 的 asys、msaicerr、msprof 等分析工具，开发者可实现 分钟级故障定位 与 自动化根因报告生成，显著提升大规模 AI 集群的运维效率与系统稳定性。

随着 CANN 社区对 driver 仓库的持续开源（如容器设备共享、版本兼容性优化等新特性），oam-tools 的诊断能力也将同步增强，为构建高可靠 AI 基础设施提供坚实支撑。

🔗 相关链接：

• CANN 组织主页：https://atomgit.com/cann
• driver 仓库地址：https://atomgit.com/cann/driver