CANN Runtime 回调式 Dump 实战基于 acldumpRegCallback 解析单算子 Dump 数据块【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime导读本文以 CANN Runtime 开源仓库中1_adump_callback示例为切入点系统讲解如何在单算子执行场景下通过acldumpRegCallback注册回调函数、以数据块Chunk形式实时接收 Dump 数据并解析acldumpChunk中的文件名、偏移、分块标记、flag 与数据预览字段。读完本文你将掌握回调式 Dump 的完整调用流程、acldumpChunk结构体各字段的语义与使用建议以及如何将分块回调数据与acldumpGetPath查询到的落盘路径对应为后续自行实现 Dump 数据实时处理如流式落盘、在线校验、旁路监控打下基础。一、为什么需要回调式 Dump在常规 Dump 流程中Dump 数据由 Runtime 按配置直接写入磁盘文件如acl.json中dump_path指定的目录。这种配置即落盘的模式简单可靠但存在两个局限事后才能取数需要等待算子执行结束、再按文件路径读取转换无法在数据产生的第一时间消费路径与数据解耦调用方需要自行维护 Dump 配置与输出文件之间的对应关系。回调式 Dump 则提供了另一条通路通过acldumpRegCallback注册一个回调函数Dump 数据不再直接落盘而是以内存块的形式分片Chunk推送给回调函数。应用可以在回调中完成数据预览、统计、校验、流式写盘等自定义处理实现了Dump 数据即产即取。在 CANN Runtime 开源仓库中1_adump_callback示例正是这一能力的完整落地位于 example/5_performance/adump/1_adump_callback 目录与0_adump_args算子信息统计、2_model_dump_config配置式 Dump、3_save_exception_info异常算子 Dump共同构成 adump 能力的递进示例集合详见 example/5_performance/adump/README.md。二、示例目录与文件构成example/5_performance/adump/1_adump_callback/ ├── CMakeLists.txt # 编译配置链接 ascendcl / nnopbase / opapi / ascend_dump 库 ├── README.md # 本示例说明本文主体依据 ├── README_en.md # 英文说明 ├── acl.json # Dump 配置文件开启 tensor 数据 Dump ├── main.cpp # 示例主程序初始化、注册回调、执行 Add 算子、解析回调 └── run.sh # 一键编译运行脚本其中 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)关键点在于libascend_dump.so——acldumpRegCallback等 Dump 接口的实现即位于该动态库中。三、产品支持情况本示例支持以下产品产品是否支持Ascend 950PR/Ascend 950DT√Atlas A3 训练系列产品/Atlas A3 推理系列产品√Atlas A2 训练系列产品/Atlas A2 推理系列产品√环境的安装与运行详情见 example 目录下的 README在仓库中对应为 example/README.md。四、编译与运行环境安装详情以及运行详情请见 example 目录下的 README。运行步骤如下# ${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内部会依次完成source $_ASCEND_INSTALL_PATH/bin/setenv.bash cmake -B build -DASCEND_CANN_PACKAGE_PATH${_ASCEND_INSTALL_PATH} cmake --build build -j cmake --install build ./build/main | tee output_msg.txt即加载 CANN 环境变量 → 配置并编译工程 → 运行可执行文件同时将输出通过tee保存到output_msg.txt便于事后核对回调统计信息。五、核心接口回调的注册、查询与去注册5.1 acldumpRegCallback注册 Dump 回调接口原型定义于头文件 include/external/acl/acl_dump.hACL_DUMP_API aclError acldumpRegCallback(int32_t (*const messageCallback)(const acldumpChunk*, int32_t), int32_t flag);messageCallback回调函数指针。每次有 Dump 数据块产生时Runtime 会以(const acldumpChunk*, int32_t len)形式调用它其中len表示本次回调携带的总字节数结构体头 数据体。flag预留标志位。从当前仓库实现看目前仅允许传 0。从源码实现 src/dfx/adump/adump/host/adx_datadump_callback.cpp 可以看到底层校验逻辑aclError acldumpRegCallback(int32_t (*const messageCallback)(const acldumpChunk*, int32_t), int32_t flag) { if (messageCallback nullptr) { REPORT_EP0007_NULL_POINTER(...); // 回调为空直接报错 return ACL_ERROR_FAILURE; } if (flag ! 0) { ... // flag 非 0 视为非法参数 return ACL_ERROR_FAILURE; } Adx::MessageCallback adxMessageCallback reinterpret_castAdx::MessageCallback(messageCallback); int32_t ret Adx::AdxRegDumpProcessCallBack(adxMessageCallback); ... return ACL_SUCCESS; }也就是说回调指针为空或flag非 0 时接口会返回ACL_ERROR_FAILURE注册成功后回调被交给AdxDumpProcess单例MessageCallbackRegister后续 Dump 数据块即由该处理链路派发给用户回调。5.2 acldumpUnregCallback去注册回调ACL_DUMP_API void acldumpUnregCallback();该接口无参、无返回值底层调用AdxUnRegDumpProcessCallBack()→MessageCallbackUnRegister()将回调从 Dump 处理链路中摘除。示例中在程序收尾阶段调用见 main.cpp 第 178 行保证 Dump 回调生命周期与主程序一致。5.3 acldumpGetPath查询 Dump 输出路径ACL_FUNC_VISIBILITY const char* acldumpGetPath(acldumpType dumpType);按 Dump 类型查询当前输出路径返回路径字符串失败返回NULL。Dump 类型枚举同样定义在 acl_dump.h 中枚举值含义AIC_ERR_BRIEF_DUMP 1轻量异常 DumpAIC_ERR_NORM_DUMP 2常规异常 Dump额外导出 shape/数据类型/format/属性AIC_ERR_DETAIL_DUMP 3NPU coredump额外导出 AI Core 内部内存、寄存器和调用栈DATA_DUMP 4模型 Dump 或单算子 DumpOVERFLOW_DUMP 5溢出算子 Dump示例中调用acldumpGetPath(DATA_DUMP, ./)查询单算子数据 Dump 的路径用于与回调收到的fileName做对应见下文第六节。六、acldumpChunk回调数据块结构体详解回调的核心数据结构是acldumpChunk定义于 include/external/acl/acl_dump.h#define ACL_DUMP_MAX_FILE_PATH_LENGTH 4096 typedef struct acldumpChunk { char fileName[ACL_DUMP_MAX_FILE_PATH_LENGTH]; // name of the dump data file to be written, absolute path uint32_t bufLen; // length of dataBuf, in bytes uint32_t isLastChunk; // whether it is the last chunk. 0: no, 1: yes int64_t offset; // offset of the content in the dump data file. -1: append write int32_t flag; // reserved flag of the dump data, no flag is defined currently uint8_t dataBuf[0]; // memory address of the dump data } acldumpChunk;字段语义与使用建议汇总如下与 dump_artifact_analysis.md 中的回调字段一节一致字段含义使用建议fileNameDump 数据原计划写入的绝对文件名。用于按文件名归并同一个 tensor 或同一次 Dump 的数据块。bufLendataBuf的字节长度。判断本次回调携带的数据大小。isLastChunk是否为最后一个数据块0表示否1表示是。只有收到最后一块后才应认为该文件的数据接收完整。offset当前数据块写入文件时的偏移-1表示追加写。用于按偏移还原分块数据。flag预留标志位。当前未定义具体标志通常仅记录。dataBufDump 数据内容地址零长数组紧跟结构体头。按bufLen读取字节数据再结合文件名或元信息解析。需要特别注意的是dataBuf[0]的零长数组设计Dump 数据紧跟在acldumpChunk结构体头部之后因此回调收到的总长度len应满足sizeof(acldumpChunk) bufLen len示例正是用这一等式做数据完整性校验见下一节。七、回调解析实现剖析示例主程序位于 main.cpp回调解析的核心逻辑可分为四个部分。7.1 数据校验与统计int32_t DumpTensorCallback(const acldumpChunk* data, int32_t len) { if (data nullptr) { ERROR_LOG(Callback data is null!); return -1; } if ((sizeof(acldumpChunk) >std::string BuildChunkPreview(const acldumpChunk* data) { const uint32_t previewLen std::minuint32_t(data-bufLen, 16U); std::ostringstream preview; preview std::hex std::setfill(0); for (uint32_t i 0; i previewLen; i) { if (i ! 0) { preview ; } preview std::setw(2) static_castuint32_t(data-dataBuf[i]); } if (data-bufLen previewLen) { preview ...; } return preview.str(); }预览逻辑取dataBuf前 16 字节按十六进制逐字节格式化xx xx xx ...超过 16 字节则追加省略号。这一做法在生产调试中非常实用无需解析整个 tensor即可快速肉眼判断数据是否符合预期例如全 0、全 0xFF 或值域明显异常。7.3 按文件归并统计std::mutex gCallbackMutex; std::mapstd::string, int32_t gChunkCountByFile; int32_t gTotalChunkCount 0; int64_t gTotalBytes 0;回调可能被多个 Dump 数据源并发触发因此示例用std::mutex保护统计状态每次回调递增gTotalChunkCount、累加gTotalBytes并按fileName累加分块计数。程序结束时打印汇总INFO_LOG(Dump callback summary: total chunks%d, total bytes%ld, total files%d, ...);7.4 回调信息输出INFO_LOG( Receive dump tensor data success. file%s, bufLen%u, isLastChunk%u, offset%ld, flag%d, preview%s, >[INFO] acldumpGetPath returned dump path: ... [INFO] Get workspace size... [INFO] Begin to add... [INFO] Receive dump tensor data success. file..., bufLen..., isLastChunk..., offset..., flag..., preview... [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] Dump callback summary: total chunks..., total bytes..., total files... [INFO] Run the device_normal sample successfully.逐行解读acldumpGetPath returned dump path为当前单算子 Dump 输出路径可与回调中file的绝对路径前缀相互印证Receive dump tensor data success每出现一次代表一个 Dump 数据块回调isLastChunk1表示该文件最后一块result[i]为 Add 算子逐元素结果{1,2,3,5,6,7,10,11}恰好等于输入self other * alpha第 3 个元素213第 4 个元素325依此类推可作为校验 Dump 数据正确性的对照基准Dump callback summary汇总了total chunks总块数、total bytes总字节数、total files总文件数以及每个文件的块数分布。九、Dump 配置文件说明示例使用acl.json见 acl.json开启单算子 tensor 数据 Dump{dump: {dump_path: ./, dump_list: [], dump_op_switch: on, dump_data: tensor}}配置项值说明dump_path./Dump 输出目录模型 Dump 与单算子数据 Dump 均由该配置决定环境变量不覆盖参见 dump_artifact_analysis.md本示例的acldumpGetPath(DATA_DUMP)返回值即来源于此dump_list[]算子过滤列表为空表示不按算子名过滤dump_op_switchonDump 总开关dump_datatensorDump 数据类型为 tensor 数据该配置在aclInit(./acl.json)时生效因此回调式 Dump 并非完全脱离配置——dump_op_switch与dump_data决定哪些数据进入 Dump 链路而回调决定这些数据由谁消费。配置接口的调用顺序与参数约束可进一步参考 docs/zh/api_ref/18_dump_configuration.md。十、从回调到落盘Dump 文件解读与转换回调收到的fileName即 Dump 数据原计划写入的绝对文件名。若需要在回调之外自行落盘或离线分析可参照 dump_artifact_analysis.md 中的通用方法路径定位模型 Dump、单算子数据 Dump 和溢出算子 Dump 的文件目录由配置dump_path指定算子信息统计文件由aclopStartDumpArgs的path参数指定异常算子 Dump 根路径为dumpPath/extra-info/data-dump/deviceId/优先级为ASCEND_DUMP_PATHASCEND_WORK_PATH 配置文件dump_path 当前目录./。格式转换以 numpy 为例msaccucmp.py convert -d dump_file -out output_dir注意aclopStartDumpArgs生成的算子信息文件不适用于上述 tensor 转换命令。数据查看import numpy as np data np.load(converted_file.npy) print(data.shape) print(data.dtype) print(data)针对回调数据的分析建议必须按fileName、offset和isLastChunk将分块数据还原为完整文件后再分析——offset决定数据在文件中的写入位置isLastChunk1才代表该文件数据接收完整。示例中仅做预览与统计未将块内容写盘如需完整还原应在回调内按fileName维护分片缓冲依据offset与bufLen拼接后再统一落盘。十一、小结1_adump_callback展示了 CANN Runtime 回调式 Dump 的最小完整闭环接口面acldumpRegCallback注册→acldumpGetPath查询路径→acldumpUnregCallback去注册配合aclInit加载acl.json开启单算子 tensor Dump数据结构acldumpChunk的零长数组dataBuf设计使数据块头部与数据体连续存放回调需用sizeof(acldumpChunk) bufLen与len校验自洽性工程要点回调可能并发触发需加锁保护统计状态分块数据须按fileName/offset/isLastChunk归并还原后才能得到完整文件底层佐证接口实现位于 src/dfx/adump/adump/host/adx_datadump_callback.cpp注册与去注册最终落到AdxDumpProcess单例的回调注册/摘除是理解整个 Dump 派发链路的起点。掌握本示例后你可以将其扩展为实时数据校验器、流式落盘器或 Dump 数据旁路分析工具这也是 CANN 生态中算子精度排查与在线监控的常用工程手段。已知 issue本示例当前无已知问题。【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考