本项目提供CANN运行时组件和维测功能组件。
runtime（运行时）
🔥Latest News
- [2025/12] runtime项目首次上线。
概述
本仓提供CANN运行时组件和维测功能组件。
- Runtime组件：提供Ascend NPU运行时用户编程接口和运行时核心实现，包括设备管理、流管理、Event管理、内存管理、任务调度等功能。
- 维测功能组件：包括性能数据采集、模型和算子Dump、日志、错误日志记录等功能。
- 性能调优（msprof）模块：进行性能调优时，可以使用性能调优工具来采集和分析运行在昇腾AI处理器SoCNPU IP加速器上的AI任务各个运行阶段的关键性能指标，用于可根据输出的性能数据，快速定位软、硬件性能瓶颈，提升AI任务性能分析的效率。
- 精度调试（adump）模块：提供Ascend NPU运行时用户Dump单算子或模型（每一层算子）的输入/输出数据，用于与指定算子或模型进行对比，定位精度问题；提供Ascend NPU运行异常时Dump异常算子的输入/输出数据、Workspace信息，Tiling信息，用于分析AI Core Error问题。
- 日志（log）模块：日志提供记录进程执行过程信息的能力，在其他进程运行时，日志的接口提供进程打印和落盘日志的功能，方便系统故障的诊断分析，快速实现问题定位。该模块下的msnpureport为命令行工具，支持导出device侧日志和查询设置device侧状态等功能。
目录结构
关键目录结构如下：
├── cmake # 工程编译目录
├── docs # 文档介绍
├── example # 基于acl接口开发的样例代码
├── include # 3.1包整体对外发布的头文件
| ├── dfx # dfx相关头文件
| ├── driver # 驱动相关头文件
| ├── external # 本仓对外提供的头文件
| ......
├── pkg_inc # 仓间管控相关头文件
├── scripts # 辅助构建相关文件
├── src # 所有3.1包内各模块的源代码
| ├── acl # acl对外api存放目录
| ├── dfx # dfx模块目录
| | ├── adump # adump模块目录
| | ├── log # log模块目录
| | ├── msprof # msprof模块目录
| | ├── trace # trace模块目录
| | ......
| ├── mmpa # mmpa模块目录
| ├── runtime # runtime模块目录
| ......
├── stub # 打桩相关目录
├── tests # UT用例
├── third_party # 依赖包相关文件
......
├── CMakeLists.txt # 构建编译配置文件
├── build.sh # 项目工程编译脚本
源码编译&部署
Runtime仓整包源码编译
前提条件
使用本项目前，请确保如下基础依赖、NPU驱动和固件已安装。
-
安装依赖
本项目源码编译用到的依赖如下，请注意版本要求。
- python >= 3.7.0
- gcc >= 7.3.0, <= 13
- cmake >= 3.16.0
- ccache
- autoconf
- gperf
- libtool
- asan （仅执行UT时依赖，请确保已安装与gcc版本对应的asan版本，例如gcc 9.5.0需要安装libasan6版本）
- googletest（仅执行UT时依赖，建议版本 release-1.14.0）
上述依赖包（asan除外）可通过项目根目录下install_deps.sh安装，命令如下，若遇到不支持系统，请参考该文件自行适配：
bash install_deps.sh -
安装驱动与固件（运行态依赖）
运行Runtime时必须安装驱动与固件，安装指导详见《CANN 软件安装指南》。
环境准备
-
安装CANN toolkit包
单击下载链接，根据实际环境架构，获取对应的
Ascend-cann-toolkit_${cann_version}_linux-${arch}.run包。# 确保安装包具有可执行权限 chmod +x Ascend-cann-toolkit_${cann_version}_linux-${arch}.run # 安装命令 ./Ascend-cann-toolkit_${cann_version}_linux-${arch}.run --full --force --quiet --install-path=${install_path}- ${cann_version}：表示CANN包版本号。
- ${arch}：表示CPU架构，如aarch64、x86_64。
- ${install_path}：表示指定安装路径，可选，root用户默认安装在
/usr/local/Ascend目录，普通用户默认安装在当前目录。
-
配置环境变量
根据实际场景，选择合适的命令。
# 默认路径安装，以root用户为例（非root用户，将/usr/local替换为${HOME}） source /usr/local/Ascend/cann/set_env.sh # 指定路径安装 # source ${install_path}/cann/set_env.sh -
下载源码
# 下载项目源码，以master分支为例 git clone https://gitcode.com/cann/runtime.git
编译安装
Runtime提供一键式编译能力，可通过如下命令进行编译：
export CMAKE_TLS_VERIFY=0
bash build.sh
更多编译参数可以通过bash build.sh -h查看。
编译完成之后会在build_out目录下生产cann-npu-runtime_<version>_linux-<arch>.run软件包。
<version>表示版本号。
<arch>表示操作系统架构，取值包括x86_64与aarch64。
可执行如下命令安装编译生成的Runtime软件包：
./cann-npu-runtime_<version>_linux-<arch>.run --full --install-path=${install_path}
- ${version}：表示run包版本号。
- ${arch}：表示CPU架构，如aarch64、x86_64。
- ${install_path}：表示指定安装路径，可选，默认安装在
/usr/local/Ascend目录。
安装完成之后，用户编译生成的Runtime软件包会替换已安装CANN开发套件包中的Runtime相关软件。
关于签名的补充说明
- 本仓编译产生
cann-npu-runtime_<version>_linux-<arch>.run软件包中含有cann-tsch-compat.tar.gz（Runtime兼容升级包)。 cann-tsch-compat.tar.gz会在业务启动时加载至Device，加载过程中默认会由驱动进行安全验签，确保包可信。- 开发者下载本仓源码自行编译产生
cann-tsch-compat.tar.gz采用社区证书签名头，为此采用关闭驱动安全验签的机制。 - 关闭验签方式：
配套使用HDK 25.5.T2.B001或以上版本，并通过该HDK配套的npu-smi工具关闭验签。详见设置自定义验签能力使能状态, 设置验签模式命令文档，以root用户在物理机上执行。
以device 0为例 (其中 -i 后面的参数是device id）：npu-smi set -t custom-op-secverify-enable -i 0 -d 1 # 使能自定义验签 npu-smi set -t custom-op-secverify-mode -i 0 -d 0 # 设置成"关闭验签"模式
本地验证
编译完成后，用户可以进行开发测试（DT：Development Testing），验证项目功能是否正常。
说明：执行UT用例依赖googletest单元测试框架，详细介绍参见googletest官网，生成代码覆盖率报告需要独立安装lcov软件（如果由于lcov工具版本的原因出现报错，请根据提示修改脚本相关内容，选择合适的参数进行适配）。
编译执行UT测试用例：
bash tests/build_ut.sh --ut=acl --target=ascendcl_utest -c
--ut可以指定需要执行的tests/ut目录下的用例文件，例如acl、runtime等;--target可以指定需要执行的用例文件编译出来的目标二进制文件（可能有多个），例如acl用例可以使用tests/ut/acl/CMakeLists.txt文件中定义的ascendcl_utest；runtime用例可以使用tests/ut/runtime/runtime/CMakeLists.txt文件中定义的runtime_utest_task_910B，执行runtime全量用例则需要指定target为runtime_ut;-c可以获取覆盖率（如无需获取覆盖率，可省略此参数）。
UT测试用例编译输出目录为build，如果想清除历史编译记录，可以执行如下操作：
rm -rf build_ut/ output/ build/
注：tests/build_ut.sh脚本支持的详细命令参数可以通过bash tests/build_ut.sh -h查看。
接下来可参考样例运行尝试运行样例。