AscendC HCCL Tiling 之 GetTiling 接口详解:为通信算子生成 Mc2InitTiling 与 Mc2CcTiling
AscendC HCCL Tiling 之 GetTiling 接口详解:为通信算子生成 Mc2InitTiling 与 Mc2CcTiling
本文围绕 AscendC(asc-devkit 仓库)HCCL Tiling 高阶 API 中的
GetTiling接口展开:它负责把用户在Mc2CcTilingConfig中组装的通信信息(通信域、任务类型、算法、归约类型等)落地为算子 TilingData 中的Mc2InitTiling与Mc2CcTiling结构体,是通算融合算子 Tiling 侧组装通信参数的关键一步。读完本文,你将掌握GetTiling两个重载的函数原型、参数与返回值语义、与构造/配置接口的配合顺序、底层实现中的校验与登记逻辑,并能直接写出可运行的通信算子 Tiling 函数。
一、GetTiling 在 HCCL Tiling 流程中的位置
AscendC 提供一组 HCCL Tiling API,帮助算子在 Host 侧 Tiling 阶段获取核函数(Kernel)计算与通信所需的 Tiling 参数。开发者只需传入通信相关的基本信息,即可获得通信相关的 Tiling 参数,而无需手工拼装二进制 TilingData。
按照 HCCL Tiling 使用说明,获取 Tiling 参数的完整流程分三步:
- 创建配置对象:调用 HCCL Tiling 构造函数 创建
AscendC::Mc2CcTilingConfig对象,传入groupName、opType、algConfig、reduceType等基本信息。 - 可选配置:通过
SetOpType、SetGroupName、SetAlgConfig、SetReduceType、SetStepSize、SetSkipLocalRankCopy、SetSkipBufferWindowCopy、SetDebugMode、SetCommBlockNum、SetQueueNum、SetCommEngine等配置接口微调通信参数。 - 生成 Tiling:调用
GetTiling接口,将配置对象中的信息写入算子 TilingData 结构体,供 Kernel 侧 InitV2、SetCcTilingV2 等接口消费。
GetTiling 正是第三步的落点:它把前面所有配置“变现”为 Kernel 可读的 TilingData。
二、功能说明与函数原型
功能:获取 Mc2InitTiling 参数和 Mc2CcTiling 参数。前者保存通信任务的整体初始化信息,后者保存具体每个通信任务的参数配置(详见第五节)。
GetTiling 是 Mc2CcTilingConfig 类的两个重载成员函数(声明见 include/adv_api/hccl/hccl_tiling.h):
uint32_t GetTiling(::Mc2InitTiling& tiling)
uint32_t GetTiling(::Mc2CcTiling& tiling)
- 第一个重载:填充 Mc2InitTiling,即通信任务的初始化信息。
- 第二个重载:填充 Mc2CcTiling,即单个通信任务的具体参数配置。
两个结构体均定义在 optiling 命名空间(::Mc2InitTiling、::Mc2CcTiling),详见 hccl_tilingdata.h。
三、参数说明
表1 参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| tiling | 输出 | Tiling 结构体存储的 Tiling 信息。 |
tiling 是输出型参数,通过引用传入。实际使用时传入的是算子自己组装的 TilingData 结构体中的成员,例如 tiling->mc2InitTiling 与 tiling->reduceScatterTiling(tiling 为算子 Tiling 函数通过 GetTilingData<T>() 或类似机制拿到的 TilingData 指针,示例详见第六节)。
四、返回值说明
| 返回值 | 含义 |
|---|---|
| 0 | tiling 计算成功,该 Tiling 结构体的值可以用于后续计算。 |
| 非0 | tiling 计算失败,该 Tiling 结果无法使用。 |
实现中成功路径统一返回 EXIT_SUCCESS(即 0),任何校验失败路径返回 EXIT_FAILURE(即 1)。从实现(impl/adv_api/tiling/hccl/hccl_tiling.cpp)可以看到,失败场景包括但不限于:
- 未先调用
GetTiling(::Mc2InitTiling&)就直接调用GetTiling(::Mc2CcTiling&); groupName、algConfig超过 128 字节;opType不在合法区间或为 0;reduceType、dstDataType、srcDataType超出枚举保留边界;- 环境中无法解析
ASCEND_HOME_PATH或拿不到 SoC 版本信息。
这些失败会通过 ASCENDC_HOST_ASSERT 打印具体的失败原因日志,便于定位。
五、TilingData 结构体与内部布局
按 TilingData 结构体 的说明:
- Mc2InitTiling:
uint8_t*类型,用于初始化通信任务配置,支持最大长度 64 字节,该结构体仅支持通过GetTiling接口获取。 - Mc2CcTiling:
uint8_t*类型,用于各通信域中每个通信任务的参数配置,该结构体仅支持通过GetTiling接口获取;注意最多支持配置 8 个通信任务。
从当前仓库的头文件(hccl_tilingdata.h)看,两个结构体均通过 BEGIN_TILING_DATA_DEF / TILING_DATA_FIELD_DEF_ARR / END_TILING_DATA_DEF 宏声明,Mc2InitTiling 为 64 字节 reserved 数组,Mc2CcTiling 为 512 字节 reserved 数组(说明文档中描述为最大 280 字节,两者以实际安装的 CANN 版本头文件为准,请以当前环境的 hccl_tilingdata.h 为最终依据)。
对外暴露为 reserved 不透明字节,对内则由内部结构 Mc2InitTilingInner / Mc2CcTilingInner 承载(定义见 include/adv_api/hccl/internal/hccl_tiling_msg.h):
Mc2InitTilingInner:version(版本号)、mc2HcommCnt(已登记的通信任务个数)、offset[8](每个 Mc2CcTiling 相对 Mc2InitTiling 的偏移)、debugMode、preparePosition、queueNum、commBlockNum、devType等,合计 64 字节。Mc2CcTilingInner:skipLocalRankCopy、skipBufferWindowCopy、stepSize、version、commEngine、srcDataType、dstDataType、groupName[128]、algConfig[128]、opType、reduceType等,合计 512 字节。
GetTiling 的本质工作,就是把 Mc2CcTilingConfig 内部的 HcclTilingImpl 状态(见 impl/adv_api/tiling/hccl/hccl_tiling_impl_def.h)逐字段写入上述内部结构,并登记偏移关系。
六、调用示例
6.1 原文档基础示例(ReduceScatter 场景)
以下示例来自 GetTiling 接口说明,展示一个 ReduceScatter 通信任务的 Tiling 组装:
const char* groupName = "testGroup";
uint32_t opType = HCCL_CMD_REDUCE_SCATTER;
std::string algConfig = "ReduceScatter=level0:fullmesh";
uint32_t reduceType = HCCL_REDUCE_SUM;
AscendC::Mc2CcTilingConfig mc2CcTilingConfig(groupName, opType, algConfig, reduceType);
mc2CcTilingConfig.GetTiling(tiling->mc2InitTiling); // tiling为算子组装的TilingData结构体,获取Mc2InitTiling
mc2CcTilingConfig.GetTiling(tiling->reduceScatterTiling); // tiling为算子组装的TilingData结构体,获取Mc2CcTiling
要点:
tiling为算子组装的 TilingData 结构体指针,mc2InitTiling必须是该结构体的第一个成员(这是 TilingData 结构体 的使用约束),reduceScatterTiling(Mc2CcTiling)的位置没有要求。- 先调用
GetTiling(tiling->mc2InitTiling),再调用GetTiling(tiling->reduceScatterTiling),顺序不可颠倒(原因见第七节)。
6.2 完整 Tiling 函数示例(含可选配置接口)
把构造函数、可选配置接口与 GetTiling 组合在一个标准的 Tiling 函数中(综合参考 HCCL Tiling 使用说明 与 SetStepSize 调用示例):
static ge::graphStatus AllToAllVCustomTilingFunc(gert::TilingContext* context)
{
AllToAllVCustomV3TilingData* tiling = context->GetTilingData<AllToAllVCustomV3TilingData>();
const std::string groupName = "testGroup";
const std::string algConfig = "AlltoAll=level0:fullmesh;level1:pairwise";
AscendC::Mc2CcTilingConfig mc2CcTilingConfig(groupName, HCCL_CMD_ALLTOALLV, algConfig, 0);
// 可选:通过配置接口调整通信细节
mc2CcTilingConfig.SetSkipLocalRankCopy(0); // 计算结果是否输出到recvBuf
mc2CcTilingConfig.SetSkipBufferWindowCopy(1); // 通信算法获取输入数据的位置
mc2CcTilingConfig.SetStepSize(1U); // 细粒度通信步长,仅Atlas A3系列支持
mc2CcTilingConfig.GetTiling(tiling->mc2InitTiling);
mc2CcTilingConfig.GetTiling(tiling->mc2CcTiling);
return ge::GRAPH_SUCCESS;
}
配置接口一览(详见 HCCL Tiling 使用说明 中的接口列表):
| 接口 | 功能 |
|---|---|
| SetOpType | 设置通信任务类型。 |
| SetGroupName | 设置通信任务所在的通信域。 |
| SetAlgConfig | 设置通信算法。 |
| SetReduceType | 设置 Reduce 操作类型。 |
| SetStepSize | 设置细粒度通信时,通信算法的步长。 |
| SetSkipLocalRankCopy | 设置本卡的通信算法计算结果是否输出到 recvBuf。 |
| SetSkipBufferWindowCopy | 设置通信算法获取输入数据的位置。 |
| SetDebugMode | 设置调测模式。 |
| SetCommBlockNum | 设置通信块数量。 |
| SetQueueNum | 设置队列数量。 |
| SetCommEngine | 设置通信引擎。 |
6.3 多通信任务场景
当算子在一次执行中包含多个通信任务时,可定义多个 Mc2CcTiling 成员(最多 8 个),分别调用 GetTiling 填充:
mc2CcTilingConfig.GetTiling(tiling->mc2InitTiling);
mc2CcTilingConfig.GetTiling(tiling->allReduceTiling); // 第一个通信任务
mc2CcTilingConfig.GetTiling(tiling->reduceScatterTiling); // 第二个通信任务
每次调用 GetTiling(::Mc2CcTiling&) 都会在 Mc2InitTiling 中登记该任务相对初始化结构的偏移并递增 mc2HcommCnt;当超过 8 个时会触发断言失败。
七、源码级原理:调用顺序与校验逻辑
两个重载在 impl/adv_api/tiling/hccl/hccl_tiling.cpp 中实现,其行为可以从源码确认:
7.1 GetTiling(::Mc2InitTiling&):初始化通信任务
- 归约类型预检:当
opType为HCCL_CMD_ALLREDUCE、HCCL_CMD_REDUCE或HCCL_CMD_REDUCE_SCATTER时,reduceType必须小于HCCL_REDUCE_RESERVED,否则断言失败。 - 写入初始字段:
version置为INIT_TILING_VERSION(100),mc2HcommCnt清零,写入debugMode、preparePosition=0、queueNum、commBlockNum,并清零 8 个offset。 - CCU 版本升级:若
algConfig命中注册的 CCU 算法(commEngine为 5/6 且算法名在REGISTERED_CCU_ALGORITHMS集合中,或以[开头的外部算法可通过ParseExternalAlg语法校验),version置为INIT_TILING_CCU_NEW_VERSION(101),该版本仅由 CCU 链消费。 - 设备类型探测:通过
ASCEND_HOME_PATH定位libruntime.so,动态加载rtGetSocVersion获取 SoC 版本,再经ResolveDevType映射:Ascend910B→ A2(1)、Ascend950→ A5(6)、Ascend910_96/ascend960→ A6(8),写入devType。
7.2 GetTiling(::Mc2CcTiling&):填充单个通信任务
- 顺序强约束:实现开头断言
impl_.initTilingAddr_ != 0,否则报错must be set Mc2InitTiling first——也就是说,必须先调用GetTiling(::Mc2InitTiling&),把初始化结构体的地址登记下来,才能调用本重载。这正是 6.1 示例中两个调用顺序不可颠倒的原因。 - 参数合法性校验:
groupName长度 ≤GROUP_NAME_SIZE(128);algConfig长度 ≤ALG_CONFIG_SIZE(128);opType满足0 < opType < HCCL_CMD_ALL(即不能为 0,也不能越界);reduceType<HCCL_REDUCE_RESERVED;dstDataType、srcDataType<HCCL_DATA_TYPE_RESERVED。
- 字段写入:写入
skipLocalRankCopy、skipBufferWindowCopy、stepSize、version=1,通过strcpy_s拷贝groupName与algConfig,随后写入opType、reduceType、srcDataType、dstDataType、commEngine。 - 偏移登记:调用
UpdateMc2InitTiling(initTilingAddr, ccTilingAddr),将当前 Mc2CcTiling 相对 Mc2InitTiling 的字节偏移写入offset[mc2HcommCnt]并递增计数;计数上限为MAX_CC_TILING_NUM(8)。
7.3 与 Kernel 侧的衔接
Tiling 侧生成的 Mc2InitTiling / Mc2CcTiling 会随 TilingData 下发给 Kernel。Kernel 侧在 HCCL 使用说明 描述的流程中,通过 InitV2(contextGM, &tilingData) 传入含这两个结构体的 TilingData,并用 SetCcTilingV2(offsetof(..., mc2CcTiling)) 把对应通信任务的 Tiling 地址发给 AI CPU 或 CCU 服务端解析执行——GetTiling 生成的偏移登记(offset[]/mc2HcommCnt)正是服务端定位各通信任务配置的依据。
八、关键取值参考
以下枚举用于构造 Mc2CcTilingConfig 及校验 opType / reduceType / 数据类型(详细定义见 HCCL Tiling 构造函数 与 HCCL 使用说明)。
HcclCMDType(通信任务类型,opType 取值):
enum class HcclCMDType {
HCCL_CMD_INVALID = 0,
HCCL_CMD_BROADCAST = 1,
HCCL_CMD_ALLREDUCE,
HCCL_CMD_REDUCE,
HCCL_CMD_SEND,
HCCL_CMD_RECEIVE,
HCCL_CMD_ALLGATHER,
HCCL_CMD_REDUCE_SCATTER,
HCCL_CMD_ALLTOALLV,
HCCL_CMD_ALLTOALLVC,
HCCL_CMD_ALLTOALL,
HCCL_CMD_GATHER,
HCCL_CMD_SCATTER,
HCCL_CMD_BATCH_SEND_RECV,
HCCL_CMD_BATCH_PUT,
HCCL_CMD_BATCH_GET,
HCCL_CMD_ALLGATHER_V,
HCCL_CMD_REDUCE_SCATTER_V,
HCCL_CMD_BATCH_WRITE,
HCCL_CMD_HALF_ALLTOALLV = 20,
HCCL_CMD_ALL
};
- 不同产品系列支持的通信任务类型不同:例如 Ascend 950PR&950DT 支持 ALLREDUCE、ALLGATHER、REDUCE_SCATTER、ALLTOALL、ALLTOALLV、HALF_ALLTOALLV;Atlas A3 支持 ALLREDUCE、ALLGATHER、REDUCE_SCATTER、ALLTOALL、ALLTOALLV、BATCH_WRITE;Atlas A2 支持 ALLREDUCE、ALLGATHER、REDUCE_SCATTER、ALLTOALL、BATCH_WRITE。请以实际使用的产品系列为准。
HcclReduceOp(归约操作类型,reduceType 取值,仅对有归约操作的通信任务生效):
enum HcclReduceOp {
HCCL_REDUCE_SUM = 0, /* sum */
HCCL_REDUCE_PROD = 1, /* prod */
HCCL_REDUCE_MAX = 2, /* max */
HCCL_REDUCE_MIN = 3, /* min */
HCCL_REDUCE_RESERVED /* reserved */
}
HcclDataType(dstDataType / srcDataType 取值,uint8_t):HCCL_DATA_TYPE_INT8=0、INT16=1、INT32=2、FP16=3(half/float16)、FP32=4(float)、INT64=5、UINT64=6、UINT8=7、UINT16=8、UINT32=9、FP64=10、BFP16=11(bfloat16)、INT128=12(预留暂不支持)、HIF8=14、FP8E4M3=15、FP8E5M2=16、FP8E8M0=17、HCCL_DATA_TYPE_RESERVED。
注意:dstDataType / srcDataType / commEngine 参数在不同产品系列上的支持情况不同(例如 Atlas A2 与 Atlas A3 系列暂不支持数据类型参数,配置后不生效;Ascend 950 系列支持且对输入输出类型有配套约束),请参考构造函数文档中的分产品说明。
九、使用建议与常见问题
- 先 Init 后 Cc:务必先
GetTiling(tiling->mc2InitTiling)再GetTiling(tiling->mc2CcTiling),否则返回非 0。 - 结构体位置:
Mc2InitTiling必须定义为算子 TilingData 结构体的第一个成员;Mc2CcTiling位置不限,但一个算子最多 8 个通信任务。 - 返回值检查:生产代码中建议对两次
GetTiling的返回值做非 0 校验,失败时该 Tiling 结果不可使用,避免把非法 TilingData 传给 Kernel。 - 命名空间与头文件:
Mc2CcTilingConfig位于AscendC命名空间,声明于 include/adv_api/hccl/hccl_tiling.h;Mc2InitTiling/Mc2CcTiling位于optiling命名空间,声明于 include/adv_api/hccl/hccl_tilingdata.h。 - 调试手段:HCCL 相关算子编译时增加编译选项
-DASCENDC_DEBUG可开启异常场景拦截,配合 assert 接口 使用;实现中也通过TILING_LOG_INFO/DEBUG打印了完整的 Mc2InitTiling 与 Mc2CcTiling 字段,便于在日志中核对。
总结
GetTiling 是 AscendC HCCL Tiling 高阶 API 的“临门一脚”:它以 Mc2CcTilingConfig 中已组装的通信信息为输入,向 Mc2InitTiling 与 Mc2CcTiling 两个结构体输出 Kernel 侧可消费的 Tiling 数据,并在底层完成参数校验、CCU 版本识别、设备类型探测与偏移登记。理解其函数原型、返回值语义、调用顺序约束(先 Init 后 Cc)以及 8 个通信任务的上限,即可在通算融合算子开发中稳定、正确地组装通信侧 TilingData,为后续 Kernel 侧 InitV2 / SetCcTilingV2 / Prepare 接口的通信编排打下基础。