CANN SHMEM 对外头文件与库文件全景解析：接口分层、SO 依赖关系与部署要点

CANN SHMEM 对外头文件与库文件全景解析接口分层、SO 依赖关系与部署要点【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库基于OpenSHMEM 标准协议实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmemCANN SHMEM 是基于 OpenSHMEM 标准协议、面向昇腾平台的多机多卡内存通信库。本文以仓库文档 docs/public-headers-and-libraries.md 为骨架系统梳理对外公开的头文件体系与安装产物中的共享库.so清单并结合 src/CMakeLists.txt、src/host/init/bootstrap/shmemi_bootstrap.cpp 等源码说明各库的构建、加载与依赖关系帮助开发者理解头文件—库—实现的对应关系正确完成编译链接与部署排查。1. 库文件总览安装产物中的共享库SHMEM 安装产物中的动态库可分为四类核心运行时、工具/支撑库、Bootstrap 插件、Python 扩展。下表完整列出各库的类型、用途与依赖版本信息库文件类型用途依赖版本信息libshmem.so核心运行时Host 侧主库初始化、堆、Team、Host RMA/同步/集合通信等依赖ASCEND_HOME_PATH下 CANN 库runtime/ascendcl/tiling_api/platform/c_sec等链接libshmem_utils.soSOC_TYPEAscend950时另链hcommlibshmem_utils.so工具/支撑库日志、内部工具与公共支撑符号供主库与 bootstrap 插件链接无独立对外版本号UDMA 开启时编译期依赖 nlohmann/json 头文件aclshmem_bootstrap_config_store.soBootstrap 插件无lib前缀Default / UniqueID 初始化控制面Config Store。ACLSHMEMX_INIT_WITH_DEFAULT与ACLSHMEMX_INIT_WITH_UNIQUEID均加载本库运行时由 init 动态加载链接libshmem_utils.so无独立版本号aclshmem_bootstrap_uid.soBootstrap 插件UniqueID bootstrap 相关库链接libshmem_utils.so无独立版本号aclshmem_bootstrap_mpi.soBootstrap 插件可选MPI 模式 bootstrapCMakefind_package(MPI)成功时才编译链接MPI::MPI_CXX与libshmem_utils.so_pyshmem*.soPython 扩展可选pybind11 绑定供import shmem构建find_package(pybind11)链接libshmem.so等运行torch-npusetup.py需要特别说明的三点Device 侧接口多为头文件内联Host 侧符号由libshmem.so提供。因此 Device 侧头文件在表格中对应 so 库一栏多为无。应用侧通常的用法#include shmem.h链接-lshmem并保证libshmem_utils.so与实际使用的 bootstrap 插件可被动态链接器解析。构建层面的印证在 src/CMakeLists.txt 中可以看到add_library(shmem SHARED ...)第 130 行、add_library(shmem_utils SHARED ...)第 115 行、add_library(aclshmem_bootstrap_config_store SHARED ...)第 190 行等目标定义且各 bootstrap 插件均设置了PREFIX 无lib前缀与文档中无lib前缀的描述完全一致。1.1 为什么核心库分拆为libshmem.so与libshmem_utils.so从构建脚本看shmem_utils由ACLSHMEM_UTILS_FILES日志、内部工具与公共支撑符号构成并被主库与所有 bootstrap 插件共享链接。这种分拆让日志等公共能力成为可复用的独立单元主库与插件可以各自按需复用避免符号重复膨胀。1.2 Ascend950 平台的特殊链接在 src/CMakeLists.txt 中if(SOC_TYPE STREQUAL Ascend950) target_link_libraries(shmem PRIVATE shmem_utils hcomm) else() target_link_libraries(shmem PRIVATE shmem_utils) endif()即SOC_TYPEAscend950时libshmem.so还会额外链接hcomm这是 UDMA 等 Ascend950 专属能力落地的基础。同时SOC_TYPE为 Ascend950 时shmem_utils会额外加入3rdparty/json/single_includenlohmann/json 头文件依赖对应文档中UDMA 开启时编译期依赖 nlohmann/json 头文件的描述。2. 对外公开接口头文件列表统一入口为include/shmem.h它按编译环境条件包含 Host / Device / SIMT 三类头文件#if defined(__CCE_AICORE__) || defined(__CCE_KT_TEST__) #include device/gm2gm/shmem_device_amo.h #include device/gm2gm/shmem_device_cc.h ... #include device/team/shmem_device_team.h #if defined(USE_SIMT) #include device_simt/gm2gm/shmem_device_simt_rma.h ... #endif #endif #include host/shmem_host_def.h #include host/mem/shmem_host_heap.h #include host/init/shmem_host_init.h ...可见 include/shmem.h 本身不定义任何业务 API只负责按编译宏__CCE_AICORE__、USE_SIMT等聚合各个模块的公开接口。2.1 总入口与公共定义对外公开接口文件对应 so 库文件文件用途依赖版本信息include/shmem.hHost 部分对应libshmem.so及 utils/bootstrapDevice/SIMT 部分无对外总头文件按编译宏聚合 Host / Device / SIMT 公开 APIDevice/SIMT 分支依赖编译宏如__CCE_AICORE__、USE_SIMT无独立外部版本号include/host_device/shmem_common_types.h无Host/Device 共用类型、枚举、ACLSHMEM_DEVICE等宏依赖 CANN 头文件acl/acl_rt.hinclude/host_device/shmem_common_macros.h无Host/Device 共用宏无include/host/shmem_host_def.hlibshmem.soHost 侧常量、版本宏、ACLSHMEM_HOST_API、公共结构/枚举无外部版本约束仅定义本库 API 宏include/device/shmem_def.h无Device 侧公共定义与非连续拷贝等结构依赖 CANNUSE_SIMT时有条件分支关于目录组织可对照 docs/code_organization.md 中给出的 include 目录树include/device/下按gm2gm高阶接口 engine/低阶接口、ub2gm、team分门别类include/host/下按init、team、mem、data_plane、utils组织与本文表格一一对应。2.2 Host 侧公开接口对外公开接口文件对应 so 库文件文件用途依赖版本信息include/host/init/shmem_host_init.hlibshmem.so 运行时加载 bootstrap 插件初始化/终结、UniqueId、init 状态查询、aclshmemx_init_attr等Default/UniqueID 加载aclshmem_bootstrap_config_store.soMPI 模式加载aclshmem_bootstrap_mpi.so需系统 MPIinclude/host/mem/shmem_host_heap.hlibshmem.so对称堆分配malloc/calloc/align/free及扩展内存类型接口无include/host/team/shmem_host_team.hlibshmem.soTeam 创建/拆分/销毁、PE 翻译、my_pe/n_pes等无include/host/data_plane/shmem_host_rma.hlibshmem.soHost 侧 RMAput/get 等与aclshmem_ptr无include/host/data_plane/shmem_host_so.hlibshmem.soHost 侧 putsignal 同步/异步接口无include/host/data_plane/shmem_host_p2p_sync.hlibshmem.soHost 侧 P2P 同步、handle_wait、signal wait、ffts 配置获取无include/host/data_plane/shmem_host_cc.hlibshmem.soHost 侧集合通信barrier/sync 及 on_stream 变体无include/host/utils/shmem_log.hlibshmem.so/libshmem_utils.so外部 logger、日志级别、profiling 打印/获取无提示头文件中的ACLSHMEM_HOST_API宏定义于shmem_host_def.h声明了这些接口的可见性与调用约定链接时由libshmem.so导出对应符号。2.3 Device 侧公开接口GM↔GM / UB↔GMDevice 侧接口全部以内联头文件形式提供libshmem.so的 Device 部分符号由shmem目标中的$TARGET_OBJECTS:aclshmem_device编译进主库按数据通路分为 GM↔GM 与 UB↔GM 两个子域对外公开接口文件对应 so 库文件文件用途依赖版本信息include/device/gm2gm/shmem_device_rma.h无Device GM↔GM 标准 RMA多 dtype put/get 等依赖 CANN底层可走 MTE/RDMA/SDMA/UDMA由拓扑与编译选项决定远端操作数用于对称地址换算未使能 RDMA 时本地 Put 源端或 Get 目的端可使用任意有效的本地 GM 地址使能 RDMA 后两端均须指向对称内存调用者无需判断单次实际引擎include/device/gm2gm/shmem_device_so.h无Device 侧 putsignal 同步接口依赖 CANNinclude/device/gm2gm/shmem_device_amo.h无Device 原子操作atomic_add 等依赖 CANN头文件注明各引擎支持类型随 SoC如 UDMA 面向 Ascend950include/device/gm2gm/shmem_device_mo.h无Device 内存序quiet/fence依赖 CANNinclude/device/gm2gm/shmem_device_p2p_sync.h无Device P2P 同步signal_op、wait_until 等依赖 CANNinclude/device/gm2gm/shmem_device_cc.h无Device 集合通信barrier含 vector-only 等变体、ffts 地址设置依赖 CANN头文件限制主要用于 MIX Kernelinclude/device/gm2gm/engine/shmem_device_mte.h无MTE 引擎对称地址翻译、连续/非连续异步 put/get依赖 CANNinclude/device/gm2gm/engine/shmem_device_rdma.h无RDMA 引擎本地和远端操作数均须指向对称内存且完整传输范围不得越过各自内存分配的异步 RMA依赖 CANNHost 侧需开启ACLSHMEM_RDMA_SUPPORTAscend950 另需指定 RDMA backendinclude/device/gm2gm/engine/shmem_device_sdma.h无SDMA 引擎参数设置与异步 put/get依赖 CANNinclude/device/gm2gm/engine/shmem_device_udma.h无UDMA 引擎低阶异步 RMA仅面向 Ascend950需 CANN 9.1.0 及以上版本初始化时加载并检查所需 HCOMM 资源接口include/device/ub2gm/shmem_device_rma.h无UB↔GM 标准 RMAUB 侧 get/put 等依赖 CANNinclude/device/ub2gm/engine/shmem_device_mte.h无UB↔GM 的 MTE 引擎异步拷贝依赖 CANNinclude/device/team/shmem_device_team.h无Device 侧 Team/PE 查询与 PE 翻译依赖 CANN从源码看 UDMA 引擎的能力边界在 include/device/gm2gm/engine/shmem_device_udma.h 中可以看到 UDMA 提供基于 WQE如PIPE_MTE3的 put/get/atomic 操作并定义了ACLSHMEMX_UDMA_OP_CONFIG_SOStrong Order WQE用于后续排序点如对同一 PE/QP 的多次 UDMA Put 之后的原子 flag 更新与ACLSHMEMX_UDMA_OP_CONFIG_NO_CQE不产生 CQE等配置常量同时头文件明确提示以 UDMA 作为底层传输时对同一 PE 的并发 RMA/AMO 操作不受支持、单次 UDMA get 请求最多传输 256 MB 等约束——这印证了文档中低阶异步 RMA的定位。2.4 Device SIMT 公开接口需开启 SIMT 支持SIMT 接口属于条件编译分支构建时需定义USE_SIMT对应 CMake 的ACLSHMEM_SIMT_SUPPORT见 src/CMakeLists.txtshmem.h才会将其包含进来。对外公开接口文件对应 so 库文件文件用途依赖版本信息include/device_simt/shmem_simt_common_types.h无SIMT 公共状态/类型定义需编译定义USE_SIMTACLSHMEM_SIMT_SUPPORTinclude/device_simt/gm2gm/shmem_device_simt_rma.h无SIMT 作用域下的 GM↔GM RMA需USE_SIMT依赖 CANNinclude/device_simt/gm2gm/engine/shmem_device_simt_mte.h无SIMT MTEthread/block/warp 作用域异步拷贝需USE_SIMT依赖 CANNinclude/device_simt/team/shmem_device_simt_team.h无SIMT 侧 Team 相关接口需USE_SIMT依赖 CANN3. Bootstrap 插件的动态加载机制aclshmem_bootstrap_config_store.so与aclshmem_bootstrap_mpi.so并非由libshmem.so在链接期静态依赖而是在初始化阶段通过dlopen按需加载。其加载逻辑位于 src/host/init/bootstrap/shmemi_bootstrap.cpp定义了插件模块名常量BOOTSTRAP_MODULE_MPI aclshmem_bootstrap_mpi.so、BOOTSTRAP_MODULE_CONFIG_STORE aclshmem_bootstrap_config_store.soaclshmemi_bootstrap_pre_init中ACLSHMEMX_INIT_WITH_UNIQUEID与ACLSHMEMX_INIT_WITH_DEFAULT都选择aclshmem_bootstrap_config_store.soaclshmemi_bootstrap_init中ACLSHMEMX_INIT_WITH_MPI选择aclshmem_bootstrap_mpi.so加载时通过dladdr获取libshmem.so自身所在目录get_current_so_dir优先以同目录绝对路径 dlopen方式加载插件失败才回退到dlopen(so_name)依赖系统动态链接器搜索路径。这就是文档中bootstrap 插件需与libshmem.so放置在同一目录这一部署约束的源码依据。这一设计意味着初始化模式的选型直接决定加载哪个插件。开发者在使用aclshmemx_init_attr时接口声明见 include/host/init/shmem_host_init.h对应宏shmem_init_attr应根据需要传入ACLSHMEMX_INIT_WITH_DEFAULT/ACLSHMEMX_INIT_WITH_UNIQUEID/ACLSHMEMX_INIT_WITH_MPI并保证对应插件可被解析。4. 编译链接与部署要点4.1 应用侧编译链接应用通常只依赖一个头文件入口与一个主库# 头文件包含 include/ 目录 -I${SHMEM_INSTALL_DIR}/include # 链接主库与工具库 -L${SHMEM_INSTALL_DIR}/lib -lshmem -lshmem_utils同时在部署目录中确保以下文件齐全清单来自 docs/deployment/shmem_so_library_dependencies.md文件名功能说明是否为核心依赖libshmem.soSHMEM 主功能库提供对外核心接口是aclshmem_bootstrap_config_store.so默认/UniqueID 引导初始化能力是aclshmem_bootstrap_mpi.soMPI 引导初始化能力仅 MPI 场景否libshmem_utils.so如构建产物存在公共工具与基础能力库是4.2 运行时可见的外部 SOlibshmem.so及其插件运行时还会依赖 CANN Toolkit / 驱动运行时 / OpenSSL 等外部库部署环境需保证其可见性libascend_hal.soHAL 能力加载、libascendcl.soACL 接口、libruntime.soRuntime 接口、libopapi.soOP API 接口、libra.soHCCP 相关能力、libtsdclient.soTSD 能力、libssl.so/libcrypto.soTLS/加密由配置存储模块通过绝对路径动态加载路径来源于EP_OPENSSL_PATH。4.3 加载两阶段语义阶段 A动态链接阶段由系统动态链接器解析主程序与libshmem.so的NEEDED依赖实际装载先后由链接关系决定不作为接口语义约束阶段 B初始化阶段调用aclshmemx_init_attr后libshmem.so内部按 bootstrap 模式选择并加载aclshmem_bootstrap_config_store.so或aclshmem_bootstrap_mpi.soPython 包场景中 src/python/shmem/init.py 的导入阶段预加载仅用于 Python 封装侧依赖兜底不能等同于libshmem.so初始化阶段的插件加载顺序语义。4.4 依赖排查与验证在部署后可使用以下命令核验依赖完整性详见 docs/deployment/shmem_so_library_dependencies.md# 检查依赖项是否缺失 ldd ${CUSTOM_PROJECT}/lib/libshmem.so ldd ${CUSTOM_PROJECT}/lib/aclshmem_bootstrap_config_store.so # 检查 NEEDED 条目是否与部署清单一致 objdump -p ${CUSTOM_PROJECT}/lib/libshmem.so | grep NEEDED # 确认插件与主库来自同一目录 LD_DEBUGlibs,files ${CUSTOM_PROJECT}/bin/app --version 21 | grep -E libshmem.so|aclshmem_bootstrap_config_store.so若ldd出现not found需补齐缺失 SO 到${CUSTOM_PROJECT}/lib/若跨 Linux 发行版复用 SO 加载失败建议在目标发行版上重新构建并保证 glibc 版本与编译基线一致。5. 总结CANN SHMEM 对外接口采用统一入口shmem.h 分域头文件的组织方式Host 侧接口由libshmem.so导出符号Device 侧接口以内联头文件形式编译进应用内核SIMT 接口受USE_SIMT编译宏控制安装产物中libshmem.so与libshmem_utils.so构成核心运行时三个aclshmem_bootstrap_*插件由初始化阶段按模式动态加载Python 扩展则以_pyshmem*.so独立交付。理解这层头文件—库—加载机制的映射关系是正确使用 SHMEM API、完成应用部署与排障的基础。【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库基于OpenSHMEM 标准协议实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考