---
title: 接口列表
description: "通信算子开发接口分为控制面接口与数据面接口。- 控制面接口：提供拓扑信息查询、通信资源管理等功能。"
url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/programug/commopdev/hcclopdevapi_07_0001.html
sourcePath: /source/zh/canncommercial/900/programug/commopdev/hcclopdevapi_07_0001.html
indexId: fc661b6632b93b4b8c048d24252e501764b4a2ec4328b29981f7399c6d88bf0375
---
# 接口列表

通信算子开发接口分为控制面接口与数据面接口。- 控制面接口：提供拓扑信息查询、通信资源管理等功能。
- 数据面接口：提供本地操作、算子间同步、通信操作等数据搬运和计算功能。


开发者可在“CANN软件安装目录/include/hccl/”目录中查看通信算子开发接口的定义。- hccl_rank_graph.h：控制面的拓扑信息查询接口定义文件。
- hccl_res.h：控制面的资源管理定义文件。
- hcomm_primitives.h：数据面接口定义文件。


#### 控制面接口

- 拓扑信息查询| 接口 | 简介 |
| --- | --- |
| HcclGetRankId | 获取Device在指定通信域中对应的rank序号。 |
| HcclGetRankSize | 查询指定通信域的rank数量。 |
| HcclRankGraphGetLayers | 查询包含当前rank的拓扑层级编号列表以及拓扑层级数量。 |
| HcclRankGraphGetRanksByLayer | 给定通信域和拓扑层级编号，返回该层级下本rank所在拓扑实例的所有rank编号列表以及rank数量。 |
| HcclRankGraphGetRankSizeByLayer | 给定通信域和拓扑层级编号，返回该层级下本rank所在拓扑实例的rank数量。 |
| HcclRankGraphGetTopoTypeByLayer | 给定通信域和拓扑层级编号，返回本rank所在拓扑层级中的拓扑类型。 |
| HcclRankGraphGetInstSizeListByLayer | 给定通信域和拓扑层级编号，查询该层级下的拓扑实例数量，以及每个实例包含的rank数量。 |
| HcclRankGraphGetLinks | 给定通信域和拓扑层级编号，查询源rank和目的rank之间的通信连接信息。 |
| HcclRankGraphGetTopoInstsByLayer | 给定通信域和拓扑层级编号，查询当前rank所在的拓扑实例集合。 |
| HcclRankGraphGetTopoType | 给定通信域和拓扑层级编号，查询当前rank在指定拓扑实例中对应的拓扑类型。 |
| HcclRankGraphGetRanksByTopoInst | 给定通信域和拓扑层级编号，查询当前rank对应的指定拓扑实例中包含的rank信息。 |
| HcclGetHeterogMode | 给定通信域，获取通信域的异构组网模式。 |
| HcclRankGraphGetEndpointNum | 获取拓扑实例中的EndPoint数量。 |
| HcclRankGraphGetEndpointDesc | 获取拓扑实例的EndPoint描述列表。 |
| HcclRankGraphGetEndpointInfo | 获取指定通信设备的拓扑属性信息。 |


- 通信域资源管理| 接口 | 简介 |
| --- | --- |
| HcclGetHcclBuffer | 获取通信域中的HCCL通信内存，首次调用时将在Device侧进行内存初始化分配，后续调用将复用已分配内存，不会重复初始化。 |
| HcclThreadAcquire | 基于通信域获取通信线程。 |
| HcclThreadAcquireWithStream | 基于已有runtime stream获取指定notifyNum的通信线程资源。 |
| HcclChannelDescInit | 初始化通信通道描述列表。 |
| HcclChannelAcquire | 基于通信域获取多个通信通道，如果通信域中没有对应的通信通道则直接创建。 |
| HcclChannelGetHcclBuffer | 获取指定channel对端的HCCL通信内存。 |
| HcclEngineCtxCreate | 指定通信域与通信引擎，使用特定标签创建对应的通信引擎上下文。 |
| HcclEngineCtxGet | 指定通信域和通信引擎，通过通信引擎上下文标签获取对应的通信引擎上下文。 |
| HcclEngineCtxCopy | 指定通信域、通信引擎与通信引擎上下文标签，将Host侧内存数据拷贝至对应的通信引擎上下文中。 |
| HcclEngineCtxDestroy | 指定通信域与通信引擎，使用特定标签销毁对应的通信引擎上下文。 |
| HcclCommMemReg | 向通信域注册已申请的内存，并获取对应的注册句柄。 |
| HcclChannelGetRemoteMems | 获取通信通道中交换的远端内存信息。 |


- 基础资源管理| 接口 | 简介 |
| --- | --- |
| HcommEndpointCreate | 创建通信设备Endpoint。 |
| HcommEndpointDestroy | 销毁通信设备Endpoint。 |
| HcommMemReg | 注册内存到指定EndPoint。 |
| HcommMemUnreg | 从EndPoint解除内存注册。 |
| HcommMemExport | 内存注册后，导出指定内存描述，用于交换。 |
| HcommMemImport | 本端通过导入对端导出的内存描述，获取相应的内存描述信息。 |
| HcommMemUnimport | 关闭内存导入。 |
| HcommChannelDescInit | 初始化通信通道描述列表。 |
| HcommChannelCreate | 该接口为创建通信通道的资源管理接口，基于已创建的网络端点（Endpoint），根据给定的通道描述信息批量创建通信通道，为点对点通信或集合通信提供数据传输的基础设施。 |
| HcommChannelGetStatus | 该接口用于查询通信通道的状态，支持批量查询多个通道的连接状态，用于在通道创建后、通信操作前确认通道是否已就绪。 |
| HcommChannelGetNotifyNum | 获取指定channel的Notify数量。 |
| HcommChannelDestroy | 该接口为销毁通信通道的资源管理接口，释放由HcommChannelCreate创建的通信通道及其占用的所有系统资源，包括网络连接、同步信号、通信队列等。 |
| HcommThreadAlloc | 申请通信线程，当前支持AI CPU+TS、HOST CPU+TS、CCU通信引擎。注意如果通信引擎是AI CPU+TS，需要额外下发一次kernel，AI CPU侧才能使用此通信线程。 |
| HcommThreadFree | 使用HcommThreadAlloc接口申请的thread需要通过本接口进行释放。 |


#### 数据面接口

- 本地操作| 接口 | 简介 |
| --- | --- |
| HcommLocalCopyOnThread | 提供本地内存拷贝功能，将src指向的长度为len的内存数据，拷贝到dst所指向的相同长度的内存中。 |
| HcommLocalReduceOnThread | 提供本地归约操作，将src指向的长度为count\*sizeof(dataType)的内存数据，与dst所指向的相同长度的内存数据进行reduceOp操作，并将结果输出到dst中。 |
| HcommThreadNotifyRecordOnThread | 向其他Thread发送同步信号，主要用于多Thread之间的同步等待场景。 |
| HcommThreadNotifyWaitOnThread | 等待同步信号，该接口会阻塞等待Thread的运行，直到指定的Notify被record完成。 |
| HcommAclrtNotifyRecordOnThread | 基于acl接口创建的Notify发送同步信号，需与HcommAclrtNotifyWaitOnThread配对使用。 |
| HcommAclrtNotifyWaitOnThread | 基于acl接口创建的Notify等待同步信号，须与HcommAclrtNotifyRecordOnThread配对使用。 |


- 通信操作| 接口 | 简介 |
| --- | --- |
| HcommWriteOnThread | 向channel上的指定内存写数据，将src中长度为len的内存数据写入dst所指向的相同长度的内存区域。接口调用方为src所在节点，该接口为异步接口。 |
| HcommWriteReduceOnThread | 向channel上的指定内存写数据，将src中长度为count\*sizeof(dataType)的内存数据，与dst所指向的相同长度的内存数据进行reduceOp操作，并将结果输出到dst中。接口调用方为src所在节点。 |
| HcommReadOnThread | 从channel上的指定内存读数据，从src中读取长度为len的内存数据，并写入dst。接口调用方为dst所在节点，为异步接口。 |
| HcommReadReduceOnThread | 从channel上的指定内存读数据，从src中读取长度为count\*sizeof(dataType)的内存数据，与dst所指向的相同长度的内存数据进行reduceOp操作，并将结果输出到dst中。接口调用方为dst所在节点。 |
| HcommChannelNotifyRecordOnThread | 发送同步信号，在Thread上记录一个Notify。该接口为异步接口，主要用于Channel两端同步等待场景。 |
| HcommChannelNotifyWaitOnThread | 等待同步信号，阻塞等待Thread的运行，直到指定的Notify完成。 |
| HcommWriteWithNotifyOnThread | 向channel上的指定内存写数据，将src中长度为len的内存数据写入dst所指向的相同长度的内存区域，并且向dst所在节点发送同步信号。接口调用方为src所在节点，该接口为异步接口。 |
| HcommWriteReduceWithNotifyOnThread | 向channel上的指定内存写数据，将src中长度为count\*sizeof(dataType)的内存数据，与dst所指向的相同长度的内存数据进行reduceOp操作，并将结果输出到dst中，并向dst所在节点发送同步信号。接口调用方为src所在节点，该接口为异步接口。 |


- 其他接口| 接口 | 简介 |
| --- | --- |
| HcommBatchModeStart | 该接口用于开启批量模式，在HcommBatchModeStart和HcommBatchModeEnd之间的所有数据面接口调用（如 HcommLocalCopy、HcommWrite 等）将被缓存，不会立即执行。所有操作将在调用HcommBatchModeEnd时统一提交并执行。 |
| HcommBatchModeEnd | 该接口用于提交并触发批量模式下缓存的所有操作的执行。所有在HcommBatchModeStart和HcommBatchModeEnd之间的数据面接口调用操作将在此时统一执行。 |
| HcommAcquireComm | 根据传入的commId获取对应通信域，并对该通信域加锁，防止该通信域被重复获取。 |
| HcommReleaseComm | 根据传入的commId，查找对应通信域，并释放锁。 |