Pull Request has been successfully merged by CANN-robot.
（Thank you for ting010's contribution.）
变更摘要
本 PR 为 CCU 新增 Variable/Event 资源的预约（Alloc）与地址暴露（AddrGet）接口：新增 HcommCcuVariableAlloc / HcommCcuEventAlloc / HcommCcuVariableAddrGet / HcommCcuEventAddrGet 四个 C 接口，并配套新增资源管理器 CcuVarEventResMgr 负责从资源仓库按 dieId/type 分配连续资源块、缓存每个资源映射出的进程可访问 VA，以及按句柄/实例释放回收；同时扩展了 CreateByAcquire 系列接口（C 层、CcuKernel 层与上层 ccu::Variable / ccu::Event / ccu::Array<T> 封装），使预约句柄可按索引派生实际资源句柄。该改动还涉及 CCU 实例生命周期（CcuInstance 析构与 Reset）对预约资源的回收/排除处理，以及对应的 UT 用例和 runtime 桩修改。
主要改动
- 新增资源预约与地址暴露 C 接口：在
ccu_res.h中声明HcommCcuVariableAlloc/HcommCcuEventAlloc/HcommCcuVariableAddrGet/HcommCcuEventAddrGet，实现在ccu_launch.cc中通过CcuVarEventResMgr::Acquire预约资源，并调用CcuMapDevResAddress（基于rtGetDevResAddress）逐个注册进程可访问 VA，失败时回滚（unmap 已映射资源并归还资源池）；地址查询接口从管理器读取已保存的 VA。 - 新增资源管理器
CcuVarEventResMgr：新增ccu_var_event_res_mgr.h/.cc，按CcuVarEventType（VARIABLE/EVENT）从资源仓库的continuousXn/cke池分配连续资源块，维护 handle 到资源（dieId、起止 id、VA 列表）的映射，提供Acquire/GetVariableXnId/GetEventCkeId/SaveAddrs/GetSavedAddr/ReleaseByHandle/ReleaseByInstance/ExcludeAllocatedFromRepo，并在释放前通过rtReleaseDevResAddress解除已映射 VA。 - 新增 CreateByAcquire 派生接口：
ccu_primitives_impl.h/.cc增加CcuVariableCreateByAcquire/CcuEventCreateByAcquire，CcuKernel增加对应实现，通过预约句柄与 index 解析出 xnId/ckeId 后创建实际子句柄。 - 上层封装扩展：
ccu::Array<T>新增以 acquire 句柄和数量构造的构造函数（逐个CreateByAcquire并填充句柄，任一失败则析构已构造元素并抛出CcuException）；ccu::Variable与ccu::Event新增(acquireHandle, index)构造函数。 - 实例生命周期与测试配套：
CcuInstance新增SetHandle记录insHandle_，并在析构时通过ReleaseByInstance释放资源、在Reset时通过ExcludeAllocatedFromRepo从仓库排除已预约资源；新增ccu_var_acquire_demo.h演示内核及两个 UT 用例（覆盖连续分配、地址获取、越界 index 失败等场景），并修改rtGetDevResAddress桩以返回按 resId 偏移的合成地址。
Thanks for your pull-request.
The full list of commands accepted by me can be found at here。
You can get sig-info at here
PR Approval Progress
✅ Congratulations! All modules have met the lgtm and approve requirements.
Module Approval Details
| module | lgtm status | approve status |
|---|---|---|
| include | ✅ yanzhenghang, hulk1997 (2/2) | ✅ yanzhenghang (1/1) |
| pkg_inc | ✅ yanzhenghang, hulk1997 (2/2) | ✅ yanzhenghang (1/1) |
| src/base_comm | ✅ Innoecho, hulk1997 (2/2) | ✅ Innoecho (1/1) |
| test | ✅ Innoecho, hulk1997 (2/2) | ✅ Innoecho (1/1) |
💡 Tip:
- Committer can comment
/approveor/lgtm- Commenting
/approveimplies both code review (lgtm) and intent to merge (approve)
CLA Signature Pass
ting010, thanks for your pull request. All authors of the commits have signed the CLA. 👍
Something went wrong during merge: All discussions should be resolved.
If you want to solve this problem, you can click here to do it in the FAQs.
[LOW] GetInstance 边界检查逻辑可简化
问题分析：
- 第 31 行：
if (devLogicId < 0 || static_cast<uint32_t>(devLogicId) >= MAX_MODULE_DEVICE_NUM) - 这个逻辑是正确的（负值不会被 cast 掩盖），但
static_cast<uint32_t>的使用略显复杂 - 可读性稍差，且容易让人误以为负值会有问题
建议修复：
简化为更直观的表达方式，或保持原样（这是代码风格问题，不影响功能）。
src/base_comm/resources/ccu/ccu_instance/ccu_var_event_res_mgr.cc:31
[LOW] Array 构造函数错误路径字符串拼接可优化
问题分析：
- 第 97-99 行：使用
+操作符拼接字符串，会产生多个临时对象
std::string errMsg = "Array creation failed at index " + std::to_string(i) +
", requested count=" + std::to_string(count) +
"; the acquire handle likely holds fewer resources than count";
- 这在错误路径（很少发生）上影响很小，但可使用更高效的方式
建议修复：
使用 std::ostringstream 或 fmt::format（如果可用）优化字符串拼接。
说明：这是微优化，在错误路径上影响不大。
include/ccu/ccu_array.hpp:97
描述
改动原因：CCU 的 Variable（对应硬件 XN 标量寄存器）与 Event（对应硬件 CKE 完成事件位）此前只能在 kernel 注册期由 kernel 内部自行申请，资源 id 与设备地址对外不可见。由此产生两个限制：一是 host 侧无法预先规划资源布局；二是同一批资源无法在多个 kernel 之间共享，跨 kernel 的算子融合缺少可寻址的共享状态。
所采取的方法：在控制面新增"资源预约 + 地址暴露"能力，并让 kernel 侧可以按句柄复用已预约的资源。改动分四部分：
1. 控制面新增 4 个 C 接口（声明在
include/ccu/ccu_res.h，实现在src/framework/next/comms/api_c_adpt/ccu/ccu_launch.cc）HcommCcuVariableAlloc(insHandle, dieId, num, &varHandle)HcommCcuEventAlloc(insHandle, dieId, num, &eventHandle)HcommCcuVariableAddrGet(varHandle, index, &va)HcommCcuEventAddrGet(eventHandle, index, &va)2. 新增资源管理器
CcuVarEventResMgr（src/framework/next/comms/ccu/ccu_instance/ccu_var_event_res_mgr.{h,cc}，per-device 单例）以
{startId, num}连续块的形式记录每次预约的结果，并保存每个资源对应的设备地址，供AddrGet按 index 查询。资源随CcuInstance销毁而释放。3. kernel 侧新增按预约句柄取用的构造路径
CcuVariableCreateByAcquire(acqHandle, index, &handle)/CcuEventCreateByAcquire(acqHandle, index, &handle)（声明在pkg_inc/hcomm/ccu/ccu_primitives_impl.h）从预约句柄按 index 取出 XN / CKE 构造 IR 对象，不再重复申请。4. C++ wrapper 同步扩展（
include/ccu/）新增
ccu::Variable(varHandle, index)与ccu::Event(acqHandle, index)构造函数；ccu::Array<Variable>/ccu::Array<Event>支持从预约句柄批量构造，句柄内资源数量不足时抛CcuException并回滚已构造元素，避免半构造对象泄漏。兼容性：本次改动全部为新增接口与新增文件，未修改任何已有接口的签名与行为，对存量算子无影响。
变更类型
请选择本次引入的变更类型：
关联的Issue
NA（本次为 CCU 算子融合特性的能力补齐，未关联独立 Issue）
测试
已完成的测试用例和场景：
接口级正反向验证 ——
HcommCcuControlApiTest.Ut_HcommCcuVariableAndEventAllocAddrGet_When_AllFine_Expect_ReturnCcuSUCCESSAddrGet均返回CCU_SUCCESS且地址非 0；index == num（越界）调用HcommCcuVariableAddrGet/HcommCcuEventAddrGet，均返回非CCU_SUCCESS，并打印index out of range错误日志；CcuVarEventResMgr中记录的资源总数与申请数一致；HcommCcuInsDestroyLegacy收尾，验证资源正常回收。预约资源在 kernel 中可用的端到端验证 ——
HcommCcuControlApiTest.Ut_HcommCcuVariableAllocConsecutive_When_AllFine_Expect_ReturnCcuSUCCESSCcuVarEventResMgr中记录为单个连续块（resInfos.size() == 1），块内 id 连续、总数与申请数一致；AddrGet返回的地址按 4KB 步进连续递增（实测 Variable0x100090000 ~ 0x100099000，Event0x1000e0000 ~ 0x1000e3000）；ccu_var_acquire_demo，在 kernel 内用ccu::Array<ccu::Variable>(acqHandle, num)/ccu::Array<ccu::Event>(acqHandle, num)从预约句柄批量构造并做赋值、累加、EventRecord/EventWait，经HcommCcuKernelRegister+HcommCcuKernelRegisterEnd完整走通注册与翻译流程。存量用例回归 ——
hccl_utest_comms_ccu_features全量执行，16 个 test suite 共 208 条用例全部通过，无新增失败。验证方法（本地执行）：
cd <repo> && sh build.sh -u --noclean ./build_ut/test/ut/framework/next/comms/ccu/hccl_utest_comms_ccu_features \ --gtest_filter='HcommCcuControlApiTest.Ut_HcommCcuVariable*' # [ PASSED ] 2 tests. ./build_ut/test/ut/framework/next/comms/ccu/hccl_utest_comms_ccu_features # [==========] 208 tests from 16 test suites ran. (166 ms total) # [ PASSED ] 208 tests.补充的UT用例：
test/ut/framework/next/comms/ccu/ut_HcommCcuControlApi_test.cc：新增上述 2 条TEST_F。test/ut/framework/next/comms/ccu/ccu_kernel_impl/ccu_var_acquire_demo.h：新增示例 kernelCcuVarAcquireDemoKernel。test/ut/stub/llt_hccl_stub_rts.cc：补充预约路径依赖的 rts 打桩。文档更新
本次未涉及 README / 独立设计文档更新。新增的 4 个控制面 C 接口的语义、参数与越界返回约定已在本 PR 描述的接口表中说明。
合入检查