人工智能深度学习算子库CANNAscend【免费下载链接】asc-devkit本项目是CANN 推出的昇腾AI处理器专用的算子程序开发语言原生支持C和C标准规范主要由类库和语言扩展层构成提供多层级API满足多维场景算子开发诉求。项目地址https://gitcode.com/cann/asc-devkit点击查看免费下载上板打印Onboard Print是 Ascend C 调试接口体系中的核心子模块用于在算子核函数Kernel侧直接输出 Tensor 数据内容、偏移位置数据与执行时间戳帮助开发者在不依赖外部调试器的情况下快速定位计算中间结果是否正确。本文以 asc-devkit 仓库中 上板打印文档 为骨架结合接口声明、底层实现、测试用例与配套示例工程系统讲解 DumpTensor、DumpAccChkPoint、PrintTimeStamp 三个接口的用法、约束与原理读完即可在自有算子中落地这套数据可视化 关键点打点的调试方案。1. 上板打印功能概览在 调试接口 目录下Ascend C 提供了上板打印、异常检测、CPU 孪生调试、性能统计四类调试手段其中上板打印onboard_print负责把运行在 AI Core 上的核函数内部数据搬运到 Host 侧可见的打印输出中包含三个接口接口能力头文件DumpTensor打印 Tensor 内容支持自定义标签与按 shape 排版basic_api/kernel_operator_dump_tensor_intf.hDumpAccChkPoint从指定偏移位置开始打印 Tensor 内容同上PrintTimeStamp时间戳打点标记关键执行点并输出当前 cycle 数同上三者统一声明在 kernel_operator_dump_tensor_intf.h 中属于 SIMD 场景调试能力。需要特别注意的是该头文件在编译时做了严格约束若开启--enable-simt纯 SIMT 编译标志会直接报错kernel_operator_dump_tensor_intf.h cannot be used with compile flag --enable-simt enabled即这套上板打印接口只服务于 SIMD向量/矩阵计算编程场景。从定位上看上板打印接口主要用于调试分析开启后会对算子性能产生一定影响通常只在调试阶段使用生产环境建议通过开关关闭详见第 6 节。2. 产品支持情况一览三个接口在不同昇腾产品上的支持情况存在差异汇总如下产品DumpTensorDumpAccChkPointPrintTimeStampAscend 950PR950DT 系列产品支持支持支持Atlas A3 系列产品支持支持支持Atlas A2 系列产品支持支持支持Atlas 200I/500 A2 推理产品支持不支持支持Atlas 推理系列产品 AI Core支持支持不支持Atlas 推理系列产品 Vector Core不支持不支持不支持Atlas 训练系列产品不支持不支持不支持Kirin X90 处理器系列产品支持支持—Kirin 9030 处理器系列产品支持支持——表示原文档未列出该项支持信息。可以看到DumpTensor 覆盖面最广PrintTimeStamp 在 Atlas 推理系列AI Core 与 Vector Core及训练系列上均不可用选用前应首先对照目标产品确认能力。3. DumpTensorTensor 内容可视化打印3.1 功能说明与使用场景DumpTensor 可以在核函数代码中打印 Tensor 的内容同时支持携带一个用户自定义标签desc仅支持uint32_t类型信息例如当前行号用于区分不同位置的 Dump 输出从而精准定位问题来源。典型调用方式为在 Kernel 侧需要观察数据的位置直接调用AscendC::DumpTensor(srcLocal, 5, dataLen);3.2 函数原型DumpTensor 提供两组重载分别对应无 Tensor shape 的打印与带 Tensor shape 的打印// 无 Tensor shape 的打印 template typename T __aicore__ inline void DumpTensor(const LocalTensorT tensor, uint32_t desc, uint32_t dumpSize) template typename T __aicore__ inline void DumpTensor(const GlobalTensorT tensor, uint32_t desc, uint32_t dumpSize) // 带 Tensor shape 的打印 template typename T __aicore__ inline void DumpTensor(const LocalTensorT tensor, uint32_t desc, uint32_t dumpSize, const ShapeInfo shapeInfo) template typename T __aicore__ inline void DumpTensor(const GlobalTensorT tensor, uint32_t desc, uint32_t dumpSize, const ShapeInfo shapeInfo)3.3 参数说明模板参数参数名称描述T需要 dump 的 Tensor 的数据类型函数参数参数名称输入/输出描述tensor输入需要 dump 的 Tensor。位于 UB/L1 Buffer/L0C Buffer 时使用LocalTensor类型位于 Global Memory 时使用GlobalTensor类型desc输入用户自定义附加信息行号或其他自定义数字用于在不同场景下区分 Dump 内容来源dumpSize输入需要 dump 的元素个数shapeInfo输入Tensor 的 shape 信息可按照 shape 排版打印。当 shape 尺寸大于 dumpSize 元素个数时按 shape 打印元素不足部分用-展示当 shape 尺寸小于等于 dumpSize 元素个数时多出的 Dump 数据不展示ShapeInfo结构体定义在 kernel_tensor.h 中包含shapeDim、shape、originalShape与dataFormat字段并提供了(shapeDim, shape[])等构造函数实际使用中可直接用AscendC::ShapeInfo(2, array)形式构造。3.4 支持的数据类型DumpTensor 的模板参数 T 支持的数据类型随产品略有差异产品支持的数据类型Ascend 950PR950DT 系列产品bool、int8_t、uint8_t、hifloat8_t、fp8_e8m0_t、fp8_e5m2_t、fp8_e4m3fn_t、int16_t、uint16_t、half、bfloat16_t、int32_t、uint32_t、float、int64_t、uint64_tAtlas A3/A2 系列、Atlas 200I/500 A2 推理产品、Atlas 推理系列产品 AI Core、Kirin X90/9030bool、int8_t、uint8_t、int16_t、uint16_t、half、bfloat16_t、int32_t、uint32_t、float、int64_t、uint64_t其中 950PR950DT 额外支持hifloat8_t及三种 fp8 类型fp8_e8m0_t、fp8_e5m2_t、fp8_e4m3fn_t适合在 HiFloat8/fp8 量化算子调试中使用。3.5 约束说明使用 DumpTensor 需要遵守以下约束存储位置当前支持打印存储位置为 Unified BufferUB/L1 Buffer/L0C Buffer/Global Memory 的 Tensor 信息Ascend 950PR950DT 系列产品额外新增了BiasTable Buffer 和 Fixpipe Buffer的 Tensor 数据打印。HDK 版本要求针对 950PR950DT使用该接口打印 L1 Buffer、BiasTable Buffer 或 Fixpipe Buffer 数据时HDK 版本需至少升级到25.7.RC1.6 以上。Fixpipe Buffer 打印语义Fixpipe Buffer 保存的是硬件参数位域打印结果不一定与 L1 Buffer 中的原始数据按位相同。前级 Quant 参数每 8 字节保留 bit[7:0]、bit[31:13] 和 bit[46:37]期望值为input 0x00007fe0ffffe0ffULL前级 ReLU 参数每 4 字节保留 bit[31:13]期望值为word 0xffffe000U。地址对齐操作数地址对齐要求请参见 通用地址对齐约束不同存储单元对齐要求不同UB/L1 Buffer 为 32Byte 对齐L0C/BiasTable/Fixpipe Buffer 为 64Byte 对齐L0A/L0B 为 512Byte 对齐。打印大小限制SIMD 场景下单次调用本接口打印的数据总量不可超过打印大小限制默认为 30KB超出则该部分数据不会被打印。可通过 Host 侧aclInit接口的simd_printf_fifo_size_per_core字段调整打印 FIFO 大小配置范围最小 1KB、最大 64MB。3.6 调用示例与打印结果无 Tensor shape 的打印AscendC::DumpTensor(srcLocal, 5, dataLen);对应打印输出格式为DumpTensor: desc5, addr0, data_typefloat16, positionUB, dump_size32随后逐行打印 32 个 float16 元素DumpTensor: desc5, addr0, data_typefloat16, positionUB, dump_size32 [19.000000, 4.000000, 38.000000, 50.000000, 39.000000, 67.000000, 84.000000, 98.000000, 21.000000, 36.000000, 18.000000, 46.000000, 10.000000, 92.000000, 26.000000, 38.000000, 39.000000, 9.000000, 82.000000, 37.000000, 35.000000, 65.000000, 97.000000, 59.000000, 89.000000, 63.000000, 70.000000, 57.000000, 35.000000, 3.000000, 16.000000, 42.000000] DumpTensor: desc5, addr100, data_typefloat16, positionUB, dump_size32 [6.000000, 34.000000, 52.000000, 38.000000, 73.000000, 38.000000, 35.000000, 14.000000, 67.000000, 62.000000, 30.000000, 49.000000, 86.000000, 37.000000, 84.000000, 18.000000, 38.000000, 18.000000, 44.000000, 21.000000, 86.000000, 99.000000, 13.000000, 79.000000, 84.000000, 9.000000, 48.000000, 74.000000, 52.000000, 99.000000, 80.000000, 53.000000] ...带 Tensor shape 的打印分三种情况Shape 等于 dumpSize 元素个数按 shape 二维排版输出uint32_t array[] {static_castuint32_t(8), static_castuint32_t(8)}; AscendC::ShapeInfo shapeInfo(2, array); // dim为2 shape为(8,8) AscendC::DumpTensor(x, 2, 64, shapeInfo); // dump x的64个元素且解析按照shapeInfo的(8,8)排列DumpTensor: desc2, addr0x0, data_typefloat16, positionUB, dump_size64 [[2.048828,0.113037,4.042969,3.505859,4.554688,4.019531,0.598633,2.160156], [2.707031,0.117981,1.134766,4.835938,1.190430,3.085938,1.334961,0.406250], ... [2.820312,2.835938,2.957031,2.398438,4.449219,0.516113,4.796875,0.786133]]Shape 小于 dumpSize 元素个数按 ShapeInfo 打印多出的 Dump 数据不展示输出中会提示dumpSize is greater than shapeSizeuint32_t array1[] {static_castuint32_t(7), static_castuint32_t(8)}; AscendC::ShapeInfo shapeInfo1(2, array1); // dim为2 shape为(7,8) AscendC::DumpTensor(x1, 3, 64, shapeInfo1); // Shape尺寸小于dumpSize多出的数据不展示Shape 大于 dumpSize 元素个数按 ShapeInfo 打印不足的 Dump 数据用-展示输出中会提示data is not enoughuint32_t array2[] {static_castuint32_t(9), static_castuint32_t(8)}; AscendC::ShapeInfo shapeInfo2(2, array2); // dim为2 shape为(9,8) AscendC::DumpTensor(x2, 4, 64, shapeInfo2); // Shape尺寸大于dumpSize不足部分用-展示DumpTensor: desc4, addr0x0, data_typefloat16, positionUB, dump_size64 shape is [9, 8], dumpSize is 64, data is not enough. [[2.048828,0.113037,4.042969,3.505859,4.554688,4.019531,0.598633,2.160156], ... [2.820312,2.835938,2.957031,2.398438,4.449219,0.516113,4.796875,0.786133], [-,-,-,-,-,-,-,-]]3.7 底层实现原理接口声明位于 kernel_operator_dump_tensor_intf.h实现位于 kernel_operator_dump_tensor_intf_impl.h并按 NPU 架构分发到对应的dav_*/kernel_operator_dump_tensor_impl.h。从实现看DumpTensor 的打印链路有以下关键点开关守卫所有 DumpTensor 实现都包裹在#if !(defined(ASCENDC_DUMP) ASCENDC_DUMP 0)中即宏ASCENDC_DUMP0时整个调用被编译为空操作这是生产环境关闭打印的底层机制详见第 6 节。位置分发LocalTensor版本通过DumpTensorLocal2GMImpl按 Tensor 物理位置分发——UB 走asc_dump_ubuf、L1 走asc_dump_l1buf、L0C 走asc_dump_cbuf、BiasTable 与 Fixpipe 走asc_dumpGlobalTensor版本通过DumpTensorGM2GMImpl走asc_dump_gm。对应实现可参见 dav_9201 架构实现。数据通路打印数据写入g_sysPrintFifoSpace系统打印 FIFO 空间实现中会先执行dcci指令刷新 cache line 再写入并通过get_ctrl/set_atomic_none/set_ctrl切换原子模式保证 dump 过程不被并发写干扰。Shape 打印带 shapeInfo 的版本中部分架构如 1001/3002/3003/3113/3102先调用DumpShapeImpl单独打印 shape 行即输出中的shape is [...]提示其余架构则把 shape/shapeDim 直接传给底层 dump 函数。CPU 模式限制除__NPU_ARCH__为 3003/3113 的架构外在 CPU 调试模式下调用会触发ASCENDC_ASSERT断言并报DumpTensor is not supported in cpu mode说明该接口主要面向 NPU 运行场景。4. DumpAccChkPoint指定偏移位置打印4.1 功能说明DumpAccChkPoint 与 DumpTensor 能力基本一致同样支持自定义标签仅uint32_t类型信息如行号核心区别在于可以指定偏移位置它从tensor[countOff]开始打印指定数量的元素适合在循环/分块处理场景中只观察数据流中某一段内容。AscendC::DumpAccChkPoint(srcLocal, 5, 32, dataLen);4.2 函数原型与参数说明template typename T __aicore__ inline void DumpAccChkPoint(const LocalTensorT tensor, uint32_t index, uint32_t countOff, uint32_t dumpSize) template typename T __aicore__ inline void DumpAccChkPoint(const GlobalTensorT tensor, uint32_t index, uint32_t countOff, uint32_t dumpSize)参数名称输入/输出描述tensor输入需要 dump 的 Tensor。位于 UB/L1 Buffer/L0C Buffer 时使用LocalTensor类型位于 Global Memory 时使用GlobalTensor类型index输入用户自定义附加信息行号或其他自定义数字对应输出中的desccountOff输入偏移元素个数。偏移后的 Tensor 地址需满足所在物理位置的对齐约束dumpSize输入需要 dump 的元素个数该接口无返回值。4.3 约束说明与数据类型当前仅支持打印存储位置为 UB/L1 Buffer/L0C Buffer/Global Memory 的 Tensor 信息。针对 Ascend 950PR950DT使用该接口打印 L1 Tensor 数据时HDK 版本需至少升级到25.7.RC1.6 以上。操作数地址对齐要求同 DumpTensor参见 通用地址对齐约束。单次调用打印的数据总量不可超过 30KB另含少量框架需要的头尾信息通常可忽略超出则数据不会被打印。数据类型支持范围与 DumpTensor 完全一致950PR950DT 额外支持 hifloat8_t 与三种 fp8 类型。4.4 调用示例constexpr uint32_t totalLength 256; // 参与搬运的元素个数 AscendC::LocalTensorhalf srcLocal; AscendC::GlobalTensorhalf srcGlobal; AscendC::DataCopy(srcLocal, srcGlobal, totalLength * sizeof(half)); uint32_t index 56; // 用户自定义附加信息此处传入DumpAccChkPoint指令的行号 uint32_t countOff 32; // 偏移元素个数从srcLocal[32]开始打印 uint32_t dumpSize 128; // dump的元素个数从srcLocal[32]开始打印128个元素个数 AscendC::DumpAccChkPoint(srcLocal, index, countOff, dumpSize);打印结果如下注意addr0x40即从第 32 个 half 元素、偏移 64 字节处开始输出DumpTensor: desc56, addr0x40, data_typefloat16, positionUB, dump_size15 [4.710938, 4.707031, 4.773438, 2.271484, 4.347656, 2.359375, 1.284180, 1.073242, 1.242188, 2.298828, 0.521973, 1.099609, 1.880859, 1.226562, 3.916016]4.5 底层实现原理从 kernel_operator_dump_tensor_intf_impl.h 的实现可以看到 DumpAccChkPoint 的两个关键设计越界保护调用前先检查countOff input.GetSize()若越界则断言报错tensor offset [%d] exceeds limit [%d]并直接返回避免非法地址打印。偏移视图通过LocalTensorT tmp input[countOff]构造偏移后的 Tensor 视图再复用DumpTensorLocal2GMImpl/DumpTensorGM2GMImpl完成打印因此打印格式与 DumpTensor 完全一致。开关控制守卫条件为#if !(defined(ASCENDC_DUMP) ASCENDC_DUMP 0) || defined(ASCENDC_ACC_DUMP)即在 ASCENDC_DUMP 关闭时仍可通过定义ASCENDC_ACC_DUMP宏强制开启该接口的打印便于精度比对Acc CheckPoint场景使用。5. PrintTimeStamp时间戳打点5.1 功能说明与打印字段PrintTimeStamp 提供时间戳打点功能用于在核函数代码中标记关键执行点调用后会打印以下信息字段含义descId用户自定义标识符用于区分不同打点位置rsv保留值默认为 0无需关注timeStamp当前系统 cycle 数用于计算时间差pcPtrpc 指针数值若无特殊需求无需关注entry算子开始执行的 cycle 数若无特殊需求无需关注打印示例如下descId is 11, rsv is 0, timeStamp is 815603975350485, pcPtr is 19792358553124, entry is 815603975328116.通过两个打点位置的timeStamp差值即可得到代码段的 cycle 消耗时间换算规则可参考 GetSystemCycle(ISASI)Ascend 950PR950DT 按 1GHz 换算time (cycle数/1000)usAtlas A3/A2 系列按 50MHz 换算time (cycle数/50)us。5.2 函数原型与参数说明__aicore__ inline void PrintTimeStamp(uint32_t descId)参数名称输入/输出描述descId输入用户自定义标识符自定义数字用于区分不同打点位置。注意[00xffff] 是预留给 Ascend C 内部各模块使用的 id 值用户自定义的 descId 建议使用大于 0xffff 的数值函数无返回值。约束方面可参考 Utils 目录 SIMD 约束下的 asc_time_stamp 说明。5.3 编译开关开启方式与 DumpTensor 系列默认开启、可关闭不同PrintTimeStamp 默认关闭必须通过编译宏ASCENDC_TIME_STAMP_ON显式开启。开发者可以修改 CMakeLists.txt 文件或xxx.cmake文件在target_compile_definitions命令中增加-DASCENDC_TIME_STAMP_ONtarget_compile_definitions({kernel_target_name} PRIVATE -DASCENDC_TIME_STAMP_ON )5.4 调用示例AscendC::PrintTimeStamp(65577);打印结果如下65577 大于 0xffff符合自定义 descId 的取值建议// 一些框架内部的打点信息 descId is 65577, rsv is 0, timeStamp is 13806084506158, pcPtr is 20619064414544, entry is 13806084502126.5.5 底层实现原理PrintTimeStamp 的实现非常轻量。在 kernel_operator_dump_tensor_intf_impl.h 中__aicore__ inline void PrintTimeStamp(uint32_t descId) { #ifdef ASCENDC_TIME_STAMP_ON // 打点开关宏 DumpTimeStampImpl(descId); #endif }即未定义ASCENDC_TIME_STAMP_ON时函数体为空编译器可直接优化掉零性能开销。各架构的DumpTimeStampImpl实现如 dav_9201通过asc_capture_time_stamp_cycle()捕获当前 cycle 数再调用asc_time_stamp_impl(descId, time)将打点信息写入系统打印 FIFO并同样使用dcci刷 cache line 保证可见性。6. 生产环境关闭调试打印ASCENDC_DUMP 开关上板打印、异常检测等调试接口开启后会影响算子性能通常在调测阶段使用生产环境建议关闭。ASCENDC_DUMP宏定义是控制调试接口打印的总开关具体操作方式见 关闭ASCENDC_DUMP说明。CMake 编译选项控制方式核函数Kernel直调工程修改 CMakeLists.txt 中ascendc_compile_definitions命令增加ASCENDC_DUMP0// 关闭所有算子的打印功能 ascendc_compile_definitions({kernel_target_name} PRIVATE ASCENDC_DUMP0 )自定义算子工程修改算子工程 op_kernel 目录下 CMakeLists.txt 中的add_ops_compile_options或npu_op_kernel_options首行增加编译选项-DASCENDC_DUMP0// 使用add_ops_compile_options关闭所有算子的打印功能 ascendc_compile_definitions(ALL OPTIONS -DASCENDC_DUMP0) // 使用npu_op_kernel_options关闭所有算子的打印功能 ascendc_compile_definitions(ascendc_kernels ALL OPTIONS -DASENDC_DUMP0)宏定义控制方式在核函数代码文件的开头、包含头文件之前添加#define ASCENDC_DUMP 0#define ASCENDC_DUMP 0 // 在包含头文件之前添加 #include ... // 包含所需的头文件结合第 3.7/4.5 节的实现可知该宏在源码层面直接控制DumpTensor/DumpAccChkPoint的调用是否被编译为空操作因此生产构建时关闭它不会留下任何运行时开销。7. 仓库配套示例工程与测试用例除 API 文档外asc-devkit 仓库还提供了可直接编译运行的配套样例与自动化测试可作为上手参考simple_dump 示例README以静态 Tensor 编程模式的矩阵乘法C A * BM256, N256, K64为背景在 Kernel 中依次打印 GM、L1、L0C 三个层级的数据展示asc_dump_gm/asc_dump_l1buf/asc_dump_cbuf/asc_dump_ubuf系列接口的用法。该系列接口兼容AscendC::DumpTensor后续开发建议优先使用如需打印指定偏移位置数据asc_dump 系列暂不支持可继续使用DumpAccChkPoint。cube_buffer_dump 示例README面向 Ascend 950PR950DTdav-3510以 HiFloat8 量化 MatMulQuantMatmulHifp8为背景用 DumpTensor 打印 L1 Buffer、Bias Table Buffer 与 Fixpipe Buffer 中的数据并演示了 Fixpipe Buffer 位域掩码fixpipe_value l1_value 0x00007fe0ffffe0ff的校验方法与文档 3.5 节约束一一对应。测试用例如 ascendc_case_ascend950pr_9599_aiv_basic/test_dump_tensor.cpp 覆盖了 DumpTensor 在 950PR 系列上的参数化测试数据大小、类型大小、dumpSize 等维度组合tests/api/basic_api 下还有 ascend310b1、ascend310p、ascend910b1 等多个架构的test_dump_tensor.cpp可据此了解各产品上的行为差异。8. 小结与最佳实践综合文档与源码使用上板打印调试接口时建议遵循以下实践按需选择接口观察完整 Tensor 用DumpTensor可带 shapeInfo 排版只观察数据流中某段用DumpAccChkPoint指定 countOff测量代码段执行时间用PrintTimeStamp配合 descId 区分打点位置建议 descId 0xffff。先确认产品能力对照第 2 节的支持矩阵特别是 Atlas 推理系列与训练系列不支持相关接口的场景。遵守大小与对齐约束单次打印不超过 30KB可通过aclInit的simd_printf_fifo_size_per_core在 1KB~64MB 范围内调整偏移后的地址满足 通用地址对齐约束。调试期开启、生产期关闭DumpTensor 系列默认开启生产构建通过ASCENDC_DUMP0编译选项关闭PrintTimeStamp 默认关闭仅调试构建通过-DASCENDC_TIME_STAMP_ON开启。优先复用示例直接基于 simple_dump / cube_buffer_dump 工程修改可快速获得编译-运行-验证完整闭环避免从零搭建调试环境。赞分享人工智能深度学习算子库CANNAscend【免费下载链接】asc-devkit本项目是CANN 推出的昇腾AI处理器专用的算子程序开发语言原生支持C和C标准规范主要由类库和语言扩展层构成提供多层级API满足多维场景算子开发诉求。项目地址https://gitcode.com/cann/asc-devkit点击查看免费下载相关推荐昇腾算子调试打印实战Ascend C printf 与 simd_vf printf 接口使用指南基于 asc-devkit 示例昇腾算子调试打印实战Ascend C printf 与 simd_vf printf 接口使用指南基于 asc devkit 示例 本文以 example人工智能深度学习算子库CANNAscendPTO-ISA TPRINT 指令详解Ascend 平台上 Tile/GlobalTensor 的调试打印实战指南PTO ISA TPRINT 指令详解Ascend 平台上 Tile/GlobalTensor 的调试打印实战指南 导读 TPRINT 是 CANN PTO算子库人工智能CANNAscend C printf 接口实战在 SIMD 静态 Tensor 矩阵乘样例中打印核函数调试信息Ascend C printf 接口实战在 SIMD 静态 Tensor 矩阵乘样例中打印核函数调试信息 导读 本文以 asc devkit 仓库中的 sim人工智能深度学习算子库CANNAscend上一篇Label Studio 外部存储接入实战云存储与本地目录的同步、权限与安全配置指南下一篇ESLint require-await 规则详解检测未使用 await 的 async 函数并自动修复创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
