API List

Communication operator development APIs are classified into control plane APIs and data plane APIs.

Control plane APIs: provide functions such as topology information query and communication resource management.
Data plane APIs: provide data movement and computing functions such as local operations, inter-operator synchronization, and communication operations.

You can view the communication operator development API definition in CANN software installation directory/include/hccl/.

hccl_rank_graph.h: definition file of the topology information query API on the control plane.
hccl_res.h: resource management definition file on the control plane.
hcomm_primitives.h: definition file of the data plane APIs.

Control Plane APIs

Topology information query

API	Description
HcclGetRankId	Obtains the rank ID of a device in a specified communicator.
HcclGetRankSize	Queries the number of ranks in a specified communicator.
HcclRankGraphGetLayers	Queries the list of topology layers that contain the current rank and the number of topology layers.
HcclRankGraphGetRanksByLayer	Returns the list of all rank IDs and the number of ranks in the topology instance where the current rank is located at a specified topology layer in a specified communicator.
HcclRankGraphGetRankSizeByLayer	Returns the number of ranks in the topology instance where the current rank is located at a specified topology layer in a specified communicator.
HcclRankGraphGetTopoTypeByLayer	Returns the topology type of the topology layer where the current rank is located in a specified communicator.
HcclRankGraphGetInstSizeListByLayer	Queries the number of topology instances at a specified topology layer and the number of ranks in each instance in a specified communicator.
HcclRankGraphGetLinks	Queries information about the communication connection between the source rank and the destination rank at a specified topology layer in a specified communicator.
HcclRankGraphGetTopoInstsByLayer	Queries the topology instance set of the current rank based on the given communicator and topology layer ID.
HcclRankGraphGetTopoType	Queries the topology type of the current rank in the specified topology instance based on the given communicator and topology layer ID.
HcclRankGraphGetRanksByTopoInst	Queries the rank information in the topology instance of the current rank based on the given communicator and topology layer ID.
HcclGetHeterogMode	Obtains the heterogeneous networking mode of a given communicator.
HcclRankGraphGetEndpointNum	Obtains the number of endpoints in a topology instance.
HcclRankGraphGetEndpointDesc	Obtains the endpoint description list of a topology instance.
HcclRankGraphGetEndpointInfo	Obtains the topology attributes of a given communication device.

Communicator resource management

API	Description
HcclGetHcclBuffer	Obtains the HCCL communication memory in the communicator. Memory will be initialized and allocated on the device during the first call; subsequent calls will reuse the allocated memory without reinitialization.
HcclThreadAcquire	Obtains the communication thread based on the communicator.
HcclThreadAcquireWithStream	Obtains the communication thread resource of the specified notifyNum based on the existing runtime stream.
HcclChannelDescInit	Initializes the communication channel description list.
HcclChannelAcquire	Obtains multiple communication channels based on the communicator. If the communicator does not have the corresponding communication channel, the communication channel is directly created.
HcclChannelGetHcclBuffer	Obtains the HCCL communication memory of the remote end of a specified channel.
HcclEngineCtxCreate	Creates the corresponding communication engine context with a specified tag by specifying the communicator and communication engine.
HcclEngineCtxGet	Obtains the corresponding communication engine context based on the communication engine context tag by specifying the communicator and communication engine.
HcclEngineCtxCopy	Copies the memory data on the host to the corresponding communication engine context by specifying the communicator, communication engine, and communication engine context tag.
HcclEngineCtxDestroy	Destroys the corresponding communication engine context with a specified tag by specifying the communicator and communication engine.
HcclCommMemReg	Registers the allocated memory with the communicator and obtains the corresponding registered handle.
HcclChannelGetRemoteMems	Obtains the remote memory information exchanged in the communication channel.

Basic resource management

API	Description
HcommEndpointCreate	Creates a communication endpoint.
HcommEndpointDestroy	Destroys a communication endpoint.
HcommMemReg	Registers memory to a specified endpoint.
HcommMemUnreg	Unregisters memory from an endpoint.
HcommMemExport	Exports the specified memory description for exchange after the memory is registered.
HcommMemImport	Imports the memory description exported by the remote end to obtain the corresponding memory description information on the local end.
HcommMemUnimport	Disables memory import.
HcommChannelDescInit	Initializes the communication channel description list.
HcommChannelCreate	Creates communication channels in batches based on the given channel description and the created network endpoints, providing the infrastructure for data transmission in point-to-point communication or collective communication.
HcommChannelGetStatus	Query the status of communication channels in batches. This API is used to check whether the channels are ready after they are created and before communication operations are performed.
HcommChannelGetNotifyNum	Obtains the number of Notifies of a specified channel.
HcommChannelDestroy	Destroys a communication channel created by HcommChannelCreate, along with the system resources occupied by the communication channel, including network connections, synchronization signals, and communication queues.
HcommThreadAlloc	Allocates communication threads. Currently, the AICPU+TS, host CPU+TS, and CCU communication engines are supported. For the AICPU+TS communication engine, the allocated communication threads can be used on the AICPU only after an additional kernel is delivered.
HcommThreadFree	Destroys threads allocated by the HcommThreadAlloc API.

Data Plane APIs

Local operations

API	Description
HcommLocalCopyOnThread	Copies memory data of length len pointed to by src into the memory of the same length pointed to by dst.
HcommLocalReduceOnThread	Performs a reduceOp operation on the memory data of length count × sizeof(dataType) pointed to by src and the memory data of the same length pointed to by dst, and outputs the result to dst.
HcommThreadNotifyRecordOnThread	Sends a synchronization signal to other threads, which is primarily used for synchronization between multiple threads.
HcommThreadNotifyWaitOnThread	Waits for a synchronization signal. This API blocks and waits for the thread execution until the specified Notify is recorded.
HcommAclrtNotifyRecordOnThread	Sends a synchronization signal based on the Notify created by the ACL API. This API must be used in pair with HcommAclrtNotifyWaitOnThread.
HcommAclrtNotifyWaitOnThread	Waits for a synchronization signal based on the Notify created by the ACL API. This API must be used in pair with HcommAclrtNotifyRecordOnThread.

Communication operations

API	Description
HcommWriteOnThread	Writes data to the specified memory on a channel. It writes memory data of length len from src into the memory of the same length pointed to by dst. The API caller is the node where src resides. This API is asynchronous.
HcommWriteReduceOnThread	Writes data to the specified memory on a channel. It performs a reduceOp operation on the memory data of length count × sizeof(dataType) pointed to by src and the memory data of the same length pointed to by dst, and outputs the result to dst. The API caller is the node where src resides.
HcommReadOnThread	Reads data from the specified memory on a channel. It reads memory data of length len from src and writes it into dst. The API caller is the node where dst resides. This API is asynchronous.
HcommReadReduceOnThread	Reads data from the specified memory on a channel. It performs a reduceOp operation on the memory data of length count × sizeof(dataType) pointed to by src and the memory data of the same length pointed to by dst, and outputs the result to dst. The API caller is the node where dst resides.
HcommChannelNotifyRecordOnThread	Sends a synchronization signal and records a Notify on the thread. This API is asynchronous and is mainly used for synchronization between the two ends of a channel.
HcommChannelNotifyWaitOnThread	Waits for a synchronization signal. This API blocks and waits for the thread execution until the specified Notify is completed.
HcommWriteWithNotifyOnThread	Writes data to the specified memory on a channel. It writes memory data of length len from src into the memory of the same length pointed to by dst, and sends a synchronization signal to the node where dst resides. The API caller is the node where src resides. This API is asynchronous.
HcommWriteReduceWithNotifyOnThread	Writes data to the specified memory on a channel. It performs a reduceOp operation on the memory data of length count × sizeof(dataType) pointed to by src and the memory data of the same length pointed to by dst, outputs the result to dst, and sends a synchronization signal to the node where dst resides. The API caller is the node where src resides. This API is asynchronous.

Other APIs

API	Description
HcommBatchModeStart	Enables the batch mode. All data plane API calls (such as HcommLocalCopy and HcommWrite) called between HcommBatchModeStart and HcommBatchModeEnd will be cached instead of being executed immediately. All operations will be submitted and executed collectively when HcommBatchModeEnd is called.
HcommBatchModeEnd	Submits and triggers the execution of all operations cached in batch mode. All data plane API call operations between HcommBatchModeStart and HcommBatchModeEnd will be executed collectively at this point.
HcommAcquireComm	Obtains the corresponding communicator based on the passed commId and locks the communicator to prevent it from being obtained repeatedly.
HcommReleaseComm	Finds the corresponding communicator based on the passed commId and releases the lock.

Parent topic: Communication Operator Development APIs