Star551
1026
代码
代码
Issues99
Pull Requests396
Actions
项目讨论
Wiki
分析
Star551
1026
已合并
[Docs] 优化 docs 资料 #3918
Yuanhao Ji创建于 7月21日
[Docs] 优化 docs 资料 #3918
已合并
Yuanhao Ji创建于 7月21日
从jiyuanhao/hcommdocs/misc合入到cann/hcommmaster
共 106 个文件变更+678-296
M.gitignore+1-0
@@ -36,6 +36,7 @@ __pycache__/
36.omo/36.omo/
37.claude/37.claude/
38.opencode/38.opencode/
39+.codegraph/
39CLAUDE.md40CLAUDE.md
40AGENTS.local.md41AGENTS.local.md
41 42 
MREADME.md+3-1
@@ -37,8 +37,9 @@ HCOMM通信基础库采用分层解耦的设计思路，将通信能力划分为
37│ │ ├── api_c_adpt # C接口适配37│ │ ├── api_c_adpt # C接口适配
38│ │ ├── common # 集合通信层公共基础功能目录38│ │ ├── common # 集合通信层公共基础功能目录
39│ │ ├── communicator # 通信域39│ │ ├── communicator # 通信域
40+│ │ ├── config_mgr # 配置管理
40│ │ ├── dfx # 维测41│ │ ├── dfx # 维测
41-│ │ ├── rank_graphs # 拓扑管理42+│ │ ├── rank_graph # 拓扑管理
42│ │ └── resource_mgr # 资源管理43│ │ └── resource_mgr # 资源管理
43│ └── legacy # 历史版本兼容目录44│ └── legacy # 历史版本兼容目录
44│ ├── ascend910 # A2&A3兼容代码45│ ├── ascend910 # A2&A3兼容代码
@@ -59,6 +60,7 @@ HCOMM通信基础库采用分层解耦的设计思路，将通信能力划分为
59├── python # Python 包60├── python # Python 包
60├── include # 对外头文件61├── include # 对外头文件
61├── pkg_inc # 包间接口头文件62├── pkg_inc # 包间接口头文件
63+├── experimental # 社区贡献的试验性代码目录
62├── test # 测试代码目录64├── test # 测试代码目录
63│ ├── ut # 单元测试代码目录65│ ├── ut # 单元测试代码目录
64│ └── st # 系统测试代码目录66│ └── st # 系统测试代码目录
MREADME_en.md+3-1
@@ -37,8 +37,9 @@ The key directories of this project are as follows:
37│ │ ├── api_c_adpt # C interface adaptation37│ │ ├── api_c_adpt # C interface adaptation
38│ │ ├── common # Common basic functionality for the collective communication layer38│ │ ├── common # Common basic functionality for the collective communication layer
39│ │ ├── communicator # Communication domain39│ │ ├── communicator # Communication domain
40+│ │ ├── config_mgr # Configuration management
40│ │ ├── dfx # Diagnostics and tracing41│ │ ├── dfx # Diagnostics and tracing
41-│ │ ├── rank_graphs # Topology management42+│ │ ├── rank_graph # Topology management
42│ │ └── resource_mgr # Resource management43│ │ └── resource_mgr # Resource management
43│ └── legacy # Historical version compatibility directory44│ └── legacy # Historical version compatibility directory
44│ ├── ascend910 # A2 and A3 compatibility code45│ ├── ascend910 # A2 and A3 compatibility code
@@ -59,6 +60,7 @@ The key directories of this project are as follows:
59├── python # Python package60├── python # Python package
60├── include # External header files61├── include # External header files
61├── pkg_inc # Inter-package interface header files62├── pkg_inc # Inter-package interface header files
63+├── experimental # Community-contributed experimental code directory
62├── test # Test code directory64├── test # Test code directory
63│ ├── ut # Unit test code directory65│ ├── ut # Unit test code directory
64│ └── st # System test code directory66│ └── st # System test code directory
Mblacklist.txt+0-1
@@ -48,7 +48,6 @@ src/base_comm/resources/endpoint_pairs/channels/aicpu/aicpu_ts_p2p_channel.cc
48src/base_comm/resources/endpoint_pairs/channels/channel.cc48src/base_comm/resources/endpoint_pairs/channels/channel.cc
49src/base_comm/common/orion_adpt_utils.cc49src/base_comm/common/orion_adpt_utils.cc
50src/coll_communicator_mgr/dfx/taskException/host/hcclCommTaskException.cc50src/coll_communicator_mgr/dfx/taskException/host/hcclCommTaskException.cc
51-src/common/launch_aicpu/launch_aicpu.cc
52src/legacy/ascend910/algorithm/impl/hccl_alg_device.cc51src/legacy/ascend910/algorithm/impl/hccl_alg_device.cc
53src/legacy/ascend910/algorithm/impl/hccl_alg.cc52src/legacy/ascend910/algorithm/impl/hccl_alg.cc
54src/legacy/ascend910/algorithm/impl/operator/all_reduce_operator.cc53src/legacy/ascend910/algorithm/impl/operator/all_reduce_operator.cc
Mdocs/zh/api_ref/comm_mgr_c/HcclAicpuKernelLaunch.md+1-1
@@ -34,7 +34,7 @@ HcclResult HcclAicpuKernelLaunch(HcclComm comm, const HcclOpDesc *opInfo, const
34 34 
35| 参数名 | 输入/输出 | 描述 |35| 参数名 | 输入/输出 | 描述 |
36| --- | --- | --- |36| --- | --- | --- |
37-| comm | 输入 | 集合通信操作所在的通信域。 |37+| comm | 输入 | 集合通信操作所在的通信域。<br>HcclComm类型的定义可参见[HcclComm](./data_type_definition/HcclComm.md)。 |
38| opInfo | 输入 | 算子描述参数，包含算子类型和名称相关参数。<br>HcclOpDesc类型的定义可参见数据类型[HcclOpDesc](./data_type_definition/HcclOpDesc.md)。 |38| opInfo | 输入 | 算子描述参数，包含算子类型和名称相关参数。<br>HcclOpDesc类型的定义可参见数据类型[HcclOpDesc](./data_type_definition/HcclOpDesc.md)。 |
39| funcInfo | 输入 | 核函数信息，包含动态库名、函数名、参数及参数大小。<br>HcclKernelFuncInfo类型的定义可参见数据类型[HcclKernelFuncInfo](./data_type_definition/HcclKernelFuncInfo.md)。 |39| funcInfo | 输入 | 核函数信息，包含动态库名、函数名、参数及参数大小。<br>HcclKernelFuncInfo类型的定义可参见数据类型[HcclKernelFuncInfo](./data_type_definition/HcclKernelFuncInfo.md)。 |
40| aicpuThreadHandle | 输入 | AICPU通信主流线程句柄。<br>ThreadHandle类型的定义可参见[ThreadHandle](../comm_opdev/datatype_definition/ThreadHandle.md) |40| aicpuThreadHandle | 输入 | AICPU通信主流线程句柄。<br>ThreadHandle类型的定义可参见[ThreadHandle](../comm_opdev/datatype_definition/ThreadHandle.md) |
Mdocs/zh/api_ref/comm_mgr_c/HcclBarrier.md+1-1
@@ -32,7 +32,7 @@ HcclResult HcclBarrier(HcclComm comm, aclrtStream stream)
32 32 
33| 参数名 | 输入/输出 | 描述 |33| 参数名 | 输入/输出 | 描述 |
34| --- | --- | --- |34| --- | --- | --- |
35-| comm | 输入 | 集合通信操作所在的通信域。 |35+| comm | 输入 | 集合通信操作所在的通信域。<br>HcclComm类型的定义可参见[HcclComm](./data_type_definition/HcclComm.md)。 |
36| stream | 输入 | 本rank所使用的stream。 |36| stream | 输入 | 本rank所使用的stream。 |
37 37 
38## 返回值38## 返回值
Mdocs/zh/api_ref/comm_mgr_c/HcclCommActivateCommMemory.md+24-0
@@ -50,3 +50,27 @@ HcclResult HcclCommActivateCommMemory(HcclComm comm, void *virPtr, size_t size,
50 50 
51- 待激活的虚拟内存地址必须在[HcclCommSetMemoryRange](HcclCommSetMemoryRange.md)设置的地址范围内。51- 待激活的虚拟内存地址必须在[HcclCommSetMemoryRange](HcclCommSetMemoryRange.md)设置的地址范围内。
52- 该虚拟内存地址不能与已经激活的虚拟内存地址有重叠、交叠。52- 该虚拟内存地址不能与已经激活的虚拟内存地址有重叠、交叠。
53+ 
54+## 调用示例
55+ 
56+```c
57+// 假设已通过HcclCommSetMemoryRange设置了虚拟内存范围
58+// baseVirPtr为虚拟内存基地址
59+ 
60+// 申请物理内存
61+aclrtDrvMemHandle handle;
62+aclrtMallocPhysical(&handle, size, NULL, 0);
63+ 
64+// 将物理内存映射到虚拟内存
65+void *virPtr = baseVirPtr;
66+aclrtMapMem(virPtr, size, 0, handle, 0);
67+ 
68+// 激活预留的虚拟内存
69+HcclCommActivateCommMemory(hcclComm, virPtr, size, 0, handle, 0);
70+ 
71+// 后续可使用激活后的内存进行零拷贝通信
72+// ...
73+ 
74+// 反激活内存
75+HcclCommDeactivateCommMemory(hcclComm, virPtr);
76+```
Mdocs/zh/api_ref/comm_mgr_c/HcclCommConfigInit.md+2-1
@@ -57,7 +57,8 @@ HcclCommConfigInit(&config);
57// 按需修改通信域配置57// 按需修改通信域配置
58config.hcclBufferSize = 1024; // 共享数据的缓存区大小，单位为：MB，取值需 >= 1，默认值为：20058config.hcclBufferSize = 1024; // 共享数据的缓存区大小，单位为：MB，取值需 >= 1，默认值为：200
59config.hcclDeterministic = 1; // 开启归约类通信算子的确定性计算，默认值为：0，表示关闭确定性计算功能59config.hcclDeterministic = 1; // 开启归约类通信算子的确定性计算，默认值为：0，表示关闭确定性计算功能
60-std::strcpy(config.hcclCommName, "comm_1");60+strncpy(config.hcclCommName, "comm_1", COMM_NAME_MAX_LENGTH - 1);
61+config.hcclCommName[COMM_NAME_MAX_LENGTH - 1] = '\0';
61// 初始化集合通信域62// 初始化集合通信域
62HcclComm hcclComm;63HcclComm hcclComm;
63HCCLCHECK(HcclCommInitRootInfoConfig(rankSize, &rootInfo, deviceId, &config, &hcclComm));64HCCLCHECK(HcclCommInitRootInfoConfig(rankSize, &rootInfo, deviceId, &config, &hcclComm));
Mdocs/zh/api_ref/comm_mgr_c/HcclCommDeactivateCommMemory.md+12-0
@@ -45,3 +45,15 @@ HcclResult HcclCommDeactivateCommMemory(HcclComm comm, void *virPtr)
45## 约束说明45## 约束说明
46 46 
47无47无
48+ 
49+## 调用示例
50+ 
51+```c
52+// 假设virPtr为已通过HcclCommActivateCommMemory激活的虚拟内存地址
53+ 
54+// 反激活已激活的虚拟内存
55+HcclCommDeactivateCommMemory(hcclComm, virPtr);
56+ 
57+// 后续该地址无法再用于零拷贝通信
58+// 如需重新使用，需再次调用HcclCommActivateCommMemory激活
59+```
Mdocs/zh/api_ref/comm_mgr_c/HcclCommInitAll.md+1-1
@@ -25,7 +25,7 @@
25## 函数原型25## 函数原型
26 26 
27```c27```c
28-HcclResult HcclCommInitAll(uint32_t ndev, int32_t* devices, HcclComm* comms)28+HcclResult HcclCommInitAll(uint32_t ndev, int32_t* devices, HcclComm* comms)
29```29```
30 30 
31## 参数说明31## 参数说明
Mdocs/zh/api_ref/comm_mgr_c/HcclCommInitClusterInfo.md+2-2
@@ -22,7 +22,7 @@
22 22 
23基于rank table初始化HCCL，创建HCCL通信域。23基于rank table初始化HCCL，创建HCCL通信域。
24 24 
25-Rank table文件是一个JSON格式的文件，配置了参与集合通信的NPU资源信息，关于rank table文件的配置可参见[集群信息配置](https://gitcode.com/cann/hccl/blob/master/docs/zh/user_guide/cluster_info_config/README.md)。25+rank table文件是一个JSON格式的文件，配置了参与集合通信的NPU资源信息，关于rank table文件的配置可参见[集群信息配置](https://gitcode.com/cann/hccl/blob/master/docs/zh/user_guide/cluster_info_config/README.md)。
26 26 
27## 函数原型27## 函数原型
28 28 
@@ -34,7 +34,7 @@ HcclResult HcclCommInitClusterInfo(const char *clusterInfo, uint32_t rank, HcclC
34 34 
35| 参数名 | 输入/输出 | 描述 |35| 参数名 | 输入/输出 | 描述 |
36| --- | --- | --- |36| --- | --- | --- |
37-| clusterInfo | 输入 | Rank table的文件路径（含文件名），作为字符串最大长度为4096字节，含结束符。 |37+| clusterInfo | 输入 | rank table的文件路径（含文件名），作为字符串最大长度为4096字节，含结束符。 |
38| rank | 输入 | 本rank的id。<br>需要注意，此参数取值需要与rank table中对应的“rank_id”字段取值一致。 |38| rank | 输入 | 本rank的id。<br>需要注意，此参数取值需要与rank table中对应的“rank_id”字段取值一致。 |
39| comm | 输出 | 将初始化后的通信域以指针的信息回传给调用者。<br>HcclComm类型的定义可参见[HcclComm](./data_type_definition/HcclComm.md)。 |39| comm | 输出 | 将初始化后的通信域以指针的信息回传给调用者。<br>HcclComm类型的定义可参见[HcclComm](./data_type_definition/HcclComm.md)。 |
40 40 
Mdocs/zh/api_ref/comm_mgr_c/HcclCommInitClusterInfoConfig.md+2-1
@@ -61,7 +61,8 @@ HcclCommConfig config;
61HcclCommConfigInit(&config);61HcclCommConfigInit(&config);
62// 按需修改通信域配置62// 按需修改通信域配置
63config.hcclBufferSize = 50; // 共享数据的缓存区大小，单位为：MB，取值需 >= 1，默认值为：20063config.hcclBufferSize = 50; // 共享数据的缓存区大小，单位为：MB，取值需 >= 1，默认值为：200
64-std::strcpy(config.hcclCommName, "comm_1");64+strncpy(config.hcclCommName, "comm_1", COMM_NAME_MAX_LENGTH - 1);
65+config.hcclCommName[COMM_NAME_MAX_LENGTH - 1] = '\0';
65// 初始化通信域66// 初始化通信域
66HcclComm hcclComm;67HcclComm hcclComm;
67// 此样例以devId作为当前rank的rank id68// 此样例以devId作为当前rank的rank id
Mdocs/zh/api_ref/comm_mgr_c/HcclCommSetMemoryRange.md+29-0
@@ -51,3 +51,32 @@ HcclResult HcclCommSetMemoryRange(HcclComm comm, void *baseVirPtr, size_t size,
51- 该接口仅支持在范围是单Server的通信域内调用，否则会报错。51- 该接口仅支持在范围是单Server的通信域内调用，否则会报错。
52- 多次调用该接口时，输入的内存地址不能重复或存在区间交叠。52- 多次调用该接口时，输入的内存地址不能重复或存在区间交叠。
53- 其他约束请参见[通用约束](./zero_copy_readme.md)。53- 其他约束请参见[通用约束](./zero_copy_readme.md)。
54+ 
55+## 调用示例
56+ 
57+```c
58+// 设备资源初始化
59+aclInit(NULL);
60+aclrtSetDevice(devId);
61+ 
62+// 创建通信域
63+HcclComm hcclComm;
64+HcclRootInfo rootInfo;
65+HcclGetRootInfo(&rootInfo);
66+HcclCommInitRootInfo(8, &rootInfo, 0, &hcclComm);
67+ 
68+// 通过aclrtReserveMemAddress申请虚拟内存
69+void *baseVirPtr = NULL;
70+size_t size = 1024 * 1024 * 1024; // 1GB
71+aclrtReserveMemAddress(&baseVirPtr, size, 0, NULL, 0);
72+ 
73+// 通知HCCL预留的虚拟内存地址
74+HcclCommSetMemoryRange(hcclComm, baseVirPtr, size, 0, 0);
atomgit-bot
atomgit-botatomgit-bot7月28日

🟡 Medium Priority

新增的调用示例（第 59-74 行）中，多个关键 API 调用的返回值均未检查：aclInit（第 59 行）、aclrtSetDevice（第 60 行）、HcclGetRootInfo（第 65 行）、HcclCommInitRootInfo（第 66 行）、aclrtReserveMemAddress（第 71 行）、HcclCommSetMemoryRange（第 74 行）。若其中任一调用失败，后续操作将使用无效的资源或未初始化的数据。此问题在上轮审查中已被指出，但本次改动仍未修复。

建议：为每个关键 API 调用添加返回值检查，失败时进行错误处理和资源清理后再返回。可使用类似 if (aclInit(NULL) != ACL_SUCCESS) { return; } 的模式，或使用 HCCLCHECK/HCCL_CHK_RET 等宏。

likedislike
不准确？
75+ 
76+// 后续可调用HcclCommActivateCommMemory激活内存并使用零拷贝功能
77+// ...
78+ 
79+// 销毁通信域
80+HcclCommDestroy(hcclComm);
81+aclFinalize();
82+```
atomgit-bot
atomgit-botatomgit-bot7月22日

🟡 Medium Priority

新增的调用示例（第 58-82 行）中，多个关键 API 调用的返回值均未检查：aclInit（第 59 行）、aclrtSetDevice（第 60 行）、HcclGetRootInfo（第 65 行）、HcclCommInitRootInfo（第 66 行）、aclrtReserveMemAddress（第 71 行）、HcclCommSetMemoryRange（第 74 行）。若其中任一调用失败，后续代码将在错误状态下继续执行，可能导致资源泄漏、空指针解引用或未定义行为。例如 aclrtReserveMemAddress 失败时 baseVirPtr 仍为 NULL，传入 HcclCommSetMemoryRange 将导致错误。

建议：为每个关键 API 调用添加返回值检查，失败时进行错误处理和资源清理后再返回。

likedislike
不准确？
Mdocs/zh/api_ref/comm_mgr_c/HcclCommSuspend.md+24-0
@@ -47,3 +47,27 @@ HcclResult HcclCommSuspend(HcclComm comm)
47 47 
48- 本接口需要与[HcclCommResume](HcclCommResume.md)接口配对使用。48- 本接口需要与[HcclCommResume](HcclCommResume.md)接口配对使用。
49- 本接口不能与集合通信、点对点通信的相关接口并发执行。49- 本接口不能与集合通信、点对点通信的相关接口并发执行。
50+ 
51+## 调用示例
52+ 
53+```c
54+// 设备资源初始化
55+aclInit(NULL);
56+aclrtSetDevice(devId);
57+ 
58+// 创建通信域
59+HcclComm hcclComm;
60+HcclRootInfo rootInfo;
61+HcclGetRootInfo(&rootInfo);
62+HcclCommInitRootInfo(8, &rootInfo, 0, &hcclComm);
63+ 
64+// 检测到片上内存UCE故障后，挂起通信域
65+HcclCommSuspend(hcclComm);
66+ 
67+// 故障修复后，恢复通信域
68+HcclCommResume(hcclComm);
atomgit-botatomgit-bot
atomgit-botatomgit-bot7月21日

🟡 Medium Priority

变更行（新增的调用示例第 64-68 行）：HcclResult ret = HcclCommSuspend(hcclComm) 的返回值虽被捕获但未被检查，随后第 68 行无条件调用了 HcclCommResume(hcclComm)。若 HcclCommSuspend 调用失败（如通信域已处于异常状态），通信域并未进入挂起状态，此时调用 HcclCommResume 可能导致未定义行为或其他意外——该接口文档明确说明"本接口需要与 HcclCommResume 接口配对使用"，即只有在成功挂起后才应恢复。

修复方向：在调用 HcclCommResume 之前检查 HcclCommSuspend 的返回值，仅在返回 HCCL_SUCCESS 时才执行恢复操作。

建议：在 HcclCommSuspend 返回 HCCL_SUCCESS 时才调用 HcclCommResume，否则应进行错误处理而非恢复通信域。

likedislike
不准确？
atomgit-botatomgit-bot7月22日

🟡 Medium Priority

变更行（第 65-68 行）：HcclResult ret = HcclCommSuspend(hcclComm) 的返回值虽被捕获但未被检查，随后第 68 行无条件调用了 HcclCommResume(hcclComm)。若 HcclCommSuspend 调用失败（如通信域已处于异常状态），通信域并未进入挂起状态，此时调用 HcclCommResume 可能引发未定义行为或掩盖真实错误。此问题在上轮审查中已指出，但本次 diff 中未修复。

建议：在 HcclCommSuspend 返回 HCCL_SUCCESS 时才调用 HcclCommResume，否则应进行错误处理而非恢复通信域。

likedislike
不准确？
atomgit-botatomgit-bot7月22日

🟡 Medium Priority

变更行（新增的调用示例第 65-68 行）：HcclResult ret = HcclCommSuspend(hcclComm); 的返回值虽被捕获但未被检查，随后第 68 行无条件调用了 HcclCommResume(hcclComm)。若 HcclCommSuspend 调用失败（如通信域已处于异常状态），通信域并未进入挂起状态，此时调用 HcclCommResume 可能产生未预期的行为（如对未挂起的通信域执行恢复操作）。该接口的约束说明明确指出"需要与 HcclCommResume 接口配对使用"，这意味着二者应仅在成功挂起后才配对调用。

建议：在 HcclCommSuspend 返回 HCCL_SUCCESS 时才调用 HcclCommResume，否则应进行错误处理而非恢复通信域。

likedislike
不准确？
atomgit-botatomgit-bot7月28日

🟡 Medium Priority

变更行（第 65-68 行）：HcclResult ret = HcclCommSuspend(hcclComm) 的返回值虽被捕获但未被检查，随后第 68 行无条件调用了 HcclCommResume(hcclComm)。若 HcclCommSuspend 调用失败（如通信域已处于异常状态），通信域并未进入挂起状态，此时调用 HcclCommResume 可能产生未定义行为或错误的状态转换。此问题在上轮审查中已被指出，但本次改动仍未修复。

建议：在 HcclCommSuspend 返回 HCCL_SUCCESS 时才调用 HcclCommResume，否则应进行错误处理而非恢复通信域。示例：if (ret == HCCL_SUCCESS) { HcclCommResume(hcclComm); } else { /* 错误处理 */ }

likedislike
不准确？
69+ 
70+// 销毁通信域
71+HcclCommDestroy(hcclComm);
72+aclFinalize();
73+```
Mdocs/zh/api_ref/comm_mgr_c/HcclCommSymWinGet.md+1-1
@@ -39,7 +39,7 @@ HcclResult HcclCommSymWinGet(HcclComm comm, void *ptr, size_t size, HcclCommSymW
39 39 
40| 参数名 | 输入/输出 | 描述 |40| 参数名 | 输入/输出 | 描述 |
41| --- | --- | --- |41| --- | --- | --- |
42-| comm | 输入 | HCCL通信域。 |42+| comm | 输入 | HCCL通信域。<br>HcclComm类型的定义可参见[HcclComm](./data_type_definition/HcclComm.md)。 |
43| ptr | 输入 | 已注册对称内存的地址指针，该内存需要已使用[HcclCommSymWinRegister](HcclCommSymWinRegister.md)接口进行注册。<br>Atlas A3 训练系列产品/Atlas A3 推理系列产品的HCCS场景下，该地址为预留并完成物理内存映射的虚拟地址。<br>Ascend 950PR/Ascend 950DT的URMA场景下，该地址为已注册的Device内存地址。 |43| ptr | 输入 | 已注册对称内存的地址指针，该内存需要已使用[HcclCommSymWinRegister](HcclCommSymWinRegister.md)接口进行注册。<br>Atlas A3 训练系列产品/Atlas A3 推理系列产品的HCCS场景下，该地址为预留并完成物理内存映射的虚拟地址。<br>Ascend 950PR/Ascend 950DT的URMA场景下，该地址为已注册的Device内存地址。 |
44| size | 输入 | 对称内存窗口大小。<br>假设对称内存窗口大小为symSize，已注册对称内存的地址指针为addr，size需要满足以下条件：<br> - size > 0<br> - ptr+size <= addr + symSize |44| size | 输入 | 对称内存窗口大小。<br>假设对称内存窗口大小为symSize，已注册对称内存的地址指针为addr，size需要满足以下条件：<br> - size > 0<br> - ptr+size <= addr + symSize |
45| winHandle | 输出 | 指向“对称内存窗口资源句柄”的指针。 |45| winHandle | 输出 | 指向“对称内存窗口资源句柄”的指针。 |
Mdocs/zh/api_ref/comm_mgr_c/HcclCommUnsetMemoryRange.md+13-0
@@ -45,3 +45,16 @@ HcclResult HcclCommUnsetMemoryRange(HcclComm comm, void *baseVirPtr)
45## 约束说明45## 约束说明
46 46 
47如果本虚拟地址空间内仍存在激活的内存，此接口会执行失败。47如果本虚拟地址空间内仍存在激活的内存，此接口会执行失败。
48+ 
49+## 调用示例
50+ 
51+```c
52+// 假设已通过HcclCommSetMemoryRange设置了虚拟内存范围
53+// baseVirPtr为HcclCommSetMemoryRange传入的虚拟内存基地址
54+ 
55+// 确保该地址范围内所有已激活的内存均已反激活
56+// HcclCommDeactivateCommMemory(hcclComm, activatedVirPtr);
57+ 
58+// 取消预留的虚拟内存
59+HcclCommUnsetMemoryRange(hcclComm, baseVirPtr);
60+```
Mdocs/zh/api_ref/comm_mgr_c/HcclConfigGetInfo.md+1-1
@@ -34,7 +34,7 @@ HcclResult HcclConfigGetInfo(HcclComm comm, HcclConfigType cfgType, uint32_t inf
34 34 
35| 参数名 | 输入/输出 | 描述 |35| 参数名 | 输入/输出 | 描述 |
36| --- | --- | --- |36| --- | --- | --- |
37-| comm | 输入 | 通信域句柄。 |37+| comm | 输入 | 通信域句柄。<br>HcclComm类型的定义可参见[HcclComm](./data_type_definition/HcclComm.md)。 |
38| cfgType | 输入 | 需要查询的配置项类型，HcclConfigType的定义可参见[HcclConfigType](./data_type_definition/HcclConfigType.md)。 |38| cfgType | 输入 | 需要查询的配置项类型，HcclConfigType的定义可参见[HcclConfigType](./data_type_definition/HcclConfigType.md)。 |
39| infoLen | 输入 | 目标配置类型的大小（字节），必须等于待查询配置类型的实际大小。 |39| infoLen | 输入 | 目标配置类型的大小（字节），必须等于待查询配置类型的实际大小。 |
40| info | 输出 | 配置信息输出缓冲区，必须按目标配置类型对齐且可写。 |40| info | 输出 | 配置信息输出缓冲区，必须按目标配置类型对齐且可写。 |
Mdocs/zh/api_ref/comm_mgr_c/HcclCreateSubCommConfig.md+1-1
@@ -76,5 +76,5 @@ strcpy(config.hcclCommName, "comm_1");
76HcclComm hcclComm;76HcclComm hcclComm;
77uint32_t rankIds[4] = {0, 1, 2, 3}; // 子通信域的Rank列表77uint32_t rankIds[4] = {0, 1, 2, 3}; // 子通信域的Rank列表
78// 当前rank在子通信域中的rank id设置为078// 当前rank在子通信域中的rank id设置为0
79-HcclCreateSubCommConfig(&globalHcclComm, 4, rankIds, 1, 0, &config, &hcclComm); 79+HcclCreateSubCommConfig(&globalHcclComm, 4, rankIds, 1, 0, &config, &hcclComm);
80```80```
Mdocs/zh/api_ref/comm_mgr_c/HcclGetCommAsyncError.md+26-1
@@ -42,9 +42,34 @@ HcclResult HcclGetCommAsyncError(HcclComm comm, HcclResult *asyncError)
42 42 
43## 返回值43## 返回值
44 44 
45-参见[HcclResult](./data_type_definition/HcclResult.md)类型，当前版本仅返回HCCL_E_REMOTE错误类型。45+参见[HcclResult](./data_type_definition/HcclResult.md)类型，接口成功返回HCCL_SUCCESS，失败返回对应错误码。
46 46 
47## 约束说明47## 约束说明
48 48 
49- 建立通信域后，才可调用此接口。49- 建立通信域后，才可调用此接口。
50- 通信域销毁后，不可调用此接口。50- 通信域销毁后，不可调用此接口。
51+ 
52+## 调用示例
53+ 
54+```c
55+// 设备资源初始化
56+aclInit(NULL);
57+aclrtSetDevice(devId);
58+ 
59+// 创建通信域
60+HcclComm hcclComm;
61+HcclRootInfo rootInfo;
62+HcclGetRootInfo(&rootInfo);
63+HcclCommInitRootInfo(8, &rootInfo, 0, &hcclComm);
64+ 
65+// 查询通信域内是否存在异步错误
66+HcclResult asyncError;
67+HcclGetCommAsyncError(hcclComm, &asyncError);
atomgit-bot
atomgit-botatomgit-bot7月28日

🟡 Medium Priority

变更行（第 67 行）：HcclGetCommAsyncError(hcclComm, &asyncError) 的返回值未被检查。该函数返回 HcclResult，若调用失败（返回非 HCCL_SUCCESS），输出参数 asyncError 可能未被写入。随后第 68 行 if (asyncError == HCCL_E_REMOTE) 将读取可能未初始化的 asyncError，导致未定义行为。此问题在上轮审查中已被指出，但本次改动仍未修复。

建议：检查 HcclGetCommAsyncError 的返回值，仅在返回 HCCL_SUCCESS 时才根据 asyncError 的值判断异步错误类型。示例：HcclResult ret = HcclGetCommAsyncError(hcclComm, &asyncError); if (ret == HCCL_SUCCESS && asyncError == HCCL_E_REMOTE) { ... }

likedislike
不准确？
68+if (asyncError == HCCL_E_REMOTE) {
atomgit-bot
atomgit-botatomgit-bot7月22日

🟡 Medium Priority

变更行（第 67 行）：HcclGetCommAsyncError(hcclComm, &asyncError) 的返回值未被检查。该函数返回 HcclResult，若调用失败（返回非 HCCL_SUCCESS），输出参数 asyncError 可能未被写入。随后第 68 行 if (asyncError == HCCL_E_REMOTE) 将读取未初始化的 asyncError，导致误判或漏判异步错误。此问题在上轮审查中已指出，但本次 diff 中未修复。

建议：检查 HcclGetCommAsyncError 的返回值，仅在返回 HCCL_SUCCESS 时才根据 asyncError 的值判断异步错误类型。

likedislike
不准确？
69+ // 通信域内发生了"RDMA ERROR CQE"错误，进行相应处理
70+}
atomgit-botatomgit-bot
atomgit-botatomgit-bot7月21日

🟡 Medium Priority

变更行（新增的调用示例第 66-70 行）：HcclGetCommAsyncError(hcclComm, &asyncError) 的返回值未被检查。该函数返回 HcclResult，若调用失败（返回非 HCCL_SUCCESS），输出参数 asyncError 可能未被写入。后续第 68 行 if (asyncError == HCCL_E_REMOTE) 将读取未初始化的内存，属于未定义行为。用户若复制此示例代码，在接口调用失败时将出现不可预期的行为。

修复方向：检查 HcclGetCommAsyncError 的返回值，仅在返回 HCCL_SUCCESS 时才读取 asyncError。

建议：在调用 HcclGetCommAsyncError 后应检查其返回值，仅当返回 HCCL_SUCCESS 且 asyncError == HCCL_E_REMOTE 时才进行错误处理。

likedislike
不准确？
atomgit-botatomgit-bot7月22日

🟡 Medium Priority

变更行（新增的调用示例第 66-70 行）：HcclResult asyncError; HcclGetCommAsyncError(hcclComm, &asyncError); if (asyncError == HCCL_E_REMOTE)。HcclGetCommAsyncError 的返回值未被检查——该函数返回 HcclResult，若调用本身失败（返回非 HCCL_SUCCESS），输出参数 asyncError 可能未被写入或保持未初始化状态。第 68 行直接读取 asyncError 与 HCCL_E_REMOTE 比较，可能读取未初始化的内存导致错误判断。

建议：在调用 HcclGetCommAsyncError 后检查其返回值，仅当返回 HCCL_SUCCESS 且 asyncError == HCCL_E_REMOTE 时才进行错误处理。

likedislike
不准确？
71+ 
72+// 销毁通信域
73+HcclCommDestroy(hcclComm);
74+aclFinalize();
75+```
Mdocs/zh/api_ref/comm_mgr_c/HcclGetErrorString.md+27-1
@@ -25,7 +25,7 @@
25## 函数原型25## 函数原型
26 26 
27```c27```c
28-const char* HcclGetErrorString(HcclResult code)28+const char *HcclGetErrorString(HcclResult code)
29```29```
30 30 
31## 参数说明31## 参数说明
@@ -41,3 +41,29 @@ const char* HcclGetErrorString(HcclResult code)
41## 约束说明41## 约束说明
42 42 
43无。43无。
44+ 
45+## 调用示例
46+ 
47+```c
48+// 设备资源初始化
49+aclInit(NULL);
50+aclrtSetDevice(devId);
51+ 
52+// 创建通信域
53+HcclComm hcclComm;
54+HcclRootInfo rootInfo;
55+HcclGetRootInfo(&rootInfo);
56+HcclCommInitRootInfo(8, &rootInfo, 0, &hcclComm);
57+ 
58+// 查询通信域异步错误并解析错误码
59+HcclResult asyncError = HCCL_SUCCESS;
60+HcclGetCommAsyncError(hcclComm, &asyncError);
atomgit-bot
atomgit-botatomgit-bot7月28日

🟡 Medium Priority

变更行（第 60 行）：HcclGetCommAsyncError(hcclComm, &asyncError) 的返回值未被检查。虽然 asyncError 已初始化为 HCCL_SUCCESS，但若 HcclGetCommAsyncError 调用自身失败（如通信域已销毁），其返回值能区分"查询操作失败"与"查询成功且无异步错误"两种语义。当前代码仅通过 asyncError != HCCL_SUCCESS 判断，无法区分这两种情况。此问题在上轮审查中已被指出，但本次改动仍未修复。

建议：检查 HcclGetCommAsyncError 的返回值，仅在返回 HCCL_SUCCESS 时才根据 asyncError 的值进行错误解析。示例：HcclResult ret = HcclGetCommAsyncError(hcclComm, &asyncError); if (ret == HCCL_SUCCESS && asyncError != HCCL_SUCCESS) { ... }

likedislike
不准确？
61+if (asyncError != HCCL_SUCCESS) {
atomgit-bot
atomgit-botatomgit-bot7月22日

🟡 Medium Priority

变更行（第 60 行）：HcclGetCommAsyncError(hcclComm, &asyncError) 的返回值未被检查。若调用失败，asyncError 可能保持未初始化状态，后续第 61 行的 if (asyncError != HCCL_SUCCESS) 将读取未初始化的内存，可能导致错误地调用 HcclGetErrorString 解析无效错误码。此问题在上轮审查中已指出，但本次 diff 中未修复。

建议：检查 HcclGetCommAsyncError 的返回值，仅在返回 HCCL_SUCCESS 时才根据 asyncError 的值进行错误解析。

likedislike
不准确？
62+ const char *errStr = HcclGetErrorString(asyncError);
63+ printf("comm async error: %s\n", errStr);
atomgit-botatomgit-bot
atomgit-botatomgit-bot7月21日

🟡 Medium Priority

变更行（新增的调用示例第 59-63 行）：HcclGetCommAsyncError(hcclComm, &asyncError) 的返回值未被检查。若调用失败，asyncError 可能保持未初始化状态，后续第 61 行的 if (asyncError != HCCL_SUCCESS) 将读取未初始化的内存。此外，asyncError 声明时初始化为 HCCL_SUCCESS，但若接口调用失败且未写回该输出参数，则错误将被静默忽略。

修复方向：检查 HcclGetCommAsyncError 的返回值，仅在成功时才依据 asyncError 进行错误判断。

建议：检查 HcclGetCommAsyncError 的返回值，仅在返回 HCCL_SUCCESS 时才根据 asyncError 的值进行错误解析。

likedislike
不准确？
atomgit-botatomgit-bot7月22日

🟡 Medium Priority

变更行（新增的调用示例第 59-63 行）：HcclResult asyncError = HCCL_SUCCESS; HcclGetCommAsyncError(hcclComm, &asyncError); if (asyncError != HCCL_SUCCESS)。HcclGetCommAsyncError 的返回值未被检查。虽然 asyncError 被初始化为 HCCL_SUCCESS（缓解了部分风险），但若 HcclGetCommAsyncError 调用本身失败（返回非 HCCL_SUCCESS），asyncError 可能未被正确写入，第 61 行仍然读取的是初始化值而非实际错误码，导致漏检通信域内的异步错误。

建议：检查 HcclGetCommAsyncError 的返回值，仅在返回 HCCL_SUCCESS 时才根据 asyncError 的值进行错误解析。

likedislike
不准确？
64+}
65+ 
66+// 销毁通信域
67+HcclCommDestroy(hcclComm);
68+aclFinalize();
69+```
Mdocs/zh/api_ref/comm_mgr_c/HcclSymWinGetPeerPointer.md+1-1
@@ -36,7 +36,7 @@ HcclResult HcclSymWinGetPeerPointer(HcclCommSymWindow winHandle, size_t offset,
36 36 
37| 参数名 | 输入/输出 | 描述 |37| 参数名 | 输入/输出 | 描述 |
38| --- | --- | --- |38| --- | --- | --- |
39-| winHandle | 输入 | 对称内存窗口资源句柄。 |39+| winHandle | 输入 | 对称内存窗口资源句柄。<br>HcclCommSymWindow类型的定义可参见[HcclCommSymWindow](./data_type_definition/HcclCommSymWindow.md)。 |
40| offset | 输入 | 使用[HcclCommSymWinGet](HcclCommSymWinGet.md)获取到的偏移量。 |40| offset | 输入 | 使用[HcclCommSymWinGet](HcclCommSymWinGet.md)获取到的偏移量。 |
41| peerRank | 输入 | rank ID，取值范围：[0, rankSize)。 |41| peerRank | 输入 | rank ID，取值范围：[0, rankSize)。 |
42| ptr | 输出 | 指向“对称内存窗口中对应地址”的指针。 |42| ptr | 输出 | 指向“对称内存窗口中对应地址”的指针。 |
Adocs/zh/api_ref/comm_mgr_c/data_type_definition/HcclCMDType.md+41-0
@@ -0,0 +1,41 @@
1+# HcclCMDType
2+ 
3+## 功能说明
4+ 
5+用于标识HCCL通信命令类型，区分不同的集合通信与点对点通信操作。该枚举在[HcclOpP2pDesc](./HcclOpP2pDesc.md)中作为`cmdType`字段，指定点对点通信任务的命令类型。
6+ 
7+> [!NOTE]说明
8+> 在[HcclOpP2pDesc](./HcclOpP2pDesc.md)中使用时，`cmdType`应设置为`HCCL_CMD_SEND`或`HCCL_CMD_RECEIVE`。
9+ 
10+## 定义原型
11+ 
12+```c
13+typedef enum {
14+ HCCL_CMD_INVALID = 0,
15+ HCCL_CMD_BROADCAST = 1,
16+ HCCL_CMD_ALLREDUCE,
17+ HCCL_CMD_REDUCE,
18+ HCCL_CMD_SEND,
19+ HCCL_CMD_RECEIVE,
20+ HCCL_CMD_ALLGATHER,
21+ HCCL_CMD_REDUCE_SCATTER,
22+ HCCL_CMD_ALLTOALLV,
23+ HCCL_CMD_ALLTOALLVC,
24+ HCCL_CMD_ALLTOALL,
25+ HCCL_CMD_GATHER,
26+ HCCL_CMD_SCATTER,
27+ HCCL_CMD_BATCH_SEND_RECV,
28+ HCCL_CMD_BATCH_PUT,
29+ HCCL_CMD_BATCH_GET,
30+ HCCL_CMD_ALLGATHER_V,
31+ HCCL_CMD_REDUCE_SCATTER_V,
32+ HCCL_CMD_BATCH_WRITE,
33+ HCCL_CMD_HALF_ALLTOALLV = 20,
34+ HCCL_CMD_ALL,
35+ HCCL_CMD_FINALIZE = 100,
36+ HCCL_CMD_INTER_GROUP_SYNC,
37+ HCCL_CMD_INIT,
38+ HCCL_CMD_BARRIER,
39+ HCCL_CMD_MAX
40+} HcclCMDType;
41+```
Mdocs/zh/api_ref/comm_mgr_c/data_type_definition/HcclConfig.md+2-1
@@ -8,7 +8,7 @@
8 8 
9```c9```c
10typedef enum {10typedef enum {
11- HCCL_DETERMINISTIC = 0, /* 0: non-deterministic, 1: deterministic */11+ HCCL_DETERMINISTIC = 0, /* 0: non-deterministic, 1: deterministic, 2: strict(order-preserving) */
12 HCCL_CONFIG_RESERVED12 HCCL_CONFIG_RESERVED
13} HcclConfig;13} HcclConfig;
14```14```
@@ -19,5 +19,6 @@ typedef enum {
19 19 
20 - 0：不开启确定性计算。20 - 0：不开启确定性计算。
21 - 1：开启确定性计算。21 - 1：开启确定性计算。
22+ - 2：开启保序功能（仅Atlas A2训练系列产品/Atlas A2推理系列产品支持）。
22 23 
23- HCCL_CONFIG_RESERVED：预留参数。24- HCCL_CONFIG_RESERVED：预留参数。
Adocs/zh/api_ref/comm_mgr_c/data_type_definition/HcclConn.md+11-0
@@ -0,0 +1,11 @@
1+# HcclConn
2+ 
3+## 功能说明
4+ 
5+指向HCCL连接的句柄。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef void *HcclConn;
11+```
Mdocs/zh/api_ref/comm_mgr_c/data_type_definition/HcclOpDesc.md+1-29
@@ -24,35 +24,7 @@ typedef struct {
24- **opDescType**：算子描述类型。24- **opDescType**：算子描述类型。
25- **opName**：算子名称，最大长度为256字节（HCCL_OP_DESC_OP_NAME_MAX_LEN）。25- **opName**：算子名称，最大长度为256字节（HCCL_OP_DESC_OP_NAME_MAX_LEN）。
26- **raws**：原始数据，用于通用场景，长度76字节。26- **raws**：原始数据，用于通用场景，长度76字节。
27-- **p2p**：Send和Receive通信任务的描述参数，[HcclOpP2pDesc](#hcclopp2pdesc)类型，作为联合体成员与raws共用76字节空间。27+- **p2p**：Send和Receive通信任务的描述参数，类型定义请参见[HcclOpP2pDesc](./HcclOpP2pDesc.md)，作为联合体成员与raws共用76字节空间。
28- 
29-## HcclOpP2pDesc
30- 
31-用于描述Send和Receive通信任务的详细信息，包含数据缓冲区地址、通信命令类型、数据类型、数据个数、对端rank编号以及展开流等参数。该结构体作为HcclOpDesc的联合体成员使用。
32- 
33-### 定义原型
34- 
35-```c
36-typedef struct {
37- void *buffer;
38- uint8_t reserved[8];
39- HcclCMDType cmdType;
40- HcclDataType dataType;
41- uint64_t count;
42- uint32_t remoteRank;
43- void *unfoldStream;
44-} HcclOpP2pDesc;
45-```
46- 
47-### 参数说明
48- 
49-- **buffer**：数据缓冲区地址，用于发送或接收数据的内存地址。需确保内存已正确分配且可访问。
50-- **reserved**：预留字段，长度8字节，用于未来扩展。
51-- **cmdType**：通信命令类型，指定通信操作类型（如HCCL_CMD_SEND、HCCL_CMD_RECEIVE等）。
52-- **dataType**：数据类型，类型定义请参见[HcclDataType](./HcclDataType.md)。
53-- **count**：数据个数，指定需要传输的数据元素数量。需与dataType匹配buffer的实际数据大小和类型。
54-- **remoteRank**：对端rank编号，指定通信的对端节点编号。需在通信域的有效rank编号范围内。
55-- **unfoldStream**：展开流，用于AICPU通信任务的流控制。
56 28 
57## 相关常量29## 相关常量
58 30 
Mdocs/zh/api_ref/comm_mgr_c/data_type_definition/HcclOpExpansionMode.md+2-2
@@ -7,8 +7,6 @@
7## 定义原型7## 定义原型
8 8 
9```c9```c
10-typedef HcclOpExpansionMode HcclConfigTypeOpExpansionMode;
11- 
12typedef enum {10typedef enum {
13 HCCL_OP_EXPANSION_MODE_INVALID = -1, /* 无效模式，未初始化或保留。 */11 HCCL_OP_EXPANSION_MODE_INVALID = -1, /* 无效模式，未初始化或保留。 */
14 HCCL_OP_EXPANSION_MODE_AI_CPU = 0, /* 在Device侧AI CPU上展开。 */12 HCCL_OP_EXPANSION_MODE_AI_CPU = 0, /* 在Device侧AI CPU上展开。 */
@@ -19,4 +17,6 @@ typedef enum {
19 HCCL_OP_EXPANSION_MODE_CCU_SCHED = 5, /* 在Device侧CCU上展开，使用调度模式（CCU作为调度器向UB引擎调度任务）。 */17 HCCL_OP_EXPANSION_MODE_CCU_SCHED = 5, /* 在Device侧CCU上展开，使用调度模式（CCU作为调度器向UB引擎调度任务）。 */
20 HCCL_OP_EXPANSION_AIV_ONLY = 6, /* 仅在Device侧Vector Core (AIV) 上展开，不随数据量变化进行模式切换。 */18 HCCL_OP_EXPANSION_AIV_ONLY = 6, /* 仅在Device侧Vector Core (AIV) 上展开，不随数据量变化进行模式切换。 */
21} HcclOpExpansionMode;19} HcclOpExpansionMode;
20+ 
21+typedef HcclOpExpansionMode HcclConfigTypeOpExpansionMode;
22```22```
Adocs/zh/api_ref/comm_mgr_c/data_type_definition/HcclOpP2pDesc.md+29-0
@@ -0,0 +1,29 @@
1+# HcclOpP2pDesc
2+ 
3+## 功能说明
4+ 
5+用于描述Send和Receive通信任务的详细信息，包含数据缓冲区地址、通信命令类型、数据类型、数据个数、对端rank编号以及展开流等参数。该结构体作为[HcclOpDesc](./HcclOpDesc.md)的联合体成员使用，与`raws`共用76字节空间。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef struct {
11+ void *buffer;
12+ uint8_t reserved[8];
13+ HcclCMDType cmdType;
14+ HcclDataType dataType;
15+ uint64_t count;
16+ uint32_t remoteRank;
17+ void *unfoldStream;
18+} HcclOpP2pDesc;
19+```
20+ 
21+## 参数说明
22+ 
23+- **buffer**：数据缓冲区地址，用于发送或接收数据的内存地址。需确保内存已正确分配且可访问。
24+- **reserved**：预留字段，长度8字节，用于未来扩展。
25+- **cmdType**：通信命令类型，指定通信操作类型（如HCCL_CMD_SEND、HCCL_CMD_RECEIVE等）。HcclCMDType类型的定义可参见[HcclCMDType](./HcclCMDType.md)。
26+- **dataType**：数据类型，类型定义请参见[HcclDataType](./HcclDataType.md)。
27+- **count**：数据个数，指定需要传输的数据元素数量。需与dataType匹配buffer的实际数据大小和类型。
28+- **remoteRank**：对端rank编号，指定通信的对端节点编号。需在通信域的有效rank编号范围内。
29+- **unfoldStream**：展开流，用于AICPU通信任务的流控制。
Adocs/zh/api_ref/comm_mgr_c/data_type_definition/HcclP2pKernelParam.md+21-0
@@ -0,0 +1,21 @@
1+# HcclP2pKernelParam
2+ 
3+## 功能说明
4+ 
5+用于描述P2P（点对点）通信任务的核函数参数，包含收发通信线程句柄和操作参数缓存。该结构体在AICPU核函数启动时用于传递P2P通信所需的上下文信息。
6+ 
7+## 定义原型
8+ 
9+```c
10+const uint32_t P2P_MAX_ARG_SIZE = 8192U;
11+ 
12+typedef struct {
13+ ThreadHandle sendRecvThread;
14+ uint8_t opParams[P2P_MAX_ARG_SIZE];
15+} HcclP2pKernelParam;
16+```
17+ 
18+## 参数说明
19+ 
20+- **sendRecvThread**：收发通信线程句柄，用于标识执行点对点收发操作的通信线程，类型定义请参见[ThreadHandle](../../comm_opdev/datatype_definition/ThreadHandle.md)。
21+- **opParams**：操作参数缓存，用于存储核函数执行所需的参数数据，最大长度为`P2P_MAX_ARG_SIZE`（8192字节）。实际使用的参数长度由具体的通信操作决定。
Mdocs/zh/api_ref/comm_mgr_c/data_type_definition/README.md+4-0
@@ -9,14 +9,18 @@
9- [HcclOpExpansionMode](HcclOpExpansionMode.md)9- [HcclOpExpansionMode](HcclOpExpansionMode.md)
10- [HcclRootInfo](HcclRootInfo.md)10- [HcclRootInfo](HcclRootInfo.md)
11- [HcclComm](HcclComm.md)11- [HcclComm](HcclComm.md)
12+- [HcclConn](HcclConn.md)
12- [HcclSendRecvType](HcclSendRecvType.md)13- [HcclSendRecvType](HcclSendRecvType.md)
13- [HcclSendRecvItem](HcclSendRecvItem.md)14- [HcclSendRecvItem](HcclSendRecvItem.md)
15+- [HcclCMDType](HcclCMDType.md)
14- [HcclCommConfig](HcclCommConfig.md)16- [HcclCommConfig](HcclCommConfig.md)
15- [HcclCommConfigCapability](HcclCommConfigCapability.md)17- [HcclCommConfigCapability](HcclCommConfigCapability.md)
16- [HcclCommSymWindow](HcclCommSymWindow.md)18- [HcclCommSymWindow](HcclCommSymWindow.md)
17- [HcclCommStatus](HcclCommStatus.md)19- [HcclCommStatus](HcclCommStatus.md)
18- [HcclKernelFuncInfo](HcclKernelFuncInfo.md)20- [HcclKernelFuncInfo](HcclKernelFuncInfo.md)
19- [HcclKernelLaunchCfg](HcclKernelLaunchCfg.md)21- [HcclKernelLaunchCfg](HcclKernelLaunchCfg.md)
22+- [HcclP2pKernelParam](HcclP2pKernelParam.md)
20- [HcclOpDesc](HcclOpDesc.md)23- [HcclOpDesc](HcclOpDesc.md)
24+- [HcclOpP2pDesc](HcclOpP2pDesc.md)
21- [HcclCommStatePhase](HcclCommStatePhase.md)25- [HcclCommStatePhase](HcclCommStatePhase.md)
22- [HcclCommStateCallback](HcclCommStateCallback.md)26- [HcclCommStateCallback](HcclCommStateCallback.md)
Mdocs/zh/api_ref/comm_mgr_python/create_group.md+23-23
@@ -61,59 +61,59 @@ def create_group(group, rank_num, rank_ids)
61 **针对Atlas A2 训练系列产品/Atlas A2 推理系列产品：**61 **针对Atlas A2 训练系列产品/Atlas A2 推理系列产品：**
62 - 对于Server单机场景，rank_ids无限制条件。62 - 对于Server单机场景，rank_ids无限制条件。
63 - 对于Server集群场景，rank_ids需满足如下条件：63 - 对于Server集群场景，rank_ids需满足如下条件：
64- 64+ 
65 建议各Server要选取相同数量的rank（数量大小无要求），且各Server选取的rank对应位置要相等（即rank id按8取模相等）。若各Server选取的rank数量不同，会造成性能劣化。65 建议各Server要选取相同数量的rank（数量大小无要求），且各Server选取的rank对应位置要相等（即rank id按8取模相等）。若各Server选取的rank数量不同，会造成性能劣化。
66- 66+ 
67 举例：67 举例：
68- 68+ 
69 假设对三台Server创建group，三台Server的rank id分别为：69 假设对三台Server创建group，三台Server的rank id分别为：
70- 70+ 
71 {0,1,2,3,4,5,6,7}71 {0,1,2,3,4,5,6,7}
72- 72+ 
73 {8,9,10,11,12,13,14,15}73 {8,9,10,11,12,13,14,15}
74- 74+ 
75 {16,17,18,19,20,21,22,23}75 {16,17,18,19,20,21,22,23}
76- 76+ 
77 则满足要求的rank_ids列表可以是：77 则满足要求的rank_ids列表可以是：
78- 78+ 
79 rank_ids=[1,9,17]79 rank_ids=[1,9,17]
80- 80+ 
81 rank_ids=[1,2,9,10,17,18]81 rank_ids=[1,2,9,10,17,18]
82- 82+ 
83 rank_ids=[4,5,6,7,12,13,14,15,20,21,22,23]83 rank_ids=[4,5,6,7,12,13,14,15,20,21,22,23]
84 <!-- end id9 -->84 <!-- end id9 -->
85- 85+ 
86 <!-- npu="910" id6 -->86 <!-- npu="910" id6 -->
87 **针对Atlas 训练系列产品：**87 **针对Atlas 训练系列产品：**
88 - 对于Server单机场景，rank_ids需满足如下条件：88 - 对于Server单机场景，rank_ids需满足如下条件：
89- 89+ 
90 rank数量必须为1/2/4/8，0-3卡与4-7卡各为一个组网，rank数量为2/4时要求选取的AI处理器同属一个cluster。90 rank数量必须为1/2/4/8，0-3卡与4-7卡各为一个组网，rank数量为2/4时要求选取的AI处理器同属一个cluster。
91 - 对于Server集群场景，rank_ids满足如下条件：91 - 对于Server集群场景，rank_ids满足如下条件：
92 - 各Server要选取相同数量的rank（且数量要求为1/2/4/8）。92 - 各Server要选取相同数量的rank（且数量要求为1/2/4/8）。
93 - 各Server选取rank数量为2/4时要求选取的AI处理器同属一个cluster（即rank id按8取模余数都小于4或都大于等于4）。93 - 各Server选取rank数量为2/4时要求选取的AI处理器同属一个cluster（即rank id按8取模余数都小于4或都大于等于4）。
94- 94+ 
95 举例：95 举例：
96 96 
97 假设对三台Server创建group，三台Server的rank id分别为：97 假设对三台Server创建group，三台Server的rank id分别为：
98- 98+ 
99 {0,1,2,3,4,5,6,7}99 {0,1,2,3,4,5,6,7}
100- 100+ 
101 {8,9,10,11,12,13,14,15}101 {8,9,10,11,12,13,14,15}
102- 102+ 
103 {16,17,18,19,20,21,22,23}103 {16,17,18,19,20,21,22,23}
104- 104+ 
105 则满足要求的rank_ids列表可以是：105 则满足要求的rank_ids列表可以是：
106- 106+ 
107 rank_ids=[1,9,17]107 rank_ids=[1,9,17]
108- 108+ 
109 rank_ids=[1,2,9,10,17,18]109 rank_ids=[1,2,9,10,17,18]
110- 110+ 
111- rank_ids=[4,5,6,7,12,13,14,15,20,21,22,23] 111+ rank_ids=[4,5,6,7,12,13,14,15,20,21,22,23]
112 <!-- end id6 -->112 <!-- end id6 -->
113- <!-- npu="310p" id7 --> 113+ <!-- npu="310p" id7 -->
114 **针对Atlas 300I Duo 推理卡**：仅支持Server单机场景，rank_ids无限制条件。114 **针对Atlas 300I Duo 推理卡**：仅支持Server单机场景，rank_ids无限制条件。
115 <!-- end id7 -->115 <!-- end id7 -->
116- 116+ 
117 补充说明：建议rank_ids按照Device物理连接顺序进行排序，即将物理连接上较近的device编排在一起。例如，若device_ip按照物理连接从小到大设置，则rank_ids也建议按照从小到大的顺序设置。117 补充说明：建议rank_ids按照Device物理连接顺序进行排序，即将物理连接上较近的device编排在一起。例如，若device_ip按照物理连接从小到大设置，则rank_ids也建议按照从小到大的顺序设置。
118 118 
119## 调用示例119## 调用示例
Mdocs/zh/api_ref/comm_opdev/control_plane_api/basic_resource_mgmt/EndpointDescInit.md+1-1
@@ -37,7 +37,7 @@ HcommResult EndpointDescInit(EndpointDesc *endpoint, uint32_t num)
37 37 
38## 返回值38## 返回值
39 39 
40-HcommResult：接口成功返回0，其他失败。40+[HcommResult](../../datatype_definition/HcommResult.md)：接口成功返回0，其他失败。
41 41 
42## 约束说明42## 约束说明
43 43 
Mdocs/zh/api_ref/comm_opdev/control_plane_api/basic_resource_mgmt/HcommChannelDescInit.md+1-1
@@ -11,7 +11,7 @@
11<!-- npu="910b" id3 -->11<!-- npu="910b" id3 -->
12- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持12- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
13<!-- end id3 -->13<!-- end id3 -->
14- <!-- npu="910" id4 -->14+<!-- npu="910" id4 -->
15- Atlas 训练系列产品：不支持15- Atlas 训练系列产品：不支持
16<!-- end id4 -->16<!-- end id4 -->
17<!-- npu="310p" id5 -->17<!-- npu="310p" id5 -->
Mdocs/zh/api_ref/comm_opdev/control_plane_api/basic_resource_mgmt/HcommMemExport.md+1-1
@@ -25,7 +25,7 @@
25## 函数原型25## 函数原型
26 26 
27```c27```c
28-HcommResult HcommMemExport(EndpointHandle endpointHandle, void* memHandle, void** memDesc, uint32_t* memDescLen)28+HcommResult HcommMemExport(EndpointHandle endpointHandle, HcommMemHandle memHandle, void** memDesc, uint32_t* memDescLen)
29```29```
30 30 
31## 参数说明31## 参数说明
Mdocs/zh/api_ref/comm_opdev/control_plane_api/basic_resource_mgmt/HcommThreadAlloc.md+1-1
@@ -50,7 +50,7 @@ HcommResult：接口成功返回0，其他失败。
50## 调用示例50## 调用示例
51 51 
52```c52```c
53-ThreadHandle thread[3];53+ThreadHandle thread[2];
54//申请两条流，每条流Notify数量为354//申请两条流，每条流Notify数量为3
55const uint32_t notifyNumPerThread[2] = {3, 3};55const uint32_t notifyNumPerThread[2] = {3, 3};
56HcommResult ret = HcommThreadAlloc(COMM_ENGINE_AICPU_TS, 2, notifyNumPerThread, thread);56HcommResult ret = HcommThreadAlloc(COMM_ENGINE_AICPU_TS, 2, notifyNumPerThread, thread);
Mdocs/zh/api_ref/comm_opdev/control_plane_api/basic_resource_mgmt/HcommThreadFree.md+3-2
@@ -47,6 +47,7 @@ HcommResult：接口成功返回0，其他失败。
47 47 
48```c48```c
49ThreadHandle thread[2];49ThreadHandle thread[2];
50-HcommResult ret = HcommThreadAlloc(COMM_ENGINE_AICPU_TS, 2, 3, thread);50+const uint32_t notifyNumPerThread[2] = {3, 3};
51-HcommResult ret = HcommThreadFree(thread, 2);51+HcommResult ret = HcommThreadAlloc(COMM_ENGINE_AICPU_TS, 2, notifyNumPerThread, thread);
52+ret = HcommThreadFree(thread, 2);
52```53```
Mdocs/zh/api_ref/comm_opdev/control_plane_api/basic_resource_mgmt/README.md+15-15
@@ -1,18 +1,18 @@
1# 基础资源管理1# 基础资源管理
2 2 
3+- [HcommEndpointCreate](HcommEndpointCreate.md)
4+- [HcommEndpointDestroy](HcommEndpointDestroy.md)
5+- [HcommEndpointCheckFeature](HcommEndpointCheckFeature.md)
6+- [HcommEndpointGetListenPort](HcommEndpointGetListenPort.md)
7+- [HcommMemReg](HcommMemReg.md)
8+- [HcommMemUnreg](HcommMemUnreg.md)
9+- [HcommMemExport](HcommMemExport.md)
10+- [HcommMemImport](HcommMemImport.md)
11+- [HcommMemUnimport](HcommMemUnimport.md)
3- [EndpointDescInit](EndpointDescInit.md)12- [EndpointDescInit](EndpointDescInit.md)
4-- [HcommEndpointCreate](HcommEndpointCreate.md) 13+- [HcommChannelDescInit](HcommChannelDescInit.md)
5-- [HcommEndpointDestroy](HcommEndpointDestroy.md) 14+- [HcommChannelCreate](HcommChannelCreate.md)
6-- [HcommEndpointCheckFeature](HcommEndpointCheckFeature.md) 15+- [HcommChannelGetStatus](HcommChannelGetStatus.md)
7-- [HcommEndpointGetListenPort](HcommEndpointGetListenPort.md) 16+- [HcommChannelDestroy](HcommChannelDestroy.md)
8-- [HcommMemReg](HcommMemReg.md) 17+- [HcommThreadAlloc](HcommThreadAlloc.md)
9-- [HcommMemUnreg](HcommMemUnreg.md) 18+- [HcommThreadFree](HcommThreadFree.md)
10-- [HcommMemExport](HcommMemExport.md)
11-- [HcommMemImport](HcommMemImport.md)
12-- [HcommMemUnimport](HcommMemUnimport.md)
13-- [HcommChannelDescInit](HcommChannelDescInit.md)
14-- [HcommChannelCreate](HcommChannelCreate.md)
15-- [HcommChannelGetStatus](HcommChannelGetStatus.md)
16-- [HcommChannelDestroy](HcommChannelDestroy.md)
17-- [HcommThreadAlloc](HcommThreadAlloc.md)
18-- [HcommThreadFree](HcommThreadFree.md)
Mdocs/zh/api_ref/comm_opdev/control_plane_api/ccu_kernel_launch_execution/HcommCcuGetMemToken.md+1-1
@@ -58,7 +58,7 @@ CcuResult HcommCcuGetMemToken(uint64_t srcVa, uint64_t size, uint64_t *tokenInfo
58- `(srcVa, size)`须落在同一段已注册的连续内存区域内，跨区域或覆盖未注册内存区域会导致驱动返回错误。58- `(srcVa, size)`须落在同一段已注册的连续内存区域内，跨区域或覆盖未注册内存区域会导致驱动返回错误。
59- Token的有效生命周期与对应内存的注册生命周期绑定，内存注销后Token失效。59- Token的有效生命周期与对应内存的注册生命周期绑定，内存注销后Token失效。
60- 在跨rank通信场景中，本端Token须通过带外通道（非CCU数据面）传递给对端，由对端组装`RemoteAddr.token`，不能通过CCU数据面明文传输Token值。60- 在跨rank通信场景中，本端Token须通过带外通道（非CCU数据面）传递给对端，由对端组装`RemoteAddr.token`，不能通过CCU数据面明文传输Token值。
61-- 本接口只能在主机侧调用，不能在Kernel函数体内调用。61+- 本接口只能在Host侧调用，不能在Kernel函数体内调用。
62 62 
63## 调用示例63## 调用示例
64 64 
Mdocs/zh/api_ref/comm_opdev/control_plane_api/ccu_kernel_launch_execution/HcommCcuKernelLaunch.md+1-1
@@ -56,7 +56,7 @@ CcuResult HcommCcuKernelLaunch(ThreadHandle threadHandle,
56- 必须在[HcommCcuKernelRegisterEnd](HcommCcuKernelRegisterEnd.md)之后调用。56- 必须在[HcommCcuKernelRegisterEnd](HcommCcuKernelRegisterEnd.md)之后调用。
57- `argNum`的单位是`uint64_t`元素个数，不是字节数。传入字节数会导致`CCU_E_INTERNAL`错误。57- `argNum`的单位是`uint64_t`元素个数，不是字节数。传入字节数会导致`CCU_E_INTERNAL`错误。
58- 当`taskArgs`参数较多时，框架会自动分批下发，无需用户干预。58- 当`taskArgs`参数较多时，框架会自动分批下发，无需用户干预。
59-- 本接口只能在主机侧调用，不能在Kernel函数体内调用。59+- 本接口只能在Host侧调用，不能在Kernel函数体内调用。
60 60 
61## 调用示例61## 调用示例
62 62 
Mdocs/zh/api_ref/comm_opdev/control_plane_api/ccu_kernel_launch_execution/HcommCcuKernelRegister.md+2-2
@@ -20,7 +20,7 @@
20 20 
21## 功能说明21## 功能说明
22 22 
23-注册一个CCU Kernel函数。本接口在主机侧执行一次用户提供的Kernel函数，该函数体内所有`Ccu*`接口不执行实际硬件操作，仅记录该Kernel的完整操作序列。注册成功后返回Kernel句柄，供后续[HcommCcuKernelLaunch](HcommCcuKernelLaunch.md)使用。23+注册一个CCU Kernel函数。本接口在Host侧执行一次用户提供的Kernel函数，该函数体内所有`Ccu*`接口不执行实际硬件操作，仅记录该Kernel的完整操作序列。注册成功后返回Kernel句柄，供后续[HcommCcuKernelLaunch](HcommCcuKernelLaunch.md)使用。
24 24 
25注册失败时框架自动回滚当前Kernel，已注册的其他Kernel不受影响。Kernel函数体内的`CCU_IF`分支若未显式配对`CCU_ELSE`，会在本次`HcommCcuKernelRegister`调用结束时自动关闭。25注册失败时框架自动回滚当前Kernel，已注册的其他Kernel不受影响。Kernel函数体内的`CCU_IF`分支若未显式配对`CCU_ELSE`，会在本次`HcommCcuKernelRegister`调用结束时自动关闭。
26 26 
@@ -65,7 +65,7 @@ CcuResult HcommCcuKernelRegister(CcuInsHandle insHandle, uint32_t dieId,
65- `argNum`当前仅支持`0`或`1`；为`1`时仅`kernelArgs[0]`生效，其余元素被忽略。65- `argNum`当前仅支持`0`或`1`；为`1`时仅`kernelArgs[0]`生效，其余元素被忽略。
66- `kernelArgs[0]`指向的标量在注册阶段即被读取，并固化为立即数。若某个标量的值需在每次启动时动态指定，须通过`taskArgs`数组与Kernel内的`CcuLoadArg`接口传入，而不是通过`kernelArgs`。66- `kernelArgs[0]`指向的标量在注册阶段即被读取，并固化为立即数。若某个标量的值需在每次启动时动态指定，须通过`taskArgs`数组与Kernel内的`CcuLoadArg`接口传入，而不是通过`kernelArgs`。
67- `dieId`为预留参数，当前实现未使用。67- `dieId`为预留参数，当前实现未使用。
68-- 本接口只能在主机侧调用，不能嵌套调用（即Kernel函数体内不能再次调用本接口）。68+- 本接口只能在Host侧调用，不能嵌套调用（即Kernel函数体内不能再次调用本接口）。
69 69 
70## 调用示例70## 调用示例
71 71 
Mdocs/zh/api_ref/comm_opdev/control_plane_api/ccu_kernel_launch_execution/HcommCcuKernelRegisterEnd.md+1-1
@@ -55,7 +55,7 @@ CcuResult HcommCcuKernelRegisterEnd(CcuInsHandle insHandle);
55> 须按 [HcommCcuKernelRegisterStart](HcommCcuKernelRegisterStart.md) → [HcommCcuKernelRegister](HcommCcuKernelRegister.md) → 本接口的顺序调用。未先调用[HcommCcuKernelRegisterStart](HcommCcuKernelRegisterStart.md)就调用本接口会返回`CCU_E_INTERNAL`。55> 须按 [HcommCcuKernelRegisterStart](HcommCcuKernelRegisterStart.md) → [HcommCcuKernelRegister](HcommCcuKernelRegister.md) → 本接口的顺序调用。未先调用[HcommCcuKernelRegisterStart](HcommCcuKernelRegisterStart.md)就调用本接口会返回`CCU_E_INTERNAL`。
56 56 
57- 本接口调用成功后，本轮注册的Kernel即可独立启动。若需注册新一轮Kernel，须重新调用[HcommCcuKernelRegisterStart](HcommCcuKernelRegisterStart.md)开始新一轮流程。57- 本接口调用成功后，本轮注册的Kernel即可独立启动。若需注册新一轮Kernel，须重新调用[HcommCcuKernelRegisterStart](HcommCcuKernelRegisterStart.md)开始新一轮流程。
58-- 本接口只能在主机侧调用，不能在Kernel函数体内调用。58+- 本接口只能在Host侧调用，不能在Kernel函数体内调用。
59 59 
60## 调用示例60## 调用示例
61 61 
Mdocs/zh/api_ref/comm_opdev/control_plane_api/ccu_kernel_launch_execution/HcommCcuKernelRegisterStart.md+1-1
@@ -52,7 +52,7 @@ CcuResult HcommCcuKernelRegisterStart(CcuInsHandle insHandle);
52 52 
53- CcuInsHandle 必须在Hccl通信域中先获取，且必须先于[HcommCcuKernelRegister](HcommCcuKernelRegister.md)。53- CcuInsHandle 必须在Hccl通信域中先获取，且必须先于[HcommCcuKernelRegister](HcommCcuKernelRegister.md)。
54- 本接口与[HcommCcuKernelRegisterEnd](HcommCcuKernelRegisterEnd.md)须成对调用：开始新一轮注册前，上一轮必须已通过[HcommCcuKernelRegisterEnd](HcommCcuKernelRegisterEnd.md)结束，否则本接口返回`CCU_E_INTERNAL`。54- 本接口与[HcommCcuKernelRegisterEnd](HcommCcuKernelRegisterEnd.md)须成对调用：开始新一轮注册前，上一轮必须已通过[HcommCcuKernelRegisterEnd](HcommCcuKernelRegisterEnd.md)结束，否则本接口返回`CCU_E_INTERNAL`。
55-- 本接口只能在主机侧调用，不能在Kernel函数体内调用。55+- 本接口只能在Host侧调用，不能在Kernel函数体内调用。
56 56 
57## 调用示例57## 调用示例
58 58 
Mdocs/zh/api_ref/comm_opdev/control_plane_api/ccu_kernel_launch_execution/README.md+3-3
@@ -1,6 +1,6 @@
1# 简介1# 简介
2 2 
3-本节包含CCU Kernel主机侧生命周期管理接口及内存Token查询接口。3+本节包含CCU Kernel Host侧生命周期管理接口及内存Token查询接口。
4 4 
5通过这些接口，用户可以完成CCU实例的创建与销毁、Kernel的注册与翻译、Kernel的启动执行，以及进程虚拟地址到CCU访问Token的转换。5通过这些接口，用户可以完成CCU实例的创建与销毁、Kernel的注册与翻译、Kernel的启动执行，以及进程虚拟地址到CCU访问Token的转换。
6 6 
@@ -30,8 +30,8 @@
30 }30 }
31 ```31 ```
32 32 
33-> 该接口属于 hccl 层（不在 `Hcomm*` / `Ccu*` 系列内），暂未提供独立 API 参考页面，33+> 该接口属于Hccl层（不在`Hcomm*`/`Ccu*`系列内），暂未提供独立API参考页面，
34-> 完整签名以头文件 `include/hccl/hccl_ccu_res.h` 为准。34+> 完整签名以头文件`include/hccl/hccl_ccu_res.h`为准。
35 35 
36## 接口调用顺序36## 接口调用顺序
37 37 
Mdocs/zh/api_ref/comm_opdev/control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md+1-1
@@ -36,7 +36,7 @@ HcclResult HcclChannelAcquire(HcclComm comm, CommEngine engine, const HcclChanne
36| --- | --- | --- |36| --- | --- | --- |
37| comm | 输入 | 通信域句柄。<br>HcclComm类型的定义如下：<br>typedef void *HcclComm; |37| comm | 输入 | 通信域句柄。<br>HcclComm类型的定义如下：<br>typedef void *HcclComm; |
38| engine | 输入 | 通信引擎类型。<br>CommEngine类型的定义可参见[CommEngine](../../datatype_definition/CommEngine.md)。 |38| engine | 输入 | 通信引擎类型。<br>CommEngine类型的定义可参见[CommEngine](../../datatype_definition/CommEngine.md)。 |
39-| channelDescs | 输入 | 通信通道描述列表，列表长度为channelNum。<br>HcclChannelDesc类型的定义可参见[HcclChannelDesc](../../datatype_definition/HcclChannelDesc.md)，通过[HcclRankGraphGetLinks](../topo_info_query/HcclRankGraphGetLinks.md)函数获取。 |39+| channelDescs | 输入 | 通信通道描述列表，列表长度为channelNum。<br>HcclChannelDesc类型的定义可参见[HcclChannelDesc](../../datatype_definition/HcclChannelDesc.md)，可通过[HcclRankGraphGetLinks](../topo_info_query/HcclRankGraphGetLinks.md)获取链路信息后填充。 |
40| channelNum | 输入 | 通信通道数量，channelNum的取值范围为(0, 1024 * 1024]。 |40| channelNum | 输入 | 通信通道数量，channelNum的取值范围为(0, 1024 * 1024]。 |
41| channels | 输出 | 通信通道句柄列表，通信通道句柄列表长度为channelNum。 |41| channels | 输出 | 通信通道句柄列表，通信通道句柄列表长度为channelNum。 |
42 42 
Mdocs/zh/api_ref/comm_opdev/control_plane_api/comms_domain_resource_mgmt/HcclCommMemReg.md+3-2
@@ -51,9 +51,10 @@ HcclResult HcclCommMemReg(HcclComm comm, const char *memTag, const CommMem *mem,
51 51 
52```c52```c
53HcclComm comm; // 通信域句柄，省略获取53HcclComm comm; // 通信域句柄，省略获取
54-char* memTag = "memTag"; // 内存标签54+const char* memTag = "memTag"; // 内存标签
55+void *deviceBuffer = nullptr; // 已申请的设备内存地址（需通过aclrtMalloc等接口申请）
55CommMem memInfo; // 内存信息56CommMem memInfo; // 内存信息
56-memInfo.addr = 0x00; // 配置已申请的内存地址 57+memInfo.addr = deviceBuffer; // 配置已申请的内存地址
atomgit-bot
atomgit-botatomgit-bot7月21日

🟡 Medium Priority

变更行（第 55-57 行）：声明了 void *deviceBuffer = nullptr 并注释"需通过aclrtMalloc等接口申请"，但实际并未调用任何内存分配接口，直接将 nullptr 赋值给 memInfo.addr。随后第 61 行调用 HcclCommMemReg(comm, memTag, &memInfo, &memHandle) 时传入的 memInfo.addr 为空指针。根据该接口功能说明"向通信域注册已申请的内存"，传入空指针显然不是有效用法，用户若直接复制此示例将得到一个无效的调用。

修复方向：示例中应包含实际的内存分配调用（如 aclrtMalloc(&deviceBuffer, size, ...)）后再将 deviceBuffer 赋值给 memInfo.addr，或至少在注释中明确说明此处为示意代码、实际使用时需替换为已分配的有效地址。

建议：在示例中补全 aclrtMalloc 等内存分配调用，确保 deviceBuffer 指向有效的已分配内存后再传给 memInfo.addr。

likedislike
不准确？
57memInfo.size = 1024; // 配置已申请的内存大小58memInfo.size = 1024; // 配置已申请的内存大小
58memInfo.type = COMM_MEM_TYPE_DEVICE; // 配置已申请的内存类型59memInfo.type = COMM_MEM_TYPE_DEVICE; // 配置已申请的内存类型
59HcclMemHandle memHandle; // 内存句柄60HcclMemHandle memHandle; // 内存句柄
Mdocs/zh/api_ref/comm_opdev/control_plane_api/comms_domain_resource_mgmt/HcclEngineCtxCopy.md+8-4
@@ -50,11 +50,15 @@ HcclResult HcclEngineCtxCopy(HcclComm comm, CommEngine engine, const char *ctxTa
50## 调用示例50## 调用示例
51 51 
52```c52```c
53+// 通信域句柄
53HcclComm comm;54HcclComm comm;
54-CommEngine engine = CommEngine::COMM_ENGINE_AICPU_TS;55+CommEngine engine = COMM_ENGINE_AICPU_TS;
55-string ctxTag = "ctxTag";56+const char *ctxTag = "ctxTag";
56-AlgResourceCtx* resCtx; // 有效的源ctx57+void *resCtx = nullptr; // 有效的源ctx，需指向已分配的内存
57uint64_t size = 16; // 需要拷贝的实际大小58uint64_t size = 16; // 需要拷贝的实际大小
58uint64_t dstCtxOffset = 0; // 全部拷贝情况下，偏移传059uint64_t dstCtxOffset = 0; // 全部拷贝情况下，偏移传0
59-ret = HcclEngineCtxCopy(comm, engine, ctxTag, resCtx, size, dstCtxOffset);60+HcclResult ret = HcclEngineCtxCopy(comm, engine, ctxTag, resCtx, size, dstCtxOffset);
61+if (ret != HCCL_SUCCESS) {
62+ // 错误处理
63+}
60```64```
Mdocs/zh/api_ref/comm_opdev/control_plane_api/comms_domain_resource_mgmt/HcclEngineCtxGet.md+2-2
@@ -52,7 +52,7 @@ HcclResult HcclEngineCtxGet(HcclComm comm, const char *ctxTag, CommEngine engine
52HcclComm comm;52HcclComm comm;
53uint64_t size = 0;53uint64_t size = 0;
54void *ctx = nullptr;54void *ctx = nullptr;
55-string ctxTag = "ctxTag";55+const char *ctxTag = "ctxTag";
56CommEngine engine = CommEngine::COMM_ENGINE_CPU_TS;56CommEngine engine = CommEngine::COMM_ENGINE_CPU_TS;
57-ret = HcclEngineCtxGet(comm, ctxTag, engine, &ctx, &size);57+HcclResult ret = HcclEngineCtxGet(comm, ctxTag, engine, &ctx, &size);
58```58```
Mdocs/zh/api_ref/comm_opdev/control_plane_api/comms_domain_resource_mgmt/README.md+18-18
@@ -1,20 +1,20 @@
1# 通信域资源管理1# 通信域资源管理
2 2 
3-- [HcclGetHcclBuffer](HcclGetHcclBuffer.md) 3+- [HcclGetHcclBuffer](HcclGetHcclBuffer.md)
4-- [HcclGetHcclBufferCleared](HcclGetHcclBufferCleared.md) 4+- [HcclGetHcclBufferCleared](HcclGetHcclBufferCleared.md)
5-- [HcclThreadAcquire](HcclThreadAcquire.md) 5+- [HcclThreadAcquire](HcclThreadAcquire.md)
6-- [HcclThreadAcquireWithStream](HcclThreadAcquireWithStream.md) 6+- [HcclThreadAcquireWithStream](HcclThreadAcquireWithStream.md)
7-- [HcclThreadAcquireWithConfig](HcclThreadAcquireWithConfig.md) 7+- [HcclThreadAcquireWithConfig](HcclThreadAcquireWithConfig.md)
8-- [HcclDedicatedThreadAcquire](HcclDedicatedThreadAcquire.md) 8+- [HcclDedicatedThreadAcquire](HcclDedicatedThreadAcquire.md)
9-- [ThreadConfigInit](ThreadConfigInit.md) 9+- [ThreadConfigInit](ThreadConfigInit.md)
10-- [HcclThreadResGetInfo](HcclThreadResGetInfo.md) 10+- [HcclThreadResGetInfo](HcclThreadResGetInfo.md)
11-- [HcclChannelDescInit](HcclChannelDescInit.md) 11+- [HcclChannelDescInit](HcclChannelDescInit.md)
12-- [HcclChannelAcquire](HcclChannelAcquire.md) 12+- [HcclChannelAcquire](HcclChannelAcquire.md)
13-- [HcclChannelGetHcclBuffer](HcclChannelGetHcclBuffer.md) 13+- [HcclChannelGetHcclBuffer](HcclChannelGetHcclBuffer.md)
14-- [HcclChannelGetRemoteMems](HcclChannelGetRemoteMems.md) 14+- [HcclChannelGetRemoteMems](HcclChannelGetRemoteMems.md)
15-- [HcclEngineCtxCreate](HcclEngineCtxCreate.md) 15+- [HcclEngineCtxCreate](HcclEngineCtxCreate.md)
16-- [HcclEngineCtxGet](HcclEngineCtxGet.md) 16+- [HcclEngineCtxGet](HcclEngineCtxGet.md)
17-- [HcclEngineCtxCopy](HcclEngineCtxCopy.md) 17+- [HcclEngineCtxCopy](HcclEngineCtxCopy.md)
18-- [HcclEngineCtxDestroy](HcclEngineCtxDestroy.md) 18+- [HcclEngineCtxDestroy](HcclEngineCtxDestroy.md)
19-- [HcclCommMemReg](HcclCommMemReg.md) 19+- [HcclCommMemReg](HcclCommMemReg.md)
20-- [HcclCommQueryCcuIns](HcclCommQueryCcuIns.md) 20+- [HcclCommQueryCcuIns](HcclCommQueryCcuIns.md)
Mdocs/zh/api_ref/comm_opdev/control_plane_api/topo_info_query/HcclRankGraphGetEndpointDesc.md+7-1
@@ -44,16 +44,22 @@ HcclResult HcclRankGraphGetEndpointDesc(HcclComm comm, uint32_t layer, uint32_t
44 44 
45## 约束说明45## 约束说明
46 46 
47-无47+无。
48 48 
49## 调用示例49## 调用示例
50 50 
51```c51```c
52+// 通信域句柄
52HcclComm comm;53HcclComm comm;
54+ 
55+// 获取EndPoint数量
53uint32_t layer = 0;56uint32_t layer = 0;
54uint32_t topoInstId = 0;57uint32_t topoInstId = 0;
55uint32_t num = 0;58uint32_t num = 0;
56HcclRankGraphGetEndpointNum(comm, layer, topoInstId, &num);59HcclRankGraphGetEndpointNum(comm, layer, topoInstId, &num);
60+ 
61+// 获取EndPoint描述列表
57uint32_t descNum = num;62uint32_t descNum = num;
63+EndpointDesc endpointDesc[descNum];
58HcclRankGraphGetEndpointDesc(comm, layer, topoInstId, &descNum, endpointDesc);64HcclRankGraphGetEndpointDesc(comm, layer, topoInstId, &descNum, endpointDesc);
atomgit-bot
atomgit-botatomgit-bot7月22日

🟡 Medium Priority

变更行（第 58 行）：EndpointDesc endpointDesc[8] 将数组大小硬编码为 8，但注释说明"数组大小需不小于 num"，而 num 由 HcclRankGraphGetEndpointNum 动态返回。若实际端点数量超过 8，后续 HcclRankGraphGetEndpointDesc(comm, layer, topoInstId, &descNum, endpointDesc) 将发生缓冲区溢出，导致内存越界写入。示例代码应展示安全的动态分配或至少使用足够大的常量。

建议：将 endpointDesc 改为动态分配，先通过 HcclRankGraphGetEndpointNum 获取 num，再根据 num 值分配数组；或使用较大的常数值（如 1024）并在注释中说明上限。

likedislike
不准确？
59```65```
Mdocs/zh/api_ref/comm_opdev/control_plane_api/topo_info_query/HcclRankGraphGetEndpointInfo.md+15-6
@@ -45,19 +45,28 @@ HcclResult HcclRankGraphGetEndpointInfo(HcclComm comm, uint32_t rankId, const En
45 45 
46## 约束说明46## 约束说明
47 47 
48-无48+无。
49 49 
50## 调用示例50## 调用示例
51 51 
52```c52```c
53+// 通信域句柄
53HcclComm comm;54HcclComm comm;
54-uint32_t netLayer = 0;55+ 
56+// 获取EndPoint数量
57+uint32_t layer = 0;
55uint32_t topoInstId = 0;58uint32_t topoInstId = 0;
56uint32_t num = 0;59uint32_t num = 0;
57-HcclRankGraphGetEndpointNum(comm, netLayer, topoInstId, &num);60+HcclRankGraphGetEndpointNum(comm, layer, topoInstId, &num);
61+ 
62+// 获取EndPoint描述列表
58uint32_t descNum = num;63uint32_t descNum = num;
59-HcclRankGraphGetEndpointDesc(comm, netLayer, topoInstId, &descNum, endpointDesc);64+EndpointDesc endpointDesc[descNum];
60-EndpointAttrBwCoeff bwCoeff{};65+HcclRankGraphGetEndpointDesc(comm, layer, topoInstId, &descNum, endpointDesc);
61-uint32_t size = sizeof(EndpointAttrBwCoeff); //必须等于目标类型大小66+ 
67+// 获取拓扑属性信息
68+uint32_t rankId = 0; // 需要查询的端点所属的rank ID
69+EndpointAttrBwCoeff bwCoeff = {0};
70+uint32_t size = sizeof(EndpointAttrBwCoeff); // 必须等于目标类型大小
62HcclRankGraphGetEndpointInfo(comm, rankId, endpointDesc, ENDPOINT_ATTR_BW_COEFF, size, &bwCoeff);71HcclRankGraphGetEndpointInfo(comm, rankId, endpointDesc, ENDPOINT_ATTR_BW_COEFF, size, &bwCoeff);
63```72```
Mdocs/zh/api_ref/comm_opdev/control_plane_api/topo_info_query/HcclRankGraphGetRanksByLayer.md+4-4
@@ -65,9 +65,9 @@ HcclResult HcclRankGraphGetRanksByLayer(HcclComm comm, uint32_t netLayer, uint32
65HcclComm commTp;65HcclComm commTp;
66uint32_t* ranks = nullptr;66uint32_t* ranks = nullptr;
67uint32_t rankNum;67uint32_t rankNum;
68-HcclRankGraphGetRanksByLayer(commTp, netLayer=0, &ranks, &rankNum);68+HcclRankGraphGetRanksByLayer(commTp, 0, &ranks, &rankNum);
69// 对于0级拓扑，ranks=[0,1,2], rankNum=369// 对于0级拓扑，ranks=[0,1,2], rankNum=3
70-HcclRankGraphGetRanksByLayer(commTp, netLayer=1, &ranks, &rankNum);70+HcclRankGraphGetRanksByLayer(commTp, 1, &ranks, &rankNum);
71// 对于1级拓扑，ranks=[0,1,2,3,4,5], rankNum=671// 对于1级拓扑，ranks=[0,1,2,3,4,5], rankNum=6
72```72```
73 73 
@@ -77,8 +77,8 @@ HcclRankGraphGetRanksByLayer(commTp, netLayer=1, &ranks, &rankNum);
77HcclComm commTp;77HcclComm commTp;
78uint32_t* ranks = nullptr;78uint32_t* ranks = nullptr;
79uint32_t rankNum;79uint32_t rankNum;
80-HcclRankGraphGetRanksByLayer(commTp, netLayer=0, &ranks, &rankNum);80+HcclRankGraphGetRanksByLayer(commTp, 0, &ranks, &rankNum);
81// 对于0级拓扑，ranks=[3,4,5], rankNum=381// 对于0级拓扑，ranks=[3,4,5], rankNum=3
82-HcclRankGraphGetRanksByLayer(commTp, netLayer=1, &ranks, &rankNum);82+HcclRankGraphGetRanksByLayer(commTp, 1, &ranks, &rankNum);
83// 对于1级拓扑，ranks=[0,1,2,3,4,5], rankNum=683// 对于1级拓扑，ranks=[0,1,2,3,4,5], rankNum=6
84```84```
Mdocs/zh/api_ref/comm_opdev/control_plane_api/topo_info_query/HcclRankGraphGetRanksByTopoInst.md+2-2
@@ -52,10 +52,10 @@ HcclResult HcclRankGraphGetRanksByTopoInst(HcclComm comm, uint32_t netLayer, uin
52```c52```c
53 //8卡通信域，同一个8p Mesh53 //8卡通信域，同一个8p Mesh
54HcclComm comm;54HcclComm comm;
55-uint32_t netlayer = 0;55+uint32_t netLayer = 0;
56uint32_t topoInstId = 0;56uint32_t topoInstId = 0;
57uint32_t *ranks;57uint32_t *ranks;
58uint32_t rankNum;58uint32_t rankNum;
59-HcclRankGraphGetRanksByTopoInst( comm, netLayer, topoInstId, &ranks, &rankNum )59+HcclRankGraphGetRanksByTopoInst(comm, netLayer, topoInstId, &ranks, &rankNum);
60 // ranks = [0,1,2,…,7], rankNum=860 // ranks = [0,1,2,…,7], rankNum=8
61```61```
Mdocs/zh/api_ref/comm_opdev/control_plane_api/topo_info_query/HcclRankGraphGetTopoType.md+1-1
@@ -50,5 +50,5 @@ HcclResult HcclRankGraphGetTopoType(HcclComm comm, uint32_t netLayer, uint32_t t
50```c50```c
51HcclComm comm;51HcclComm comm;
52CommTopo topoType;52CommTopo topoType;
53-HcclRankGraphGetTopoType(comm, netLayer=0, topoInstId=0, &topoType); // topoType=1 (1DMesh)53+HcclRankGraphGetTopoType(comm, 0, 0, &topoType); // topoType=1 (1DMesh)
54```54```
Mdocs/zh/api_ref/comm_opdev/control_plane_api/topo_info_query/HcclRankGraphGetTopoTypeByLayer.md+2-2
@@ -59,7 +59,7 @@ HcclResult HcclRankGraphGetTopoTypeByLayer(HcclComm comm, uint32_t netLayer, Com
59 59 
60```c60```c
61HcclComm comm;61HcclComm comm;
62-uint32_t topoType;62+CommTopo topoType;
63HcclRankGraphGetTopoTypeByLayer(comm, 0, &topoType); 63HcclRankGraphGetTopoTypeByLayer(comm, 0, &topoType);
64// Layer0的topoType=1 (1DMesh)64// Layer0的topoType=1 (1DMesh)
65HcclRankGraphGetTopoTypeByLayer(comm, 1, &topoType); 65HcclRankGraphGetTopoTypeByLayer(comm, 1, &topoType);
@@ -70,7 +70,7 @@ HcclRankGraphGetTopoTypeByLayer(comm, 1, &topoType);
70 70 
71```c71```c
72HcclComm comm;72HcclComm comm;
73-uint32_t topoType;73+CommTopo topoType;
74HcclRankGraphGetTopoTypeByLayer(comm, 0, &topoType); 74HcclRankGraphGetTopoTypeByLayer(comm, 0, &topoType);
75// Layer0的topoType=0 (Clos)75// Layer0的topoType=0 (Clos)
76HcclRankGraphGetTopoTypeByLayer(comm, 1, &topoType); 76HcclRankGraphGetTopoTypeByLayer(comm, 1, &topoType);
Mdocs/zh/api_ref/comm_opdev/control_plane_api/topo_info_query/README.md+15-15
@@ -1,17 +1,17 @@
1# 拓扑信息查询1# 拓扑信息查询
2 2 
3-- [HcclGetRankId](HcclGetRankId.md) 3+- [HcclGetRankId](HcclGetRankId.md)
4-- [HcclGetRankSize](HcclGetRankSize.md) 4+- [HcclGetRankSize](HcclGetRankSize.md)
5-- [HcclRankGraphGetLayers](HcclRankGraphGetLayers.md) 5+- [HcclRankGraphGetLayers](HcclRankGraphGetLayers.md)
6-- [HcclRankGraphGetRanksByLayer](HcclRankGraphGetRanksByLayer.md) 6+- [HcclRankGraphGetRanksByLayer](HcclRankGraphGetRanksByLayer.md)
7-- [HcclRankGraphGetRankSizeByLayer](HcclRankGraphGetRankSizeByLayer.md) 7+- [HcclRankGraphGetRankSizeByLayer](HcclRankGraphGetRankSizeByLayer.md)
8-- [HcclRankGraphGetTopoTypeByLayer](HcclRankGraphGetTopoTypeByLayer.md) 8+- [HcclRankGraphGetTopoTypeByLayer](HcclRankGraphGetTopoTypeByLayer.md)
9-- [HcclRankGraphGetInstSizeListByLayer](HcclRankGraphGetInstSizeListByLayer.md) 9+- [HcclRankGraphGetInstSizeListByLayer](HcclRankGraphGetInstSizeListByLayer.md)
10-- [HcclRankGraphGetLinks](HcclRankGraphGetLinks.md) 10+- [HcclRankGraphGetLinks](HcclRankGraphGetLinks.md)
11-- [HcclRankGraphGetTopoInstsByLayer](HcclRankGraphGetTopoInstsByLayer.md) 11+- [HcclRankGraphGetTopoInstsByLayer](HcclRankGraphGetTopoInstsByLayer.md)
12-- [HcclRankGraphGetTopoType](HcclRankGraphGetTopoType.md) 12+- [HcclRankGraphGetTopoType](HcclRankGraphGetTopoType.md)
13-- [HcclRankGraphGetRanksByTopoInst](HcclRankGraphGetRanksByTopoInst.md) 13+- [HcclRankGraphGetRanksByTopoInst](HcclRankGraphGetRanksByTopoInst.md)
14-- [HcclGetHeterogMode](HcclGetHeterogMode.md) 14+- [HcclGetHeterogMode](HcclGetHeterogMode.md)
15-- [HcclRankGraphGetEndpointNum](HcclRankGraphGetEndpointNum.md) 15+- [HcclRankGraphGetEndpointNum](HcclRankGraphGetEndpointNum.md)
16-- [HcclRankGraphGetEndpointDesc](HcclRankGraphGetEndpointDesc.md) 16+- [HcclRankGraphGetEndpointDesc](HcclRankGraphGetEndpointDesc.md)
17-- [HcclRankGraphGetEndpointInfo](HcclRankGraphGetEndpointInfo.md) 17+- [HcclRankGraphGetEndpointInfo](HcclRankGraphGetEndpointInfo.md)
Mdocs/zh/api_ref/comm_opdev/data_plane_api/ccu/arg_load_store/LoadArg.md+1-1
@@ -84,7 +84,7 @@ CcuResult MyKernel(CcuKernelArg arg) {
84 return CCU_SUCCESS;84 return CCU_SUCCESS;
85}85}
86 86 
87-// host侧对应的Launch调用（示意）：87+// Host侧对应的Launch调用（示意）：
88// uint64_t taskArgs[] = {100, 4096}; // n=100轮，offset=4096字节88// uint64_t taskArgs[] = {100, 4096}; // n=100轮，offset=4096字节
89// HcommCcuKernelLaunch(..., taskArgs, /*argNum=*/2);89// HcommCcuKernelLaunch(..., taskArgs, /*argNum=*/2);
90```90```
Mdocs/zh/api_ref/comm_opdev/data_plane_api/ccu/data_movement/LocalReduce.md+4-4
@@ -25,7 +25,7 @@
25| 重载 | 数据通路 | 归约方式 |25| 重载 | 数据通路 | 归约方式 |
26| --- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |26| --- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
27| 重载1 | 本端HBM（`src`）→本端HBM（`dst`） | `dst = reduce(dst, src, opType)`，输入输出类型相同 |27| 重载1 | 本端HBM（`src`）→本端HBM（`dst`） | `dst = reduce(dst, src, opType)`，输入输出类型相同 |
28-| 重载2 | N 个本端MS Buffer → `buffers[0]`（2 ≤ N ≤ 8） | `buffers[0] = reduce(buffers[0..N-1], opType)`，硬件一次性归约N 路MS 到 `buffers[0]`。输入数据类型可以为（`HCCL_DATA_TYPE_UINT8`/`HCCL_DATA_TYPE_INT16`/`HCCL_DATA_TYPE_INT32`/`HCCL_DATA_TYPE_FP16`/`HCCL_DATA_TYPE_BF16`/`HCCL_DATA_TYPE_FP32`），输出数据类型支持与输入同精度，或在 `HCCL_REDUCE_SUM` 下升精度输出（详见 `outputDataType` 参数说明）。 |28+| 重载2 | N 个本端MS Buffer → `buffers[0]`（2 ≤ N ≤ 8） | `buffers[0] = reduce(buffers[0..N-1], opType)`，硬件一次性归约N 路MS 到 `buffers[0]`。输入数据类型可以为（`HCCL_DATA_TYPE_UINT8`/`HCCL_DATA_TYPE_INT16`/`HCCL_DATA_TYPE_INT32`/`HCCL_DATA_TYPE_FP16`/`HCCL_DATA_TYPE_BFP16`/`HCCL_DATA_TYPE_FP32`），输出数据类型支持与输入同精度，或在 `HCCL_REDUCE_SUM` 下升精度输出（详见 `outputDataType` 参数说明）。 |
29 29 
30> [!NOTE]说明30> [!NOTE]说明
31> 本接口为异步接口，调用后须通过`EventWait(event, mask)`等待归约完成，否则目标内存数据不确定。归约为原地操作，调用前`dst`（重载1）或`buffers[0]`（重载2）须已写入有效初值（如0或负无穷）。31> 本接口为异步接口，调用后须通过`EventWait(event, mask)`等待归约完成，否则目标内存数据不确定。归约为原地操作，调用前`dst`（重载1）或`buffers[0]`（重载2）须已写入有效初值（如0或负无穷）。
@@ -57,8 +57,8 @@ CcuResult LocalReduce(CcuBuffer* buffers, uint32_t count,
57| dst | 输入/输出 | 目标HBM地址（`LocalAddr`）。调用前须写入有效初值；硬件完成后更新为归约结果。 |57| dst | 输入/输出 | 目标HBM地址（`LocalAddr`）。调用前须写入有效初值；硬件完成后更新为归约结果。 |
58| src | 输入 | 源HBM地址（`LocalAddr`）。 |58| src | 输入 | 源HBM地址（`LocalAddr`）。 |
59| len | 输入 | 操作字节数，类型为`Variable`（运行期可变长度）。 |59| len | 输入 | 操作字节数，类型为`Variable`（运行期可变长度）。 |
60-| dataType | 输入 | 数据类型，取值见`HcclDataType`枚举。仅支持以下6种：`HCCL_DATA_TYPE_UINT8`、`HCCL_DATA_TYPE_INT16`、`HCCL_DATA_TYPE_INT32`、`HCCL_DATA_TYPE_FP16`、`HCCL_DATA_TYPE_FP32`、`HCCL_DATA_TYPE_BF16`；其他取值会被拒绝并抛出异常（携带错误码）。 |60+| dataType | 输入 | 数据类型，取值见`HcclDataType`枚举。仅支持以下6种：`HCCL_DATA_TYPE_UINT8`、`HCCL_DATA_TYPE_INT16`、`HCCL_DATA_TYPE_INT32`、`HCCL_DATA_TYPE_FP16`、`HCCL_DATA_TYPE_FP32`、`HCCL_DATA_TYPE_BFP16`；其他取值会被拒绝并抛出异常（携带错误码）。 |
61-| opType | 输入 | 归约算子，取值见`HcclReduceOp`枚举。仅支持`HCCL_REDUCE_SUM`（求和）、`HCCL_REDUCE_MAX`（最大值）、`HCCL_REDUCE_MIN`（最小值）；`HCCL_REDUCE_PROD`不支持，传入会被拒绝并抛出异常（携带错误码）。 当采用SUM操作时低精度输入数据的求和结果会先进行精度上升然后再进行精度调整为与输入数据精度相同 |61+| opType | 输入 | 归约算子，取值见`HcclReduceOp`枚举。仅支持`HCCL_REDUCE_SUM`（求和）、`HCCL_REDUCE_MAX`（最大值）、`HCCL_REDUCE_MIN`（最小值）；`HCCL_REDUCE_PROD`不支持，传入会被拒绝并抛出异常（携带错误码）。 当采用SUM操作时低精度输入数据的求和结果会先进行精度上升然后再进行精度调整为与输入数据精度相同。 |
62| event | 输入 | 完成事件对象。硬件归约完成时自动置位`event[mask]`。 |62| event | 输入 | 完成事件对象。硬件归约完成时自动置位`event[mask]`。 |
63| mask | 输入 | 16位事件掩码。默认值为`1`（即bit0）。 |63| mask | 输入 | 16位事件掩码。默认值为`1`（即bit0）。 |
64 64 
@@ -68,7 +68,7 @@ CcuResult LocalReduce(CcuBuffer* buffers, uint32_t count,
68| -------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |68| -------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
69| buffers | 输入/输出 | MS Buffer数组首地址（`CcuBuffer*`），不可为`nullptr`。推荐通过`ccu::Array<CcuBuffer>`申请以保证物理连续。`buffers[0]`为归约结果的输出位置，调用前须写入有效初值。精度膨胀场景（低精度输入 + SUM 升精度输出，如INT8→FP32时输出元素4×于输入）下，传入的MS 数组须同时覆盖输入与膨胀后的输出占用（例如2路INT8输入升FP32输出时须预留4个MS，而非2个）；预留不足会导致硬件读写越界、行为未定义。 |69| buffers | 输入/输出 | MS Buffer数组首地址（`CcuBuffer*`），不可为`nullptr`。推荐通过`ccu::Array<CcuBuffer>`申请以保证物理连续。`buffers[0]`为归约结果的输出位置，调用前须写入有效初值。精度膨胀场景（低精度输入 + SUM 升精度输出，如INT8→FP32时输出元素4×于输入）下，传入的MS 数组须同时覆盖输入与膨胀后的输出占用（例如2路INT8输入升FP32输出时须预留4个MS，而非2个）；预留不足会导致硬件读写越界、行为未定义。 |
70| count | 输入 | Buffer数量。取值范围为`[2, 8]`（超过上限会抛出异常并携带错误码）。`count == 0` 会被直接拒绝并返回`CCU_E_PARA`；`count == 1`不会被拒绝但硬件行为未定义，单Buffer 场景请用重载1。`count`须等于`buffers`数组实际长度。 |70| count | 输入 | Buffer数量。取值范围为`[2, 8]`（超过上限会抛出异常并携带错误码）。`count == 0` 会被直接拒绝并返回`CCU_E_PARA`；`count == 1`不会被拒绝但硬件行为未定义，单Buffer 场景请用重载1。`count`须等于`buffers`数组实际长度。 |
71-| dataType | 输入 | 输入数据类型，取值见`HcclDataType`枚举。仅支持以下6种：`HCCL_DATA_TYPE_UINT8`、`HCCL_DATA_TYPE_INT16`、`HCCL_DATA_TYPE_INT32`、`HCCL_DATA_TYPE_FP16`、`HCCL_DATA_TYPE_FP32`、`HCCL_DATA_TYPE_BF16`。 其他取值会被拒绝并抛出异常（携带错误码）。 |71+| dataType | 输入 | 输入数据类型，取值见`HcclDataType`枚举。仅支持以下6种：`HCCL_DATA_TYPE_UINT8`、`HCCL_DATA_TYPE_INT16`、`HCCL_DATA_TYPE_INT32`、`HCCL_DATA_TYPE_FP16`、`HCCL_DATA_TYPE_FP32`、`HCCL_DATA_TYPE_BFP16`。 其他取值会被拒绝并抛出异常（携带错误码）。 |
72| outputDataType | 输入 | 输出数据类型，取值见`HcclDataType`枚举。支持两种组合：①同精度——取值与`dataType`相同；②升精度——仅在`opType == HCCL_REDUCE_SUM`时支持，将低精度输入归约后升至高精度输出（如`HCCL_DATA_TYPE_INT8`→`HCCL_DATA_TYPE_FP32`，见"调用示例 - 场景2"）。其他`dataType`/`outputDataType`组合返回`CCU_E_NOT_SUPPORT`（见返回值表）。升精度场景下`buffers`须按精度膨胀比例预留 MS，详见`buffers`参数说明。 |72| outputDataType | 输入 | 输出数据类型，取值见`HcclDataType`枚举。支持两种组合：①同精度——取值与`dataType`相同；②升精度——仅在`opType == HCCL_REDUCE_SUM`时支持，将低精度输入归约后升至高精度输出（如`HCCL_DATA_TYPE_INT8`→`HCCL_DATA_TYPE_FP32`，见"调用示例 - 场景2"）。其他`dataType`/`outputDataType`组合返回`CCU_E_NOT_SUPPORT`（见返回值表）。升精度场景下`buffers`须按精度膨胀比例预留 MS，详见`buffers`参数说明。 |
73| opType | 输入 | 归约算子，取值见`HcclReduceOp`枚举。仅支持`HCCL_REDUCE_SUM`、`HCCL_REDUCE_MAX`、`HCCL_REDUCE_MIN`；`HCCL_REDUCE_PROD`不支持，传入会被拒绝并抛出异常（携带错误码）。 |73| opType | 输入 | 归约算子，取值见`HcclReduceOp`枚举。仅支持`HCCL_REDUCE_SUM`、`HCCL_REDUCE_MAX`、`HCCL_REDUCE_MIN`；`HCCL_REDUCE_PROD`不支持，传入会被拒绝并抛出异常（携带错误码）。 |
74| len | 输入 | 每个Buffer参与归约的字节数，类型为`Variable`，不可超过单片大小（4096字节）。 |74| len | 输入 | 每个Buffer参与归约的字节数，类型为`Variable`，不可超过单片大小（4096字节）。 |
Mdocs/zh/api_ref/comm_opdev/data_plane_api/ccu/data_movement/ReadReduce.md+2-2
@@ -50,8 +50,8 @@ CcuResult ReadReduce(ChannelHandle ch, LocalAddr local, RemoteAddr remote,
50| local | 输入/输出 | 本端HBM目标地址（`LocalAddr`）。调用前须写入有效初值；硬件完成后更新为归约结果。 |50| local | 输入/输出 | 本端HBM目标地址（`LocalAddr`）。调用前须写入有效初值；硬件完成后更新为归约结果。 |
51| remote | 输入 | 对端HBM源地址（`RemoteAddr`）。 |51| remote | 输入 | 对端HBM源地址（`RemoteAddr`）。 |
52| len | 输入 | 操作字节数，类型为`Variable`（运行期可变长度）。 |52| len | 输入 | 操作字节数，类型为`Variable`（运行期可变长度）。 |
53-| dataType | 输入 | 数据类型，取值见`HcclDataType`枚举。仅支持以下6种：`HCCL_DATA_TYPE_UINT8`、`HCCL_DATA_TYPE_INT16`、`HCCL_DATA_TYPE_INT32`、`HCCL_DATA_TYPE_FP16`、`HCCL_DATA_TYPE_FP32`、`HCCL_DATA_TYPE_BF16`；其他取值会被拒绝并抛出异常（携带错误码）。 |53+| dataType | 输入 | 数据类型，取值见`HcclDataType`枚举。仅支持以下6种：`HCCL_DATA_TYPE_UINT8`、`HCCL_DATA_TYPE_INT16`、`HCCL_DATA_TYPE_INT32`、`HCCL_DATA_TYPE_FP16`、`HCCL_DATA_TYPE_FP32`、`HCCL_DATA_TYPE_BFP16`；其他取值会被拒绝并抛出异常（携带错误码）。 |
54-| opType | 输入 | 归约算子，取值见`HcclReduceOp`枚举。仅支持`HCCL_REDUCE_SUM`（求和）、`HCCL_REDUCE_MAX`（最大值）、`HCCL_REDUCE_MIN`（最小值）；`HCCL_REDUCE_PROD`不支持，传入会被拒绝并抛出异常（携带错误码）。 当采用SUM操作时低精度输入数据的求和结果会先进行精度上升然后再进行精度调整为与输入数据精度相同|54+| opType | 输入 | 归约算子，取值见`HcclReduceOp`枚举。仅支持`HCCL_REDUCE_SUM`（求和）、`HCCL_REDUCE_MAX`（最大值）、`HCCL_REDUCE_MIN`（最小值）；`HCCL_REDUCE_PROD`不支持，传入会被拒绝并抛出异常（携带错误码）。 当采用SUM操作时低精度输入数据的求和结果会先进行精度上升然后再进行精度调整为与输入数据精度相同。 |
55| event | 输入 | 完成事件对象。硬件归约读完成时自动置位`event[mask]`，下游调用`EventWait(event, mask)`等待。 |55| event | 输入 | 完成事件对象。硬件归约读完成时自动置位`event[mask]`，下游调用`EventWait(event, mask)`等待。 |
56| mask | 输入 | 16位事件掩码。默认值为`1`（即bit0）。 |56| mask | 输入 | 16位事件掩码。默认值为`1`（即bit0）。 |
57 57 
Mdocs/zh/api_ref/comm_opdev/data_plane_api/ccu/data_movement/WriteReduce.md+2-2
@@ -47,8 +47,8 @@ CcuResult WriteReduce(ChannelHandle ch, RemoteAddr remote, LocalAddr local,
47| remote | 输入 | 对端HBM目标地址（`RemoteAddr`）。对端内存在调用前须已写入有效初值（由对端kernel负责写入）；硬件完成后该地址内容更新为归约结果。 |47| remote | 输入 | 对端HBM目标地址（`RemoteAddr`）。对端内存在调用前须已写入有效初值（由对端kernel负责写入）；硬件完成后该地址内容更新为归约结果。 |
48| local | 输入 | 本端HBM源地址（`LocalAddr`）。 |48| local | 输入 | 本端HBM源地址（`LocalAddr`）。 |
49| len | 输入 | 操作字节数，类型为`Variable`（运行期可变长度）。 |49| len | 输入 | 操作字节数，类型为`Variable`（运行期可变长度）。 |
50-| dataType | 输入 | 数据类型，取值见`HcclDataType`枚举。仅支持以下6种：`HCCL_DATA_TYPE_UINT8`、`HCCL_DATA_TYPE_INT16`、`HCCL_DATA_TYPE_INT32`、`HCCL_DATA_TYPE_FP16`、`HCCL_DATA_TYPE_FP32`、`HCCL_DATA_TYPE_BF16`；其他取值会被拒绝并抛出异常（携带错误码）。 |50+| dataType | 输入 | 数据类型，取值见`HcclDataType`枚举。仅支持以下6种：`HCCL_DATA_TYPE_UINT8`、`HCCL_DATA_TYPE_INT16`、`HCCL_DATA_TYPE_INT32`、`HCCL_DATA_TYPE_FP16`、`HCCL_DATA_TYPE_FP32`、`HCCL_DATA_TYPE_BFP16`；其他取值会被拒绝并抛出异常（携带错误码）。 |
51-| opType | 输入 | 归约算子，取值见`HcclReduceOp`枚举。仅支持`HCCL_REDUCE_SUM`（求和）、`HCCL_REDUCE_MAX`（最大值）、`HCCL_REDUCE_MIN`（最小值）；`HCCL_REDUCE_PROD`不支持，传入会被拒绝并抛出异常（携带错误码）。 当采用SUM操作时低精度输入数据的求和结果会先进行精度上升然后再进行精度调整为与输入数据精度相同|51+| opType | 输入 | 归约算子，取值见`HcclReduceOp`枚举。仅支持`HCCL_REDUCE_SUM`（求和）、`HCCL_REDUCE_MAX`（最大值）、`HCCL_REDUCE_MIN`（最小值）；`HCCL_REDUCE_PROD`不支持，传入会被拒绝并抛出异常（携带错误码）。 当采用SUM操作时低精度输入数据的求和结果会先进行精度上升然后再进行精度调整为与输入数据精度相同。 |
52| event | 输入 | 完成事件对象。硬件归约写完成时自动置位`event[mask]`，下游调用`EventWait(event, mask)`等待。 |52| event | 输入 | 完成事件对象。硬件归约写完成时自动置位`event[mask]`，下游调用`EventWait(event, mask)`等待。 |
53| mask | 输入 | 16位事件掩码。默认值为`1`（即bit0）。 |53| mask | 输入 | 16位事件掩码。默认值为`1`（即bit0）。 |
54 54 
Mdocs/zh/api_ref/comm_opdev/data_plane_api/ccu/execution_control/CCU_IF.md+1-1
@@ -52,7 +52,7 @@ CCU_IF(condExpr) {
52## 约束说明52## 约束说明
53 53 
54- `CCU_IF（condExpr）`后必须紧跟{}包裹的then代码块54- `CCU_IF（condExpr）`后必须紧跟{}包裹的then代码块
55-- A5代际的`CCU_IF`当前的`condExpr`只支持==和！=两种判断模式55+- A5代际的`CCU_IF`当前的`condExpr`只支持==和!=两种判断模式
56- `CCU_IF`可以单独使用（无`CCU_ELSE`），也可以配合`CCU_ELSE`使用，两种写法均合法。56- `CCU_IF`可以单独使用（无`CCU_ELSE`），也可以配合`CCU_ELSE`使用，两种写法均合法。
57- 支持嵌套：`CCU_IF`内部可以再嵌套`CCU_IF`。57- 支持嵌套：`CCU_IF`内部可以再嵌套`CCU_IF`。
58- `CCU_IF`不建议在硬件Loop（`ccu::Loop`）的body lambda内部使用——硬件Loop body内不支持软件分支；框架不强制校验，但行为未定义。58- `CCU_IF`不建议在硬件Loop（`ccu::Loop`）的body lambda内部使用——硬件Loop body内不支持软件分支；框架不强制校验，但行为未定义。
Mdocs/zh/api_ref/comm_opdev/data_plane_api/ccu/execution_control/CCU_WHILE.md+2-2
@@ -55,8 +55,8 @@ CCU_DO {
55 55 
56## 约束说明56## 约束说明
57 57 
58-- `CCU_WHILE（condExpr）`后必须紧跟{}包裹的循环代码块58+- `CCU_WHILE（condExpr）`后必须紧跟{}包裹的循环代码块。
59-- A5代际的`CCU_WHILE`当前的`condExpr`只支持==和！=两种判断模式59+- 针对Ascend 950PR/Ascend 950DT，`CCU_WHILE`当前的`condExpr`只支持==和!=两种判断模式。
60- `condExpr`中比较的立即数（`imm`）必须为`uint64_t`类型。60- `condExpr`中比较的立即数（`imm`）必须为`uint64_t`类型。
61- 作为独立while循环使用时，`CCU_WHILE`可以嵌套，内层`CCU_WHILE`可在外层`CCU_WHILE`的body内使用。61- 作为独立while循环使用时，`CCU_WHILE`可以嵌套，内层`CCU_WHILE`可在外层`CCU_WHILE`的body内使用。
62- `CCU_WHILE`（独立while）可以与`CCU_IF`组合嵌套。62- `CCU_WHILE`（独立while）可以与`CCU_IF`组合嵌套。
Mdocs/zh/api_ref/comm_opdev/data_plane_api/ccu/execution_control/LoopGroup.md+1-1
@@ -59,7 +59,7 @@ public:
59 59 
60| 参数名 | 输入/输出 | 描述 |60| 参数名 | 输入/输出 | 描述 |
61| --- | --- | --- |61| --- | --- | --- |
62-| parallelCfg | 输入 | 并行配置Variable，运行期决定并行参数。该参数包含64bit，其中[47:41]表示loopgroup内包含的Loop指令个数，其中[54:48]表似乎Loopgroup中包含的Loop指令需要完成Loop自动展开的Loop偏移，其中[61:55]表示Loop需要展开的次数。举例：X[47:41]=4表示程序中包含4个Loop指令，Xn[54:48]=1表示从编号为1的Loop开始展开，Xn[61:55]=3表示loop1，loop2，loop3分别复制展开3次，loop0不进行复制，经过展开后总Loop个数为4 + (4-1) * 3 = 13 |62+| parallelCfg | 输入 | 并行配置Variable，运行期决定并行参数。该参数包含64bit，其中[47:41]表示loopgroup内包含的Loop指令个数，其中[54:48]表示Loopgroup中包含的Loop指令需要完成Loop自动展开的Loop偏移，其中[61:55]表示Loop需要展开的次数。举例：X[47:41]=4表示程序中包含4个Loop指令，Xn[54:48]=1表示从编号为1的Loop开始展开，Xn[61:55]=3表示loop1，loop2，loop3分别复制展开3次，loop0不进行复制，经过展开后总Loop个数为4 + (4-1) * 3 = 13 |
63| offsetCfg | 输入 | 偏移配置Variable，运行期决定偏移参数。 该参数包含64bit，其中[9:0]表示Loop进行展开后使用的Event资源偏移量，[20:10]表示Loop进行展开后使用的CcuBuffer资源偏移量，[52:21]表示Loop进行展开后各个数据传输类指令使用的Address累加的偏移量。|63| offsetCfg | 输入 | 偏移配置Variable，运行期决定偏移参数。 该参数包含64bit，其中[9:0]表示Loop进行展开后使用的Event资源偏移量，[20:10]表示Loop进行展开后使用的CcuBuffer资源偏移量，[52:21]表示Loop进行展开后各个数据传输类指令使用的Address累加的偏移量。|
64| maxLoopNum | 输入 | 同构造方式1。 |64| maxLoopNum | 输入 | 同构造方式1。 |
65| loops | 输入 | 同构造方式1。 |65| loops | 输入 | 同构造方式1。 |
Mdocs/zh/api_ref/comm_opdev/data_plane_api/cpu-cpu_ts-aicpu_ts/README.md+11-11
@@ -9,23 +9,23 @@
9 - [HcommAclrtNotifyRecordOnThread](./local_operations/HcommAclrtNotifyRecordOnThread.md)9 - [HcommAclrtNotifyRecordOnThread](./local_operations/HcommAclrtNotifyRecordOnThread.md)
10 - [HcommAclrtNotifyWaitOnThread](./local_operations/HcommAclrtNotifyWaitOnThread.md)10 - [HcommAclrtNotifyWaitOnThread](./local_operations/HcommAclrtNotifyWaitOnThread.md)
11- [通信操作](./communication_operations/_dump_node.md)11- [通信操作](./communication_operations/_dump_node.md)
12- - [HcommWriteOnThread](./communication_operations/HcommWriteOnThread.md) 12+ - [HcommWriteOnThread](./communication_operations/HcommWriteOnThread.md)
13- - [HcommWriteNbiOnThread](./communication_operations/HcommWriteNbiOnThread.md) 13+ - [HcommWriteNbiOnThread](./communication_operations/HcommWriteNbiOnThread.md)
14 - [HcommWriteNbi](./communication_operations/HcommWriteNbi.md)14 - [HcommWriteNbi](./communication_operations/HcommWriteNbi.md)
15- - [HcommWriteReduceOnThread](./communication_operations/HcommWriteReduceOnThread.md) 15+ - [HcommWriteReduceOnThread](./communication_operations/HcommWriteReduceOnThread.md)
16- - [HcommReadOnThread](./communication_operations/HcommReadOnThread.md) 16+ - [HcommReadOnThread](./communication_operations/HcommReadOnThread.md)
17- - [HcommReadNbiOnThread](./communication_operations/HcommReadNbiOnThread.md) 17+ - [HcommReadNbiOnThread](./communication_operations/HcommReadNbiOnThread.md)
18 - [HcommReadNbi](./communication_operations/HcommReadNbi.md)18 - [HcommReadNbi](./communication_operations/HcommReadNbi.md)
19- - [HcommReadReduceOnThread](./communication_operations/HcommReadReduceOnThread.md) 19+ - [HcommReadReduceOnThread](./communication_operations/HcommReadReduceOnThread.md)
20- - [HcommChannelNotifyRecordOnThread](./communication_operations/HcommChannelNotifyRecordOnThread.md) 20+ - [HcommChannelNotifyRecordOnThread](./communication_operations/HcommChannelNotifyRecordOnThread.md)
21 - [HcommChannelNotifyRecord](./communication_operations/HcommChannelNotifyRecord.md)21 - [HcommChannelNotifyRecord](./communication_operations/HcommChannelNotifyRecord.md)
22- - [HcommChannelNotifyWaitOnThread](./communication_operations/HcommChannelNotifyWaitOnThread.md) 22+ - [HcommChannelNotifyWaitOnThread](./communication_operations/HcommChannelNotifyWaitOnThread.md)
23 - [HcommChannelNotifyWait](./communication_operations/HcommChannelNotifyWait.md)23 - [HcommChannelNotifyWait](./communication_operations/HcommChannelNotifyWait.md)
24 - [HcommChannelNotifyWaitOnThreadWithDefaultTimeout](./communication_operations/HcommChannelNotifyWaitOnThreadWithDefaultTimeout.md)24 - [HcommChannelNotifyWaitOnThreadWithDefaultTimeout](./communication_operations/HcommChannelNotifyWaitOnThreadWithDefaultTimeout.md)
25- - [HcommWriteWithNotifyOnThread](./communication_operations/HcommWriteWithNotifyOnThread.md) 25+ - [HcommWriteWithNotifyOnThread](./communication_operations/HcommWriteWithNotifyOnThread.md)
26- - [HcommWriteWithNotifyNbiOnThread](./communication_operations/HcommWriteWithNotifyNbiOnThread.md) 26+ - [HcommWriteWithNotifyNbiOnThread](./communication_operations/HcommWriteWithNotifyNbiOnThread.md)
27 - [HcommWriteWithNotifyNbi](./communication_operations/HcommWriteWithNotifyNbi.md)27 - [HcommWriteWithNotifyNbi](./communication_operations/HcommWriteWithNotifyNbi.md)
28- - [HcommWriteReduceWithNotifyOnThread](./communication_operations/HcommWriteReduceWithNotifyOnThread.md) 28+ - [HcommWriteReduceWithNotifyOnThread](./communication_operations/HcommWriteReduceWithNotifyOnThread.md)
29 - [HcommChannelFenceOnThread](./communication_operations/HcommChannelFenceOnThread.md)29 - [HcommChannelFenceOnThread](./communication_operations/HcommChannelFenceOnThread.md)
30 - [HcommChannelFence](./communication_operations/HcommChannelFence.md)30 - [HcommChannelFence](./communication_operations/HcommChannelFence.md)
31 - [HcommFenceOnThread](./communication_operations/HcommFenceOnThread.md)31 - [HcommFenceOnThread](./communication_operations/HcommFenceOnThread.md)
Mdocs/zh/api_ref/comm_opdev/data_plane_api/cpu-cpu_ts-aicpu_ts/communication_operations/HcommBatchTransferOnThread.md+1-1
@@ -20,7 +20,7 @@
20 20 
21## 功能说明21## 功能说明
22 22 
23-在指定线程和通道上异步提交一组传输任务。每个传输任务由[HcommBatchTransferDesc](../../../datatype_definition/HcommBatchTransferDesc.md)描述，支持单边写、单边读、写规约、带通知的写以及通知记录/等待等操作类型。23+在指定线程和通道上异步提交一组传输任务。每个传输任务由[HcommBatchTransferDesc](../../../datatype_definition/HcommBatchTransferDesc.md)描述，支持单边写、单边读、写归约、带通知的写以及通知记录/等待等操作类型。
24 24 
25## 函数原型25## 函数原型
26 26 
Mdocs/zh/api_ref/comm_opdev/data_plane_api/cpu-cpu_ts-aicpu_ts/communication_operations/HcommChannelDrainOnThread.md+5-7
@@ -25,16 +25,15 @@
25## 函数原型25## 函数原型
26 26 
27```c27```c
28-int32_t HcommChannelDrainOnThread(ThreadHandle thread, ChannelHandle channel, uint32_t timeout)28+int32_t HcommChannelDrainOnThread(ThreadHandle thread, ChannelHandle channel)
29```29```
30 30 
31## 参数说明31## 参数说明
32 32 
33| 参数名 | 输入/输出 | 描述 |33| 参数名 | 输入/输出 | 描述 |
34| --- | --- | --- |34| --- | --- | --- |
35-| thread | 输入 | 通信线程句柄。Host CPU侧调用时，该参数无作用，传入0即可。<br>ThreadHandle类型的定义可参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。35+| thread | 输入 | 通信线程句柄。<br>ThreadHandle类型的定义可参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |
36| channel | 输入 | 通信通道句柄，为[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口获取到的channels。<br>ChannelHandle类型的定义可参见[ChannelHandle](../../../datatype_definition/ChannelHandle.md)。 |36| channel | 输入 | 通信通道句柄，为[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口获取到的channels。<br>ChannelHandle类型的定义可参见[ChannelHandle](../../../datatype_definition/ChannelHandle.md)。 |
37-| timeout | 输入 | 超时时间。 |
38 37 
39## 返回值38## 返回值
40 39 
@@ -51,14 +50,14 @@ int32_t：接口成功返回0，其他失败。
51CommEngine engine = CommEngine::COMM_ENGINE_AICPU_TS;50CommEngine engine = CommEngine::COMM_ENGINE_AICPU_TS;
52uint32_t threadNum = 1;51uint32_t threadNum = 1;
53uint32_t notifyNumPerThread = 1;52uint32_t notifyNumPerThread = 1;
53+HcclComm comm;
54ThreadHandle thread;54ThreadHandle thread;
55-HcclThreadAcquire(engine, threadNum, notifyNumPerThread, &thread);55+HcclThreadAcquire(comm, engine, threadNum, notifyNumPerThread, &thread);
56 56 
57// 申请通信通道资源57// 申请通信通道资源
58uint32_t channelNum = 1;58uint32_t channelNum = 1;
59HcclChannelDesc channelDesc;59HcclChannelDesc channelDesc;
60HcclChannelDescInit(&channelDesc, channelNum);60HcclChannelDescInit(&channelDesc, channelNum);
61-HcclComm comm;
62ChannelHandle channel;61ChannelHandle channel;
63HcclChannelAcquire(comm, engine, &channelDesc, channelNum, &channel);62HcclChannelAcquire(comm, engine, &channelDesc, channelNum, &channel);
64 63 
@@ -76,6 +75,5 @@ uint64_t len = std::min(localBufferSize, remoteBufferSize);
76// 将对端内存的内容读到本端内存上75// 将对端内存的内容读到本端内存上
77HcommReadOnThread(thread, channel, localBuffer, remoteBuffer, len);76HcommReadOnThread(thread, channel, localBuffer, remoteBuffer, len);
78 77 
79-uint32_t timeout = 120;78+HcommChannelDrainOnThread(thread, channel);
80-HcommChannelDrainOnThread(thread, channel, timeout);
81```79```
Mdocs/zh/api_ref/comm_opdev/data_plane_api/cpu-cpu_ts-aicpu_ts/communication_operations/HcommChannelNotifyRecordOnThread.md+1-1
@@ -34,7 +34,7 @@ int32_t HcommChannelNotifyRecordOnThread(ThreadHandle thread, ChannelHandle chan
34| --- | --- | --- |34| --- | --- | --- |
35| thread | 输入 | 通信线程句柄。针对Ascend 950PR/Ascend 950DT的CPU引擎RoCE场景，该参数无作用，传入0即可；CPU_TS/AICPU_TS场景下，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义可参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |35| thread | 输入 | 通信线程句柄。针对Ascend 950PR/Ascend 950DT的CPU引擎RoCE场景，该参数无作用，传入0即可；CPU_TS/AICPU_TS场景下，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义可参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |
36| channel | 输入 | 通信通道句柄，为通过[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口获取到的channels。关于channel的约束参见约束说明。<br>ChannelHandle类型的定义可参见[ChannelHandle](../../../datatype_definition/ChannelHandle.md)。 |36| channel | 输入 | 通信通道句柄，为通过[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口获取到的channels。关于channel的约束参见约束说明。<br>ChannelHandle类型的定义可参见[ChannelHandle](../../../datatype_definition/ChannelHandle.md)。 |
37-| remoteNotifyIdx | 输入 | 通信通道另一端的Notify索引。<br>取值范围：[0, notifyNum)。<br>notifyNum为[HcommChannelCreate](../../../control_plane_api/basic_resource_mgmt/HcommChannelCreate.md)或[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口传入的channelDesc参数中的notifyNum。 |37+| remoteNotifyIdx | 输入 | 通信通道另一端的Notify索引。<br>取值范围：[0, notifyNum)。<br>notifyNum为[HcommChannelCreate](../../../control_plane_api/basic_resource_mgmt/HcommChannelCreate.md)或[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口传入的channelDescs参数中的notifyNum。 |
38 38 
39## 返回值39## 返回值
40 40 
Mdocs/zh/api_ref/comm_opdev/data_plane_api/cpu-cpu_ts-aicpu_ts/communication_operations/HcommChannelNotifyWaitOnThread.md+5-5
@@ -25,7 +25,7 @@
25## 函数原型25## 函数原型
26 26 
27```c27```c
28-int32_t HcommChannelNotifyWaitOnThread(ThreadHandle thread, ChannelHandle channel, uint32_t localNotifyIdx, uint32_t timeout)28+int32_t HcommChannelNotifyWaitOnThread(ThreadHandle thread, ChannelHandle channel, uint32_t localNotifyIdx, uint32_t timeOut)
29```29```
30 30 
31## 参数说明31## 参数说明
@@ -34,8 +34,8 @@ int32_t HcommChannelNotifyWaitOnThread(ThreadHandle thread, ChannelHandle channe
34| --- | --- | --- |34| --- | --- | --- |
35| thread | 输入 | 通信线程句柄。<br>ThreadHandle类型的定义可参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |35| thread | 输入 | 通信线程句柄。<br>ThreadHandle类型的定义可参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |
36| channel | 输入 | 通信通道句柄，为通过[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口获取到的channels。关于channel的约束参见约束说明。<br>ChannelHandle类型的定义可参见[ChannelHandle](../../../datatype_definition/ChannelHandle.md)。 |36| channel | 输入 | 通信通道句柄，为通过[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口获取到的channels。关于channel的约束参见约束说明。<br>ChannelHandle类型的定义可参见[ChannelHandle](../../../datatype_definition/ChannelHandle.md)。 |
37-| localNotifyIdx | 输入 | 本地Notify索引。<br>取值范围：[0, notifyNum)。<br>notifyNum为[HcommChannelCreate](../../../control_plane_api/basic_resource_mgmt/HcommChannelCreate.md)或[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口传入的channelDesc参数中的notifyNum。 |37+| localNotifyIdx | 输入 | 本地Notify索引。<br>取值范围：[0, notifyNum)。<br>notifyNum为[HcommChannelCreate](../../../control_plane_api/basic_resource_mgmt/HcommChannelCreate.md)或[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口传入的channelDescs参数中的notifyNum。 |
38-| timeout | 输入 | 超时时间，单位：秒。<br> - 0：表示永久等待。<br> - >0：配置的具体超时时间。|38+| timeOut | 输入 | 超时时间，单位：秒。<br> - 0：表示永久等待。<br> - >0：配置的具体超时时间。|
39 39 
40<!-- npu="950" id7 -->40<!-- npu="950" id7 -->
41**补充说明**：41**补充说明**：
@@ -44,7 +44,7 @@ int32_t HcommChannelNotifyWaitOnThread(ThreadHandle thread, ChannelHandle channe
44 44 
45 针对Ascend 950PR/Ascend 950DT，CPU引擎RoCE场景下，“thread”参数无作用，传入0即可。CPU_TS/AICPU_TS场景下，“thread”参数为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。45 针对Ascend 950PR/Ascend 950DT，CPU引擎RoCE场景下，“thread”参数无作用，传入0即可。CPU_TS/AICPU_TS场景下，“thread”参数为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。
46 46 
47-- timeout参数：47+- timeOut参数：
48 48
49 针对Ascend 950PR/Ascend 950DT的CPU引擎RoCE场景，需配置大于0的超时时间。49 针对Ascend 950PR/Ascend 950DT的CPU引擎RoCE场景，需配置大于0的超时时间。
50<!-- end id7 -->50<!-- end id7 -->
@@ -59,7 +59,7 @@ int32_t：接口成功返回0，其他失败。
59<!-- npu="950" id6 -->59<!-- npu="950" id6 -->
60- 针对Ascend 950PR/Ascend 950DT，支持AICPU_TS场景在Device侧调用，也支持CPU引擎RoCE场景在Host CPU侧调用。60- 针对Ascend 950PR/Ascend 950DT，支持AICPU_TS场景在Device侧调用，也支持CPU引擎RoCE场景在Host CPU侧调用。
61- 针对Ascend 950PR/Ascend 950DT的CPU引擎RoCE场景，调用[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)申请入参channel时，需传入`engine = COMM_ENGINE_CPU`，且`channelDesc.remoteEndpoint.protocol = COMM_PROTOCOL_ROCE`。URMA/UBC等协议通道当前不支持该接口。61- 针对Ascend 950PR/Ascend 950DT的CPU引擎RoCE场景，调用[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)申请入参channel时，需传入`engine = COMM_ENGINE_CPU`，且`channelDesc.remoteEndpoint.protocol = COMM_PROTOCOL_ROCE`。URMA/UBC等协议通道当前不支持该接口。
62-- 针对Ascend 950PR/Ascend 950DT的CPU引擎RoCE场景，`localNotifyIdx`必须小于本端通信通道的Notify数量，且通信通道创建时的`notifyNum`需大于0；`timeout`需大于0。62+- 针对Ascend 950PR/Ascend 950DT的CPU引擎RoCE场景，`localNotifyIdx`必须小于本端通信通道的Notify数量，且通信通道创建时的`notifyNum`需大于0；`timeOut`需大于0。
63<!-- end id6 -->63<!-- end id6 -->
64- Host CPU侧调用时，`thread`参数无作用，可传入0。64- Host CPU侧调用时，`thread`参数无作用，可传入0。
65 65 
Mdocs/zh/api_ref/comm_opdev/data_plane_api/cpu-cpu_ts-aicpu_ts/communication_operations/HcommChannelNotifyWaitOnThreadWithDefaultTimeout.md+1-1
@@ -34,7 +34,7 @@ int32_t HcommChannelNotifyWaitOnThreadWithDefaultTimeout(ThreadHandle thread, Ch
34| --- | --- | --- |34| --- | --- | --- |
35| thread | 输入 | 通信线程句柄。<br>ThreadHandle类型的定义可参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |35| thread | 输入 | 通信线程句柄。<br>ThreadHandle类型的定义可参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |
36| channel | 输入 | 通信通道句柄，为通过[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口获取到的channels。<br>ChannelHandle类型的定义可参见[ChannelHandle](../../../datatype_definition/ChannelHandle.md)。 |36| channel | 输入 | 通信通道句柄，为通过[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口获取到的channels。<br>ChannelHandle类型的定义可参见[ChannelHandle](../../../datatype_definition/ChannelHandle.md)。 |
37-| localNotifyIdx | 输入 | 本地Notify索引。<br>取值范围：[0, notifyNum)。<br>notifyNum为[HcommChannelCreate](../../../control_plane_api/basic_resource_mgmt/HcommChannelCreate.md)或[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口传入的channelDesc参数中的notifyNum。 |37+| localNotifyIdx | 输入 | 本地Notify索引。<br>取值范围：[0, notifyNum)。<br>notifyNum为[HcommChannelCreate](../../../control_plane_api/basic_resource_mgmt/HcommChannelCreate.md)或[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口传入的channelDescs参数中的notifyNum。 |
38 38 
39<!-- npu="950" id7 -->39<!-- npu="950" id7 -->
40**补充说明**：40**补充说明**：
Mdocs/zh/api_ref/comm_opdev/data_plane_api/cpu-cpu_ts-aicpu_ts/communication_operations/HcommReadOnThread.md+1-1
@@ -35,7 +35,7 @@ int32_t HcommReadOnThread(ThreadHandle thread, ChannelHandle channel, void *dst,
35| thread | 输入 | 通信线程句柄，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义可参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |35| thread | 输入 | 通信线程句柄，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义可参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |
36| channel | 输入 | 通信通道句柄，为通过[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口获取到的channels。<br>ChannelHandle类型的定义可参见[ChannelHandle](../../../datatype_definition/ChannelHandle.md)。 |36| channel | 输入 | 通信通道句柄，为通过[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口获取到的channels。<br>ChannelHandle类型的定义可参见[ChannelHandle](../../../datatype_definition/ChannelHandle.md)。 |
37| dst | 输出 | 目标内存地址，使用[HcclGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclGetHcclBuffer.md)或[HcclChannelGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelGetHcclBuffer.md)获取到的内存。 |37| dst | 输出 | 目标内存地址，使用[HcclGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclGetHcclBuffer.md)或[HcclChannelGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelGetHcclBuffer.md)获取到的内存。 |
38-| src | 输入 | 源内存地址，使用[HcclGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclGetHcclBuffer.md)或[3.2.6-HcclChannelGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelGetHcclBuffer.md)获取到的内存。 |38+| src | 输入 | 源内存地址，使用[HcclGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclGetHcclBuffer.md)或[HcclChannelGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelGetHcclBuffer.md)获取到的内存。 |
39| len | 输入 | 数据长度（字节）。 |39| len | 输入 | 数据长度（字节）。 |
40 40 
41## 返回值41## 返回值
Mdocs/zh/api_ref/comm_opdev/data_plane_api/cpu-cpu_ts-aicpu_ts/communication_operations/HcommWriteWithNotifyNbiOnThread.md+1-1
@@ -37,7 +37,7 @@ int32_t HcommWriteWithNotifyNbiOnThread(ThreadHandle thread, ChannelHandle chann
37| dst | 输出 | 目的内存地址，使用[HcclGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclGetHcclBuffer.md)、[HcclChannelGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelGetHcclBuffer.md)获取到的内存。 |37| dst | 输出 | 目的内存地址，使用[HcclGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclGetHcclBuffer.md)、[HcclChannelGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelGetHcclBuffer.md)获取到的内存。 |
38| src | 输入 | 源内存地址，使用[HcclGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclGetHcclBuffer.md)、[HcclChannelGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelGetHcclBuffer.md)获取到的本端内存地址。 |38| src | 输入 | 源内存地址，使用[HcclGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclGetHcclBuffer.md)、[HcclChannelGetHcclBuffer](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelGetHcclBuffer.md)获取到的本端内存地址。 |
39| len | 输入 | 数据长度（字节），需大于0。 |39| len | 输入 | 数据长度（字节），需大于0。 |
40-| remoteNotifyIdx | 输入 | 通信通道另一端的Notify索引。<br>取值范围：[0, notifyNum)。<br>notifyNum为[HcommChannelCreate](../../../control_plane_api/basic_resource_mgmt/HcommChannelCreate.md)或[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口传入的channelDesc参数中的notifyNum。 |40+| remoteNotifyIdx | 输入 | 通信通道另一端的Notify索引。<br>取值范围：[0, notifyNum)。<br>notifyNum为[HcommChannelCreate](../../../control_plane_api/basic_resource_mgmt/HcommChannelCreate.md)或[HcclChannelAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclChannelAcquire.md)接口传入的channelDescs参数中的notifyNum。 |
41 41 
42## 返回值42## 返回值
43 43 
Mdocs/zh/api_ref/comm_opdev/data_plane_api/cpu-cpu_ts-aicpu_ts/local_operations/HcommAclrtNotifyWaitOnThread.md+1-1
@@ -34,7 +34,7 @@ int32_t HcommAclrtNotifyWaitOnThread(ThreadHandle thread, uint64_t notifyId, uin
34| --- | --- | --- |34| --- | --- | --- |
35| thread | 输入 | 线程句柄，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义请参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |35| thread | 输入 | 线程句柄，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义请参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |
36| notifyId | 输入 | 同步信号ID，为通过aclrtGetNotifyId接口获取到的notifyId。 |36| notifyId | 输入 | 同步信号ID，为通过aclrtGetNotifyId接口获取到的notifyId。 |
37-| timeOut | 输入 | 超时时间，单位：毫秒。<br> - 0：表示永久等待。<br> - >0：配置的具体超时时间。 |37+| timeOut | 输入 | 超时时间，单位：秒。<br> - 0：表示永久等待。<br> - >0：配置的具体超时时间。 |
38 38 
39## 返回值39## 返回值
40 40 
Mdocs/zh/api_ref/comm_opdev/data_plane_api/cpu-cpu_ts-aicpu_ts/local_operations/HcommThreadNotifyRecordOnThread.md+1-1
@@ -32,7 +32,7 @@ int32_t HcommThreadNotifyRecordOnThread(ThreadHandle thread, ThreadHandle dstThr
32 32 
33| 参数名 | 输入/输出 | 描述 |33| 参数名 | 输入/输出 | 描述 |
34| --- | --- | --- |34| --- | --- | --- |
35-| thread | 输入 | 通信线程句柄，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义请参见[ThreadHandle](.././../../datatype_definition/ThreadHandle.md)。 |35+| thread | 输入 | 通信线程句柄，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义请参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |
36| dstThread | 输入 | 目标通信线程句柄，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义请参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |36| dstThread | 输入 | 目标通信线程句柄，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义请参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |
37| dstNotifyIdx | 输入 | 目标Notify索引。<br>取值范围为：[0, [HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口传入的notifyNumPerThread参数的值)。 |37| dstNotifyIdx | 输入 | 目标Notify索引。<br>取值范围为：[0, [HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口传入的notifyNumPerThread参数的值)。 |
38 38 
Mdocs/zh/api_ref/comm_opdev/data_plane_api/cpu-cpu_ts-aicpu_ts/local_operations/HcommThreadNotifyWaitOnThread.md+2-2
@@ -25,7 +25,7 @@
25## 函数原型25## 函数原型
26 26 
27```c27```c
28-int32_t HcommThreadNotifyWaitOnThread(ThreadHandle thread, uint32_t notifyIdx, uint32_t timeout)28+int32_t HcommThreadNotifyWaitOnThread(ThreadHandle thread, uint32_t notifyIdx, uint32_t timeOut)
29```29```
30 30 
31## 参数说明31## 参数说明
@@ -34,7 +34,7 @@ int32_t HcommThreadNotifyWaitOnThread(ThreadHandle thread, uint32_t notifyIdx, u
34| --- | --- | --- |34| --- | --- | --- |
35| thread | 输入 | 线程句柄，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义请参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |35| thread | 输入 | 线程句柄，为通过[HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口获取到的threads。<br>ThreadHandle类型的定义请参见[ThreadHandle](../../../datatype_definition/ThreadHandle.md)。 |
36| notifyIdx | 输入 | 需等待的Notify通知索引。<br>取值范围为：[0, [HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口传入的notifyNumPerThread参数的值)。 |36| notifyIdx | 输入 | 需等待的Notify通知索引。<br>取值范围为：[0, [HcclThreadAcquire](../../../control_plane_api/comms_domain_resource_mgmt/HcclThreadAcquire.md)接口传入的notifyNumPerThread参数的值)。 |
37-| timeout | 输入 | 超时时间，单位：秒。<br> - 0：表示永久等待。<br> - >0：配置的具体超时时间。<br> |37+| timeOut | 输入 | 超时时间，单位：秒。<br> - 0：表示永久等待。<br> - >0：配置的具体超时时间。<br> |
38 38 
39## 返回值39## 返回值
40 40 
Adocs/zh/api_ref/comm_opdev/datatype_definition/CcuAddressHandle.md+11-0
@@ -0,0 +1,11 @@
1+# CcuAddressHandle
2+ 
3+## 功能说明
4+ 
5+CCU Address（地址）的句柄类型，用于标识CCU kernel内通过[Address](../data_plane_api/ccu/resource_allocation_operation/Address.md)资源创建的地址资源。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef uint64_t CcuAddressHandle;
11+```
Adocs/zh/api_ref/comm_opdev/datatype_definition/CcuBufferHandle.md+11-0
@@ -0,0 +1,11 @@
1+# CcuBufferHandle
2+ 
3+## 功能说明
4+ 
5+CCU Buffer（MS Buffer）的句柄类型，用于标识CCU kernel内通过[CcuBuffer](../data_plane_api/ccu/resource_allocation_operation/CcuBuffer.md)资源创建的MS Buffer资源。MS Buffer是CCU die内的片上高速暂存区，用于在片上内存与对端之间中转数据。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef uint64_t CcuBufferHandle;
11+```
Adocs/zh/api_ref/comm_opdev/datatype_definition/CcuEventHandle.md+11-0
@@ -0,0 +1,11 @@
1+# CcuEventHandle
2+ 
3+## 功能说明
4+ 
5+CCU Event（事件）的句柄类型，用于标识CCU kernel内通过[Event](../data_plane_api/ccu/resource_allocation_operation/Event.md)资源创建的事件资源。该句柄用于CCU数据面同步接口（如EventRecord、EventWait）中。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef uint64_t CcuEventHandle;
11+```
Mdocs/zh/api_ref/comm_opdev/datatype_definition/CcuInsHandle.md+1-1
@@ -2,7 +2,7 @@
2 2 
3## 功能说明3## 功能说明
4 4 
5-CCU实例句柄，从hccl通信域中获取，用于标识一个CCU实例。后续的Kernel注册、翻译、启动和实例销毁操作均通过此句柄进行。5+CCU实例句柄，从HCCL通信域中获取，用于标识一个CCU实例。后续的Kernel注册、翻译、启动和实例销毁操作均通过此句柄进行。
6 6 
7## 定义原型7## 定义原型
8 8 
Adocs/zh/api_ref/comm_opdev/datatype_definition/CcuKernelArg.md+11-0
@@ -0,0 +1,11 @@
1+# CcuKernelArg
2+ 
3+## 功能说明
4+ 
5+CCU kernel函数的参数类型，用于在CCU kernel注册时传递用户自定义参数。该类型为void*指针，调用方需自行管理参数内存的生命周期。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef void *CcuKernelArg;
11+```
Adocs/zh/api_ref/comm_opdev/datatype_definition/CcuLocalAddrHandle.md+11-0
@@ -0,0 +1,11 @@
1+# CcuLocalAddrHandle
2+ 
3+## 功能说明
4+ 
5+CCU LocalAddr（本端地址）的句柄类型，用于标识CCU kernel内通过[LocalAddr](../data_plane_api/ccu/resource_allocation_operation/LocalAddr.md)资源创建的本端HBM地址资源。该句柄在CCU数据面接口（如LocalCopy、LocalReduce、Read、Write等）中作为本端地址参数使用。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef uint64_t CcuLocalAddrHandle;
11+```
Adocs/zh/api_ref/comm_opdev/datatype_definition/CcuRemoteAddrHandle.md+11-0
@@ -0,0 +1,11 @@
1+# CcuRemoteAddrHandle
2+ 
3+## 功能说明
4+ 
5+CCU RemoteAddr（对端地址）的句柄类型，用于标识CCU kernel内通过[RemoteAddr](../data_plane_api/ccu/resource_allocation_operation/RemoteAddr.md)资源创建的对端片上内存地址资源。该句柄在CCU数据面跨rank接口（如Read、ReadReduce、Write、WriteReduce等）中作为对端地址参数使用。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef uint64_t CcuRemoteAddrHandle;
11+```
Adocs/zh/api_ref/comm_opdev/datatype_definition/CcuVariableHandle.md+11-0
@@ -0,0 +1,11 @@
1+# CcuVariableHandle
2+ 
3+## 功能说明
4+ 
5+CCU Variable（变量）的句柄类型，用于标识CCU kernel内通过[Variable](../data_plane_api/ccu/resource_allocation_operation/Variable.md)资源创建的变量资源。该句柄由CCU资源创建接口返回，在CCU数据面接口中使用。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef uint64_t CcuVariableHandle;
11+```
Mdocs/zh/api_ref/comm_opdev/datatype_definition/CommMemType.md+2-2
@@ -9,7 +9,7 @@
9```c9```c
10typedef enum {10typedef enum {
11 COMM_MEM_TYPE_INVALID = -1, /* 无效的内存类别 */11 COMM_MEM_TYPE_INVALID = -1, /* 无效的内存类别 */
12- COMM_MEM_TYPE_DEVICE = 0, /* 设备侧内存（如NPU等） */12+ COMM_MEM_TYPE_DEVICE = 0, /* Device侧内存（如NPU等） */
13- COMM_MEM_TYPE_HOST, /* 主机侧内存 */13+ COMM_MEM_TYPE_HOST = 1, /* Host侧内存 */
14} CommMemType;14} CommMemType;
15```15```
Mdocs/zh/api_ref/comm_opdev/datatype_definition/HcclCommSymWindow.md+1-1
@@ -2,7 +2,7 @@
2 2 
3## 功能说明3## 功能说明
4 4 
5-对称内存窗口资源句柄5+对称内存窗口资源句柄。
6 6 
7## 定义原型7## 定义原型
8 8 
Mdocs/zh/api_ref/comm_opdev/datatype_definition/HcommBatchTransferDesc.md+3-3
@@ -26,7 +26,7 @@ typedef struct {
26 uint64_t count; /* 元素个数 */26 uint64_t count; /* 元素个数 */
27 void *dst; /* 远端目的地址 */27 void *dst; /* 远端目的地址 */
28 void *src; /* 本地源地址 */28 void *src; /* 本地源地址 */
29- HcommReduceOp reduceOp; /* 规约操作类型 */29+ HcommReduceOp reduceOp; /* 归约操作类型 */
30 HcommDataType dataType; /* 数据类型 */30 HcommDataType dataType; /* 数据类型 */
31 } reduce;31 } reduce;
32 struct {32 struct {
@@ -42,9 +42,9 @@ typedef struct {
42 uint64_t count; /* 元素个数 */42 uint64_t count; /* 元素个数 */
43 void *dst; /* 远端目的地址 */43 void *dst; /* 远端目的地址 */
44 void *src; /* 本地源地址 */44 void *src; /* 本地源地址 */
45- HcommReduceOp reduceOp; /* 规约操作类型 */45+ HcommReduceOp reduceOp; /* 归约操作类型 */
46 HcommDataType dataType; /* 数据类型 */46 HcommDataType dataType; /* 数据类型 */
47- uint32_t notifyIdx; /* 写规约完成后通知的远端通知索引 */47+ uint32_t notifyIdx; /* 写归约完成后通知的远端通知索引 */
48 } writeReduceWithNotify;48 } writeReduceWithNotify;
49 } transferInfo;49 } transferInfo;
50} HcommBatchTransferDesc;50} HcommBatchTransferDesc;
Mdocs/zh/api_ref/comm_opdev/datatype_definition/HcommChannelDesc.md+1-0
@@ -37,5 +37,6 @@ typedef struct {
37 } ubAttr;37 } ubAttr;
38 };38 };
39 uint32_t qos; /* 通信域QoS与协议解耦 */39 uint32_t qos; /* 通信域QoS与协议解耦 */
40+ const char *channelName; /* channel业务匹配标识，两端需相同；NULL表示匿名channel */
40} HcommChannelDesc;41} HcommChannelDesc;
41```42```
Adocs/zh/api_ref/comm_opdev/datatype_definition/HcommMemHandle.md+11-0
@@ -0,0 +1,11 @@
1+# HcommMemHandle
2+ 
3+## 功能说明
4+ 
5+HCOMM基础通信中注册内存的句柄类型，用于标识通过[HcommMemReg](../control_plane_api/basic_resource_mgmt/HcommMemReg.md)接口注册的内存资源。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef void *HcommMemHandle;
11+```
Adocs/zh/api_ref/comm_opdev/datatype_definition/HcommResult.md+15-0
@@ -0,0 +1,15 @@
1+# HcommResult
2+ 
3+## 功能说明
4+ 
5+HCOMM基础通信接口的返回值类型。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef int32_t HcommResult;
11+```
12+ 
13+## 说明
14+ 
15+HcommResult为int32_t类型，接口成功返回0，其他值表示失败。其错误码与HcclResult保持一致，具体错误码定义可参见[HcclResult](../../comm_mgr_c/data_type_definition/HcclResult.md)。
Adocs/zh/api_ref/comm_opdev/datatype_definition/HcommSocket.md+11-0
@@ -0,0 +1,11 @@
1+# HcommSocket
2+ 
3+## 功能说明
4+ 
5+HCOMM基础通信中的套接字句柄类型，用于标识预创建的socket资源。在[HcommChannelDesc](./HcommChannelDesc.md)中作为字段使用，用于channel创建时传入预创建的socket。
6+ 
7+## 定义原型
8+ 
9+```c
10+typedef void *HcommSocket;
11+```
Mdocs/zh/api_ref/comm_opdev/datatype_definition/HcommTransferType.md+3-3
@@ -10,11 +10,11 @@
10typedef enum {10typedef enum {
11 HCOMM_TRANSFER_TYPE_INVALID = -1, /* 无效传输类型 */11 HCOMM_TRANSFER_TYPE_INVALID = -1, /* 无效传输类型 */
12 HCOMM_TRANSFER_TYPE_WRITE = 0, /* 单边写，对应transferInfo.write */12 HCOMM_TRANSFER_TYPE_WRITE = 0, /* 单边写，对应transferInfo.write */
13- HCOMM_TRANSFER_TYPE_WRITE_REDUCE = 1, /* 单边写规约，对应transferInfo.reduce */13+ HCOMM_TRANSFER_TYPE_WRITE_REDUCE = 1, /* 单边写归约，对应transferInfo.reduce */
14 HCOMM_TRANSFER_TYPE_WRITE_WITH_NOTIFY = 2, /* 带通知的单边写，对应transferInfo.writeWithNotify */14 HCOMM_TRANSFER_TYPE_WRITE_WITH_NOTIFY = 2, /* 带通知的单边写，对应transferInfo.writeWithNotify */
15- HCOMM_TRANSFER_TYPE_WRITE_REDUCE_WITH_NOTIFY = 3, /* 带通知的单边写规约，对应transferInfo.writeReduceWithNotify */15+ HCOMM_TRANSFER_TYPE_WRITE_REDUCE_WITH_NOTIFY = 3, /* 带通知的单边写归约，对应transferInfo.writeReduceWithNotify */
16 HCOMM_TRANSFER_TYPE_READ = 4, /* 单边读，对应transferInfo.read */16 HCOMM_TRANSFER_TYPE_READ = 4, /* 单边读，对应transferInfo.read */
17- HCOMM_TRANSFER_TYPE_READ_REDUCE = 5, /* 单边读规约，对应transferInfo.reduce */17+ HCOMM_TRANSFER_TYPE_READ_REDUCE = 5, /* 单边读归约，对应transferInfo.reduce */
18 HCOMM_TRANSFER_TYPE_NOTIFY_RECORD = 6 /* 记录通知事件，对应transferInfo.notifyRecord */18 HCOMM_TRANSFER_TYPE_NOTIFY_RECORD = 6 /* 记录通知事件，对应transferInfo.notifyRecord */
19} HcommTransferType;19} HcommTransferType;
20```20```
Mdocs/zh/api_ref/comm_opdev/datatype_definition/README.md+48-38
@@ -1,42 +1,52 @@
1# 数据类型定义1# 数据类型定义
2 2 
3-- [CommTopo](CommTopo.md) 3+- [CommTopo](CommTopo.md)
4-- [CommLink](CommLink.md) 4+- [CommLink](CommLink.md)
5-- [CommMem](CommMem.md) 5+- [CommMem](CommMem.md)
6-- [CommMemType](CommMemType.md) 6+- [CommMemType](CommMemType.md)
7-- [ChannelHandle](ChannelHandle.md) 7+- [ChannelHandle](ChannelHandle.md)
8-- [ThreadHandle](ThreadHandle.md) 8+- [ThreadHandle](ThreadHandle.md)
9-- [ThreadType](ThreadType.md) 9+- [ThreadType](ThreadType.md)
10-- [HcclDedicatedThreadType](HcclDedicatedThreadType.md) 10+- [HcclDedicatedThreadType](HcclDedicatedThreadType.md)
11-- [ThreadConfig](ThreadConfig.md) 11+- [ThreadConfig](ThreadConfig.md)
12- [ThreadResType](ThreadResType.md)12- [ThreadResType](ThreadResType.md)
13- [ThreadResTypeStream](ThreadResTypeStream.md)13- [ThreadResTypeStream](ThreadResTypeStream.md)
14-- [CommEngine](CommEngine.md) 14+- [CommEngine](CommEngine.md)
15-- [CommAbiHeader](CommAbiHeader.md) 15+- [CommAbiHeader](CommAbiHeader.md)
16-- [CommProtocol](CommProtocol.md) 16+- [CommProtocol](CommProtocol.md)
17-- [CommAddrType](CommAddrType.md) 17+- [CommAddrType](CommAddrType.md)
18-- [CommAddr](CommAddr.md) 18+- [CommAddr](CommAddr.md)
19-- [HcclCommSymWindow](HcclCommSymWindow.md) 19+- [HcclCommSymWindow](HcclCommSymWindow.md)
20-- [EndpointLocType](EndpointLocType.md) 20+- [EndpointLocType](EndpointLocType.md)
21-- [EndpointLoc](EndpointLoc.md) 21+- [EndpointLoc](EndpointLoc.md)
22-- [EndpointDesc](EndpointDesc.md) 22+- [EndpointDesc](EndpointDesc.md)
23-- [EndpointAttr](EndpointAttr.md) 23+- [EndpointAttr](EndpointAttr.md)
24-- [EndpointAttrBwCoeff](EndpointAttrBwCoeff.md) 24+- [EndpointAttrBwCoeff](EndpointAttrBwCoeff.md)
25-- [EndpointAttrDieId](EndpointAttrDieId.md) 25+- [EndpointAttrDieId](EndpointAttrDieId.md)
26-- [EndpointAttrLocation](EndpointAttrLocation.md) 26+- [EndpointAttrLocation](EndpointAttrLocation.md)
27-- [EndpointHandle](EndpointHandle.md) 27+- [EndpointHandle](EndpointHandle.md)
28-- [HcclChannelDesc](HcclChannelDesc.md) 28+- [HcclChannelDesc](HcclChannelDesc.md)
29-- [HcommEndpointFeatureType](HcommEndpointFeatureType.md) 29+- [HcommResult](HcommResult.md)
30-- [HcommReduceOp](HcommReduceOp.md) 30+- [HcommMemHandle](HcommMemHandle.md)
31-- [HcommSocketRole](HcommSocketRole.md) 31+- [HcommSocket](HcommSocket.md)
32-- [HcommDataType](HcommDataType.md) 32+- [HcommEndpointFeatureType](HcommEndpointFeatureType.md)
33-- [HcommTransferType](HcommTransferType.md) 33+- [HcommReduceOp](HcommReduceOp.md)
34-- [HcommBatchTransferDesc](HcommBatchTransferDesc.md) 34+- [HcommSocketRole](HcommSocketRole.md)
35-- [HcommChannelDesc](HcommChannelDesc.md) 35+- [HcommDataType](HcommDataType.md)
36-- [HcclComm](../../comm_mgr_c/data_type_definition/HcclComm.md) 36+- [HcommTransferType](HcommTransferType.md)
37-- [HcclHeterogMode](HcclHeterogMode.md) 37+- [HcommBatchTransferDesc](HcommBatchTransferDesc.md)
38-- [HcclMemHandle](HcclMemHandle.md) 38+- [HcommChannelDesc](HcommChannelDesc.md)
39-- [HcclResult](../../comm_mgr_c/data_type_definition/HcclResult.md) 39+- [HcclComm](../../comm_mgr_c/data_type_definition/HcclComm.md)
40-- [CcuResult](CcuResult.md) 40+- [HcclHeterogMode](HcclHeterogMode.md)
41-- [CcuInsHandle](CcuInsHandle.md) 41+- [HcclMemHandle](HcclMemHandle.md)
42-- [CcuKernelHandle](CcuKernelHandle.md) 42+- [HcclResult](../../comm_mgr_c/data_type_definition/HcclResult.md)
43+- [CcuResult](CcuResult.md)
44+- [CcuInsHandle](CcuInsHandle.md)
45+- [CcuKernelHandle](CcuKernelHandle.md)
46+- [CcuVariableHandle](CcuVariableHandle.md)
47+- [CcuAddressHandle](CcuAddressHandle.md)
48+- [CcuEventHandle](CcuEventHandle.md)
49+- [CcuBufferHandle](CcuBufferHandle.md)
50+- [CcuLocalAddrHandle](CcuLocalAddrHandle.md)
51+- [CcuRemoteAddrHandle](CcuRemoteAddrHandle.md)
52+- [CcuKernelArg](CcuKernelArg.md)
Mdocs/zh/api_ref/hcomm_header_and_lib.md+1-1
@@ -41,7 +41,7 @@ HCOMM对外头文件在"\${INSTALL_DIR}/include/"目录下的hccl/、hcomm/、hc
41| hccl/hccl_res.h | 用于定义HCCL通道描述、内存句柄等资源结构与常量。 | libhcomm.so |41| hccl/hccl_res.h | 用于定义HCCL通道描述、内存句柄等资源结构与常量。 | libhcomm.so |
42| hccl/hccl_sym_win.h | 用于定义对称内存窗口（Symmetric Window）访问接口。 | libhcomm.so |42| hccl/hccl_sym_win.h | 用于定义对称内存窗口（Symmetric Window）访问接口。 | libhcomm.so |
43| hccl/hccl_launch.h | 用于定义P2P算子描述与Launch相关结构。 | libhcomm.so |43| hccl/hccl_launch.h | 用于定义P2P算子描述与Launch相关结构。 | libhcomm.so |
44-| hcomm/hcomm_primitives.h | 用于定义通道/线程句柄、规约算子等基础原语类型，提供数据搬运与同步原语。 | libhcomm.so |44+| hcomm/hcomm_primitives.h | 用于定义通道/线程句柄、归约算子等基础原语类型，提供数据搬运与同步原语。 | libhcomm.so |
45| hcomm/hcomm_res.h | 用于定义Endpoint/Channel/内存注册等资源管理C接口。 | libhcomm.so |45| hcomm/hcomm_res.h | 用于定义Endpoint/Channel/内存注册等资源管理C接口。 | libhcomm.so |
46| hcomm/hcomm_res_defs.h | 用于定义HCOMM ABI版本、句柄与资源描述结构。 | libhcomm.so |46| hcomm/hcomm_res_defs.h | 用于定义HCOMM ABI版本、句柄与资源描述结构。 | libhcomm.so |
47| hcomm/ccu/ccu_primitives.hpp | CCU原语聚合头，含类型别名与资源创建入口。 | libhcomm.so |47| hcomm/ccu/ccu_primitives.hpp | CCU原语聚合头，含类型别名与资源创建入口。 | libhcomm.so |
Mdocs/zh/comm_op_dev_guide/aicpu_comm_op_dev/README.md+8-8
@@ -1,10 +1,10 @@
1# AI CPU算子开发1# AI CPU算子开发
2 2 
3-- [总体流程](overall_flow.md) 3+- [总体流程](overall_flow.md)
4-- [定义算子接口](define_op_if.md) 4+- [定义算子接口](define_op_if.md)
5-- [查询拓扑信息](query_topo.md) 5+- [查询拓扑信息](query_topo.md)
6-- [算法选择](algo_select.md) 6+- [算法选择](algo_select.md)
7-- [创建资源](create_res.md) 7+- [创建资源](create_res.md)
8-- [任务编排](task_sched.md) 8+- [任务编排](task_sched.md)
9-- [算子下发](op_dispatch.md) 9+- [算子下发](op_dispatch.md)
10-- [编译部署](build_deploy.md) 10+- [编译部署](build_deploy.md)
Mdocs/zh/comm_op_dev_guide/aicpu_comm_op_dev/query_topo.md+2-2
@@ -24,7 +24,7 @@ HCCL控制面接口支持查询的拓扑信息如下表所示。
24 ```c24 ```c
25 u32 userRank = INVALID_VALUE_RANKID;25 u32 userRank = INVALID_VALUE_RANKID;
26 HcclResult ret = HcclGetRankId(comm, &userRank);26 HcclResult ret = HcclGetRankId(comm, &userRank);
27- if (userRank == root && sendBuf == nullptr) { // root节点的send_buff不允许为空27+ if (userRank == root && sendBuf == nullptr) { // root节点的sendBuf不允许为空
28 return HCCL_E_PTR;28 return HCCL_E_PTR;
29 }29 }
30 ```30 ```
@@ -79,7 +79,7 @@ struct TopoInfo {
79 uint32_t rankSize; // 参与此次集合通信的rank的数量79 uint32_t rankSize; // 参与此次集合通信的rank的数量
80 std::vector<u32> rankList; // 参与此次集合通信的rank的rankId集合80 std::vector<u32> rankList; // 参与此次集合通信的rank的rankId集合
81 CommTopo topoType; // 链路连接类型：COMM_TOPO_1DMESH/COMM_TOPO_CLOS等81 CommTopo topoType; // 链路连接类型：COMM_TOPO_1DMESH/COMM_TOPO_CLOS等
82- std::vector<HcclCHannelDesc> channels; // 本rank和其他卡之间的链路信息82+ std::vector<HcclChannelDesc> channels; // 本rank和其他卡之间的链路信息
83};83};
84HcclResult FillSimpleTopoInfo(HcclComm comm, TopoInfo &topoInfo){84HcclResult FillSimpleTopoInfo(HcclComm comm, TopoInfo &topoInfo){
85 HcclResult ret = HcclGetRankId(comm, &topoInfo.rankId);85 HcclResult ret = HcclGetRankId(comm, &topoInfo.rankId);
Mdocs/zh/comm_op_dev_guide/aiv_comm_op_dev/README.md+7-7
@@ -1,9 +1,9 @@
1# AIV算子开发1# AIV算子开发
2 2 
3-- [总体流程](overall_flow.md) 3+- [总体流程](overall_flow.md)
4-- [定义算子接口](define_op_if.md) 4+- [定义算子接口](define_op_if.md)
5-- [查询拓扑信息](query_topo.md) 5+- [查询拓扑信息](query_topo.md)
6-- [算法选择](algo_select.md) 6+- [算法选择](algo_select.md)
7-- [创建资源](create_res.md) 7+- [创建资源](create_res.md)
8-- [任务编排](task_sched.md) 8+- [任务编排](task_sched.md)
9-- [算子下发](op_dispatch.md) 9+- [算子下发](op_dispatch.md)
Mdocs/zh/comm_op_dev_guide/aiv_comm_op_dev/create_res.md+1-1
@@ -35,7 +35,7 @@ Mesh算法的硬件拓扑如下图所示，每个rank与其他所有rank直接
35 if (ret != HCCL_SUCCESS) {35 if (ret != HCCL_SUCCESS) {
36 // 即之前没有创建过tag表示的资源36 // 即之前没有创建过tag表示的资源
37 HcclEngineCtxCreate(comm, tag, engine, size, ctx); 37 HcclEngineCtxCreate(comm, tag, engine, size, ctx);
38- }else {38+ } else {
39 // 说明之前创建过资源，直接用ctx就好39 // 说明之前创建过资源，直接用ctx就好
40 }40 }
41 ```41 ```
Mdocs/zh/comm_op_dev_guide/aiv_comm_op_dev/query_topo.md+1-1
@@ -26,7 +26,7 @@ HCCL控制面接口支持查询的拓扑信息如下表所示。
26 ```c26 ```c
27 u32 userRank = INVALID_VALUE_RANKID;27 u32 userRank = INVALID_VALUE_RANKID;
28 HcclResult ret = HcclGetRankId(comm, &userRank);28 HcclResult ret = HcclGetRankId(comm, &userRank);
29- if (userRank == root && sendBuf == nullptr) { // root节点的send_buff不允许为空29+ if (userRank == root && sendBuf == nullptr) { // root节点的sendBuf不允许为空
30 return HCCL_E_PTR;30 return HCCL_E_PTR;
31 }31 }
32 ```32 ```
Mdocs/zh/comm_op_dev_guide/ccu_comm_op_dev/algo_exec.md+1-1
@@ -85,7 +85,7 @@ CcuResult CcuAllGatherMesh1DMem2MemKernel(CcuKernelArg arg)
85 for (uint64_t peerId = 0; peerId < ctx.arg->rankSize; peerId++) {85 for (uint64_t peerId = 0; peerId < ctx.arg->rankSize; peerId++) {
86 if (peerId != ctx.arg->rankId) {86 if (peerId != ctx.arg->rankId) {
87 ctx.output[peerId] = ccu::GetResByChannel<ccu::Variable>(ctx.arg->channels[channelIdx], OUTPUT_XN_ID);87 ctx.output[peerId] = ccu::GetResByChannel<ccu::Variable>(ctx.arg->channels[channelIdx], OUTPUT_XN_ID);
88- ctx.token[peerId] = ccu::GetResByChannel<ccu::Variable>(ctx.arg->channels[channelIdx], TOKEN_XN_ID);88+ ctx.token[peerId] = ccu::GetResByChannel<ccu::Variable>(ctx.arg->channels[channelIdx], TOKEN_XN_ID);
89 channelIdx++;89 channelIdx++;
90 }90 }
91 }91 }
Mdocs/zh/comm_op_dev_guide/ccu_comm_op_dev/algo_select.md+1-1
@@ -10,7 +10,7 @@
10如上图所示，CCU通信算子支持多种算法实现，开发者可以根据拓扑信息选择最优通信算法：10如上图所示，CCU通信算子支持多种算法实现，开发者可以根据拓扑信息选择最优通信算法：
11 11 
12- Mesh算法实现：适用于Server内物理拓扑为Mesh的场景。12- Mesh算法实现：适用于Server内物理拓扑为Mesh的场景。
13-- NHR算法实现：使用于多Server，且每个Server中取一个rank进行通信的场景。13+- NHR算法实现：适用于多Server，且每个Server中取一个rank进行通信的场景。
14 14 
15> [!NOTE]说明15> [!NOTE]说明
16>16>
Mdocs/zh/comm_op_dev_guide/ccu_comm_op_dev/define_op_if.md+1-1
@@ -5,5 +5,5 @@
5以自定义通信算子AllGather为例，该类算子接口需要传入源地址、目的地址、源数据量、数据类型，以及通信域和流信息，其接口定义如下：5以自定义通信算子AllGather为例，该类算子接口需要传入源地址、目的地址、源数据量、数据类型，以及通信域和流信息，其接口定义如下：
6 6 
7```c7```c
8-HcclResult HcclAllGather(void *sendBuf, void *recvBuf, uint64_t sendCount, HcclDataType dataType, HcclComm comm, aclrtStream stream);8+HcclResult HcclAllGatherCustom(void *sendBuf, void *recvBuf, uint64_t sendCount, HcclDataType dataType, HcclComm comm, aclrtStream stream);
9```9```
Mdocs/zh/comm_op_dev_guide/ccu_comm_op_dev/op_dispatch.md+1-1
@@ -10,7 +10,7 @@
10 10 
11```c11```c
12uint64_t currentRankSliceInputOffset = 0; // 卡间输入地址偏移量12uint64_t currentRankSliceInputOffset = 0; // 卡间输入地址偏移量
13-uint64_t currentRankSliceOutputOffset = sliceSize* myRank; // 卡间目标地址偏移量13+uint64_t currentRankSliceOutputOffset = sliceSize * myRank; // 卡间目标地址偏移量
14std::vector<uint64_t> taskArgs = {14std::vector<uint64_t> taskArgs = {
15 inputAddr,15 inputAddr,
16 outputAddr,16 outputAddr,
Mdocs/zh/comm_op_dev_guide/ccu_comm_op_dev/query_topo.md+1-1
@@ -26,7 +26,7 @@ HCCL控制面接口支持查询的拓扑信息如下表所示。
26 ```c26 ```c
27 u32 userRank = INVALID_VALUE_RANKID;27 u32 userRank = INVALID_VALUE_RANKID;
28 HcclResult ret = HcclGetRankId(comm, &userRank);28 HcclResult ret = HcclGetRankId(comm, &userRank);
29- if (userRank == root && sendBuf == nullptr) { // root节点的send_buff不允许为空29+ if (userRank == root && sendBuf == nullptr) { // root节点的sendBuf不允许为空
30 return HCCL_E_PTR;30 return HCCL_E_PTR;
31 }31 }
32 ```32 ```
Mdocs/zh/comm_op_dev_guide/npu_test.md+3-3
@@ -171,8 +171,8 @@ all:
171 @echo "${TARGET} compile completed"171 @echo "${TARGET} compile completed"
172 172 
173# Test target173# Test target
174-test: 174+test:
175- export LD_LIBRARY_PATH=${CUSTOM_P2P_LIB_DIR}:${LD_LIBRARY_PATH}; \175+ export LD_LIBRARY_PATH=${CUSTOM_OPS_LIB_DIR}:${LD_LIBRARY_PATH}; \
176 ./$(TARGET)176 ./$(TARGET)
177 177 
178# Clean build artifacts178# Clean build artifacts
@@ -188,7 +188,7 @@ clean:
188 188 
189 AI CPU算子包会在业务启动时加载至Device，加载过程中驱动默认会执行安全验签，以确保包的可信性。但用户自行编译生成的AI CPU算子包不包含签名头，因此需要手工关闭驱动的验签机制，才可以正常加载。189 AI CPU算子包会在业务启动时加载至Device，加载过程中驱动默认会执行安全验签，以确保包的可信性。但用户自行编译生成的AI CPU算子包不包含签名头，因此需要手工关闭驱动的验签机制，才可以正常加载。
190 190 
191- 参考如下命令，使用root用户在物理机上执行， 以device 0为例：191+ 参考如下命令，使用root用户在物理机上执行，以device 0为例：
192 192 
193 ```bash193 ```bash
194 npu-smi set -t custom-op-secverify-enable -i 0 -d 1 # 开启验签配置194 npu-smi set -t custom-op-secverify-enable -i 0 -d 1 # 开启验签配置
Minclude/hccl/hccl_comm.h+3-3
Minclude/hccl/hccl_types.h+1-1
Minclude/hcomm_primitives.h+3-3