NPU上板调试功能
功能介绍
- 算子开发结束后，一般需要在NPU板端验证实际算子精度是否正常。
- NPU上板调试时支持printf/DumpTensor/assert/上板时间戳打印等方法，获取调试各阶段信息，方便用户高效定位问题。
NPU上板调试主要基于输入的kernel.o文件生成编译所需的文件，并自动执行算子编译和运行，该阶段支持的调测项如表1所示。
功能分类 |
功能名称 |
功能说明 |
|---|---|---|
精度调试 |
自动精度比对 |
若用户配置了标杆数据（golden数据），工具会自动将实际调测运行结果与标杆数据进行精度比对。 |
支持屏显打印Scalar数据，如常量、字符串等信息。 |
||
支持dump Tensor数据。 |
||
支持dump偏移位置的Tensor数据。 |
||
支持屏显打印断言，当核函数代码中某个条件为假，则中断运行流程并打印相关信息。 |
||
通过--pipe-all或CompileNpuOptions.pipe_all开启，检测算子NPU上板过程中是否有同步问题。 |
||
通过--memory-check或CompileNpuOptions.memory_check、RunNpuOptions.memory_check开启，提供NPU内存校验和异常检测功能。主要检测算子运行过程中对外部存储（Global Memory）和内部存储（Local Memory）越界、多核踩踏等问题。 |
||
性能调优 |
通过--profiling或RunProfilingOptions.profiling开启，可获取算子运行阶段关键性能指标，以便后续分析和优化。 |
|
通过--dump-mode或CompileNpuOptions.dump_mode、NpuCompileInfo.dump_mode开启上板时间戳打点，获取算子各阶段耗时信息。
说明：
该功能仅在如下产品支持： Atlas A2训练系列产品/Atlas 800I A2推理产品 |
使用方法（命令行）
通过命令行进行NPU调测的关键步骤如下，详细样例参考核函数NPU上板精度验证。
- 完成环境搭建，并准备好输入/标杆数据文件。
- 执行如下命令进行核函数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查看。
- 查看结果文件，详细说明参见产物说明。
使用方法（API）
通过API进行NPU调测的关键步骤如下，详细样例参考核函数NPU上板精度验证。
- 完成环境搭建，并准备好输入/标杆数据文件。
- 构建算子信息。调用DebugOp类里input系列接口（如tensor_input、custom_input等），设置算子的输入、输出、属性值等信息。
- 创建调试对象并初始化工作空间。调用create_op_executor接口，创建调试对象op_executor，用户可传入${work_dir}参数手动设置工作空间。
- （可选）参考Tiling调测功能 > 使用方法（API）章节，调用Tiling调测接口生成Tiling Info文件。
本步骤仅适用于没有Tiling Info文件的场景，需调用Tiling调测API生成Tiling Info。
- 调用NPU编译接口，进行算子源码编译，生成kernel.o文件。
- 通过CompileNpuOptions设置NPU编译相关的功能，如内存检测功能。
- 根据不同场景调用对应的NPU编译接口。
- 标准自定义算子场景： 调用compile_custom_npu接口。
- 核函数直调场景：调用compile_call_kernel_npu接口。
- ops_adv算子场景：调用compile_ops_adv_npu接口。
- 调用NPU运行接口，在板端运行核函数，完成输出数据精度比对。
- 通过RunNpuOptions设置NPU运行相关的功能（如device id等），并通过NpuCompileInfo设置NPU编译属性。
- 调用run_npu接口。
- 查看结果文件，详细说明参见产物说明。
产物说明
无论是命令行方式或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
│ ├── 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
- 查看精度比对结果
- 在output目录下，查看是否生成输出文件（bin）和精度比对文件（txt）。
- 根据精度比对文件（txt），确认算子精度比对结果。
精度比对结果输出样例如下，主要展示两份数据的均值、部分误差对比以及成功/失败的最终比对结论。若结果是失败，会将最大误差的部分数据展示出来。
data_cmp mean is -1.41e-05 data_gd mean is -1.41e-05 split_count:2359296.0; max_diff_hd:0.1; --------------------------------------------------------------------------------------- Loop ExpectOut RealOut FpDiff RateDiff --------------------------------------------------------------------------------------- 00000001 0.0395813 0.0395813 0.0000000 0.0000000 00000002 0.0160980 0.0160980 0.0000000 0.0000000 00000003 -0.0443420 -0.0443420 0.0000000 0.0000000 00000004 -0.0847778 -0.0847778 0.0000000 0.0000000 00000005 -0.0066605 -0.0066605 0.0000000 0.0000000 00000006 0.0880737 0.0880737 0.0000000 0.0000000 00000007 0.0848389 0.0848389 0.0000000 0.0000000 00000008 0.1083374 0.1083374 0.0000000 0.0000000 00000009 0.0838623 0.0838623 0.0000000 0.0000000 00000010 0.0887451 0.0887451 0.0000000 0.0000000 00000011 0.0572205 0.0572205 0.0000000 0.0000000 00000012 0.0741577 0.0741577 0.0000000 0.0000000 00000013 -0.0762329 -0.0762329 0.0000000 0.0000000 00000014 -0.0957642 -0.0957642 0.0000000 0.0000000 00000015 0.0102234 0.0102234 0.0000000 0.0000000 ... ... ... ... ... --------------------------------------------------------------------------------------- DiffThd PctThd PctRlt Result --------------------------------------------------------------------------------------- 0.0050 99.50% 100.000000% Pass Success Success Success Success Success
表2 精度比对结果说明 信息项
说明
data_cmp mean
运行输出数据的均值信息。
data_gd mean
标杆数据的均值信息。
split_count
统计输出数据的个数。
max_diff_hd
输出数据和golden数据的最大误差值阈值。
详细对比数据展示（部分）
Loop（数据位置）、ExpectOut（期望输出值）、RealOut（实际输出值）、FpDiff （绝对误差值）、RateDiff（相对误差值）。
整体对比结果展示
DiffThd（相对误差值阈值）、PctThd （精度达标数据占比阈值）、PctRlt（实际精度达标数据占比）、Result（对比结果）。
Error Line展示项
若精度比对结果为Failed，会追加展示部分误差较大的数据的详细信息，信息格式与"详细对比数据展示（部分）"一致。
- （可选）查看dump结果
若开启DumpTensor功能或DumpAccChkPoint功能，结果文件存放在dump目录下，详细结果介绍参见产物说明。
- （可选）查看PIPE_ALL调试结果
通过--pipe-all或CompileNpuOptions.pipe_all开启功能后，屏显日志会出现“generate stub pipe all_intri header”，同时src目录下是否生成stub_fun_with_pipe_all.h文件。日志信息样例如下：
[INFO] ascendedebug [914261] 2024-08-07 17:06:45,077 [INFO]: generate stub pipe all_intri header: /home/debug_workspace/add_custom/npu/src/stub_fun_with_pipe_all.h
- （可选）查看memory_check检测结果
通过--memory-check或CompileNpuOptions.memory_check、RunNpuOptions.memory_check开启检测，支持如下模式：
- oom：针对无kernel.o的场景，默认会重新编译kernel，支持开发者边开发算子边检测异常。
- oob：直接对已开发好的算子进行异常检测。
内存检测项如表3所示，若检测出异常会屏显“ERROR”日志，用户根据屏显提示分析和定位即可。以oob检测为例，屏显日志如下：
[ERROR] ASCENDCKERNEL(2677326,npu_kernel_launch):2024-08-16-14:39:21.292.536 [binary_data.cpp:282][ASCENDCTOOL][Tid:2677326]"Check write oob failed, index = 0, data = 28" [ERROR] ASCENDCKERNEL(2677326,npu_kernel_launch):2024-08-16-14:39:21.292.543 [tensor_data.cpp:258][ASCENDCTOOL][Tid:2677326]"Check tensor(x1) write oob failed, backward data check failed." [ERROR] ASCENDCKERNEL(2677326,npu_kernel_launch):2024-08-16-14:39:21.292.549 [tensor_data.cpp:409][ASCENDCTOOL][Tid:2677326]"Check tensor write oob failed, idx = 0" [ERROR] ASCENDCKERNEL(2677326,npu_kernel_launch):2024-08-16-14:39:21.292.554 [kernel_arg.cpp:32][ASCENDCTOOL][Tid:2677326]"Check tensor write oob failed." [ERROR] ASCENDCKERNEL(2677326,npu_kernel_launch):2024-08-16-14:39:21.292.563 [kernel_launcher.cpp:90][ASCENDCTOOL][Tid:2677326]"Check kernel failed." [ERROR] ASCENDCKERNEL(2677326,npu_kernel_launch):2024-08-16-14:39:21.292.850 [main.cpp:52][ASCENDCTOOL][Tid:2677326]"Run kernel failed." [ERROR] ASCENDCKERNEL(2677326,npu_kernel_launch):2024-08-16-14:39:25.054.853 [main.cpp:94][ASCENDCTOOL][Tid:2677326]"Launch kernel failed." 2024-08-16-14:39:25.493 [CONSOLE]: ===================npu kernel run end, takes 5194940.0(us)==================== 2024-08-16-14:39:25.493 [ERROR]: memory check fail: write oob check fail, skip read oob check.
- （可选）查看Profiling结果
若开启Profiling数据采集功能，结果文件存放在output目录下，详细结果介绍参见产物说明。
- （可选）查看时间戳打点结果