| feat:add A5 symmetric memory Co-authored-by: z00940303<zhangzhuopan@huawei.com> # message auto-generated for no-merge-commit merge: !2369 merge master into master feat:add A5 symmetric memory Created-by: zhangzhuopan Commit-by: z00940303 Merged-by: cann-robot Description: ## 描述 本 PR 实现 A5 对称内存控制面方案，支持用户通过 HcclCommSymWinRegister 注册对称窗口，并在 A5 next 通信域内完成窗口资源管理、延迟内存注册、memHandle 管理以及 UB/URMA 类 channel 建链时的 remoteMem 交换。 ### 背景 A3 对称内存基于 VMM/PA 映射模型：每个 rank 获取本端 paHandle，通过 SymmetricMemoryAgent 的 ring 交换机制获取其他 rank 的 PA 信息，并在本地预留的 stride * rankSize VA 空间中完成全 rank 映射。 A5 对称内存不走 A3 的 PA/VMM full-rank 映射路径，而是基于 A5 next 通信域已有的 channel 建链能力交换本端/远端内存信息。用户注册 symmetric window 时，host 侧只记录窗口区间并初始化 device 侧 window 结构；真正的本端内存注册延迟到 HcclChannelAcquire 阶段，在确认本次申请 UB/URMA 类 channel 后，将未注册的 symmetric window 注册到 CommMems，得到可参与建链交换的 HcclMemHandle。 后续算子调用 HcclChannelAcquire 创建 UB/URMA 类 channel 时，框架将 symmetric memory 的 memHandle 追加到 HcclChannelDesc，建链完成后通过 ChannelGetRemoteMem 获取远端 remoteMem + memTag，并按 memTag 回填到对应 window 的 remoteMems[remoteRank]，供 device 侧 HcclSymWinGetPeerPointer 根据 windowHandle + peerRank + offset 获取远端地址。实际 HccommWriteOnThread、HccommReadOnThread、HcommChannelNotifyRecordOnThread、HcommChannelNotifyWaitOnThread 由算子侧在拿到远端地址后自行调用。 ### 改动内容 1. A5 对称内存管理接入 next 通信域 CollComm - A5 DEV_TYPE_950 的 symmetric memory 初始化、window 注册、反注册、查询能力接入 CollComm。 - CollComm 创建 SymmetricMemoryMode::URMA 模式的 SymmetricMemory 对象。 - A5 依赖 A3 legacy 中已有的 SymmetricMemory 基础结构，但不反向引入 next 依赖，避免 A3 依赖 A5。 - 删除旧方案 callback 设计，避免 legacy SymmetricMemory 通过 callback 反向调用 next CollComm。 2. A3 / A5 对称内存逻辑分离 - A3/HCCS 继续走原有 EnsureInit -> Init -> GetMemoryInfo -> RegisterInternal -> AddSymmetricWindow 路径。 - A5/URMA 在 RegisterSymmetricMem 入口直接分流到 RegisterUrmaMode，不进入 EnsureInit，不预留 HCCS VA 空间。 - A3 使用 AddSymmetricWindow 保持原有行为。 - A5 使用新增 AddUrmaSymmetricWindow，单独完成地址区间排序、重叠校验和 window 插入，避免影响 A3 对称内存功能。 3. A5 symmetric window 注册流程 - HcclCommSymWinRegister 在 A5 通信域内转发到 CollComm::RegisterWindow。 - RegisterUrmaMode 使用用户传入的 ptr / size 作为 symmetric window 范围，不再额外调用 aclrtMemGetAddressRange 获取 base range。 - 注册时检查： - ptr 非空； - size 非 0； - 地址加 size 不溢出； - 与已有 A5 symmetric window 不重叠。 - 注册时仅记录本端窗口信息，不立即执行 CommRegMem。 - 为每个 window 初始化独立的 remoteMems[rankSize] 数组，并拷贝到 device 侧 SymmetricWindow 中。 - host 侧使用 remoteMemMap_[devWin][remoteRank] 保存远端内存，逻辑上支持多个 window、多个 remote rank 的二维映射关系。 4. A5 ChannelAcquire 阶段执行 symmetric memory 内存注册和 remoteMem 交换 - 在 HcclChannelAcquire 中检查本次申请的 channel 协议。 - 仅对以下 UB/URMA 类协议进入 symmetric memory 处理： - COMM_PROTOCOL_UBC_CTP - COMM_PROTOCOL_UBC_TP - COMM_PROTOCOL_UBOE - 通过 CollComm::RegisterPendingSymmetricMemHandles 查询通信域内尚未注册到 CommMems 的 symmetric window。 - 对未注册 window 执行 CommRegMem，生成内部 memTag 和 HcclMemHandle。 - 将 symmetric memHandles 追加到 HcclChannelDesc::memHandles，并对已有 handle 做去重。 - CreateChannels 成功后，通过 MyRank::ChannelGetRemoteMem 获取远端 remoteMems + memTags。 - 根据完整 memTag 精确匹配对应 symmetric window，并回填 remoteMems[remoteRank] 到 host/device 两侧 window 结构。 5. symmetric memory memTag 生成和校验增强 - 内部 symmetric memory tag 使用固定关键字前缀：__hccl_sym_win__。 - tag 不依赖本地自增 winId，改为由 prefix + commId + addr + size 生成，避免不同 rank 注册顺序不一致导致错误匹配。 - 普通用户 HcclCommMemReg 禁止使用 symmetric memory 内部前缀，避免用户 memTag 与内部 memTag 冲突。 - remoteMem 回填时校验： - memTag 必须能匹配到本地已注册 window； - 远端 remoteMem.addr 非空； - 远端 remoteMem.size 非 0； - 远端 remoteMem.size 必须等于本地 window 的 userSize。 - 如果某个 symmetric window 在当前 remoteRank 的 memTags 中匹配不到，返回错误，用于拦截各 rank 注册窗口不一致的异常场景。 6. device 侧 remote pointer 查询 - HcclSymWinGetPeerPointer 支持 A5/URMA 模式。 - URMA 模式下，根据 windowHandle + peerRank + offset 查询 remoteMems[peerRank]，并返回 remoteMem.addr + offset。 - device 侧接口只负责 remote pointer 查询，不负责执行 write/read/notify/wait。 - 算子侧拿到 remote pointer 后，自行调用： - HccommWriteOnThread - HccommReadOnThread - HcommChannelNotifyRecordOnThread - HcommChannelNotifyWaitOnThread 7. API 层按 A3/A5 分流 - HcclCommSymWinRegister - HcclCommSymWinDeregister - HcclCommSymWinGet 对 A5 IsCommunicatorV2() 通信域，转发到 CollComm；非 A5 通信域继续走原有 hcclComm -> HcclCommunicator 路径。 8. 资源释放和异常处理 - HcclCommSymWinDeregister 释放 window、remoteMems、mem registration 等资源。 - CollComm::DeregisterWindow 在 window 已注册到 CommMems 时执行 CommUnregMem。 - RegisterPendingSymmetricMemHandles 中途失败时，回滚本次已经注册成功的 symmetric memory resource。 - SymmetricMemory 析构时先收集 winHandle，再逐个反注册，避免遍历 windowMap_ 过程中擦除 map 导致迭代器失效。 - 单 rank 场景通过构造函数初始化 isSingleRank_，保证 A3/A5 都能正确识别单 P。 ### 关键设计说明 - A5/URMA 不走 A3 EnsureInit / Init，不预留 HCCS VA，不使用 SymmetricMemoryAgent 做 PA ring 交换。 - A5 注册 symmetric window 时只记录窗口和初始化 remoteMems，实际 CommRegMem 延迟到 HcclChannelAcquire。 - remoteMem 不是全局一维数组，而是通过 remoteMemMap_[devWin][remoteRank] 形成逻辑二维结构，支持同一 remote rank 下多个 symmetric window。 - A3 和 A5 的 window 插入逻辑拆分为 AddSymmetricWindow 和 AddUrmaSymmetricWindow，避免 A5 地址重叠校验影响 A3 行为。 - 本 PR 不修改 DFX task exception、cluster monitor 等与 A5 对称内存时序无关的逻辑。 ## 变更类型 请选择本次引入的变更类型： - [ ] 🐛 Bug修复 - [x] ✨ 新特性 - [ ] 🚀 性能优化 - [ ] 📝 文档更新 - [ ] 📋 其他，请描述： ## 关联的Issue NA ## 测试 已完成的测试用例和场景： - 已完成代码静态扫查： - 确认无冲突标记残留； - 确认旧的 symmetric memory 自增 winId tag 逻辑已移除； - git diff --check 未发现 whitespace error。 - 已完成本地代码路径检查： - A5 HcclCommSymWinRegister/Deregister/Get 分流到 CollComm； - HcclChannelAcquire 对 UB/URMA 类 channel 自动追加 symmetric memHandles； - remoteMem 按 symmetric memory memTag 精确匹配并回填； - 用户 HcclCommMemReg 禁止使用内部 symmetric memory tag 前缀。 补充的UT用例： - A5 symmetric memory 注册窗口成功，生成带 __hccl_sym_win__ 前缀的内部 memTag。 - 用户 HcclCommMemReg 使用 __hccl_sym_win__ 前缀时返回参数错误。 - 注册多个 symmetric window 时，memTag 根据 commId + addr + size 区分，不依赖本地自增顺序。 - ChannelAcquire 时 UB/URMA 类 channel 自动追加 symmetric memHandles。 - remoteMem 回填时： - memTag 匹配成功，正确更新对应 window 的 remoteMems[remoteRank]； - remoteRank 缺少对应 symmetric memTag 时返回错误； - remoteMem size 与本地 window size 不一致时返回错误。 - SymmetricMemory 析构时多 window 反注册不触发 map 迭代器失效。 ## 文档更新 NA ## 合入检查 - [x] 🧐 已经详细阅读了贡献指南（CONTRIBUTING.md），并遵守了其中的所有规定，包括但不限于commit message的格式、无效commit的合并等 - [x] 🔍 邀请 committer评论/lgtm前的必要检查 - [x] 🏷️ 标题中使用了合适的类型标签（如：[feat], [fix]） - [x] 📄 代码修改内容已简要描述，相关文档已更新 - [x] 📝 代码注释已更新，代码遵循项目整体代码风格 - [x] 🧪 代码UT测试已更新，覆盖率已达标 - [x] 🔬 验证方法已更新到"测试"部分 - [x] 🛠️ 代码已通过静态分析工具检查，无错误 - [x] 👥 代码检视/code review/同行评议和必要的代码串讲，确保代码质量 - [x] ✅ 代码检视意见已处理或答复，无未处理的检视意见 - [ ] 🚀 预约 前冒烟 用例前的必要检查 - [ ] ✔️ 代码已有committer的/lgtm 和 模块committer的/lgtm评论 - [ ] 🔧 代码已通过compile，编译无错误，无告警 - [ ] 🖥️ 代码已通过基本功能本地测试或者在线测试，确保基本功能正常 - [ ] 🎯 预约 approver评论/approve，正式合入前的必要检查 - [ ] 📊 前冒烟 用例已全量通过 - [ ] 📦 新增功能已同步补充基本功能测试用例到前冒烟里 See merge request: cann/hcomm!2369 | 6 天前 |
