NPU上板调试功能

功能介绍

  • 算子开发结束后，一般需要在NPU板端上板验证实际算子精度是否正常。
  • NPU上板调试时支持printf/DumpTensor/assert/上板时间戳打印等方法，获取调试各阶段信息，方便用户高效定位问题。

NPU上板调试主要基于输入的kernel.o文件生成编译所需的文件，并自动执行算子编译和运行，该阶段支持的调测项如表1所示。

表1 NPU调测功能列表

功能分类

功能名称

功能说明

精度调试

自动精度比对

若用户配置了标杆数据（golden数据），工具会自动将实际调测运行结果与标杆数据进行精度比对。

printf/PRINTF功能

支持屏显打印Scalar数据，如常量、字符串等信息。

DumpTensor功能

支持dump Tensor数据。

DumpAccChkPoint功能

支持dump偏移位置的Tensor数据。

assert功能

支持屏显打印断言，当核函数代码中某个条件为假，则中断运行流程并打印相关信息。

一键PIPE_ALL调试

通过--pipe-all或CompileNpuOptions.pipe_all开启，检测算子NPU上板过程中是否有同步问题。

memory_check功能

通过--memory-check或CompileNpuOptions.memory_check、RunNpuOptions.memory_check开启，提供NPU内存校验和异常检测功能。主要检测算子运行过程中对外部存储（Global Memory）和内部存储（Local Memory）越界、多核踩踏等问题。

性能调优

Profiling数据采集功能

通过--profiling或RunProfilingOptions.profiling开启，可获取算子运行阶段关键性能指标，以便后续分析和优化。

上板时间戳打点功能

通过--dump-mode或CompileNpuOptions.dump_mode、NpuCompileInfo.dump_mode开启上板时间戳打点，获取算子各阶段耗时信息。

说明：

该功能在如下产品支持：

Atlas A2 训练系列产品/Atlas 800I A2 推理产品

使用方法（命令行）

通过命令行进行NPU调测的关键步骤如下，详细样例参考核函数NPU上板精度验证。

  1. 完成环境搭建，并准备好输入/标杆数据文件。
  2. 执行如下命令进行核函数NPU上板调测，这里仅提供关键参数项示例，其他参数请参考NPU调测参数按需设置。

    ascendebug kernel --backend npu --json-file ${op_config_json_file} --repo-type ${repo_type} --chip-version ${chip_version} --core-type ${core_type} --install-path ${cann_install_path} --work-dir ${work_dir} --profiling ... {其他参数}

    NPU调测涉及的所有参数可通过ascendebug kernel -h或ascendebug kernel --help查看。

    Profiling数据采集功能只支持在NPU调测场景中开启，CPU调测场景不支持。使能“--profiling”后，可一键式采集、解析并导出性能数据，详情参见Profiling数据采集功能。

  3. 查看结果文件，详细说明参见产物说明。

使用方法（API）

通过API进行NPU调测的关键步骤如下，详细样例参考核函数NPU上板精度验证。

  1. 完成环境搭建，并准备好输入/标杆数据文件。

    核函数直调工程场景下，需提前配置好核函数源码信息OpKernelInfo。

  2. 构建算子信息。调用DebugOp类里input系列接口（如tensor_input、custom_input等），设置算子的输入、输出、属性值等信息。
  3. 创建调试对象并初始化工作空间。调用create_op_executor接口，创建调试对象op_executor，用户可传入${work_dir}参数手动设置工作空间。
  4. （可选）参考Tiling调测功能 > 使用方法（API）章节，调用Tiling调测接口生成Tiling Info文件。

    本步骤仅适用于没有Tiling Info文件的场景，需调用Tiling调测API生成Tiling Info。

  5. 调用NPU编译接口，进行算子源码编译，生成kernel.o文件。

    1. 通过CompileNpuOptions设置NPU编译相关的功能，如内存检测功能。
    2. 根据不同场景调用对应的NPU编译接口。

  6. 调用NPU运行接口，在板端运行核函数，完成输出数据精度比对。

    1. 通过RunNpuOptions设置NPU运行相关的功能（如device id等），并通过NpuCompileInfo设置NPU编译属性。
    2. 调用run_npu接口。

  7. 查看结果文件，详细说明参见产物说明。

产物说明

无论是命令行方式或API方式，NPU调测结果存放在${root}/${work_dir}/npu路径下，其中${root}表示当前操作路径，${work_dir}表示调测工作空间，默认为/debug_workspace/${op_type}目录，${op_type}为算子名。目录结构示例如下：

├ ${op_type}                                            // 算子名
├── npu
│   ├── build                                        // 存放NPU编译生成的中间文件
│       ├── gen_${op_type}.o                         // 此处以opc编译为例，若采用ccec编译，产物文件名为auto_gen_${op_type}_kernel.o
│       ├── launch_args.so
│       ├── kernel_meta_gen_${op_type}              // opc编译时的产物目录,生成的文件类型与op_debug_config取值相关
│           ├── kernel_meta                         // 注意，*.i是预编译文件，*.o是算子二进制文件，*.json文件是算子描述文件，*.cpp算子编译中间产物
│               ├── gen_xxxx.i                      
│               ├── gen_xxxx.o
│               ├── gen_xxxx.json
│               ├── gen_xxxx.cpp
│               ├── ......
│   ├── output                                        // 存放NPU编译运行的输出文件及精度比对结果
│       ├── y.bin                                    // 运行输出原始数据
│       ├── y.txt                                    // 精度比对结果文件
│       ├── PROF_00000x_xxxx_xxx                    // 存放Profiling结果文件
│           ├── mindstudio_profiler_output
│               ├── ......
│   ├── src                                           // 存放NPU编译生成的临时代码文件
│       ├── _gen_args_${op_type}.cpp
│       ├── stub_fun_with_pipe_all.h                // PIPE_ALL功能结果文件      
│   ├── dump                                         // dump文件落盘目录
│       ├── PARSER_${timestamp}
│           ├── dump_data    
│               ├──0                                  // core number
│                   ├──time_stamp_core_0.csv         // 时间戳打点落盘文件
│                   ├──index_1                       // index是dump接口的desc唯一标识值
│                       ├──core_0_index_1_loop_0.bin
│                       ├──core_0_index_1_loop_0.txt
父主题： 调测功能介绍