Star448
554
代码
代码
Issues37
Pull Requests112
流水线
讨论
Wiki
分析
Star448
554
cann-robotcann-robotreadme add ref material
eb8928b8创建于 2月27日历史提交

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侧状态等功能。

版本配套

本项目源码会跟随CANN软件版本发布，关于CANN软件版本与本项目标签的对应关系请参阅release仓库中的相应版本说明。 请注意，为确保您的源码定制开发顺利进行，请选择配套的CANN版本与Gitcode标签源码，使用master分支可能存在版本不匹配的风险。

目录结构

关键目录结构如下：

├── 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用例
......
├── CMakeLists.txt                                 # 构建编译配置文件
├── build.sh                                       # 项目工程编译脚本

源码编译&部署

Runtime仓整包源码编译

前提条件

使用本项目前，请确保如下基础依赖、NPU驱动和固件已安装。

  1. 安装依赖

    本项目源码编译用到的依赖如下，请注意版本要求。

    • python >= 3.7.0
    • pip3
    • gcc >= 7.3.0, <= 13
    • cmake >= 3.16.0
    • ccache
    • autoconf
    • gperf
    • libtool
    • asan （仅执行UT时依赖。asan通常不需要单独安装，已集成在gcc中，如需要单独安装asan，请确保与gcc版本兼容，例如gcc 9.5.0匹配libasan6版本。）

    上述依赖包（asan除外）可通过项目根目录下install_deps.sh安装，命令如下。

    bash install_deps.sh

  2. 安装驱动与固件（运行态依赖）

    若仅编译runtime包，可跳过本操作步骤。运行Runtime时必须安装驱动与固件。

    单击下载链接，根据实际产品型号和环境架构，获取对应的Ascend-hdk-<chip_type>-npu-driver_<version>_linux-<arch>.run、Ascend-hdk-<chip_type>-npu-firmware_<version>.run包。 安装指导详见《CANN 软件安装指南》。

    通过如下方式验证驱动安装是否正常

    # 运行npu-smi, 若能正常显示设备信息，则驱动正常。
npu-smi info

环境准备

  1. 安装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目录，普通用户默认安装在当前目录。

  2. 配置环境变量

    根据实际场景，选择合适的命令。

    # 默认路径安装，以root用户为例（非root用户，将/usr/local替换为${HOME}）  
source /usr/local/Ascend/cann/set_env.sh
# 指定路径安装
# source ${install_path}/cann/set_env.sh

  3. 下载源码

    # 下载项目源码，以master分支为例
git clone https://gitcode.com/cann/runtime.git

注意

gitcode平台在使用HTTPS协议的时候要配置并使用个人访问令牌代替登录密码进行克隆，推送等操作。

若您的编译环境无法访问网络，由于无法通过git指令下载代码，须在联网环境中下载源码后，手动上传至目标环境。

  • 在联网环境中，进入本项目主页, 通过下载ZIP或clone按钮，根据指导，完成源码下载。
  • 连接至离线环境中，上传源码至您指定的目录下。若下载的为源码压缩包，还需进行解压。

开源第三方软件依赖

Runtime在编译时，依赖的第三方开源软件列表如下：

开源软件 版本 下载地址
abseil-cpp 20230802.1 abseil-cpp-20230802.1.tar.gz
acl-compat (x86_64) 8.5.0 acl-compat_8.5.0_linux-x86_64.tar.gz
acl-compat (aarch64) 8.5.0 acl-compat_8.5.0_linux-aarch64.tar.gz
boost 1.87.0 boost_1_87_0.tar.gz
eigen 5.0.0 eigen-5.0.0.tar.gz
googletest 1.14.0 googletest-1.14.0.tar.gz
json 3.11.3 include.zip
libboundscheck 1.1.16 libboundscheck-v1.1.16.tar.gz
libseccomp 2.5.4 libseccomp-2.5.4.tar.gz
mockcpp 2.7-h2 mockcpp-2.7.tar.gz
mockcpp_patch 2.7-h2 mockcpp-2.7_py3.patch
openssl 3.0.9 openssl-openssl-3.0.9.tar.gz
protobuf 25.1 protobuf-25.1.tar.gz
makeself 2.5.0 makeself-release-2.5.0-patch1.tar.gz

注意

如果您从其他地址下载，请确保版本号一致。

编译安装

若您的编译环境可以访问网络，编译过程中将自动下载上述开源第三方软件，可以使用如下命令进行编译：

export CMAKE_TLS_VERIFY=0
bash build.sh

若您的编译环境无法访问网络，可以直接调用脚本获取开源组件压缩包，脚本将自动下载至当前新建的 third_party 目录中：

python download_3rd_party.py

下载完成后，可以使用如下命令进行编译：

bash build.sh --cann_3rd_lib_path=third_party

更多编译参数可以通过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 --cann_3rd_lib_path={your_3rd_party_path}
  • --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可以获取覆盖率（如无需获取覆盖率，可省略此参数）。
  • --cann_3rd_lib_path指定第三方依赖的路径，若在联网环境中，可省略此参数。

UT测试用例编译输出目录为build，如果想清除历史编译记录，可以执行如下操作：

rm -rf build_ut/ output/ build/

注：tests/build_ut.sh脚本支持的详细命令参数可以通过bash tests/build_ut.sh -h查看。

接下来可参考样例运行尝试运行样例。

学习教程

Runtime提供了开发指南、API参考，详细可参见 Runtime 参考资料。

相关信息