asc-devkit HCCL Tiling 接口 SetCommEngine 详解:通信引擎的配置原理与实战

原创2026-10-15 20:26:511,999 阅读
文章标签:人工智能深度学习高性能计算CANN

asc-devkit HCCL Tiling 接口 SetCommEngine 详解:通信引擎的配置原理与实战

导读

SetCommEngine 是 asc-devkit 中 Ascend C HCCL Tiling 侧接口 Mc2CcTilingConfig 的配置方法之一,用于显式指定通信任务(如 AllReduce、AllToAllV、ReduceScatter 等)运行时使用的通信引擎。在多引擎并存的昇腾平台上,正确配置通信引擎直接决定算子 Kernel 侧通信计算走 AICPU、CCU 还是 CPU 线程链路。本文以 SetCommEngine.md 为骨架,结合 hccl_tiling.h 与 hccl_tiling.cpp 的实现细节,讲清函数原型、参数取值、返回值、底层落点与完整调用示例。读完本文,你将能在通算融合算子的 Tiling 阶段正确使用 SetCommEngine,并理解该配置如何影响 TilingData 生成与通信资源分配。

背景:HCCL Tiling 接口与 Mc2CcTilingConfig

在 asc-devkit 的通信算子开发中,HCCL Tiling API 用于在 Host 侧组装通信算子的 Tiling 参数。使用流程为:先创建 Mc2CcTilingConfig 对象,再通过一组 Set* 配置接口设置通信信息,最后调用 GetTiling 获取 TilingData。这一流程在 HCCL_Tiling_usage.md 中有完整说明。

Mc2CcTilingConfig 类声明于 hccl_tiling.h,构造函数原型为:

Mc2CcTilingConfig(const std::string& groupName, uint32_t opType, const std::string& algConfig,
                  uint32_t reduceType = 0, uint8_t dstDataType = 0, uint8_t srcDataType = 0,
                  uint8_t commEngine = 0);

可以看到 commEngine 本身也是构造函数的最后一个可选参数(默认值 0)。除了在构造时直接传入,还可以在对象创建后通过 SetCommEngine 单独设置,为按需调整通信引擎提供了灵活性。

功能说明与函数原型

功能说明

SetCommEngine 的功能是:设置通信任务使用的通信引擎。通信引擎决定了集合通信(Collective Communication)任务在设备侧由哪个执行单元或线程承载,是影响通信算子执行路径的关键配置项。

函数原型

uint32_t SetCommEngine(uint8_t commEngine)

该接口是 Mc2CcTilingConfig 的公有成员函数(见 hccl_tiling.h),接收一个 uint8_t 类型的通信引擎取值,返回 uint32_t 类型的设置结果。

参数说明

commEngine 参数

参数名 输入/输出 描述
commEngine 输入 通信引擎。uint8_t 类型,该参数的取值范围请参考 HcclCommConfig 中的 hcclOpExpansionMode 参数的取值说明。

原文档指出该参数的取值语义与 HcclCommConfig.hcclOpExpansionMode 一致。在仓库源码中,通信引擎的取值集合定义于 alg_param.h 的 OpExecuteConfig 枚举:

enum class OpExecuteConfig {
    DEFAULT = 0,
    HOSTCPU_TS = 1,
    AICPU_TS = 2,
    AIV = 3,
    AIV_ONLY = 4,
    CCU_MS = 5,
    CCU_SCHED = 6,
    AICPU = 7,
    HOSTCPU = 8,
    CCU_FAIL
};

其中与 SetCommEngine 直接相关的常用取值包括:

  • 0(DEFAULT):默认引擎,未显式指定时使用。
  • 2(AICPU_TS):AICPU 线程(Task Scheduler)引擎,通信任务调度到 AICPU 线程执行。
  • 5(CCU_MS):CCU 引擎,对应集合通信单元(CCU)加速模式。
  • 6(CCU_SCHED):CCU 调度引擎,CCU 加速模式下由调度器统一编排。
  • 7(AICPU):AICPU 引擎。

取值的深层语义

该枚举与 HcclCommConfig.hcclOpExpansionMode 的对应关系,在 types.h 中有明确注释:用户配置的 hcclOpExpansionMode 会转为 HcclAccelerator 枚举,其成员顺序与上述 OpExecuteConfig 一一对应(DEFAULT, HOSTCPU_TS, AICPU_TS, AIV, AIV_ONLY, CCU_MS, CCU_SCHED, AICPU)。因此 Tiling 侧写入的 commEngine 数值可直接与运行时的引擎枚举对齐。

需要特别说明的是:从源码实现看,SetCommEngine 本身不做取值范围校验(见下文"返回值说明"),但底层消费链会对取值做严格检查。例如 hccl_alloc_ctx_res.cc 中 ObtainCommEngine 会校验各 Tiling 的 commEngine 一致性并拒绝非 AICPU_TS/CCU_SCHED 的取值;hccl_tiling.cpp 中 IsCcuAlgorithmRegistered 仅当 commEngine 为 5 或 6(CCU 系引擎)时才进入 CCU 算法判定逻辑。因此建议严格按照 hcclOpExpansionMode 的合法取值传参。

返回值说明

  • 0 表示设置成功。
  • 非 0 表示设置失败。

对照实现(hccl_tiling.cpp):

uint32_t Mc2CcTilingConfig::SetCommEngine(uint8_t commEngine)
{
    impl_.commEngine_ = commEngine;
    return EXIT_SUCCESS;
}

该接口直接将取值写入内部实现类 HcclTilingImpl 的 commEngine_ 成员(定义见 hccl_tiling_impl_def.h),不做范围校验,当前实现恒返回成功(EXIT_SUCCESS,值为 0)。这也意味着取值是否合法要到后续 GetTiling 生成 TilingData 或运行期分配资源时才会暴露问题,开发者应在调用前自行确认取值。

约束说明

原文档标注"约束说明:无"。结合实现可以看出:

  • SetCommEngine 单次调用无附加约束,可随时在 GetTiling 前调用;
  • 但需要注意调用顺序约束:GetTiling(Mc2InitTiling) 必须先于 GetTiling(Mc2CcTiling) 调用,后者在 hccl_tiling.cpp 中通过 ASCENDC_HOST_ASSERT(impl_.initTilingAddr_ != 0, ...) 强制校验;
  • 多个通信任务场景下,不同任务的 commEngine 应保持一致,否则在资源分配阶段会触发一致性校验失败(见 hccl_alloc_ctx_res.cc)。

调用示例与实战解读

原文档示例

原文档给出一个通算融合算子 Tiling 函数的完整示例:

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.SetCommEngine(1U);
    mc2CcTilingConfig.GetTiling(tiling->mc2InitTiling);
    mc2CcTilingConfig.GetTiling(tiling->mc2CcTiling);
    return ge::GRAPH_SUCCESS;
}

该示例的完整步骤解读如下:

  1. 获取算子 TilingData 结构体:通过 context->GetTilingData<AllToAllVCustomV3TilingData>() 拿到算子自定义的 Tiling 结构体。按 HCCL_Tiling_usage.md 的约定,Mc2InitTiling 必须定义为该 Tiling 结构体的第一个成员,Mc2CcTiling 的位置无要求;单算子最多支持 8 个 Mc2CcTiling 通信任务(见 hccl_tiling_msg.h 中 MAX_CC_TILING_NUM = 8U)。

  2. 构造配置对象:Mc2CcTilingConfig(groupName, HCCL_CMD_ALLTOALLV, algConfig, 0) 指定通信域 testGroup、通信任务类型 HCCL_CMD_ALLTOALLV、算法配置 "AlltoAll=level0:fullmesh;level1:pairwise",reduceType 传 0(AllToAllV 非归约操作,不生效)。

  3. 设置通信引擎:SetCommEngine(1U) 将通信引擎设置为 1。示例中的 1U 对应 HOSTCPU_TS 引擎,表示 AllToAllV 通信任务交由 CPU Task Scheduler 线程执行。若改用 CCU 加速,可传 5U(CCU_MS)或 6U(CCU_SCHED)。

  4. 生成 TilingData:依次调用 GetTiling(tiling->mc2InitTiling) 和 GetTiling(tiling->mc2CcTiling) 生成两个 Tiling 结构体。第一次调用初始化 Mc2InitTiling(写入版本号、通信任务计数、队列数、通信块数、设备类型等),第二次调用将 commEngine 连同 groupName、algConfig、opType、reduceType 等写入 Mc2CcTiling,并把该 Tiling 的偏移量登记进 Mc2InitTiling(见 hccl_tiling.cpp 与 UpdateMc2InitTiling)。

commEngine 在 TilingData 中的落点

通过 GetTiling(::Mc2CcTiling&) 生成 TilingData 时,commEngine 被写入 Mc2CcTilingInner 结构体的 commEngine 字段(hccl_tiling_msg.h)。Mc2CcTilingInner 是 Mc2CcTiling 的内部内存布局,字段顺序如下:

struct Mc2CcTilingInner {
    uint8_t skipLocalRankCopy;
    uint8_t skipBufferWindowCopy;
    uint8_t stepSize;
    uint8_t version;
    char reserved[9];
    uint8_t commEngine;   // SetCommEngine 写入的位置
    uint8_t srcDataType;
    uint8_t dstDataType;
    char groupName[128];
    char algConfig[128];
    uint32_t opType;
    uint32_t reduceType;
    char reserved2[232];
};

对应写入逻辑在 hccl_tiling.cpp:tilingInner->commEngine = impl_.commEngine_;。由此,Kernel 侧通信 API 与运行期资源分配均能通过 TilingData 读取到该值。

结合源码理解:SetCommEngine 的底层影响

1. CCU 算法注册判定

commEngine 取值影响 Tiling 阶段是否启用 CCU 新版本 TilingData。在 GetTiling(Mc2InitTiling) 中:

if (IsCcuAlgorithmRegistered(impl_.algConfig_, impl_.commEngine_)) {
    tilingInner->version = INIT_TILING_CCU_NEW_VERSION;  // 101
}

IsCcuAlgorithmRegistered(hccl_tiling.cpp)仅在 commEngine 为 5(CCU_MS)或 6(CCU_SCHED)时继续判定,并要求算法名为已注册的 CCU 算法(如 CcuSchedAllGatherSoleMesh、CcuSchedAllToAllVSoleMesh 等)或语法合法的外部算法名。命中后 Mc2InitTiling 的 version 由默认 100 提升为 101(INIT_TILING_CCU_NEW_VERSION,定义见 hccl_tiling_msg.h),驱动 CCU 链路后续流程。这一点在测试用例 test_hccl_tiling.cpp 中有大量覆盖,例如 AllToAllVCcuSchedUsesCcuNewVersion(opType=ALLTOALLV、algConfig=CcuSchedAllToAllVSoleMesh、commEngine=6,期望 version=101)与 UnsupportedCommEngineUsesDefaultVersion(commEngine=4,期望 version=100)。

2. 运行期引擎映射与资源分配

在运行期,Tiling 中的 commEngine 会被转换为真正的 CommEngine 并用于资源分配。相关逻辑集中在 hccl_alloc_ctx_res.cc:

  • OpExecuteConfigToCommEngine(第 30-37 行):将 AICPU_TS 映射为 COMM_ENGINE_AICPU,将 CCU_SCHED 映射为 COMM_ENGINE_CCU,其余返回 COMM_ENGINE_RESERVED;
  • ObtainCommEngine(第 117-138 行):校验多个 Tiling 的 commEngine 一致,且仅允许 AICPU_TS(2)或 CCU_SCHED(6)进入后续资源分配;
  • 分配通信上下文、工作空间与 OpParam 时均以该引擎为依据调用 HcclEngineCtxCreate/HcclEngineCtxGet 等引擎级上下文接口(第 245-341 行)。

3. 算子执行链路的引擎分派

执行阶段,op_common.cc 的 SetCommEngine(OpParam&) 通过静态映射表把 OpExecuteConfig 转为 CommEngine:

{OpExecuteConfig::HOSTCPU_TS, COMM_ENGINE_CPU_TS},
{OpExecuteConfig::AICPU_TS, COMM_ENGINE_AICPU_TS},
{OpExecuteConfig::CCU_MS, COMM_ENGINE_CCU},
{OpExecuteConfig::CCU_SCHED, COMM_ENGINE_CCU},
{OpExecuteConfig::AICPU, COMM_ENGINE_AICPU},
{OpExecuteConfig::HOSTCPU, COMM_ENGINE_CPU},

不支持的配置返回 HCCL_E_NOT_SUPPORT。可见 Tiling 阶段写入的 commEngine 数值与运行期 OpExecuteConfig 枚举严格对齐,是贯穿 Tiling、资源分配与执行三条链路的关键纽带。

测试用例验证

仓库测试 test_hccl_tiling.cpp 提供了对 SetCommEngine 的覆盖:

  • Mc2CcTilingConfig_normal(第 36-72 行):先构造配置对象,依次调用各 Set* 接口(含 SetCommEngine(1)),再分别 GetTiling(Mc2InitTiling) 与 GetTiling(Mc2CcTiling),全部断言返回 EXIT_SUCCESS,验证了接口在正常流程中的可用性;
  • Mc2CcTilingConfig_multiTiling(第 164-174 行):验证一个配置对象可生成 1 个 Mc2InitTiling 加最多 8 个 Mc2CcTiling,超过上限后 GetTiling 返回非 0;
  • TestHcclTilingCcuKfc 系列(第 176-300 行):通过构造函数传入 commEngine(5 或 6)配合 CCU 算法名,断言 Mc2InitTiling 的 version 被置为 CCU 新版本 101,间接验证了 commEngine 取值的实际效果。

这些用例从"正常调用"与"CCU 引擎联动"两个维度印证了 SetCommEngine 的接口行为与 Tiling 侧语义。

使用建议

  1. 取值对齐 hcclOpExpansionMode:commEngine 的合法取值语义以 HcclCommConfig.hcclOpExpansionMode 为准,传参时需与之对齐;示例中的 1U(HOSTCPU_TS)只是其中一种选择,CCU 场景建议使用 5U/6U。
  2. 注意调用顺序:务必先 GetTiling(Mc2InitTiling) 再 GetTiling(Mc2CcTiling),否则会触发断言失败。
  3. 多任务保持一致:一个算子内多个 Mc2CcTiling 的 commEngine 应保持一致,避免运行期一致性校验报错。
  4. 配合 CCU 算法名使用:若选用 CCU 引擎(5/6),算法配置应使用已注册的 Ccu* 算法名或语法合法的外部算法名,否则 Tiling 版本不会升级为 CCU 新版本,CCU 加速链路不生效。

相关文档

登录后查看全文
asc-devkit