1. 版本历史¶

文档版本	版本	作者
V2.0	ECCL API参考	Enflame Tech

2. ECCL API参考¶

以下内容描述了ECCL集合通信库的对外接口以及相关的参数信息。包括了通信域生成与管理类接口、通信算子类接口、组操作接口以及点对点通信接口

2.1. 通信域生成与管理类接口¶

下列接口主要负责生成通信域并进行管理

ecclGetVersion¶

ecclResult_t ecclGetVersion(int *version)

ecclGetVersion接口返回目前eccl通信库的版本。目前返回的通信库都是最新版本，其余功能有待以后实现。

ecclGetUniqueId¶

ecclResult_t  ecclGetUniqueId(ecclUniqueId* uniqueId)

ecclGetUniqueId接口返回通信域的独有身份信息用于接下来的初始化通信域。每创建一个新的通信域根GCU卡都应该调用此函数，并将身份信息广播给域内所有的卡。

ecclCommInitRank¶

ecclResult_t ecclCommInitRank(ecclComm_t* comret, int nranks, ecclUniqueId commId, int rank)

ecclCommInitRank接口负责初始化指定的通信域，并返回对应的通信域信息给上层用户，上层用户将使用通信域信息调用集合通信接口。

ecclCommDestroy¶

ecclResult_t  ecclCommDestroy(ecclComm_t comm)

ecclCommDestroy会在所有操作结束后释放相应通信域内的所有资源。

ecclGetErrorString¶

const char*  ecclGetErrorString(ecclResult_t result);

ecclGetErrorString接口将程序的返回值转换成可读的字符串。

ecclCommCount¶

ecclResult_t ecclCommCount(const ecclComm_t comm, int* count);

ecclCommCount将会获取通信域内总的进程数量，并将结果保存在参数count中。

ecclCommDevice¶

ecclResult_t  ecclCommDevice(const ecclComm_t comm, int* device);

ecclCommDevice接口负责获取通信域内某张GCU卡的设备号，并将结果保存在参数device中。

ecclCommUserRank¶

ecclResult_t ecclCommUserRank(const ecclComm_t comm, int* rank);

ecclCommUserRank接口负责获取通信域内某个进程的进程号，并将结果保存在参数rank中。

参数描述¶

表 2.1.4 管理接口参数描述¶
参数	意义
int nranks	通信域内参与集合通信的进程（rank）数量，取值范围: 1 - n
ecclUniqueId commId	通信域的身份标号，总是唯一地标识一个通信域
int rank	本进程(rank)在集合通信共nranks个进程中的编号，取值范围: 0 - nrank-1
ecclcomm_t* comret	通信域创建成功后返回的通信域描述符

2.2. 通信算子类接口¶

下列接口实现了常见的集合通信操作

ecclBroadcast¶

ecclResult_t ecclBroadcast(const void* sendbuff, void* recvbuff, size_t count, ecclDataType_t datatype, int root, ecclComm_t comm, ecclStream_t stream)

ecclBroadcast将通信域内根GCU卡输出内存的数据广播到其他卡的输入内存上。输出内存只对根GCU卡起作用，其余GCU卡会忽略。输出内存和输入内存可以是同一块内存，此情况下不做任何处理。

ecclAllReduce¶

ecclResult_t ecclAllReduce(const void* sendbuff, void* recvbuff, size_t count, ecclDataType_t datatype, ecclRedOp_t op,ecclComm_t comm, ecclStream_t stream)

ecclAllReduce将通信域内所有GCU卡上输出内存的数据按照算子类型做规约操作，而每个卡的输入内存将会保存规约后的结果。输出内存和输入内存可以是同一块内存，此情况下不做任何处理。

ecclReduceScatter¶

ecclResult_t ecclReduceScatter(const void* sendbuff, void* recvbuff, size_t recvcount, ecclDataType_t datatype, ecclRedOp_t op, ecclComm_t comm, ecclStream_t stream);

ecclReduceScatter将通信域内所有GCU卡上输出内存的数据按照算子类型做规约操作，并将得到的结果均匀分片后分发到每一张卡的输入内存上，第i张卡上保存规约后的第i片数据。此集合通信方式要求输出内存上数据大小为输入内存数据大小的nranks倍。

ecclAllGather¶

ecclResult_t ecclAllGather(const void* sendbuff, void* recvbuff, size_t sendcount, ecclDataType_t datatype, ecclComm_t comm, ecclStream_t stream);

ecclAllGather将通信域内所有GCU卡上输出内存的数据做聚合操作，而每个卡的输入内存将会保存聚合后的结果。每张卡上数据大小需要一致，输入内存上第i个位置保存第i张卡的数据。输出内存和输入内存可以是同一块内存，此情况下不做任何处理。此集合通信方式要求输入内存上数据大小为输出内存数据大小的nranks倍。

ecclAllGatherv¶

ecclResult_t ecclAllGatherv(const void* sendbuff, size_t sendcount, ecclDataType_t sendtype, void* recvbuff, const size_t* recvcounts, const size_t* displs, ecclDataType_t recvtype, ecclComm_t comm, ecclStream_t stream);

ecclAllGatherv将通信域内所有GCU卡输出内存的数据做聚合操作，每张卡输入内存上第i个位置保存第i张卡的数据，每张卡上数据大小允许不同。但是第i张卡上发送数据的个数和类型需要跟其余卡上接受数据的个数（recvcounts[i]）和类型一致。每张卡上都保存了一份偏移量参数displs，参数记录了接收数据在输入内存上的偏移。

2.3. 组操作接口¶

组操作定义了当前线程的行为以避免阻塞，因此可以在多个独立线程上使用该接口

ecclGroupStart¶

ecclResult_t ecclGroupStart();

ecclGroupStart开启组操作，接下的通信操作不会因为CPU之间的同步而阻塞。

ecclGroupEnd¶

ecclResult_t ecclGroupEnd();

ecclGroupEnd结束组操作。当从上个ecclGroupStart之间的通信操作都被处理后返回。这意味着通信算子都被排入了流中，并不代表通信操作已经完成。

Attention

ecclGroupStart/End目前只支持send/recv的组操作，暂不支持其他集合通信的组操作

2.4. 点对点通信接口¶

通信域内指定多张卡之间进行数据接发

ecclSend¶

ecclResult_t ecclSend(const void* sendbuff, size_t count, ecclDataType_t datatype, int peer, ecclComm_t comm, ecclStream_t stream);

ecclSend将输出内存上的数据传输给指定的卡，同时被指定的卡需要运行ecclRecv来接受数据（数据类型和位数需要一致）。

ecclRecv¶

ecclResult_t ecclRecv(void* recvbuff, size_t count, ecclDataType_t datatype, int peer, ecclComm_t comm, ecclStream_t stream);

ecclRecv将从指定的卡上接收到的数据存入输入内存中，同时被指定的卡需要运行ecclSend来发送数据（数据类型和位数需要一致）。

ecclGather¶

ecclResult_t ecclGather(const void* sendbuff, void* recvbuff, size_t sendcount, ecclDataType_t datatype, int root, ecclComm_t comm, ecclStream_t stream);

ecclGather将通信域中非根GCU卡的数据都传输给根GCU卡。根GCU卡上第i个位置保存第i张卡的数据。如果根GCU卡想要接收全部的数据，需要保证接收数据个数是发送数据个数的nranks倍。

ecclScatter¶

ecclResult_t ecclScatter(const void* sendbuff, void* recvbuff, size_t recvcount, ecclDataType_t datatype, int root, ecclComm_t comm, ecclStream_t stream);

ecclScatter将根GCU卡上的数据均匀分片后传输给通信域中的每一张卡。第i张卡上保存的是根GCU卡上第i个分片的数据。如果根GCU卡想要发送全部的数据，需要保证发送数据个数是接收数据个数的nranks倍。

ecclAllToAll¶

ecclResult_t ecclAllToAll(const void* sendbuff, void* recvbuff, size_t count, ecclDataType_t datatype, ecclComm_t comm, ecclStream_t stream);

ecclAllToAll将每张卡上第i个分片的数据聚合到第i张卡上。第i张卡将输出内存中的第j块数据发送给第j张卡，而第j张卡将来自第i张卡的数据存入输入内存中的第i块位置。

2.5. 接口参数描述¶

表 2.5.1 通信接口参数描述¶
参数	意义
const void* sendbuff	输出内存区地址
void* recvbuff	输入内存区地址
size_t count	需要进行通信运算的元素个数
size_t sendcount	输出数据元素个数
size_t recvcount	输入数据元素个数
ecclDataType_t datatype	需要进行通信运算的元素数据类型
ecclRedOp_t op	规约通信算子的类型
ecclComm_t comm	本次通信域的描述符，ecclCommInitRank完成后得到该描述符
int peer	点对点通信指定卡的rank号
const size_t* displs	记录接收数据在输入内存上的偏移

2.6. 返回值以及枚举类参数取值¶

ecclResult_t¶

下表枚举了ecclResult_t可能的返回值

表 2.6.1 返回值描述¶
返回值	对应数值	返回值描述
ecclSuccess	0	集合通信初始化成功，或者算子下发完成
ecclUnhandledSdkError	1	调用SDK或者驱动接口返回失败
ecclSystemError	2	操作系统的功能返回失败。如初始化socket失败，读写文件失败等
ecclInternalError	3	ECCL内部流程失败
ecclInvalidArgument	4	上层输入无效的参数
ecclInvalidUsage	5	上层使用方式有误
ecclNoResources	6	申请资源失败。如HBM内存等资源
ecclNumResults	7	无效的返回值

ecclRedOp_t¶

下表枚举了Reduce算子可能出现的类型

表 2.6.2 Reduce通信算子描述¶
通信类型	对应数值	类型描述
ecclSum	0	实现加(+)操作
ecclProd	1	实现乘(*)操作
ecclMax	2	实现取最大值操作
ecclMin	3	实现取最小值操作
ecclNumOps	4	无效的类型

ecclDataType_t¶

下表枚举了ecclDataType_t可能出现的类型

表 2.6.3 数据类型描述¶
数据类型	对应数值	类型描述
ecclInt8,ecclChar	0	8位符号整数
ecclUint8	1	8位无符号整数
ecclInt32,ecclInt	2	32位符号整数
ecclUint32	3	32位无符号整数
ecclInt64	4	64位符号整数
ecclUint64	5	64位无符号整数
ecclFloat16,ecclHalf	6	16位浮点数
ecclFloat32,ecclFloat	7	32位浮点数
ecclFloat64,ecclDouble	8	64位浮点数
ecclBFloat16	9	16位截断浮点数
ecclNumTypes	10	无效的类型

Attention

ecclBroadcast算子支持任意类型的数据输入。ecclReduce和ecclALLReduce算子在T10板卡上仅支持ecclFloat32的数据，在T20板卡上支持ecclFloat32，ecclFloat16，ecclInt8，ecclInt32，ecclBFloat16的数据输入。