CANN SHMEM 初始化示例examples/init详解六种 Bootstrap 模式、运行参数与跨机部署实战【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库基于OpenSHMEM 标准协议实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem本文以 CANN SHMEM 仓库中的 examples/init 示例为主线系统讲解 SHMEM 库的六种初始化Bootstrap方式——default、mpi、uid、uid_multi、uid_default 与 uid_multi_stress 的用途、命令行参数、底层实现与跨机运行配置。读完本文你将掌握如何从零编译该示例、如何用run.sh以不同模式与 PE 数量启动单机/多机初始化用例、如何配置 MPI 与 UID 环境变量、以及跨机运行时的 hostfile 与-ipport配置方法。一、示例定位验证 SHMEM 初始化/终止的最小闭环examples/init是 CANN SHMEM 仓库中最直接的初始化/终止演示用例。它不涉及任何 RMA 数据搬运或集合通信业务只做一件事让多个 PEProcessing Element以指定 Bootstrap 方式对称地完成aclshmemx_init_attr初始化再对称地调用shmem_finalize终止并打印成功/失败日志。因此它也是排查初始化链路问题建链、UID 广播、MPI 集成、多实例的首选最小复现样例。从源码结构看该示例由三个文件构成main.cpp根据编译期宏RUN_WITH_DEFAULT/RUN_WITH_MPI/RUN_WITH_UNIQUEID/RUN_WITH_UNIQUEID_MULTI_INSTANCE/RUN_UNIQUEID_WITH_DEFAULT/STRESS_LOOP_COUNT选择不同的run_main实现CMakeLists.txt通过RUN_MODE1~6映射到上述宏并决定是否链接 MPI 与shmem库run.sh命令行参数解析、构建目录准备、按模式调用cmake/make并启动进程。三个环节一一对应run.sh的-mode参数 →RUN_MODE→ 编译宏 →main.cpp中对应的run_main。二、编译项目MPI 环境变量与构建脚本2.1 安装并导入 MPI 环境除 default 模式外均必需原文明确指出default 以外的流程mpi/uid/uid_multi/uid_default/uid_multi_stress都需要自行安装并导入 MPI 环境变量。示例基于 MPICH 实现若使用 Open MPI 等其他 MPI 实现遇到报错可能需要自行调整脚本中的 MPI 相关参数。以 MPICH 安装在默认路径为例# MPICH is installed in the default path. Replace the path with the actual path as needed. export PATH/usr/local/mpich/bin:$PATH export LD_LIBRARY_PATH/usr/local/mpich/lib:$LD_LIBRARY_PATH对应到 CMakeLists.txtRUN_MODE为 2~6 时都会执行find_package(MPI REQUIRED)并在链接阶段追加MPI::MPI_CXX而RUN_MODE1defaultNEED_MPIOFF仅链接shmem。这也解释了为何 default 模式无需 MPI它的进程启动与 rank 编号完全由run.sh直接拉起进程、通过-fpe/-fnpu/-gnpus参数手动编排。2.2 根目录构建脚本构建统一在仓库根目录执行scripts/build.sh会先定位并 source Ascend Toolkit 的set_env.sh同时支持新旧路径并读取仓库根目录 VERSION 作为发布版本号。A2/A3 与 Ascend950 平台命令如下# A2/A3 平台 bash scripts/build.sh source install/set_env.sh # Ascend950 平台 bash scripts/build.sh -soc_type Ascend950 source install/set_env.shsource install/set_env.sh用于将编译产物install/shmem/lib、install/shmem/include写入LD_LIBRARY_PATH与头文件搜索路径是后续运行示例的前提。补充若要一并构建仓库全部示例可执行bash scripts/build.sh -examples见 docs/quickstart_en.md本用例也会被安装到install/shmem安装前缀下CMAKE_INSTALL_PREFIX见 CMakeLists.txt。三、六种初始化模式与运行参数3.1 用例参数速览进入用例目录后run.sh接受若干参数其中最核心的是前两个第一个参数指定流程-mode第二个参数指定 PE 数量-pesize不能超过设备数。不指定时默认mode default、pesize 2。全部参数如下表参数含义默认值说明-mode初始化流程defaultdefault/mpi/uid/uid_multi/uid_default/uid_multi_stress-pesizePE 总数2正整数不能超过设备数-fpe本机首个 PE 编号0default 模式跨机时PE0 所在机器为 0其他机器为-fpe 2等-gnpus本机参与设备数8被pesize收敛指定每台机器启动的 PE/设备数-ipportPE0 所在机器地址tcp://127.0.0.1:8666只传host:port脚本自动拼tcp://前缀-fnpu本机首个设备号0从哪个 Device 开始映射-build仅编译不运行OFF跨机部署时先在各机器上编译从 run.sh 实现看-ipport会同时写入IPPORTtcp://前缀与SESSION_ID而SESSION_ID随后导出为SHMEM_UID_SESSION_ID环境变量仅mpi|uid|default|uid_default四种模式导出见下文 4.2 节-pesize传入时会校验必须为正整数并且当GNPU_NUM默认 8大于pesize时自动收敛为pesize值。3.2 各模式运行命令default 流程2 PE——不依赖 MPI脚本直接 fork 多个进程并传入device_id等参数bash run.sh -mode default -pesize 2mpi 流程2 PE——基于MPI_Initaclshmemx_init_attr(ACLSHMEMX_INIT_WITH_MPI, attr)bash run.sh -mode mpi -pesize 2uid 流程2 PE——基于 UID 广播 ACLSHMEMX_INIT_WITH_UNIQUEIDbash run.sh -mode uid -pesize 2uid_multi 流程4 PE——在 UID 基础上演示同一进程/进程组内创建与销毁多个 SHMEM 实例# 将 enpxxx 替换为 ip addr 命令查询到的本机网卡名 export SHMEM_UID_SOCK_IFNAMEenpxxxxxxx:inet4 bash run.sh -mode uid_multi -pesize 4 unset SHMEM_UID_SOCK_IFNAMEuid_multi_stress 流程4 PE——uid_multi 的循环压测默认循环 20 次# STRESS_LOOP_COUNT20 在编译期定义循环执行 20 次 uid_multi 的创建/销毁流程 export SHMEM_UID_SOCK_IFNAMEenpxxxxxxx:inet4 bash run.sh -mode uid_multi_stress -pesize 4 unset SHMEM_UID_SOCK_IFNAME如需修改循环次数编辑 CMakeLists.txt 中RUN_MODE6对应的STRESS_LOOP_COUNT值当前为STRESS_LOOP_COUNT20后重新运行即可。uid_default 流程2 PE——UID 获取 ACLSHMEMX_INIT_WITH_DEFAULT的组合即用 UID 方式准备参数、以 default 标志完成初始化bash run.sh -mode uid_default -pesize 23.3 模式 → 宏 → 源码实现的映射下表汇总了run.sh -mode、RUN_MODE、编译宏与 main.cpp 中实现函数的对应关系编译宏定义见 CMakeLists.txt-modeRUN_MODE编译宏使用的初始化 flag依赖 MPIdefault1RUN_WITH_DEFAULTACLSHMEMX_INIT_WITH_DEFAULT否mpi2RUN_WITH_MPIACLSHMEMX_INIT_WITH_MPI是uid3RUN_WITH_UNIQUEIDACLSHMEMX_INIT_WITH_UNIQUEID是uid_multi4RUN_WITH_UNIQUEID_MULTI_INSTANCEACLSHMEMX_INIT_WITH_UNIQUEID多实例是uid_default5RUN_UNIQUEID_WITH_DEFAULTACLSHMEMX_INIT_WITH_DEFAULT是uid_multi_stress6RUN_WITH_UNIQUEID_MULTI_INSTANCE; STRESS_LOOP_COUNT20ACLSHMEMX_INIT_WITH_UNIQUEID多实例压测是四个初始化 flag 的位定义位于公共头文件 include/host/shmem_host_def.hACLSHMEMX_INIT_WITH_DEFAULT默认模式优先级为ip_portuidcomm_args两者都未提供则报错ACLSHMEMX_INIT_WITH_MPIMPI 模式ACLSHMEMX_INIT_WITH_UNIQUEIDUID 模式。四、从源码看三种初始化的实现差异理解示例的关键是看懂 main.cpp 中不同模式的初始化参数准备方式。4.1 default 模式手动编排 rank 与地址default 模式的run_main直接接收脚本传入的 6 个参数device_id、pe_size、ipport、g_npu、f_pe、f_npuPE 编号由pe f_pe device_id计算得出然后通过test_set_attr填充aclshmemx_init_attr_tint attr_version (1 16) sizeof(aclshmemx_init_attr_t); attributes-my_pe my_pe; attributes-n_pes n_pes; attributes-ip_port[ip_len] \0; attributes-local_mem_size local_mem_size; attributes-option_attr {attr_version, ACLSHMEM_DATA_OP_MTE, DEFAULT_TIMEOUT, DEFAULT_TIMEOUT, DEFAULT_TIMEOUT}; attributes-comm_args reinterpret_castvoid *(default_flag_uid);随后调用aclshmemx_init_attr(ACLSHMEMX_INIT_WITH_DEFAULT, attributes)。ip_port填写tcp://host:port脚本负责拼接前缀本地堆大小local_mem_size设为 1 GiB。aclshmemx_init_attr_t的关键字段定义见 include/host/shmem_host_def.h包括my_pe/n_pes、ip_port[ACLSHMEM_MAX_IP_PORT_LEN]、local_mem_size、option_attr、comm_args与instance_id。其中option_attr.data_op_engine_type决定数据面传输通路ACLSHMEM_DATA_OP_MTE/SDMA/ROCE/UDMA可按位或示例统一使用ACLSHMEM_DATA_OP_MTE。4.2 MPI 模式PE 编号由 MPI 世界决定MPI 模式的run_main通过MPI_Init后取MPI_Comm_rank/MPI_Comm_size作为pe/pe_size设备号取pe % g_npu然后直接用聚合初始化构造属性并调用ACLSHMEMX_INIT_WITH_MPIuint64_t local_mem_size 1024 * 1024 * 1024; aclshmemx_init_attr_t attributes { pe, pe_size, , local_mem_size, {0, ACLSHMEM_DATA_OP_MTE, 120, 120, 120}}; status aclshmemx_init_attr(ACLSHMEMX_INIT_WITH_MPI, attributes);需要注意的是从 docs/principles/init_finalize.md 的说明看MPI 模式下comm_args为MPI_Comm*nullptr即MPI_COMM_WORLD且attr.my_pe/n_pes必须与MPI_Comm_rank/MPI_Comm_size一致否则会导致后续行为异常。示例中未显式设置comm_args默认nullptr即使用MPI_COMM_WORLD。4.3 UID 模式rank 0 生成 UID 并经 MPI 广播UID 模式的初始化流程default 模式下comm_argsfallback 到 UID 时逻辑类似为aclshmemx_get_uniqueid(uid)——仅由pe 0调用生成包含addr监听地址与magic随机通信域标识的aclshmemx_uniqueid_tMPI_Bcast(uid, sizeof(aclshmemx_uniqueid_t), MPI_UINT8_T, 0, MPI_COMM_WORLD)——将 UID 字节广播给全体 PE要求全体 rank 的 UID 字节级一致aclshmemx_set_attr_uniqueid_args(pe, pe_size, local_mem_size, uid, attributes)——由 UID 与进程信息填充属性结构对应声明见 include/host/init/shmem_host_init.haclshmemx_init_attr(ACLSHMEMX_INIT_WITH_UNIQUEID, attributes)——以 UID 模式完成初始化。UID 的监听地址来源由环境变量决定SHMEM_UID_SESSION_ID直接指定 PE 0 监听 socket 的ip:port支持 IPv4 字面量、[IPv6]:port、主机名三种格式SHMEM_UID_SOCK_IFNAME指定网口名与地址族ifname:inet4|inet6或仅ifname自动探测均可用时优先 IPv4。两者同时配置时只读取SHMEM_UID_SESSION_ID都不配置时自动搜索可用网口排除 lo/docker/veth/br-/virbr/tun/tap 等虚拟网口。上述规则详见 docs/api/env_vars_intro_en.md 与 docs/quickstart_en.md。同时注意 run.sh 的行为对于mpi|uid|default|uid_default四种模式脚本会把SESSION_ID即-ipport传入值导出为SHMEM_UID_SESSION_ID环境变量而uid_multi|uid_multi_stress模式则要求用户自行导出SHMEM_UID_SOCK_IFNAME未设置时脚本会打印告警但不会中断。4.4 uid_multi单进程组内创建多个 SHMEM 实例uid_multi是最能体现多实例能力的模式。其run_main中用MPI_Comm_split把世界通信域按dev_list划分出子组在子组内再次走rank 0 生成 UID →MPI_Bcast→aclshmemx_set_attr_uniqueid_args→aclshmemx_init_attr的流程并通过attr.instance_id区分不同实例实例 1instance_id 1dev_list {0, 1, 2, 3}4 个 PE实例 2instance_id 2dev_list {0, 2}2 个 PE。创建顺序为创建实例 1 → 创建实例 2 → 销毁实例 2aclshmemx_finalize(2)→ 销毁实例 1aclshmemx_finalize(1)每步均打印shmem create/finalize instance N SUCCESS。uid_multi_stress只是把上述创建销毁流程用STRESS_LOOP_COUNT默认 20次循环包裹并抑制单次迭代日志、在最后汇总失败次数。多实例的通用约束可参考 docs/principles/multi_instance.md每个实例拥有独立的 Bootstrap实例端口须在SHMEM_INSTANCE_PORT_RANGE范围内选择模板端口写 0非 0 实例的 team 能力受限。4.5 底层初始化/终止链路从 docs/principles/init_finalize.md 的实现说明看aclshmemx_init_attr完成后会依次完成Bootstrap控制面建链Default/UID 走aclshmem_bootstrap_config_store.so、MPI 走aclshmem_bootstrap_mpi.so、HYBM 建堆reserve_heap/setup_heap、slice 交换与 mmap、以及堆分配器/team/signal/sync 等子模块初始化shmem_finalize则按相反顺序释放并在拆除 Bootstrap 前经aclshmemi_control_barrier_all做控制面集合同步。init每个 PE 均须对称调用且各 rank 的aclshmem_malloc/aclshmem_free需保持同序同大小以保证堆内偏移对称。五、跨机运行5.1 default 模式跨机双机各 2 PEdefault 模式跨机无需 MPI/hostfile只需要在每台机器上分别以-fpe指定本机 PE 起点、以-ipport指向 PE0 所在机器。注意-ipport只传host:port脚本自动拼tcp://前缀IPv4 地址如192.168.1.100:8666也支持主机名如my-server:8666由系统 DNS 解析。在两台机器上分别执行# PE0 所在机器${该机器的ip:port} 也可使用主机名如 my-server:8666 bash run.sh -mode default -pesize 4 -fpe 0 -gnpus 2 -ipport ${该机器的ip:port} # 其他机器 bash run.sh -mode default -pesize 4 -fpe 2 -gnpus 2 -ipport ${PE0机器的ip:port}其中-pesize 4为两机总 PE 数-gnpus 2为本机设备数PE 编号由pe f_pe device_id计算保证 PE0~PE1 在首机、PE2~PE3 在次机。5.2 mpi/uid 模式跨机hostfile 一致编译mpi/uid 流程依赖 MPI 能力跨机需自行配置 hostfile 文件。以 MPICH 配置文件为例# 替换为实际机器的 IP且保证 PE0 所在机器在最前面冒号后配置每台机器可启动的 PE 数 # PE 数须小于该机设备数建议每台机器启动的 PE 数量一致。 0.0.0.1:2 0.0.0.2:2关键约束mpirun 要求多机可执行文件位置一致因此必须先在所有机器上用相同 mode 编译样例。若各机 mode 不一致会导致报错或卡死。先仅编译bash run.sh -build -mode mpi # UID 流程则将 mode 参数改为 uid然后在 PE0 所在机器上执行# mpi 流程gnpus 指定每台机器自身的 PE 数当所有机器启动的卡数一致时 # 将其设置为单机 PE 数量可保证每台机器都从 0 卡开始启动。 bash run.sh -mode mpi -gnpus 2 # uid 流程需要在 PE0 所在机器上以 -ipport 指向 PE0 机器的地址 bash run.sh -mode uid -gnpus 2 -ipport ${PE0机器的ip:port}hostfile 的识别逻辑在 run.sh 中mpi|uid|uid_multi|uid_multi_stress|uid_default模式下若当前目录存在hostfile文件则执行mpirun -f hostfile ./build/bin/init_examples $GNPU_NUM否则执行mpirun -np $NUM_PROCESSES ...。因此若之后想再次以 mpi/uid 模式执行单机用例建议删除 hostfile 文件否则 mpirun 会继续按多机 hostfile 方式拉起进程。六、运行结果与验证要点无论哪种模式成功的初始化都会打印类似pe N: shmem init SUCCESS最终在所有 PE 完成后打印[SUCCESS] pe N: demo run success!若初始化或终止失败main.cpp会打印[ERROR] pe N: demo run failed!并返回非零退出码run.sh随后打印Execution failed并以非零状态退出。uid_multi_stress模式结束时 PE0 会额外打印压测汇总[STRESS] 20 iterations, 0 failures验证时建议关注以下几点均可在 docs/debug/Troubleshooting_FAQs_en.md 与 docs/principles/init_finalize.md 找到对应排障指引建链失败/卡在连 rank 0检查-ipport或SHMEM_UID_SESSION_ID指定地址的连通性与端口占用netstat -tuln | grep port可增大shm_init_timeout示例中为DEFAULT_TIMEOUT120实现上作为 Config Store 建链重试次数UID 握手失败确认全体 rank 的 UID 字节级一致、magic已广播finalize 卡住确认全体 PE 均已调用 finalize控制面 barrier 需要所有 PE 到达不可重复 init同一instance_id需先 finalize 再 init环境变量配置SHMEM_UID_SESSION_ID与SHMEM_UID_SOCK_IFNAME同时配置时只读前者都不配置时自动搜索可用网口若查询失败请手动指定网口详见 docs/debug/Troubleshooting_FAQs_en.md 中未配置 ip/port 自动搜索失败一节。七、与仓库其他资源的关联初始化原理文档docs/principles/init_finalize.md 从源码层面详解aclshmemx_init_attr的分步流程、Bootstrap 三种模式选择、超时参数与 finalize 顺序是理解本示例底层实现的第一手资料Config Store 控制面docs/principles/config_store_bootstrap.md 详细说明 Default/UID 模式下以 PE0 为中心的星型 TCP 建链、KV 协议与 barrier/allgather 实现环境变量说明docs/api/env_vars_intro_en.md 汇总了SHMEM_UID_SESSION_ID/SHMEM_UID_SOCK_IFNAME等初始化相关环境变量的格式与优先级多实例文档docs/principles/multi_instance.md 对应uid_multi/uid_multi_stress模式的实例端口与 team 限制说明快速入门docs/quickstart_en.md 提供了包括本用例在内的整体构建与运行流程公共头文件include/host/shmem_host_def.h、include/host/init/shmem_host_init.h 定义了初始化 flag、aclshmemx_init_attr_t与aclshmemx_get_uniqueid等接口签名。总而言之examples/init是通往 SHMEM 初始化机制最直接的入口单机场景下先跑通 default再分别用 mpi 与 uid 验证两种外部通信域集成方式需要多实例能力时使用uid_multi跨机部署时按模式分别准备-fpe/-ipportdefault或 hostfilempi/uid并牢记所有机器以相同 mode 编译这一硬性前提。【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库基于OpenSHMEM 标准协议实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考