产品支持情况

产品	是否支持
Atlas A3 训练系列产品/Atlas A3 推理系列产品	√
Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件	√
Atlas 200I/500 A2 推理产品	x
Atlas 推理系列产品 AI Core	√
Atlas 推理系列产品 Vector Core	x
Atlas 训练系列产品	x
Atlas 200/300/500 推理产品	x

功能说明

基于算子工程开发的算子，可以使用该接口Dump指定Tensor的内容。同时支持打印自定义的附加信息（仅支持uint32_t数据类型的信息），比如打印当前行号等。

在算子kernel侧实现代码中需要打印Tensor数据的地方调用DumpTensor接口打印相关内容。样例如下：

       
            AscendC::DumpTensor(srcLocal,5, dataLen);

DumpTensor接口打印功能会对算子实际运行的性能带来一定影响，通常在调测阶段使用。开发者可以按需通过如下方式关闭打印功能。

自定义算子工程

修改算子工程op_kernel目录下的CMakeLists.txt文件，首行增加编译选项-DASCENDC_DUMP=0，关闭ASCENDC_DUMP开关，示例如下：

             
                  // 关闭所有算子的printf打印功能
add_ops_compile_options(ALL OPTIONS -DASCENDC_DUMP=0)

Kernel直调工程

修改cmake目录下的npu_lib.cmake文件，在ascendc_compile_definitions命令中增加-DASCENDC_DUMP=0宏定义来关闭ASCENDC_DUMP开关。示例如下：

             
                  // 关闭所有算子的printf打印功能
ascendc_compile_definitions(ascendc_kernels_${RUN_MODE} PRIVATE
    -DASCENDC_DUMP=0
)

Dump时，每个block核的dump信息前会增加对应信息头DumpHead（32字节大小），用于记录核号和资源使用信息；每次Dump的Tensor数据前也会添加信息头DumpTensorHead（32字节大小），用于记录Tensor的相关信息。如下图所示，展示了多核打印场景下的打印信息结构。

DumpHead的具体信息如下：

opType：当前运行的算子类型；
CoreType：当前运行的核的类型；
block dim：开发者设置的算子执行核数；
total_block_num：参与dump的核数；
block_remain_len：当前核剩余可用的dump的空间；
block_initial_space：当前核初始分配的dump空间；
rsv：保留字段；
magic：内存校验魔术字。

DumpHead打印时，除了上述打印还会自动打印当前所运行核的类型及对应的该类型下的核索引，如：AIV-0。

DumpTensorHead的具体信息如下：

desc：用户自定义附加信息；
addr：Tensor的地址；
data_type：Tensor的数据类型；
position：表示Tensor所在的物理存储位置，当前仅支持Unified Buffer/L1 Buffer/L0C Buffer/Global Memory。

DumpTensor打印结果的最前面会自动打印CANN_VERSION_STR值与CANN_TIMESTAMP值。其中，CANN_VERSION_STR与CANN_TIMESTAMP为宏定义，CANN_VERSION_STR代表CANN软件包的版本号信息，形式为字符串，CANN_TIMESTAMP为CANN软件包发布时的时间戳，形式为数值（uint64_t）。开发者也可在代码中直接使用这两个宏。

打印示例如下：

      
           opType=AddCustom, DumpHead: AIV-0, CoreType=AIV, block dim=8, total_block_num=8, block_remain_len=1046912, block_initial_space=1048576, rsv=0, magic=5aa5bccd
CANN Version: XX.XX, TimeStamp: XXXXXXXXXXXXXXXXX
DumpTensor: desc=5, addr=0, data_type=float16, position=UB
[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: desc=5, addr=100, data_type=float16, position=UB
[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]
...
DumpTensor: desc=5, addr=0, data_type=float16, position=UB
[35.000000, 41.000000, 41.000000, 22.000000, 84.000000, 49.000000, 60.000000, 0.000000, 90.000000, 14.000000, 67.000000, 80.000000, 16.000000, 46.000000, 16.000000, 83.000000, 6.000000, 70.000000, 97.000000, 28.000000, 97.000000, 62.000000, 80.000000, 22.000000, 53.000000, 37.000000, 23.000000, 58.000000, 65.000000, 28.000000, 4.000000,
29.000000]

函数原型

无Tensor shape的打印

        
             template <typename T>
__aicore__ inline void DumpTensor(const LocalTensor<T> &tensor, uint32_t desc, uint32_t dumpSize)
template <typename T>
__aicore__ inline void DumpTensor(const GlobalTensor<T>& tensor, uint32_t desc, uint32_t dumpSize)

带Tensor shape的打印

        
             template <typename T>
__aicore__ inline void DumpTensor(const LocalTensor<T>& tensor, uint32_t desc, uint32_t dumpSize, const ShapeInfo& shapeInfo)
template <typename T>
__aicore__ inline void DumpTensor(const GlobalTensor<T>& tensor, uint32_t desc, uint32_t dumpSize, const ShapeInfo& shapeInfo)

参数说明

表1 模板参数说明
参数名	描述
T	需要dump的Tensor的数据类型。支持的数据类型为uint8_t/int8_t/int16_t/uint16_t/int32_t/uint32_t/int64_t/uint64_t/float/half/bfloat16_t。

表2 参数说明
参数名	输入/输出	描述
tensor	输入	需要dump的Tensor。待dump的tensor位于Unified Buffer/L1 Buffer/L0C Buffer时使用LocalTensor类型的tensor参数输入。待dump的tensor位于Global Memory时使用GlobalTensor类型的tensor参数输入。
desc	输入	用户自定义附加信息（行号或其他自定义数字）。在使用DumpTensor功能时，用户可通过desc参数附加自定义信息，以便在不同调用场景下区分Dump内容的来源。此功能有助于精准定位具体DumpTensor的输出，提升调试与分析效率。
dumpSize	输入	需要dump的元素个数。dump的元素总长度需要32字节对齐。
shapeInfo	输入	传入Tensor的shape信息，可按照shape信息进行打印。

返回值

无

约束说明

该功能仅用于NPU上板调试，且仅在如下场景支持：
- 通过Kernel直调方式调用算子。
- 通过单算子API调用方式调用算子。
- 间接调用单算子API(aclnnxxx)接口：Pytorch框架单算子直调的场景。
当前仅支持打印存储位置为Unified Buffer/L1 Buffer/L0C Buffer/Global Memory的Tensor信息。
操作数地址偏移对齐要求请参见通用约束。
该接口使用Dump功能，所有使用Dump功能的接口在每个核上Dump的数据总量不可超过1M。请开发者自行控制待打印的内容数据量，超出则不会打印。

调用示例

无Tensor shape的打印

        
             AscendC::DumpTensor(srcLocal,5, dataLen);

带Tensor shape的打印

        
             uint32_t array[] = {static_cast<uint32_t>(8),static_cast<uint32_t>(8)};
AscendC::ShapeInfo shapeInfo(2, array);       // dim为2， shape为(8,8)
AscendC::DumpTensor(x, 2, 64, shapeInfo);     // dump x的64个元素，且解析按照shapeInfo的(8,8)排列

打印结果如下：

        
             [[150.000000,83.000000,109.000000,166.000000,129.000000,50.000000,150.000000,74.000000],
[135.000000,79.000000,98.000000,134.000000,146.000000,166.000000,112.000000,70.000000],
[122.000000,51.000000,116.000000,68.000000,172.000000,72.000000,102.000000,69.000000],
[136.000000,83.000000,88.000000,88.000000,112.000000,148.000000,79.000000,136.000000],
[133.000000,104.000000,83.000000,71.000000,83.000000,99.000000,103.000000,151.000000],
[98.000000,118.000000,128.000000,83.000000,25.000000,105.000000,179.000000,34.000000],
[104.000000,169.000000,115.000000,113.000000,134.000000,121.000000,88.000000,96.000000],
[29.000000,139.000000,70.000000,40.000000,158.000000,138.000000,72.000000,171.000000]]