CANN Runtime Device 身份映射实战基于 Device Identity Mapping 样例理解用户、逻辑与物理设备 ID 及 UUID/PCI 标识校验【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime本篇文章围绕 CANN Runtime 仓库中的3_device_identity_mapping样例展开面向容器、虚拟化与调度系统识别 Device 的真实场景完整讲解如何枚举用户可见 Device、查询其 UUID、在用户/逻辑/物理三层设备 ID 之间做双向映射与 round-trip 一致性校验以及如何通过 PCI Bus ID 反查设备 ID。读完本文你将掌握这组 AscendCL 设备身份接口的调用姿势、版本与形态限制并能在自己的调度或运维工具中复现这套校验逻辑。样例定位解决什么问题在多卡服务器上一套 NPU 硬件对上层应用会暴露多套编号体系用户可见的 Device ID、Runtime 内部使用的逻辑设备 ID以及驱动侧的物理设备 ID。在容器、虚拟化或 Kubernetes 等调度系统介入后用户在容器内看到的设备编号与宿主机上的实际设备编号通常并不一致此时若只凭第几号卡来管理资源很容易产生错认或越界。device_identity_mapping 样例 正是为这种场景设计的自检程序它枚举当前进程可见的全部 Device对每张卡依次查询 UUID、完成三层设备 ID 的双向映射校验并在 PCIe 互连形态下额外通过 PCI Bus ID 反查设备 ID 做 round-trip 校验最后输出汇总统计。任何一步不一致都会导致样例以失败状态退出因此它既可以作为调度系统的身份探测工具也可以作为容器/虚拟化环境设备透传正确性的回归验证用例。该样例位于 example/1_basic_features/device/3_device_identity_mapping/目录中包含四个文件main.cpp核心逻辑实现README.md/README_en.md中英文使用说明CMakeLists.txt构建配置链接libacl_rt.sorun.sh一键配置、编译并运行的一体化脚本。三种设备 ID 的概念与映射关系在深入代码之前先厘清样例中反复出现的三组 ID概念含义样例中的获取接口用户设备 IDuser device ID应用视角的设备编号受容器/虚拟化环境裁剪枚举范围为0 ~ deviceCount-1aclrtGetDeviceCount枚举逻辑设备 IDlogical device IDRuntime 内部使用的设备编号aclrtGetLogicDevIdByUserDevId物理设备 IDphysical device ID驱动侧物理设备编号aclrtGetPhyDevIdByUserDevId样例对每张卡执行的正向-反向校验逻辑见 main.cpp 的InspectDevice函数// Resolve logical and physical IDs, then map both back to the original user Device. CHECK_ERROR(aclrtGetLogicDevIdByUserDevId(userDeviceId, logicDeviceId)); CHECK_ERROR(aclrtGetUserDevIdByLogicDevId(logicDeviceId, userFromLogic)); CHECK_ERROR(aclrtGetPhyDevIdByUserDevId(userDeviceId, physicalDeviceId)); CHECK_ERROR(aclrtGetUserDevIdByPhyDevId(physicalDeviceId, userFromPhysical)); if (userFromLogic ! userDeviceId || userFromPhysical ! userDeviceId) { ERROR_LOG(Device ID round-trip is inconsistent: user%d, logic-user%d, physical-user%d, userDeviceId, userFromLogic, userFromPhysical); return -1; }这里用CHECK_ERROR宏串起四次调用先正向取逻辑/物理 ID再反向映射回用户 ID最终要求userFromLogic与userFromPhysical均等于原始的用户设备 ID任何不一致即判失败。CHECK_ERROR等日志宏定义在仓库公共头文件 example/utils.h 中失败时打印接口名与错误码并返回 -1。从调用链看三层 ID 的底层转换这组接口不是简单查表而是跨越了 ACL、RTS、Runtime 三个层次。以aclrtGetLogicDevIdByUserDevId为例完整链路为ACL 层src/acl/aclrt_impl/device.cpp 中的aclrtGetLogicDevIdByUserDevIdImpl做入参空指针检查后透传给rtsGetLogicDevIdByUserDevId并记录ACL_PROFILING_REG性能打点RTS 层src/runtime/api/api_c_device.cc 的rtsGetLogicDevIdByUserDevId先校验userDevId 0负数直接返回RT_ERROR_INVALID_VALUE再调用rtGetLogicDevIdByUserDevIdRuntime 核心层src/runtime/api/impl/api_impl_device_topology.cc 的ApiImplDeviceTopology::GetLogicDevIdByUserDevId最终调用rt-ChgUserDevIdToDeviceId完成用户设备 ID → 驱动设备 ID的转换并经过CheckDeviceIdIsValid合法性校验后输出逻辑设备 ID。反向接口aclrtGetUserDevIdByLogicDevId则走rt-GetUserDevIdByDeviceId见 api_impl_device_topology.cc。由此可以推断用户设备 ID 本质上是运行时基于当前进程可见设备集合建立的一层映射视图而逻辑/物理 ID 则对应 Runtime 与驱动侧更底层的编号体系——这正是容器与调度场景下需要反复校验映射一致性的原因。UUID 查询设备全局唯一标识仅靠设备编号无法区分换了环境后的同一张卡因此样例引入了 UUID。UUID 由aclrtDeviceGetUuid接口获取其声明在 include/external/acl/acl_rt.h/** * brief get uuid of device by device id * param [in] deviceId device id * param [out] uuid 16-byte Universally Unique Identifier for * globally unique identification of an NPU device. */ ACL_FUNC_VISIBILITY aclError aclrtDeviceGetUuid(int32_t deviceId, aclrtUuid* uuid);输出结构体aclrtUuid在 acl_rt.h 中定义为 16 字节的char bytes[16]。由于原始字节不可直接打印样例在 main.cpp 中实现了UuidToString按标准 UUID 排版在第 4、6、8、10 字节后插入-将其格式化为xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx形式的 36 字符字符串constexpr char kHexDigits[] 0123456789abcdef; std::string result; result.reserve(36U); for (std::size_t i 0U; i sizeof(uuid.bytes); i) { if (i 4U || i 6U || i 8U || i 10U) { result.push_back(-); } const auto value static_castunsigned char(uuid.bytes[i]); result.push_back(kHexDigits[value 4U]); result.push_back(kHexDigits[value 0x0FU]); }ACL 层的实现见 src/acl/aclrt_impl/device.cppaclrtDeviceGetUuidImpl校验uuid指针非空后调用 RTS 接口rtGetDeviceUuid而在 api_c_device.cc 中rtGetDeviceUuid会把底层返回的RT_ERROR_FEATURE_NOT_SUPPORT统一转换为ACL_ERROR_RT_FEATURE_NOT_SUPPORT上传与样例中非 PCIe 形态返回特性不支持的处理路径相互印证。版本要求aclrtDeviceGetUuid需要CANN 9.2.0-beta.2 及以上版本并配套 Ascend HDK 25.5.5 及以上版本见样例 README.md使用前请先核对运行环境版本。PCI Bus IDPCIe 形态下的双向反查与 round-trip 校验对于 PCIe 互连的设备样例还会利用 PCI 总线地址做第二重身份确认。VerifyPciRoundTrip函数main.cpp的流程如下char pciBusId[kPciBusIdBufferSize] {}; aclError ret aclrtDeviceGetPCIBusId(userDeviceId, pciBusId, static_castint32_t(sizeof(pciBusId))); if (ret ACL_ERROR_RT_FEATURE_NOT_SUPPORT) { WARN_LOG(Skip PCI discovery for user Device %d: the current interconnect is not PCIe., userDeviceId); return 1; // 非 PCIe 形态明确记录并跳过 } if (ret ! ACL_SUCCESS) { ... return -1; } // 其他错误判定失败 int32_t deviceFromPci -1; ret aclrtDeviceGetByPCIBusId(pciBusId, deviceFromPci); if (ret ACL_ERROR_RT_FEATURE_NOT_SUPPORT) { ... return 1; } if (ret ! ACL_SUCCESS) { ... return -1; } if (std::strlen(pciBusId) ! 12U || deviceFromPci ! userDeviceId) { ERROR_LOG(PCI round-trip is inconsistent: user%d, PCI Bus ID%s, pci-user%d, ...); return -1; } INFO_LOG(PCI Bus ID: %s (round-trip user Device ID: %d), pciBusId, deviceFromPci);这里有几个值得注意的工程细节缓冲区长度kPciBusIdBufferSize被定义为 13。PCI Bus ID 的格式为domain:bus:device.function例如0000:3d:00.0恰好 12 个字符加上\0终止符共 13 字节。头文件注释明确要求len必须大于等于 13见 acl_rt.h这也解释了校验中std::strlen(pciBusId) ! 12U的存在——PCIe 形态下 Bus ID 必须严格满足该长度特性不支持与失败的区分aclrtDeviceGetPCIBusId与aclrtDeviceGetByPCIBusId在非 PCIe 互连形态下会返回ACL_ERROR_RT_FEATURE_NOT_SUPPORT。样例对此采取记录并跳过策略返回值 1计入pciSkipCount而任何其他错误码都被视为硬失败返回值 -1避免把环境形态差异误判为设备故障round-trip 语义正向由用户设备 ID 查 Bus ID反向由 Bus ID 经aclrtDeviceGetByPCIBusId反查用户设备 ID要求两者严格相等。该接口的声明同样位于 acl_rt.h。ACL 层两个接口的实现src/acl/aclrt_impl/device.cpp均使用ACL_REQUIRES_RTS_OK_WARN_NOT_SUPPORT宏包装 RTS 调用即特性不支持仅告警、其余错误原样上报的语义与样例的跳过策略保持了一致。完整调用流程与错误处理设计样例入口main函数main.cpp编排了整体流程初始化调用aclInit(nullptr)失败则直接退出枚举调用aclrtGetDeviceCount获取用户可见设备数量若返回 0 张卡视为错误No user-visible Device is available.逐卡巡检对index从 0 到deviceCount-1依次调用InspectDevice。单卡检查失败立即终止循环result -1跳过 PCI 发现返回值大于 0则累加pciSkipCount但继续下一张卡去初始化无论巡检结果如何都调用aclFinalize保证资源释放即使aclFinalize失败也会将结果置为失败汇总输出打印枚举设备总数与跳过 PCI 发现的设备数。设计上值得借鉴的点单卡失败不影响其他卡统计PCI 跳过属于预期内分支与真正的接口错误区分对待资源清理与结果分离aclFinalize不因中间失败而跳过符合健壮性要求失败快速定位所有接口错误均携带返回的错误码打印配合错误码文档可直接定位问题可参考仓库 docs/zh/error_code_ref/ACL-Errors 下的错误码说明。编译与运行运行脚本样例提供了 run.sh 一键脚本其核心步骤为source $(cd ${SCRIPT_DIR}/../../.. pwd)/common/resolve_cann_env.sh resolve_cann_env cmake -S ${SCRIPT_DIR} -B ${BUILD_DIR} \ -DASCEND_CANN_PACKAGE_PATH${ASCEND_INSTALL_PATH} cmake --build ${BUILD_DIR} -j$(nproc) ${BUILD_DIR}/mainresolve_cann_env来自 example/common/resolve_cann_env.sh负责探测 CANN 安装路径并导出环境变量如ASCEND_INSTALL_PATH。环境安装与通用运行步骤请参考 example 目录 README。手动编译也可以参照 CMakeLists.txt 手动构建mkdir -p build cd build cmake .. -DASCEND_CANN_PACKAGE_PATH${ASCEND_INSTALL_PATH} make -j$(nproc) ./main构建配置要点头文件搜索路径包含${ASCEND_CANN_PACKAGE_PATH}/include与样例公共目录编译选项为-O2 -stdc17 -D_GLIBCXX_USE_CXX11_ABI0 -Wall -Werror其中-D_GLIBCXX_USE_CXX11_ABI0用于与 CANN 发布包保持 ABI 兼容链接库为${ASCEND_CANN_PACKAGE_PATH}/lib64/libacl_rt.so。示例输出解读在两张卡的典型环境非 PCIe 互连下运行输出如下摘自 README.md[INFO] Start to run device_identity_mapping sample. [INFO] Device ID mapping: user0, logic..., physical... [INFO] UUID: ... [WARN] Skip PCI discovery for user Device 0: the current interconnect is not PCIe. [INFO] Device ID mapping: user1, logic..., physical... [INFO] UUID: ... [WARN] Skip PCI discovery for user Device 1: the current interconnect is not PCIe. [INFO] Enumerated 2 user-visible Device(s); PCI discovery skipped for 2 Device(s). [INFO] Run the device_identity_mapping sample successfully.逐行含义Device ID mapping行展示该卡的用户/逻辑/物理三层 ID 映射结果UUID行为格式化后的 36 字符全局唯一标识Skip PCI discovery行说明当前互连非 PCIe已按设计跳过对应ACL_ERROR_RT_FEATURE_NOT_SUPPORT分支结尾汇总行统计枚举总数与跳过数最后打印successfully表示全部校验通过。若存在 ID 映射不一致或 PCI round-trip 不一致样例会以失败退出并打印ERROR级日志。产品支持情况与使用限制样例 README 声明的支持产品如下产品是否支持Ascend 950PR/Ascend 950DT√Atlas A3 训练系列产品/Atlas A3 推理系列产品√Atlas A2 训练系列产品/Atlas A2 推理系列产品√使用前还需注意两点限制UUID 接口的版本门槛aclrtDeviceGetUuid需要 CANN 9.2.0-beta.2 及以上 Ascend HDK 25.5.5 及以上PCI 反查仅适用于 PCIe 互连形态非 PCIe 互连下aclrtDeviceGetPCIBusId/aclrtDeviceGetByPCIBusId返回ACL_ERROR_RT_FEATURE_NOT_SUPPORT属预期行为样例会跳过其余错误码则按真实失败处理。典型应用场景小结这套身份识别与校验能力可以直接复用到以下工程场景容器/虚拟化设备透传自检在容器启动脚本中运行本样例验证透传后的设备编号映射与透传前一致调度系统的设备清单生成用aclrtGetDeviceCount枚举可见设备配合 UUID 建立调度编号 ↔ 全局唯一标识的台账避免节点重启或热插拔后设备错认多卡训练/推理的拓扑确认通过物理设备 ID 与 PCI Bus ID 关联真实硬件位置为通信拓扑优化如 NPU 互联亲和性提供设备身份依据回归测试基线将本样例纳入 CI任何 ID 映射逻辑变更若破坏 round-trip 一致性都能第一时间暴露。总体而言3_device_identity_mapping以一个可编译、可运行、可断言的紧凑样例完整展示了 CANN Runtime 设备身份接口族aclrtDeviceGetUuid、aclrtDeviceGetPCIBusId/aclrtDeviceGetByPCIBusId、四组 ID 映射接口的正确用法是理解 Runtime 设备视图模型与构建可靠设备管理工具的绝佳起点。【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考