asc-devkit HCCL Tiling 接口 SetCommEngine 详解:通信引擎的配置原理与实战
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;
}
该示例的完整步骤解读如下:
-
获取算子 TilingData 结构体:通过
context->GetTilingData<AllToAllVCustomV3TilingData>()拿到算子自定义的 Tiling 结构体。按 HCCL_Tiling_usage.md 的约定,Mc2InitTiling必须定义为该 Tiling 结构体的第一个成员,Mc2CcTiling的位置无要求;单算子最多支持 8 个Mc2CcTiling通信任务(见 hccl_tiling_msg.h 中MAX_CC_TILING_NUM = 8U)。 -
构造配置对象:
Mc2CcTilingConfig(groupName, HCCL_CMD_ALLTOALLV, algConfig, 0)指定通信域testGroup、通信任务类型HCCL_CMD_ALLTOALLV、算法配置"AlltoAll=level0:fullmesh;level1:pairwise",reduceType传 0(AllToAllV 非归约操作,不生效)。 -
设置通信引擎:
SetCommEngine(1U)将通信引擎设置为 1。示例中的1U对应HOSTCPU_TS引擎,表示 AllToAllV 通信任务交由 CPU Task Scheduler 线程执行。若改用 CCU 加速,可传 5U(CCU_MS)或 6U(CCU_SCHED)。 -
生成 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 侧语义。
使用建议
- 取值对齐
hcclOpExpansionMode:commEngine的合法取值语义以HcclCommConfig.hcclOpExpansionMode为准,传参时需与之对齐;示例中的1U(HOSTCPU_TS)只是其中一种选择,CCU 场景建议使用5U/6U。 - 注意调用顺序:务必先
GetTiling(Mc2InitTiling)再GetTiling(Mc2CcTiling),否则会触发断言失败。 - 多任务保持一致:一个算子内多个
Mc2CcTiling的commEngine应保持一致,避免运行期一致性校验报错。 - 配合 CCU 算法名使用:若选用 CCU 引擎(5/6),算法配置应使用已注册的
Ccu*算法名或语法合法的外部算法名,否则 Tiling 版本不会升级为 CCU 新版本,CCU 加速链路不生效。
相关文档
- HCCL Tiling使用说明:HCCL Tiling API 整体使用流程
- HCCL Tiling构造函数:
Mc2CcTilingConfig构造函数与全部参数说明 - TilingData结构体:
Mc2InitTiling与Mc2CcTiling结构说明 - GetTiling:Tiling 信息获取接口
- HCCL_Tiling.md:HCCL Tiling 侧接口索引