CANN opbase PlatformInfo 预留接口全解析：设备平台信息模型与硬件能力查询机制

CANN opbase PlatformInfo 预留接口全解析设备平台信息模型与硬件能力查询机制【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbasePlatformInfo 是 CANN opbase 算子库中封装 NPU 设备平台信息的核心数据模型负责向上层算子与框架暴露 SoC 型号、核数、指令集能力等运行时信息。本文以仓库中《Reserved APIs》预留接口清单为主体结合 platform.h 头文件、platform.cpp 实现与测试用例逐一拆解 PlatformInfo 的构造、属性查询与能力探测接口帮助读者理解其内部实现原理、适用边界以及为什么这些接口被官方标记为预留、不建议使用。一、预留接口的定位与阅读前提在 docs/en/api/nnopbase/opdev/platform/reserved_interface_platform.md中文版本见 docs/zh/api/nnopbase/opdev/platform/reserved_interface_platform.md中官方给出了明确的定位声明本章接口为预留接口后续有可能变更或废弃不建议开发者使用开发者无需关注。这段声明包含三层含义也是阅读本文的前提稳定性不保证这些接口在后续版本中可能发生签名变化、行为调整甚至直接移除基于它们编写的代码存在升级兼容风险非对外承诺它们不属于受版本化约束的稳定公共 API 契约更像是框架内部为过渡期保留的半成品能力仅供内部参考开发者不应在自研算子的对外交付代码中依赖这些接口正确做法是使用平台模块中稳定的正式接口例如GetCurrentPlatformInfo()见 platform.md 所列的 GetCurrentPlatformInfo、GetSocVersion、GetSocLongVersion、GetBlockSize 等。尽管如此这些预留接口恰恰构成了 PlatformInfo 类的完整数据面是理解整个平台信息机制内部运转的最佳切入点——因为稳定的获取入口GetCurrentPlatformInfo()返回的正是这个 PlatformInfo 对象。二、PlatformInfo 类全景数据成员与设计约束PlatformInfo 的类定义位于 include/nnopbase/opdev/platform.h。从类声明可以直观看到它的内部结构namespace op { class PlatformInfoImpl; // 前向声明实现细节被隐藏 class PlatformInfo { friend const PlatformInfo GetCurrentPlatformInfo(); // 唯一合法的构造入口 friend class PlatformThreadLocalCtx; public: PlatformInfo() {}; PlatformInfo(int32_t deviceId) : deviceId_(deviceId) {}; // ... 查询接口 private: // 拷贝/赋值均被删除禁止复制与移动 PlatformInfo operator(const PlatformInfo other) delete; PlatformInfo operator(const PlatformInfo other) delete; PlatformInfo(const PlatformInfo other) delete; PlatformInfo(const PlatformInfo other) delete; void SetPlatformImpl(PlatformInfoImpl* impl); // 由内部框架调用 bool valid_ false; // 有效性标记 int32_t deviceId_{-1}; // 设备号默认 -1 表示未指定 PlatformInfoImpl* impl_ nullptr; // 指向真正承载数据的实现对象 ~PlatformInfo(); // 私有析构防止栈上随意创建 }; } // namespace op从中可以提炼出几个关键设计决策Pimpl 模式Pointer to ImplementationPlatformInfo只是薄壳真正的平台数据SoC 版本、核数、指令集能力表等全部存放在私有的PlatformInfoImpl中这样头文件无需暴露实现细节也便于内部演进禁止拷贝与赋值所有拷贝/移动构造函数和赋值运算符均被显式delete对象只能通过引用使用避免了平台信息对象的意外复制导致数据不一致私有析构 友元工厂析构函数为私有普通代码无法在栈上或堆上随意构造/销毁 PlatformInfo唯一入口是通过友元函数GetCurrentPlatformInfo()获取框架托管的实例有效性标记valid_字段记录实例是否已成功装载平台数据未装载时所有查询接口返回默认/兜底值。三、逐接口详解构造、装载与查询3.1 三个构造函数接口定义功能说明PlatformInfo()PlatformInfo 的构造函数默认deviceId_为 -1PlatformInfo(int32_t deviceId)PlatformInfo 的构造函数指定设备号PlatformInfo(const PlatformInfo other)/PlatformInfo(const PlatformInfo other)拷贝/移动构造函数在实现中已被删除仅为历史预留第一个构造函数产生一个空壳实例valid_为false、deviceId_为-1第二个构造函数允许传入deviceId用于绑定具体 NPU 设备。从源码结构看这两个构造函数在实际运行路径中由PlatformThreadLocalCtx::GetPlatformInfo()内部使用见下文第四节开发者代码中不应直接调用。值得注意的是头文件中虽然保留了拷贝/移动构造函数的声明但实现中platform.h它们均被 delete显式删除这印证了预留属性——接口在文档中存在但实际已不可用。3.2 SetPlatformImpl内部装载数据的唯一通道void PlatformInfo::SetPlatformImpl(op::PlatformInfoImpl* impl) { impl_ impl; valid_ true; }该接口用于将PlatformInfoImpl实现对象挂载到 PlatformInfo 壳对象上并将valid_置为true。它是私有成员仅允许友元GetCurrentPlatformInfo、PlatformThreadLocalCtx调用。从源码结构看SetPlatformImpl是连接壳与实的桥梁一旦挂载成功所有查询接口即开始返回真实数据反之未挂载时查询接口全部走兜底分支。3.3 查询类接口的行为与兜底值下表汇总了预留接口中全部查询方法的行为语义与异常兜底值依据 platform.cpp 实现接口定义功能说明未装载 impl_ 时的返回值GetDeviceId()从 PlatformInfo 中获取 deviceId直接返回成员deviceId_无兜底判断CheckSupport(SocSpec socSpec, SocSpecAbility ability)查询是否支持指定 SoC 指令规格能力falseGetCubeCoreNum()从 PlatformInfo 中获取 Cube 核数0GetVectorCoreNum()从 PlatformInfo 中获取 Vector 核数0Valid()判断 PlatformInfo 是否有效返回valid_成员本身GetPlatformInfos()获取 NPU 平台信息AI 处理器型号、参数等nullptrGetFftsPlusMode()判断是否支持 ffts plus 模式falseToString(SocVersion socVersion)将 SocVersion 枚举转换为字符串未知版本返回UnknownSocVersion各方法实现要点如下GetDeviceId()直接返回成员变量deviceId_不经过 impl因此无论是否装载数据都可读取GetCubeCoreNum()/GetVectorCoreNum()委托给 impl 的GetCubeCoreNum()/GetVectorCoreNum()impl 为空时返回0调用方需结合Valid()判断返回值是否可信CheckSupport()委托给 impl 的CheckAiCoreInstSupport()其内部从aiCoreInstAbility_能力向量中查找指定能力platform.cpp找不到即返回false不会抛出异常GetFftsPlusMode()返回 impl 中缓存的fftsPlusMode_布尔值该值在初始化时通过读取平台 SoCInfo 中的ffts_mode字段确定详见第五节Valid()是最轻量的健康检查接口返回valid_标记任何使用 PlatformInfo 查询结果的代码都应先调用它。四、枚举类型SocVersion、SocSpec 与 SocSpecAbilityPlatformInfo 的查询接口依赖三个枚举类型全部定义在 platform.henum class SocVersion { ASCEND910 0, ASCEND910B, ASCEND910_93, ASCEND910_95, ASCEND950 ASCEND910_95, ASCEND910E, ASCEND310, ASCEND310P, ASCEND310B, ASCEND310C, ASCEND610LITE, KIRINX90, KIRIN9030, ASCEND350, RESERVED_VERSION 99999 }; enum class SocSpec { INST_MMAD 0, RESERVED_SPEC 99999 }; enum class SocSpecAbility { INST_MMAD_F162F16 0, INST_MMAD_F162F32, INST_MMAD_H322F32, INST_MMAD_F322F32, INST_MMAD_U32U8U8, INST_MMAD_S32S8S8, INST_MMAD_S32U8S8, INST_MMAD_F16F16F16, INST_MMAD_F32F16F16, INST_MMAD_F16F16U2, INST_MMAD_U8, INST_MMAD_S8, INST_MMAD_U8S8, INST_MMAD_F16U2, };SocVersion覆盖 Ascend910/910B/910_93/910_95/910E、Ascend310/310B/310C/310P、Ascend350、Ascend610Lite、麒麟KirinX90/Kirin9030等系列RESERVED_VERSION 99999作为未知/未识别兜底值SocSpec目前仅定义INST_MMAD矩阵乘指令规格一种RESERVED_SPEC为兜底SocSpecAbility列举了 MMAD 指令支持的具体数据类型组合如INST_MMAD_F162F16FP16 输入 FP16 累加、INST_MMAD_U32U8U8U8 输入 U32 累加等 14 种能力。CheckSupport(SocSpec, SocSpecAbility)的语义即为在当前设备上指定 socSpec 类别下是否具备指定 ability 能力。当前实现中有效组合为(SocSpec::INST_MMAD, 任意 INST_MMAD_* 能力)。五、底层实现PlatformInfoImpl 的数据装载链路所有查询数据的来源是PlatformInfoImpl它在构造函数中完成五步初始化platform.cppPlatformInfoImpl::PlatformInfoImpl(fe::PlatFormInfos* platformOriginInfo) : platformOriInfo_(platformOriginInfo) { InitAiCoreInstAbility(); // 1. 初始化能力向量容器 InitAiCoreInstFromOriginPlatformInfo(); // 2. 装载指令能力/Soc版本/BlockSize/ffts模式 InitCoreNum(); // 3. 装载 Cube/Vector 核数 InitNpuArch(); // 4. 装载 NPU 架构号 }5.1 指令能力装载InitInstMMadSocSpecAbility实现首先从fe::PlatFormInfos中读取GetAICoreIntrinsicDtype()返回的指令数据类型表找到Intrinsic_mmad条目再通过一张字符串→枚举的转换表platform.cpp将平台下发的字符串如u32u8u8、f162f16映射为SocSpecAbility枚举存入aiCoreInstAbility_[INST_MMAD]向量。转换失败的字符串会被记录日志并跳过不影响其他能力项的装载。5.2 SoC 版本装载InitSocVersion通过GetPlatformResWithLock(version, Short_SoC_version, ...)获取短版本字符串映射为SocVersion枚举同时读取SoC_version字段得到长版本字符串如Ascend910B2存入socLogVersion_。两者任一失败都会落到RESERVED_VERSION或unknownVersion兜底。5.3 BlockSize 与 ffts 模式装载InitAiCoreSpec()读取(AICoreSpec, ubblock_size)配置并解析为整数解析失败非数字字符串或越界时回退默认值32DEFAULT_BLOCK_SIZE见 platform.cppInitSoCInfo()读取(SoCInfo, ffts_mode)当返回值恰为字符串ffts-plus时fftsPlusMode_置true否则为false——这就是GetFftsPlusMode()的判定逻辑platform.cpp。5.4 核数装载InitCoreNum实现将PlatFormInfos分别按AiCore与VectorCore两种核类型设置后读取核数分别存入cubeCoreNum_与vectorCoreNum_供GetCubeCoreNum()/GetVectorCoreNum()查询。5.5 平台信息入口GetCurrentPlatformInfoGetCurrentPlatformInfo()是访问 PlatformInfo 的正式入口platform.cpp其流程为通过aclrtGetDevice获取当前线程绑定的设备号deviceId在线程局部上下文PlatformThreadLocalCtxthread_local存储见 platform.cpp的platformInfoList_中按设备号索引查找/创建 PlatformInfo 实例若实例尚未Valid()则调用fe::PlatformInfoManager::GeInstance().GetRuntimePlatformInfosByDevice(deviceId, ...)从运行时获取真实平台数据封装为PlatformInfoImpl后通过SetPlatformImpl挂载返回该实例的常量引用。因此可以推断GetCurrentPlatformInfo()返回的对象内部正是本文所讲的这一套 PlatformInfo/PlatformInfoImpl 结构预留接口中描述的查询方法正是这个对象对外暴露的全部信息读取通道。同时g_tPlatformCtx为thread_local意味着每个线程各自维护一份平台信息缓存多线程下互不干扰也无需加锁。六、测试用例印证接口的实际行为基线仓库的单元测试 tests/nnopbase/ut/composite_op/test_platform.cpp 与系统测试 tests/nnopbase/st/composite_op/test_platform.cpp 为这些接口提供了可验证的行为基线典型断言包括SoC 版本GetSocVersion()在测试环境返回SocVersion::ASCEND910GetSocLongVersion()返回Ascend910B2ToString(static_castSocVersion(100))返回UnknownSocVersion未知版本兜底能力查询CheckSupport(INST_MMAD, INST_MMAD_F162F16)返回true而CheckSupport(INST_MMAD, INST_MMAD_F322F32)返回false说明能力表按平台实际指令集动态装载而非硬编码全量支持核数测试环境断言 Cube 核数为 64、Vector 核数为 32设备号GetDeviceId()返回 0BlockSizeGetBlockSize()返回默认值 32ffts 模式测试环境断言GetFftsPlusMode()为true多线程安全TestGetCoreNumMutiThreadTest以 200 个线程并发执行核数查询并全部断言通过test_platform.cpp验证了线程局部缓存设计的并发正确性。ToString的完整映射表见 platform.cpp覆盖 Ascend910 系列、Ascend310 系列、Ascend350、Ascend610Lite、KirinX90/Kirin9030 等全部已识别版本未识别版本统一返回UnknownSocVersion并打印告警日志。七、使用建议与边界约束综合文档声明与源码实现对读者给出如下实操建议优先使用稳定入口业务代码应通过GetCurrentPlatformInfo()获取平台信息并使用GetSocVersion()、GetBlockSize()等正式文档接口而不是直接构造PlatformInfo或调用预留方法查询前先校验GetCubeCoreNum()等在 impl 未装载时会静默返回0务必先用Valid()确认实例有效再解读核数、能力等查询结果能力查询不抛异常CheckSupport()对未知 socSpec 索引有边界检查aiCoreInstAbility_.size() socSpec见 platform.cpp越界或未装载时返回false调用方无需 try-catch但需自行处理不支持分支不要跨版本假设由于接口被官方标记为可能变更或废弃以PlatformInfo预留接口为核心的代码在 CANN 版本升级后需要回归验证线程局部缓存平台信息按线程独立缓存同一进程不同线程对同一设备的查询各自触发一次运行时数据获取首次调用存在初始化开销热路径建议在初始化阶段一次性获取并复用结果。如需继续深入平台模块的其他正式接口可参考 platform.md 索引或阅读中文版 docs/zh/api/nnopbase/opdev/platform/platform.md 下的 GetSocVersion、GetSocLongVersion、GetBlockSize 等独立文档。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考