AscendC HCCL Tiling 之 GetTiling 接口详解:为通信算子生成 Mc2InitTiling 与 Mc2CcTiling

原创2026-10-15 22:31:29612 阅读
文章标签:人工智能深度学习高性能计算CANN

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 参数的完整流程分三步:

  1. 创建配置对象:调用 HCCL Tiling 构造函数 创建 AscendC::Mc2CcTilingConfig 对象,传入 groupName、opType、algConfig、reduceType 等基本信息。
  2. 可选配置:通过 SetOpType、SetGroupName、SetAlgConfig、SetReduceType、SetStepSize、SetSkipLocalRankCopy、SetSkipBufferWindowCopy、SetDebugMode、SetCommBlockNum、SetQueueNum、SetCommEngine 等配置接口微调通信参数。
  3. 生成 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&):初始化通信任务

  1. 归约类型预检:当 opType 为 HCCL_CMD_ALLREDUCE、HCCL_CMD_REDUCE 或 HCCL_CMD_REDUCE_SCATTER 时,reduceType 必须小于 HCCL_REDUCE_RESERVED,否则断言失败。
  2. 写入初始字段:version 置为 INIT_TILING_VERSION(100),mc2HcommCnt 清零,写入 debugMode、preparePosition=0、queueNum、commBlockNum,并清零 8 个 offset。
  3. CCU 版本升级:若 algConfig 命中注册的 CCU 算法(commEngine 为 5/6 且算法名在 REGISTERED_CCU_ALGORITHMS 集合中,或以 [ 开头的外部算法可通过 ParseExternalAlg 语法校验),version 置为 INIT_TILING_CCU_NEW_VERSION(101),该版本仅由 CCU 链消费。
  4. 设备类型探测:通过 ASCEND_HOME_PATH 定位 libruntime.so,动态加载 rtGetSocVersion 获取 SoC 版本,再经 ResolveDevType 映射:Ascend910B → A2(1)、Ascend950 → A5(6)、Ascend910_96/ascend960 → A6(8),写入 devType。

7.2 GetTiling(::Mc2CcTiling&):填充单个通信任务

  1. 顺序强约束:实现开头断言 impl_.initTilingAddr_ != 0,否则报错 must be set Mc2InitTiling first——也就是说,必须先调用 GetTiling(::Mc2InitTiling&),把初始化结构体的地址登记下来,才能调用本重载。这正是 6.1 示例中两个调用顺序不可颠倒的原因。
  2. 参数合法性校验:
    • 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。
  3. 字段写入:写入 skipLocalRankCopy、skipBufferWindowCopy、stepSize、version=1,通过 strcpy_s 拷贝 groupName 与 algConfig,随后写入 opType、reduceType、srcDataType、dstDataType、commEngine。
  4. 偏移登记:调用 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 接口的通信编排打下基础。

登录后查看全文
asc-devkit