企业官网建设流程全解析

CANN Runtime 算子信息 Dump 实战：基于 aclopStartDumpArgs 的单算子执行与算子参数落盘

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime

导读

本文围绕 CANN/runtime 仓库中的0_adump_args示例（README_en.md），讲解在单算子（Single Operator）执行场景下如何通过 AscendCL Dump 机制采集算子信息。读者将掌握aclopStartDumpArgs/aclopStopDumpArgs/acldumpGetPath三件套的完整用法，理解算子信息文件（包含算子类型、算子属性、输入输出 format/数据类型/shape 等）如何按 shape 落盘到指定目录，并结合仓库源码看清 Dump 开关的底层实现链路。

示例定位：单算子执行场景下的算子信息采集

0_adump_args是example/5_performance/adump/目录下的一个独立示例，它的核心能力是：

• 在单算子执行场景下管理 Dump 算子信息（Dump operator arguments）；
• 将算子信息文件输出到path参数指定的目录；
• 主线程中设置 Device，一个 shape 对应一个算子信息文件；
• 算子信息文件中包含算子类型、算子属性、算子输入&输出的 format/数据类型/shape 等信息。

该示例被组织为一段完整可运行的 C++ 工程，目录内包含：

产品支持情况

根据示例文档，该能力支持以下产品：

编译与运行：三步拿到算子信息文件

环境安装与运行时详情以 example 目录下的 README_en.md 为准。运行步骤如下：

# ${install_root} 替换为 CANN 安装根目录，默认安装在 /usr/local/Ascend 目录 source ${install_root}/cann/set_env.sh # 自动识别 SOC_VERSION 和 ASCENDC_CMAKE_DIR source ${git_clone_path}/example/set_sample_env.sh # 编译并运行 bash run.sh

run.sh的内部逻辑（见 run.sh）依次完成：

1. 读取环境变量ASCEND_INSTALL_PATH并加载${ASCEND_INSTALL_PATH}/bin/setenv.bash；
2. 清理并重建build目录；
3. 通过cmake -B build -DASCEND_CANN_PACKAGE_PATH=${_ASCEND_INSTALL_PATH}配置工程，随后cmake --build build -j编译、cmake --install build安装；
4. 运行./build/main并将终端输出同时写入output_msg.txt（用于保存运行日志）。

在 CMakeLists.txt 中可以看到示例依赖的运行时库，这从构建层面印证了 Dump 功能属于独立的维测组件：

target_link_libraries(main PRIVATE ${ASCEND_CANN_PACKAGE_PATH}/lib64/libascendcl.so ${ASCEND_CANN_PACKAGE_PATH}/lib64/libnnopbase.so ${ASCEND_CANN_PACKAGE_PATH}/lib64/libopapi.so ${ASCEND_CANN_PACKAGE_PATH}/lib64/libascend_dump.so)

其中libascendcl.so提供 AscendCL 运行时接口，libopapi.so提供算子 API（aclnnAdd等），libascend_dump.so提供 Dump 能力——这也是示例同时引入acl/acl.h、acl/acl_dump.h与aclnnop/aclnn_add.h头文件的原因。

关键接口全景：Dump 生命周期管理

示例文档将整个示例中用到的 CANN Runtime API 归纳为五个维度，对应关系如下：

初始化（AscendCL 配置与 Dump 开关）

• aclInit：初始化 AscendCL 配置；
• aclopStartDumpArgs：使能 Dump 算子信息；
• acldumpGetPath：查询当前 Dump 输出路径；
• aclopStopDumpArgs：去使能 Dump 算子信息；
• aclFinalize：AscendCL 去初始化。

Device 管理

• aclrtSetDevice：指定用于运算的 Device；
• aclrtSynchronizeDevice：阻塞等待正在运算的 Device 完成运算；
• aclrtResetDeviceForce：强制复位当前运算的 Device，回收 Device 上的资源。

Stream 管理

• aclrtCreateStream：创建 Stream；
• aclrtSynchronizeStream：阻塞等待 Stream 上任务完成；
• aclrtDestroyStream：销毁 Stream。

内存管理

• aclrtMalloc：申请 Device 上的内存；
• aclrtFree：释放 Device 上的内存。

数据传输

• aclrtMemcpy：通过内存复制实现数据传输（示例中用于将 Device 侧的算子结果拷回 Host 并打印）。

本示例新增覆盖的关键接口是acldumpGetPath：用于查询当前 Dump 输出路径，便于确认 Dump 结果的落盘目录。

主程序逐段拆解：一个 shape 一份算子信息

main.cpp 的执行脉络清晰，分为七个阶段：

1. 初始化与使能 Dump

// 示例默认使用 device 0，Dump 配置指向 ./acl.json，落盘目录为 /tmp int32_t deviceId = 0; const char* dumpCfgPath = "./acl.json"; const char* dumpPath = "/tmp"; INFO_LOG("The dump data path is %s.", dumpPath); CHECK_ERROR(adump::InitRuntime(deviceId, &stream, dumpCfgPath)); // 使能 Dump 算子信息（AICore Args 类型） CHECK_ERROR(aclopStartDumpArgs(ACL_OP_DUMP_OP_AICORE_ARGS, dumpPath)); // 查询并打印当前 Dump 路径 LogDumpPath(DATA_DUMP, dumpPath);

adump::InitRuntime定义在 adump_tensor_utils.h 中，它封装了通用的runtime::InitRuntimeAndCreateStream（实现位于 runtime_init_utils.h），负责完成aclInit、aclrtSetDevice、aclrtCreateStream以及加载 Dump 配置等初始化动作。

LogDumpPath是本示例新覆盖接口acldumpGetPath的典型用法——用DATA_DUMP类型查询数据 Dump 路径，查询成功则打印，失败则回退到传入的fallbackPath并告警。

2. 构造输入输出张量

示例构建了 shape 为{4, 2}、数据类型为ACL_FLOAT的两个输入张量和一个输出张量：

std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7}; std::vector<float> otherHostData = {1, 1, 1, 2, 2, 2, 3, 3}; std::vector<float> outHostData = {0, 0, 0, 0, 0, 0, 0, 0}; float alphaValue = 1.0f;

张量通过adump::CreateAclTensor在 Device 上分配内存（aclrtMalloc）并拷贝 Host 数据（aclrtMemcpyH2D），再以aclCreateTensor包装为aclTensor；标量alpha通过aclCreateScalar创建。这正是算子信息文件里 format（ACL_FORMAT_ND）、数据类型（ACL_FLOAT）与 shape 信息的来源。

3. 调用算子 API 执行 Add

uint64_t workspaceSize = 0; aclOpExecutor* executor; CHECK_ERROR(aclnnAddGetWorkspaceSize(self, other, alpha, out, &workspaceSize, &executor)); void* workspaceAddr = nullptr; if (workspaceSize > 0lu) { CHECK_ERROR(aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST)); } CHECK_ERROR(aclnnAdd(workspaceAddr, workspaceSize, executor, stream));

先查询 workspace 大小并按其分配 Device 内存，再在指定 Stream 上异步下发 Add 算子。

4～5. 同步等待并取回结果

CHECK_ERROR(aclrtSynchronizeStream(stream)); // 将结果从 Device 内存拷回 Host 并逐个打印 CHECK_ERROR(aclrtMemcpy(resultData.data(), ..., outDeviceAddr, ..., ACL_MEMCPY_DEVICE_TO_HOST));

6～7. 释放资源与关闭 Dump

adump::DestroyTensorResources(self, other, alpha, out); CHECK_ERROR(aclrtFree(selfDeviceAddr)); // 以及 other/out/workspace // 去使能 Dump 算子信息 CHECK_ERROR(aclopStopDumpArgs(ACL_OP_DUMP_OP_AICORE_ARGS)); CHECK_ERROR(aclrtDestroyStream(stream)); CHECK_ERROR(aclrtResetDeviceForce(deviceId)); CHECK_ERROR(aclFinalize());

注意示例在aclFinalize之前先调用了aclopStopDumpArgs，确保算子信息完整落盘后再做去初始化和 Device 强制复位——这是 Dump 生命周期管理的关键顺序。

源码级原理：Dump 开关在 Runtime 内如何落地

三个 Dump 相关接口的实现在 adump_api_platform.cpp 中，与头文件 acl_dump.h 一一对应。

dumpType 与 acldumpType 枚举

acl_dump.h中定义了 Dump 类型枚举与开启开关的宏：

#define ACL_OP_DUMP_OP_AICORE_ARGS 0x00000001U typedef enum acldumpType { AIC_ERR_BRIEF_DUMP = 1, // lite exception dump AIC_ERR_NORM_DUMP = 2, // 常规异常 dump，额外记录 shape/数据类型/format/属性 AIC_ERR_DETAIL_DUMP = 3, // npu coredump，额外记录 AI Core 内部内存、寄存器与调用栈 DATA_DUMP = 4, // 模型 dump 或单算子 dump OVERFLOW_DUMP = 5 // 溢出算子 dump } acldumpType;

示例中以ACL_OP_DUMP_OP_AICORE_ARGS作为aclopStartDumpArgs的 dumpType，以DATA_DUMP作为acldumpGetPath的查询类型。

aclopStartDumpArgs：参数校验 + 委托 DumpManager

从源码可见，aclopStartDumpArgs会做两层校验后委托给Adx::DumpManager：

• path == nullptr时上报 EP0007 空指针错误并返回ACL_ERROR_FAILURE；
• dumpType必须等于ACL_OP_DUMP_OP_AICORE_ARGS，否则上报 EP0006 非法参数错误；
• 校验通过后调用DumpManager::Instance().StartDumpArgs(dumpPath)，失败返回ACL_ERROR_FAILURE，成功返回ACL_SUCCESS。

aclopStopDumpArgs：对称地去使能

aclError aclopStopDumpArgs(uint32_t dumpType) { if ((dumpType & ACL_OP_DUMP_OP_AICORE_ARGS) == ACL_OP_DUMP_OP_AICORE_ARGS) { if (Adx::DumpManager::Instance().StopDumpArgs() != 0) { return ACL_ERROR_FAILURE; } } return ACL_SUCCESS; }

acldumpGetPath：按类型分发路径查询

const char* acldumpGetPath(acldumpType dumpType) { switch (dumpType) { case acldumpType::AIC_ERR_BRIEF_DUMP: case acldumpType::AIC_ERR_NORM_DUMP: case acldumpType::AIC_ERR_DETAIL_DUMP: return Adx::DumpManager::Instance().GetExtraExceptionDumpPath(); case acldumpType::DATA_DUMP: case acldumpType::OVERFLOW_DUMP: return Adx::DumpManager::Instance().GetDataDumpPath(); default: return nullptr; } }

异常类 Dump（AIC_ERR 系列）查询的是异常补充信息路径，数据类 Dump（DATA_DUMP / OVERFLOW_DUMP）查询的是数据落盘路径；未知类型返回nullptr。这与示例文档“查询当前 Dump 输出路径，便于确认 Dump 结果的落盘目录”的定位完全一致。

从源码结构可以推断，StartDumpArgs/StopDumpArgs经由DumpManager注册的模块回调（如 adump_api_platform.cpp 中的AdumpRegisterCallback）分发到具体落盘模块，从而在算子执行期间捕获 AICore Args。

Dump 配置文件 acl.json

示例根目录下的 acl.json 是 Dump 功能的配置文件：

{"dump": {"dump_path": "./", "dump_list": [], "dump_op_switch": "on", "dump_data": "tensor"}}

各字段含义如下：

该配置由adump::InitRuntime传入的dumpCfgPath参数（"./acl.json"）加载。需要说明的是，本示例中算子信息的实际落盘目录由aclopStartDumpArgs的path参数（"/tmp"）直接指定，acl.json负责的是 Dump 功能的使能配置。

运行结果解读

示例文档给出的标准输出如下：

[INFO] The dump data path is /tmp. [INFO] acldumpGetPath returned dump path: ... [INFO] result[0] is: 1.000000 [INFO] result[1] is: 2.000000 [INFO] result[2] is: 3.000000 [INFO] result[3] is: 5.000000 [INFO] result[4] is: 6.000000 [INFO] result[5] is: 7.000000 [INFO] result[6] is: 10.000000 [INFO] result[7] is: 11.000000 [INFO] Run the device_normal sample successfully. please make sure dump data has been in path: /tmp

逐行解读：

• 第一行确认aclopStartDumpArgs指定的落盘路径为/tmp；
• 第二行是acldumpGetPath(DATA_DUMP)查询返回的实际路径（不同版本返回格式可能带时间戳或 deviceId 子目录，示例中以...示意）；
• result[0] ~ result[7]是 Add 算子的执行结果，即self + alpha * other的逐元素和（例如0+1=1、3+2=5、6+3=9等，与selfHostData、otherHostData吻合）；
• 最后一行提示运行成功，并提醒在/tmp目录下确认算子信息 Dump 文件已经落盘。

已知问题

示例文档声明该示例暂无已知 issue（Known Issues: None）。在使用时建议注意以下前提：Dump 算子信息能力与具体的昇腾产品形态相关（参见本文“产品支持情况”小节），且需要在初始化阶段加载 Dump 配置并严格按aclopStartDumpArgs→ 执行算子 →aclopStopDumpArgs的顺序使用，以保证算子信息文件完整落盘。

延伸阅读

• 示例通用构建与运行说明：example/README_en.md、example/README.md；
• 同目录下的其他 Dump 场景示例：1_adump_callback、2_model_dump_config、3_save_exception_info；
• Dump 公共工具：adump_tensor_utils.h；
• 运行时初始化公共工具：runtime_init_utils.h；
• 接口声明：acl_dump.h；
• 接口实现：adump_api_platform.cpp。

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime