CANN PTO-ISA 测试体系全指南从 CPU 模拟器到 NPU 板载的 ST 测试与多卡 Comm 测试实战【免费下载链接】pto-isaParallel Tile Operation (PTO) is a virtual instruction set architecture designed by Ascend CANN, focusing on tile-level operations. This repository offers high-performance, cross-platform tile operations across Ascend platforms.项目地址: https://gitcode.com/cann/pto-isa导读tests/是 PTO Tile Lib 的测试总入口覆盖CPU 模拟器CPU simulation与NPUsim 模拟模式与板载 npu 模式两条完整验证链路并配套 GEMM、Flash Attention 等可运行 demo。本文以 tests/README.md 为核心骨架结合仓库内tests/run_cpu.py、tests/script/run_st.py、tests/run_st.sh、tests/run_comm_test.sh等入口脚本的源码实现系统讲解如何搭建环境、运行单用例/全量用例、以及如何基于 MPI HCCL 跑通多设备通信原语tput / tget / tput_async 等的 Comm ST 测试。读完本文你将能独立完成 CPU 模拟器全量回归、NPU 单测定位、以及 2/4/8 卡通信用例的编排与排错。一、测试体系总览一条命令覆盖两种运行后端PTO Tile Lib 的测试用例采用同一套测试代码 双后端的组织方式CPU 后端以 gtest CMake 构建在纯 CPU 上模拟 Tile 指令行为跨平台macOS / Linux / Windows无需任何 NPU 硬件是新手入门与日常回归的首选NPU 后端按 SoC 拆分A2/A3、A5、Kirin9030、KirinX90、KirinDev0000 等通过sim使用 CANN 自带 simulator/camodel或npu真实板卡两种运行模式执行。tests/README.md给出的通用测试入口如下# 全量 CPU 模拟器回归清理后重建并打印详细日志 python3 tests/run_cpu.py --clean --verbose # 运行 GEMM demo python3 tests/run_cpu.py --demo gemm --verbose # 运行 Flash Attention demo python3 tests/run_cpu.py --demo flash_attn --verbose # 运行单个 NPU ST 用例-r 指定 sim/npu-v 指定 a3/a5-t 指定用例-g 指定 gtest 过滤 python3 tests/script/run_st.py -r [sim|npu] -v [a3|a5] -t [TEST_CASE] -g [GTEST_FILTER_CASE] # 一键脚本 ./tests/run_st.sh --a3 --sim --all ./tests/run_cpu_tests.sh其中run_st.sh的用法有严格约束详见 tests/run_st.sh必须同时给出平台标志--a3/--a5/--a3_a5/--kirin9030且对于--a3/--a5还必须给出模式标志--simple或--all运行模式--sim/--npu可选缺省为板载npu。注意参数前的--前缀是必填的用无参数或非法参数方式运行./tests/run_st.sh即可打印完整 usage。从 tests/run_st.sh 的usage()实现可以看到脚本支持--a3_a5同时跑 A2/A3 与 A5、--kirinX90、--kirinDev0000等更多平台以及--comm附带通信 ST与--auto_mode以 auto 模式运行 ST两个附加开关。二、目录结构解读脚本、用例与资源的分布tests/目录采用「脚本驱动 按后端/SoC 分仓」的布局tests/README.md的 Layout 小节定义如下script/推荐使用的入口脚本run_st.py构建并运行 NPU STbuild_st.py仅构建 NPU STall_cpu_tests.py批量构建并运行 CPU ST 套件cpu_bfloat16.pyCPU bfloat16 测试脚本README.md脚本使用说明cpu/CPU 侧 ST 测试gtest CMakest/CPU 计算 ST 工程与测试数据生成脚本comm/st/CPU 通信 STnpu/按 SoC 拆分的 NPU 侧 ST 测试a2a3/src/st/、a2a3/src/common/、a2a3/comm/st/A2/A3 计算 ST、共享测试资源、通信 STa5/src/st/、a5/src/common/、a5/comm/st/A5 对应目录kirin9030/src/st/、kirin9030/src/common/Kirin9030 对应目录costmodel/成本模型测试st/成本模型 ST算子成本测量st_fit/成本模型拟合测试common/共享测试资源run_cpu.pyCPU 模拟器全量运行入口run_cpu_tests.shCPU ST 一键脚本内部就是透传调用 all_cpu_tests.pyrun_st.shNPU ST 一键脚本run_comm_test.sh通信 ST 一键脚本run_costmodel.py、run_costmodel_tests.sh成本模型运行脚本与一键脚本validate_op_coverage.py算子覆盖度校验脚本validate_testcase_names.py用例命名校验脚本从源码层面补充两点结构事实NPU 用例按 testcase 目录组织。以 tests/npu/a2a3/comm/st/testcase 为例每个通信指令tput、tget、tput_async、tget_async、tnotify、twait、ttest、tbroadcast、tgather、tscatter、treduce等都是一个独立子目录并共享comm_mpi.h、hccl_context.h、common.hpp等公共头文件。覆盖度可机器校验。tests/validate_op_coverage.py 会把tests/npu/{a2a3,a5,kirin9030}/src/st/testcase下含main.cpp的用例目录与run_st.sh中实际引用的算子做比对缺失时以非零退出码报错——这保证了「脚本能跑的用例」与「代码里存在的用例」不脱节。三、CPU 模拟器测试从零开始的全量回归3.1 环境要求进入 CPU 模拟器链路前建议先核对 docs/getting-started.md 中列出的前置依赖Python 3.11CMake 3.16支持 C20 的编译器Linux 上 GCC 13 或 Clang 15GCC 14可开启 bfloat16 支持macOS 用 Xcode/AppleClangWindows 用 VS2022 Build ToolsMSVCPython 包numpy 1.22.0以及按需的ml_dtypes、en_dtypes仅部分特定用例需要。tests/run_cpu.py会在缺少cmake/ctest时自动通过 pip 安装除非传入--no-install也会自动检测编译器从源码看其优先级是先找clang 15再找g 13找不到则报错退出同时支持CXX/CC环境变量与--cxx/--cc显式指定见 tests/run_cpu.py 的编译器检测逻辑。3.2 运行方式与参数详解参数作用说明--clean删除构建目录后重建默认构建目录为tests/cpu/st/build--verbose打印 cmake/msbuild/gtest 全量输出默认静默只输出结构化日志-t, --testcase只运行单个用例如tadd缺省运行所有已构建二进制-g, --gtest_filtergtest 过滤如TADDTest.*可精确到单个 case--demo构建并运行 demo可选gemm/flash_attn/mla/alldemo 模式单独运行不跑 CPU ST--build-typeCMake 构建类型默认Release--enable-bf16开启 BF16 CPU-SIM 覆盖需要支持 C23std::bfloat16_t的编译器--trace-mode开启 PTO 指令追踪通过PTO_CPU_SIM_TRACE_MODE生效--no-build跳过 cmake 配置与构建只运行已有二进制--no-gen跳过gen_data.py测试数据生成--xml-dir输出 gtest XML 报告便于 CI 集成--generator指定 CMake 生成器Windows 必填如MinGW Makefiles、Ninja--cmake_prefix_path指定CMAKE_PREFIX_PATH例如 Windows 上的 gtest 路径典型命令# 单用例 gtest 过滤只跑 TADDTest 下的全部 case python3 tests/run_cpu.py --testcase tadd --gtest_filter TADDTest.* # 指定编译器 python3 tests/run_cpu.py --cxx/path/to/compiler # Windows 下使用 MinGW 外部 gtest python3 tests/run_cpu.py --clean --generator MinGW Makefiles --cmake_prefix_path D:\gtest\ # 输出 XML 测试报告 python3 tests/run_cpu.py --xml-dir reports3.3 底层执行链路源码视角tests/run_cpu.py的完整流程可以拆成五段对应源码中的函数参数解析与环境准备parse_arguments/setup_environment解析上表参数缺失工具自动安装编译器决策detect_compilers显式指定 → 环境变量 → 自动探测clang15 / g13并推导配套的 CC构建决策determine_need_build/perform_build通过读取CMakeCache.txt中的TEST_CASE变量与build/bin下已有二进制判断是否需要重新 cmake configure支持增量跳过配置时会把-DPTO_CPU_SIM_ENABLE_BF16、-DPTO_CPU_SIM_TRACE_MODE、-DTEST_CASE等传入 CMake数据生成run_selected_tests对每个用例执行其testcase/name/gen_data.py复制到构建目录后运行并临时注入PYTHONPATH与PTO_CPU_SIM_ENABLE_BF16环境变量生成 golden 数据执行与汇总run_gtest_binary/print_test_summary逐个运行build/bin/testcase二进制支持--gtest_filter与--gtest_outputxml:最后以表格形式汇总每个用例的 PASS/FAIL 与耗时。从执行细节看CPU 用例的测试数据位于构建目录下测试二进制从build/bin/启动以便用../suite/input1.bin形式的相对路径访问输入数据见 tests/run_cpu.py——这一点在自定义用例或排查「找不到输入文件」类问题时值得留意。3.4 CPU ST 批量脚本若希望批量跑 CPU 套件直接使用 all_cpu_tests.py或等价的一键脚本./tests/run_cpu_tests.sh其常用选项选项说明-v, --verbose打印构建/运行输出-c, --compilerC 编译器路径或名称--enable-bf16使用 C23 编译器开启 BF16 覆盖--trace-mode以指令追踪模式构建 CPU ST-g, --generator可选 CMake 生成器-j, --jobs并行构建任务数--timeout单测试超时秒--build-folder可选构建根目录其下创建cpu_st与cpu_st_commpython3 tests/script/all_cpu_tests.py --verbose python3 tests/script/all_cpu_tests.py --trace-mode --build-folder build/trace_cpu四、NPU ST 测试sim 与板载 npu 模式4.1 前置条件NPU 链路要求 Linux 环境与 Ascend CANN 工具链Linux推荐 Ubuntu 20.04Python 3.9GCC 7.3.0CMake 3.16GoogleTest单元测试依赖CANN toolkit 8.5.0板载运行还需要 NPU 驱动与固件安装后执行source /usr/local/Ascend/cann/bin/setenv.bash或自定义安装路径下的setenv.bash。完整安装含 driver、firmware、toolkit、一键脚本scripts/install_pto.sh步骤参见 docs/getting-started.md 的 Part 2。4.2 run_st.py 参数与典型用法run_st.py 是 NPU ST 的底层构建运行入口公共参数参数说明-r, --run-modesim或npu-v, --soc-versiona3/a5/a6/kirin9030/kirinX90/kirinDev0000-t, --testcase用例名如tmatmul通信用例用comm/tput形式-g, --gtest_filter可选 gtest 过滤单跑某个 case-d, --debug-enable开启 debug 构建检查仅run_st.py-a, --auto-mode-enable以 auto 模式运行-w, --without-build跳过编译需预先编译过-n, --nrankscomm 测试最大 MPI rank 数默认 8自动按 2/4/8 分轮执行# 在 A3 模拟器上单跑 TMATMULTest.case1 python3 tests/script/run_st.py -r sim -v a3 -t tmatmul -g TMATMULTest.case1 # 在 A5 板卡上单跑 TMATMULTest.case1 python3 tests/script/run_st.py -r npu -v a5 -t tmatmul -g TMATMULTest.case1注意a3后端覆盖 A2/A3 家族对应include/pto/npu/a2a3a5对应include/pto/npu/a5。4.3 底层执行链路源码视角从 run_st.py 的main()可以看到NPU ST 的执行分为四步目录定位根据-v与是否为comm/用例把工作目录切换到对应的 ST 工程目录如tests/npu/a2a3/src/st、tests/npu/a2a3/comm/st、tests/npu/a5/src/st、tests/npu/kirin9030/src/st等环境变量设置set_env_variablessim 模式下会把ASCEND_HOME_PATH/runtime/lib64/stub加入LD_LIBRARY_PATH并剔除路径中含/runtime/lib64的旧项避免与 stub 冲突随后sourceCANN 的setenv.bash/set_env.sh并把环境注入当前进程最后把 simulator 的camodel或lib目录追加到LD_LIBRARY_PATHsim模式的 SoC 名还会做映射如Ascend950PR_9599→Ascend910_9599以便在tools/simulator/soc下找到 camodel构建build_project清理build/目录后用cmake -DRUN_MODE... -DSOC_VERSION... -DTEST_CASE...debug 时追加-DDEBUG_MODEONauto 时追加-DAUTO_MODEON配置再make -j$(nproc)编译数据生成与运行run_gen_data/run_binary把testcase/name/gen_data.py复制到构建目录并执行生成 golden 数据运行阶段若run_mode sim会预先创建camodel_log、log/ub_log目录并设置CAMODEL_LOG_PATH然后直接执行./testcase可加--gtest_filter。4.4 run_st.sh 一键编排simple / all / 平台run_st.sh在run_st.py之上做了一层编排平台、模式、运行模式三组参数任意组合脚本内部根据组合展开成大量run_st.py调用。--simple跑精心挑选的单用例子集如 A3 下TADDTest.case_float_64x64_64x64、TMULTest.case_float_64x64_64x64_64x64、TMATMULTest.case1等用于快速冒烟--all跑全量 ST 套件A3 下覆盖 tadd、tand、tor、tsels、tmul、tdiv、tmatmul、tload、tstore、textract、tinsert、tgather、mscatter、mgather、tpushpop_* 等数十个指令族A5 下额外覆盖 tinterleave、tdeinterleave、thistogram、tmatmul_mx、tload_mx_* 等平台切换--a3、--a5、--a3_a5、--kirin9030、--kirinX90、--kirinDev0000运行模式--sim或--npu缺省 npu。# A5 板卡上跑推荐子集 ./tests/run_st.sh --a5 --npu --simple # A3 模拟器上跑全量先提高文件描述符上限模拟器场景常见建议 ulimit -n 65536 ./tests/run_st.sh --a3 --sim --all # 附带通信 ST ./tests/run_st.sh --a3 --sim --all --comm从脚本源码可以看到几个值得注意的实现细节参数校验是「硬校验」未选平台或 a3/a5 未选模式会直接报错退出exit 1避免误输入导致静默空跑支持ST_PART环境变量分片执行如ST_PART1只跑清单中的第 1 片便于把长列表分发到多台机器并行部分用例在 auto 模式下会被跳过例如tpushpop_*系列目前必须直接调用 CCE intrinsicsauto 模式无法编译且 auto-sync 与 CCE intrinsics 不兼容脚本中相应位置有IS_AUTO_MODEfalse守卫。五、通信测试Comm ST多设备 PTO 通信原语验证5.1 验证对象与架构通信测试用于验证多设备PTO 通信原语覆盖Put / Get / Broadcast / Gather / Scatter / Reduce / Notify / Wait / Test底层构建在MPI HCCL之上。对应用例目录见 tests/npu/a2a3/comm/st/testcasetput、tget、tnotify、twait、ttest、tbroadcast、tgather、tscatter、treduce、tput_async、tget_async、tput_async_notify。5.2 前置条件MPI 安装Comm 测试依赖 MPI 环境MPICH 或 OpenMPI运行时需要两个组件mpirun负责拉起多进程执行libmpi.so运行时通过dlopen加载。安装 MPICH推荐# Ubuntu / Debian sudo apt install mpich libmpich-dev # CentOS / RHEL / EulerOS sudo yum install mpich mpich-devel # 可能需要手动加载 module 或加入 PATH export PATH/usr/lib64/mpich/bin:$PATH无 root 权限源码编译 MPICHwget https://www.mpich.org/static/downloads/4.2.3/mpich-4.2.3.tar.gz tar xzf mpich-4.2.3.tar.gz cd mpich-4.2.3 ./configure --prefix$HOME/mpich --disable-fortran make -j$(nproc) make install export MPI_HOME$HOME/mpich export PATH$MPI_HOME/bin:$PATH环境变量变量说明MPI_HOMEMPI 安装根目录脚本会优先查找$MPI_HOME/bin/mpirunMPI_LIB_PATHlibmpi.so的直接路径覆盖默认查找如果mpirun已经在PATH中且libmpi.so位于标准库路径这两个变量都可以不设置。验证安装mpirun --version mpirun -n 2 echo MPI OK源码佐证run_st.py 的find_mpirun()依次尝试$MPI_HOME/bin/mpirun、/usr/local/mpich/bin/mpirun、/usr/local/bin/mpirun、/usr/bin/mpirun与PATH运行时若找不到会给出「Install MPICH/OpenMPI or set MPI_HOME env」的明确报错。对于 OpenMPI脚本还会自动追加--allow-run-as-root便于容器/root 环境。运行二进制前会把mpirun所在目录的../lib/libmpi.so探测出来写入MPI_LIB_PATH。5.3 同步 vs 异步指令测试Comm 测试分为同步指令如tput、tget与异步指令如tput_async、tget_async类型用例示例所需 CANN 版本同步tput、tget、treduce、tbroadcast等CANN 8.x 及以上异步tput_async、tget_asyncCANN 9.0 及以上异步指令依赖 CANN 9.0 引入的 SDMA opapi 接口如aclnnShmemSdmaStarsQuery在更低版本 CANN 上会因缺少符号而失败。因此 run_comm_test.sh默认排除异步用例需要显式加-a开启。5.4 快速开始# 用 8 张 NPU 跑全部测试默认 A2/A3不含异步 ./run_comm_test.sh # 包含异步指令测试需要 CANN 9.0 ./run_comm_test.sh -a # 只跑异步 tput 用例 ./run_comm_test.sh -t tput_async # A5 SoC2 张 NPU ./run_comm_test.sh -v a5 -n 2 # 只跑 tput 用例 ./run_comm_test.sh -t tput # 开启 debug 日志 ./run_comm_test.sh -d -t tput也可以直接用run_st.py按 rank 数自动拆分执行# 自动把 tput_async 按 2/4/8 rank 拆分 python3 tests/script/run_st.py -r npu -v a3 -t comm/tput_async # 限制最多 2 rank python3 tests/script/run_st.py -r npu -v a3 -t comm/tput_async -n 25.5 run_comm_test.sh 选项标志说明默认-n可用 NPU 数量2、4 或 88-vSoC 版本a3Ascend910B或a5Ascend950a3-t只运行指定用例可重复如tput、treduceall-a包含名称含_async的异步用例需要 CANN 9.0off-d开启 debug 模式每个同步点打印详细日志off5.6 工作原理按 rank 数自动分轮执行run_comm_test.sh会针对每个用例在可用的 rank 数2 / 4 / 8不超过-n上分别执行一轮并用 gtest filter 只选中与当前 rank 数匹配的测试。例如-n 4时先以 2 rank 运行默认测试再以 4 rank 运行带4Ranks后缀的测试跳过 8 rank 的测试。实现层面有两处关键机制见 tests/run_comm_test.sh命名约定驱动的 filter所有多 rank 用例遵循*_NRanks/*_Nranks命名约定因此用通配即可精确筛选——2 rank*-*4Ranks*:*4ranks*:*8Ranks*:*8ranks*4 rank*4Ranks*:*4ranks*8 rank*8Ranks*:*8ranks*构建去重同一用例只在第一轮2 rank构建后续轮次复用并追加-w--without-build跳过编译脚本在每轮通过GTEST_FILTER环境变量把 filter 传给run_st.py。run_st.py侧也内置了同样的 rank 拆分逻辑RANK_LEVELS [2, 4, 8]并在运行前通过探测/dev/davinci0..N统计本机可用 NPU 数若当前 rank 数超过可用 NPU 会打印[SKIP]跳过对于以_ccu结尾的用例CCU 测试还会退化为进程隔离模式解析main.cc中的TEST_F宏为每个 gtest case 单独起一次mpirun。六、质量保障与延伸阅读tests/还提供了两个便于合入检查的辅助脚本validate_op_coverage.py对比run_st.sh引用的算子与testcase目录实际存在的用例保证覆盖无遗漏退出码 0/1 表示通过/缺失validate_testcase_names.py校验用例命名规范。需要说明的一点本文给出的版本、命令与运行方式均以当前仓库实际内容为准具体参数以python3 script -h输出为最新依据。建议按「CPU 先行、NPU 跟进」的路径上手——先通过 docs/getting-started.md 完成环境搭建再回到tests/跑通单用例最后扩展到全量回归与多卡 Comm 测试。【免费下载链接】pto-isaParallel Tile Operation (PTO) is a virtual instruction set architecture designed by Ascend CANN, focusing on tile-level operations. This repository offers high-performance, cross-platform tile operations across Ascend platforms.项目地址: https://gitcode.com/cann/pto-isa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考