APIs

HCCL provides communication operator APIs, communicator management APIs, and group call APIs to help framework developers implement distributed capabilities.

Communication operator APIs provide collective communication and P2P communication capabilities.
Communicator management APIs provide functions such as creating and destroying communicators, as well as error handling.
Communicator management supports C and Python languages.
- C APIs implement framework adaptation in single-operator mode to achieve distributed capabilities.
- Python APIs enable framework adaptation in graph mode. Currently, they only implement distributed optimization of TensorFlow networks on NPUs, working with the collective communication operator APIs provided by TF Adapter to facilitate collective communication.
Group call APIs provide capabilities for group-based call and processing.

The HCCL API definition files are as follows:

${INSTALL_DIR}/include/hccl/hccl_types.h: data type definition file.
${INSTALL_DIR}/include/hccl/hccl.h: communication operator API definition file.
${INSTALL_DIR}/include/hccl/hccl_comm.h: communicator management API definition file and group call API definition file of the C language.
${INSTALL_DIR}/include/hccl/hccl_sym_win.h: symmetric memory API.
manage/api.py and split/api.py in the ${INSTALL_DIR}/python/site-packages/hccl directory: communicator management API definition file of the Python language.

Communication Operator APIs

API	Description
HcclBroadcast	Broadcasts the data of the root rank in the communicator to other ranks.
HcclAllGather	Re-sorts the inputs of all ranks in the communicator by rank ID, combines the inputs, and sends the results to the outputs of all ranks.
HcclAllGatherV	Re-sorts the inputs of all ranks in the communicator by rank ID, combines the inputs, and sends the results to the outputs of all ranks. Unlike AllGather, the AllGatherV operator allows different data sizes to be configured for the input of different ranks in the communicator.
HcclReduce	Performs the sum operation (or other reduction operations) on the data of all ranks and sends the result to the specified position on the root rank.
HcclAllReduce	Adds the input data of all nodes in the communicator (or performs other reduction operations) and sends the result to the output buffer of all nodes. The reduction operation type is specified by the op parameter.
HcclScatter	Scatters data of the root rank to other ranks.
HcclReduceScatter	Functions as the operation API of the ReduceScatter operator to evenly divide the input data of all ranks in a communicator into rank size parts, perform reduction (sum, prod, max, and min) on 1/rank size part of data of each rank, and distributes the result to the output buffer of each rank based on the number.
HcclReduceScatterV	Functions as the operation API of the ReduceScatterV operator, which is similar to the ReduceScatter operation. The difference is that the ReduceScatterV operation supports the configuration of different data sizes for different ranks in a communicator. (The data size can be configured for different IDs in a rank, but the data size of the same ID in different ranks must be the same.) After the reduction operation (sum, prod, max, and min) is performed on data with the same ID in each rank, the result is distributed to the output buffer of each rank based on the ID.
HcclAlltoAll	Sends the same-sized data to all ranks in the communicator and receives the same-sized data from all ranks.
HcclAlltoAllV	Sends data (with customizable size) to all ranks in the communicator and receives data from all ranks.
HcclAlltoAllVC	Sends data (with customizable size) to all ranks in the communicator and receives data from all ranks. Unlike AlltoAllV, AlltoAllVC uses the input parameter sendCountMatrix to pass the RX and TX parameters of all ranks.
HcclSend	Sends the data at the specified location on the current rank to the specified location on the destination rank.
HcclRecv	Receives data from the source rank to the specified location on the current rank.
HcclBatchSendRecv	Completes sending and receiving tasks in batches on the current rank. The sending and receiving tasks of the current rank are asynchronous and do not block each other.

Communicator Management APIs

C APIs

**Table 1** HCCL (C) APIs
API	Description
HcclCommInitClusterInfo	Initializes HCCL based on the rank table and creates an HCCL communicator.
HcclCommInitClusterInfoConfig	Initializes HCCL based on the rank table and creates an HCCL communicator with specific configurations.
HcclGetRootInfo	Generates the identification information (HcclRootInfo) of the root rank. Call this API on the root rank before calling the HCCL initialization API HcclCommInitRootInfo or HcclCommInitRootInfoConfig.
HcclCommInitRootInfo	Initializes the HCCL based on rootInfo to create an HCCL communicator.
HcclCommInitRootInfoConfig	Initializes the HCCL based on rootInfo and creates an HCCL communicator with specific configurations.
HcclCommConfigInit	Initializes the communicator configuration items and sets the configurable parameters to the default values.
HcclCommInitAll	In the single-server communication scenario, a process is used to create a communicator for multiple devices (one device corresponds to one thread). During the initialization of the communicator, devices[0] functions as the root rank to automatically collect cluster information.
HcclCommDestroy	Destroys a specified HCCL communicator.
HcclGetRankSize	Queries the number of ranks in a communicator.
HcclGetRankId	Obtains the rank ID of a device in a communicator.
HcclBarrier	Blocks the streams of all ranks in the specified communicator.
HcclSetConfig	Sets collective communication. Currently, only the support status of deterministic computing can be configured.
HcclGetConfig	Obtains the configuration related to collective communication.
HcclGetCommName	Obtains the name of the communicator where the specified communication operation is performed.
HcclCommGetHandleWithName	Obtains the handle to a communicator based on the communicator name.
HcclGetCommConfigCapability	Checks whether the current software version supports the initialization configuration of a communicator.
HcclCommSuspend	Suspends a communicator when an uncorrectable error (UCE) occurs in the on-chip memory (ACL_ERROR_RT_DEVICE_MTE_ERROR is returned by an ACL API). Note: This API is reserved and may be changed in later versions. It is not supported for developers.
HcclCommResume	Resumes the status of a communicator. Note: This API is reserved and may be changed in later versions. It is not supported for developers.
HcclCreateSubCommConfig	Splits an existing global communicator into sub-communicators with specific configurations.
HcclCommWorkingDevNicSet	Configures the communication NIC in the communicator in the cluster scenario. Communication can be switched between a device NIC and the standby NIC on the same NPU. The standby NIC is another die NIC on the same NPU.
HcclGetCommAsyncError	If the cluster information shows that the communication link of the device network port is unstable or network congestion occurs, "error cqe" is printed in the device log. This error is called "RDMA ERROR CQE". In the current version, this API can only be used to check whether the "RDMA ERROR CQE" error exists in the communicator.
HcclGetErrorString	Parses error codes of the HcclResult type.
HcclCommSetMemoryRange	Notifies HCCL of the reserved virtual memory address after virtual memory is successfully allocated using the aclrtReserveMemAddress API. After this API is called, the virtual memory is accessible to all communicators within the current process. Note: The zero-copy function API can be called only by the backend code of the Ascend Extension for PyTorch plugin. It is for trial use only and cannot be used in commercial products.
HcclCommUnsetMemoryRange	Notifies an HCCL communicator to invalidate the reserved virtual memory. Note: The zero-copy function API can be called only by the backend code of the Ascend Extension for PyTorch plugin. It is for trial use only and cannot be used in commercial products.
HcclCommActivateCommMemory	Activates the reserved virtual memory. Zero-copy can be enabled only when the activated memory is used as the input and output of a communication operator. Note: The zero-copy function API can be called only by the backend code of the Ascend Extension for PyTorch plugin. It is for trial use only and cannot be used in commercial products.
HcclCommDeactivateCommMemory	Deactivates a virtual memory. If the address of a deactivated virtual memory is used for collective communication, the zero-copy function will not be enabled. Note: The zero-copy function API can be called only by the backend code of the Ascend Extension for PyTorch plugin. It is for trial use only and cannot be used in commercial products.
HcclCommSymWinRegister	Registers the virtual memory as symmetric memory after allocating and mapping virtual and physical memory.
HcclCommSymWinDeregister	Deregisters the virtual memory corresponding to a registered symmetric window and releases the symmetric window resources.
HcclCommSymWinGet	Obtains the corresponding window resource handle and its offset within the window based on the virtual address pointer of the registered symmetric memory.
HcclSymWinGetPeerPointer	Obtains the virtual address pointer on the symmetric memory for a rank ID, based on the symmetric memory window handle and offset.

Python APIs

API	Description
create_group	Creates a custom group for collective communication.
destroy_group	Destroys a user-defined group for collective communication.
get_rank_size	Obtains the number of ranks (that is, the number of devices) in a group.
get_local_rank_size	Obtains the number of local ranks on the server where the devices in the group are located.
get_rank_id	Obtains the rank ID of a device in a group.
get_local_rank_id	Obtains the local rank ID of a device in a group.
get_world_rank_from_group_rank	Obtains the world rank ID based on the rank ID of the process in the group.
get_group_rank_from_world_rank	Obtains the group rank ID of the process in the group using the world rank ID.
set_split_strategy_by_idx	Sets a gradient segmentation strategy in a collective communication group based on the gradient index ID to implement AllReduce fusion and optimize the collective communication performance.
set_split_strategy_by_size	Sets a gradient segmentation strategy in a collective communication group based on the proportion of gradient data to implement AllReduce fusion and optimize the collective communication performance.

Group Call APIs

API	Description
HcclGroupStart	Starts a group call.
HcclGroupEnd	Ends a group call.

Parent topic: API