CANN SHMEM 仓库文档与 API 索引实战指南：custom-ops 算子开发调试导航与 aclshmemx_init_attr 失败排障
CANN SHMEM 仓库文档与 API 索引实战指南custom-ops 算子开发调试导航与 aclshmemx_init_attr 失败排障【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库基于OpenSHMEM 标准协议实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem本文是面向昇腾平台 CANN SHMEM 内存通信库的文档与 API 索引 初始化排障实战指南。它以仓库内docs/、include/、examples/等官方资源为主干为生成、调试、优化 custom-ops 算子提供权威参考路径定位并给出aclshmemx_init_attr初始化失败时的完整日志采集与根因排查流程。读完本文你将能快速定位 SHMEM 调试、API 原理、头文件签名与示例代码在仓库中的准确位置并独立完成一次aclshmemx_init_attr失败问题的日志定位与常见根因处置。1. 文档定位与使用前提本指南以.agents/skills/shmem-ops-compile-debug/references/shmem-repo-docs-index.md为骨架。该索引表是 skill 侧为算子开发custom-ops提供的导航图其核心约定如下SHMEM 仓原生路径为准生成、调试、优化算子时引用的 SHMEM API 与官方文档一律以 SHMEM 仓库内docs/、include/构建安装后为install/shmem/include/、examples/下的实际文件为准不要使用 skill 树内其他文件代替。docs/只读仓内docs/为官方文档仅供 Read 引用Agent 不得修改。技能侧补充内容写在 skill 树内如.agents/skills/shmem-ops-compile-debug/references/log-debug.md、debug.md、dump-debug.md。路径规范skill 不一定位于 SHMEM 仓内。读取下表任何文档前必须先按.agents/skills/shmem-ops-dev/references/shmem-repo-resolution.md定位SHMEM_REPO再以${SHMEM_REPO}/仓内路径的完整路径读取禁止使用 skill 文件相对路径如../../../../docs/...链接仓内文档。交付物边界custom-ops/是 skill 生成的交付物不在本索引表内其规范见.agents/skills/shmem-ops-compile-debug/references/custom-ops-entrypoints.md与env-setup.snippet.md。2. 调试文档索引docs/debug/初始化、运行或性能问题出现时按下表定位对应文档仓内路径用途可参考时机docs/debug/log_debug.mdSHMEM 日志环境变量、格式、bootstrap/init 阶段日志解读aclshmemx_init_attr失败、输出全 0、端口/bootstrap 问题docs/debug/Troubleshooting_FAQs.md对称内存分配、local_mem_size、使用限制malloc 异常、精度错、init 参数不一致docs/debug/dump_debug.mdDevice DumpTensor/printfKernel 侧数据/同步异常docs/debug/profiling.md性能 profiling性能评估阶段docs/debug/tools_debug.md调试工具需配合 CANN 工具链时2.1 日志环境变量定位问题的基础aclshmemx_init_attr失败排查的第一步是打开日志。根据 docs/debug/log_debug.mdSHMEM 日志由三个环境变量控制SHMEM_LOG_LEVEL设置日志等级严重程度从低到高为DEBUG、INFO、WARN、ERROR、FATAL。默认为ERROR调试时建议设为DEBUG或INFO。SHMEM_LOG_TO_STDOUT是否输出到控制台0关闭、1开启。默认关闭日志会存储到默认路径或指定路径开启后日志打印到控制台不再落盘。SHMEM_LOG_PATH日志保存路径需为合法路径。不设置时默认存到${HOME}/shmem/log。一条完整的 SHMEM 日志通常包含时间、日志级别、进程号、日志模块、日志文件、日志所在行号、日志信息。以初始化阶段的日志为例docs/debug/images/log/0.png 展示了标准字段构成与关键输出如bootstrap plugin initialized successfully、Transport unable to load aclshmem_transport_rdma.so等错误信息同样遵循该格式日志阅读的关键观察点见 docs/debug/images/log/1.png初始化阶段会先报出 bootstrap 使用的 flag如ACLSHMEMX_INIT_WITH_DEFAULT随后开始 bootstrap 初始化并检测环境变量设置情况如SHMEM_UID_SESSION_ID未设置bootstrap 过程中涉及多个 socket 的创建与使用socket 信息会体现在日志中开启 DEBUG 级别可获得更详细但数量较大的信息bootstrap 成功、初始化成功、去初始化成功后均有专门日志打印并标明 PE 号。适用范围说明SHMEM 日志当前主要提供 host 侧定位能力device 侧如算子内部发生报错时可能无法仅凭 SHMEM 日志定位需配合 CANN 或相关工具日志联合排查。2.2 日志阅读示例一次完整的初始化周期以初始化两个 PE 后再去初始化为例docs/debug/log_debug.md 中的样例均为 INFO 级别重点关注日志信息部分时间、级别、进程号不做专门解读初始化阶段首先打印 bootstrap flag如ACLSHMEMX_INIT_WITH_DEFAULT然后进入 bootstrap 初始化并检测环境变量SHMEM 存在 root 0 节点。单机环境下 root 0 可使用回环地址但集群环境这样设置是错误的。初始化过程会报出当前 root 0remote address是否为回环地址若 root 0 为回环则默认单机环境当前 PE 也可使用回环地址当前 PE 的 IP 信息会在netifaddr中报出bootstrap 成功后、初始化成功后、去初始化成功后均有专门日志日志中会标明 PE 号。3. API 与原理文档索引docs/api/、docs/理解接口行为与选型时查阅以下文档仓内路径用途docs/api/env_vars_intro.mdSHMEM_UID_SESSION_ID、SHMEM_INSTANCE_PORT_RANGE等环境变量docs/api/stream_api_usage.mdStream init_attr 用法docs/api/atomic_api_sync_async_comparison.md原子/sync/async API 选型docs/principles/init_finalize.mdaclshmemx_init_attr初始化流程与状态docs/glossary.md术语表docs/compilation_build_guide.md编译构建docs/deployment/shmem_so_library_dependencies.mdbootstrap 插件部署docs/example/example.md各 bootstrap 模式示例docs/quickstart.md快速上手注索引原稿中docs/principles.md在仓库中实际对应docs/principles/目录含 init_finalize.md、config_store_bootstrap.md、multi_instance.md、team.md初始化流程相关内容以该目录内文档为准。3.1 与排障强相关的环境变量速查根据 docs/api/env_vars_intro.mdaclshmemx_init_attr失败排障中最常涉及的环境变量有初始化相关SHMEM_UID_SESSION_ID直接指定 PE 0 监听 socket 的 IP 和端口支持三种格式IPv4 字面量ip:port如SHMEM_UID_SESSION_ID192.168.1.100:1234IPv6 字面量[ip]:port如SHMEM_UID_SESSION_ID[::1]:886主机名hostname:port如SHMEM_UID_SESSION_IDmy-server:5555通过系统名称解析服务解析为实际 IPSHMEM_UID_SOCK_IFNAME指定 PE 0 监听 socket 的网口名和网络层协议网口名 协议ifname:inet4|inet6如enpxxxx:inet4取 IPv4、enpxxxx:inet6取 IPv6仅网口名ifname自动探测可用协议优先 IPv4如eth0两个变量同时配置时只读取SHMEM_UID_SESSION_ID均未配置时自动搜索可用网口IPv4/IPv6 均可跳过 lo/docker/veth/br-/virbr/tun/tap 等虚拟接口搜索失败时会在日志中报错见 docs/debug/images/trouble-shooting/session_id_sock_ifnam_not_set.png。多实例相关SHMEM_INSTANCE_PORT_RANGE直接指定可用端口范围如export SHMEM_INSTANCE_PORT_RANGE1024:2047。每个实例有独立的 bootstrap需提供一个可用端口default 模式下每个初始化实例独占端口端口被占用期间不支持再次初始化。日志与 Profiling 相关SHMEM_CYCLE_PROF_PE指定进行 Profiling 采集的 PE范围[0, PEs-1]取消采集用unset SHMEM_CYCLE_PROF_PE。日志相关环境变量见 docs/debug/log_debug.md。4. 头文件与接口说明include/ 与 install/shmem/include/构建并执行source ${SHMEM_REPO}/install/set_env.sh后安装目录下的头文件可作为API 参考真源仓内路径用途install/shmem/include/shmem.hHost/Device 入口、生命周期install/shmem/include/host/Host 侧 RMA、bootstrap、teaminstall/shmem/include/device/Device 侧 gm2gm、sync、MTE/RDMA/SDMAinstall/shmem/include/utils/prof、工具头代码生成时API 选型建议与上述头文件签名保持一致不确定时可在仓库内搜索install/shmem/include或直接阅读对应.hpp。源码侧镜像未执行安装时头文件与实现的源码镜像位于仓库的 include/ 与 src/ 目录例如设备侧引擎头文件 include/device/gm2gm/engine/MTE/RDMA/SDMA/UDMA 引擎与 include/device/gm2gm/shmem_device_rma.hHost 侧初始化与数据结构 src/host/init/、src/host/shmemi_host_def.h公共类型定义 include/host_device/shmem_common_types.h。5. 示例代码索引examples/仓内路径用途examples/allgather/allgather_kernel.cppsender/receiver 分核、per-chunk signalexamples/multi_instance/端口与 instance_idexamples/*/CMakeLists.txt、scripts/run.sh构建与多 PE 启动examples/torch_binding/Torch CustomClass 参考examples/python_extension/torch_test/多 PE Python 测试参考custom-ops 默认作为独立工程构建仅当设计明确要求 in-tree 时才对照${SHMEM_REPO}/examples/修改根 CMake。各示例的构建入口可参考 scripts/build.sh 与 examples/CMakeLists.txt。6. aclshmemx_init_attr 失败排障实战aclshmemx_init_attr失败是算子开发中最高频的初始化问题。按下述步骤定位。6.1 第一步定位 SHMEM_REPO 与参考文档按.agents/skills/shmem-ops-dev/references/shmem-repo-resolution.md定位SHMEM_REPORead${SHMEM_REPO}/docs/debug/log_debug.md对照 bootstrap/init 日志阶段执行下方日志采集。6.2 第二步开启日志并重跑export SHMEM_LOG_LEVELDEBUG export SHMEM_LOG_TO_STDOUT1 # 或落盘export SHMEM_LOG_PATH${HOME}/shmem/log参数说明SHMEM_LOG_LEVELDEBUG输出最详细信息含 socket 建连细节数量较大SHMEM_LOG_TO_STDOUT1将日志打印到控制台不再落盘若需落盘设置SHMEM_LOG_PATH指定目录默认${HOME}/shmem/log。6.3 第三步读取最新日志LOG_DIR${SHMEM_LOG_PATH:-$HOME/shmem/log} ls -lt ${LOG_DIR}/aclshmem_*.log 2/dev/null | head -5 grep -iE fail|error|address in use|bootstrap|AccStore|Memory Heap ${LOG_DIR}/aclshmem_*.log | tail -306.4 第四步常见根因 → 动作对照表日志/现象动作address in use清理残留进程如pkill -f build/bin/op|torch_test_scripts/run.sh动态配置IPPORT/SHMEM_UID_SESSION_IDlocal size diffs确保各 PE 的local_mem_size一致见 docs/debug/Troubleshooting_FAQs.mdMemory Heap Not Initializedinit 失败优先检查 bootstrap 与环境无日志确认已source ${SHMEM_REPO}/install/set_env.shbootstrap 插件与libshmem.so同目录6.5 常见根因的纵深解析结合 docs/debug/Troubleshooting_FAQs.md 与 docs/api/env_vars_intro.md对表中现象做源码级延伸①address in use绑定端口被占用错误日志特征address in use for bind listen on ...、ACC_LINK_ADDRESS_IN_USE、startup acc tcp server on port: ... already in use.、bind failed。排查步骤确认 IP 是否符合预期用netstat -tuln | grep 端口号检查端口是否被占用调整环境变量SHMEM_UID_SESSION_ID及实际执行文件所使用的 IP 与端口号。default 模式ACLSHMEMX_INIT_WITH_DEFAULT下每次初始化都会绑定一个独立端口多实例场景可设置SHMEM_INSTANCE_PORT_RANGEstart:end并将ip_port端口设为0如tcp://127.0.0.1:0框架按instance_id自动分配start_port instance_id单实例重复初始化场景须确保前一次finalize已释放端口。②local size diffs各 PE local_mem_size 不一致典型错误调用aclshmemx_set_attr_uniqueid_args对每个 PE 传入不同local_mem_size如(1024 pe * 2) * 1024 * 1024日志提示local size diffs。注意日志中实际分配大小与local_mem_size存在约6MB差异为 SHMEM 框架内部使用空间且local_mem_size按2MB对齐尝试其他大小如1025 * 1024 * 1024会出现不同错误信息。修正方式保证aclshmemx_init_attr_t初始化过程中每 PE 分配的local_mem_size大小一致。③ bootstrap 与初始化通信未配置SHMEM_UID_SESSION_ID/SHMEM_UID_SOCK_IFNAME时自动搜索网口失败日志见 docs/debug/images/trouble-shooting/session_id_sock_ifnam_not_set.png此时应手动配置上述环境变量配置示例见第 3.1 节。RDMA 场景下若配置HCCL_RDMA_TC范围[0, 255]需为 4 的整数倍默认 132与HCCL_RDMA_SL范围[0, 7]默认 4需保证与交换机端 TC/SL 配置一致否则可能丢包SL 还需与网卡 PFC 优先级保持一致。④ 无日志确认环境已source ${SHMEM_REPO}/install/set_env.sh且 bootstrap 插件libshmem_bootstrap_*.so与libshmem.so位于同一目录参见 docs/deployment/shmem_so_library_dependencies.md。7. 技能侧补充参考除仓内官方文档外skill 树内还提供配套摘要与执行契约可配合本文使用日志与调试摘要.agents/skills/shmem-ops-compile-debug/references/log-debug.md、dump-debug.md、debug.md完整排障表.agents/skills/shmem-ops-compile-debug/references/debug.md§4 与.agents/skills/shmem-ops-dev/references/agent-execution-contract.md§5。8. 小结本文以 SHMEM 仓库文档与 API 索引为主线完成了三层落地文档导航调试、API/原理、头文件、示例四大类资源的仓内定位、排障实战aclshmemx_init_attr失败的日志开启、日志读取与四类常见根因处置、源码印证include/、src/与 docs/debug/Troubleshooting_FAQs.md、docs/api/env_vars_intro.md 的环境变量细节。后续在生成、调试或优化 custom-ops 算子时可依据本文路径索引直接进入对应官方文档遇到初始化失败按第 6 节的四步流程即可在分钟级内完成定位。【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库基于OpenSHMEM 标准协议实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考