AI Core算子开发全流程指南:基于CANN ops-math标准工程的算子开发实战
AI Core算子开发全流程指南:基于CANN ops-math标准工程的算子开发实战
导读
本文是 CANN ops-math 开源仓库中 AI Core 算子开发的完整实战指南,以 AddExample 加法算子为贯穿样例,覆盖从工程创建、算子定义、Tiling 切分、Kernel 实现,到图模式适配、aclnn 二进制发布、编译部署与 UT/aclnn 验证的端到端流程。读完本文,你将掌握 ops-math 标准算子工程与 atvoss 框架算子的目录组织方式、TilingData/TilingKey 协作机制,以及如何用 build.sh 快速完成算子的生成、编译、安装与验证。
适用说明:算子按运行硬件单元不同,可分为 AI Core 算子(Ascend C 语言开发,运行于 AI Core 单元)和 AI CPU 算子(C++ 语言开发,运行于 AI CPU 单元,占少数)。本文面向 AI Core 算子;AI CPU 算子的开发请参考 AI CPU算子开发指南。
概述
开发前需要了解的知识
在动手开发算子前,建议先建立以下知识储备:
- Ascend C 编程语言基础:AI Core 算子使用 Ascend C 开发,需要熟悉基本语法与原理,理解硬件架构、算子 Tiling / Kernel 等核心概念。
- 开发 API:算子开发过程中使用的接口涉及 Ascend C 算子开发接口与基础数据结构和接口两部分。
- 存量算子迁移:若需要把已有工程(如 Ascend/samples 仓已贡献的算子)迁移到本项目工程,可参考下文附录:算子工程迁移。
- 跨平台迁移:若涉及多平台算子实现迁移(例如将 Atlas A2 上已实现的算子功能迁移到 Ascend 950 平台),可参考附录:算子跨平台迁移。
标准开发流程
以 AddExample 算子为例,标准 AI Core 算子开发的全流程与交付件如下(完整样例位于仓库 examples 目录,本文引用的完整实现见 examples/add_example):
- 前提条件:参考项目 README.md 完成环境准备和源码下载。
- 工程创建:创建标准算子工程目录,方便后续算子编译和部署。
- 算子定义:明确算子功能说明与原型定义。
- Tiling 实现:实现 Host 侧算子 Tiling 函数。
- Kernel 实现:实现 Device 侧算子核函数。
- 图模式适配:让自定义算子支持运行图模式。
- aclnn 适配:自定义算子推荐通过 aclnn 接口调用,需完成二进制发布;如需入图,参考附录。
- 编译部署:通过工程编译脚本完成自定义算子的编译和安装。
- 算子验证:通过常见算子调用方式验证自定义算子功能。
工程创建
目录创建是算子开发的重要步骤,为后续代码编写、编译构建和调试提供统一的目录结构和文件组织方式。
使用 build.sh 快速创建算子目录
在项目根目录执行以下命令即可生成指定算子的初始目录:
# 创建指定算子目录,如 bash build.sh --genop=examples/example_ops
# ${op_class}表示算子类型,如math类。
# ${op_name}表示算子名的小写下划线形式,如`ExampleOps`算子对应为example_ops,新增算子不允许与已有算子重名。
bash build.sh --genop=${op_class}/${op_name}
命令执行成功后会看到如下提示:
Create the initial directory for ${op_name} under ${op_class} success
标准算子目录结构
创建完成后,标准算子的目录结构如下:
${op_name} # 替换为实际算子名的小写下划线形式
├── examples # 算子调用示例
│ ├── test_aclnn_${op_name}.cpp # 算子aclnn调用示例
├── op_graph # 算子图模式
│ ├── {op_name}_graph_infer.cpp # InferDtype实现,实现算子dtype推导,在运行时推导输出dtype
│ └── {op_name}_proto.h # 实现算子图模式的原型
├── op_host # Host侧实现
│ ├── ${op_name}_def.cpp # 算子信息库,定义算子基本信息,如名称、输入输出、数据类型等
│ ├── ${op_name}_infershape.cpp # InferShape实现,实现算子形状推导,在运行时推导输出shape
│ └── ${op_name}_tiling.cpp # Tiling实现,将张量划分为多个小块,区分数据类型进行并行计算
├── op_kernel # Device侧Kernel实现
│ ├── ${op_name}_tiling_key.h # TilingKey文件,定义Tiling策略的Key,标识不同的划分方式
│ ├── ${op_name}_tiling_data.h # TilingData文件,存储Tiling策略相关的配置数据,如块大小、并行度
│ ├── ${op_name}.cpp # Kernel入口文件,包含主函数和调度逻辑
│ └── ${op_name}.h # Kernel实现文件,定义Kernel头文件,包含函数声明、结构定义、逻辑实现
└── CMakeLists.txt # 算子cmakelist入口
以仓库中实际的 add_example 算子为例,examples/add_example 目录完整对应上述结构,其 CMakeLists.txt 仅需一行 add_all_modules_sources(OPTYPE add_example ACLNNTYPE aclnn) 即可将各模块源码纳入构建,这正是标准工程统一目录结构带来的便利。
基于atvoss框架的算子目录结构
本项目部分算子(如 abs、sin、mul 等)基于 atvoss 框架开发。atvoss 是对同类算子的一次封装,让算子开发更方便。基于 atvoss 框架的算子,其目录结构与标准算子有所不同,主要体现在以下方面:
- TilingKey:atvoss 算子通常复用 atvoss 框架内置的 TilingKey 定义,不再单独提供
${op_name}_tiling_key.h文件,而是在 Tiling 实现中直接定义常量(如constexpr uint64_t ABS_TILING_KEY_XXX = 101)。 - TilingData:atvoss 算子使用
${op_name}_struct.h替代标准算子的${op_name}_tiling_data.h,内部继承 atvoss 框架提供的基础结构体(如EleBaseTilingData)。 - DAG描述:atvoss 算子使用
${op_name}_dag.h描述算子的计算过程(数据流图),通过组合框架提供的计算原语(如Vec::CopyIn、Vec::Abs、Vec::Cast等)定义算子的计算逻辑。 - 多平台支持:atvoss 算子的 Tiling 实现和 DAG 描述按芯片架构分目录存放,如
op_host/arch35/和op_kernel/arch35/。
以 abs 算子为例,基于 atvoss 框架的目录结构如下:
abs # 算子名
├── CMakeLists.txt # 算子cmakelist入口
├── README.md # 算子说明文档
├── docs # 算子接口文档
│ └── aclnnAbs.md # aclnn接口文档
├── examples # 算子调用示例
│ ├── test_aclnn_abs.cpp # 算子aclnn调用示例
│ └── test_geir_abs.cpp # 算子GE IR调用示例
├── op_api # 算子API层
│ ├── abs.cpp # 算子API实现
│ ├── abs.h # 算子API头文件
│ ├── aclnn_abs.cpp # aclnn接口实现
│ └── aclnn_abs.h # aclnn接口头文件
├── op_graph # 算子图模式
│ └── abs_proto.h # 算子图模式原型
├── op_host # Host侧实现
│ ├── abs_def.cpp # 算子信息库
│ ├── abs_infershape.cpp # InferShape实现
│ ├── arch35 # 按芯片架构分目录
│ │ ├── abs_tiling_arch35.cpp # Tiling实现(arch35架构)
│ │ └── abs_tiling_arch35.h # Tiling头文件(arch35架构)
│ └── config # 编译配置
│ └── ascend950
│ ├── abs_binary.json # 二进制编译配置
│ └── abs_simplified_key.ini # 简化TilingKey配置
├── op_kernel # Device侧Kernel实现
│ ├── abs_apt.cpp # Kernel入口文件(apt表示atvoss port),包含主函数和调度逻辑
│ ├── abs_struct.h # TilingData结构体,替代标准算子的${op_name}_tiling_data.h
│ └── arch35 # 按芯片架构分目录
│ ├── abs_dag.h # 算子计算过程描述(DAG),atvoss框架特有
│ └── abs_complex_dag.h # 复数类型的DAG描述
└── tests # 测试交付件
├── assets
│ └── golden.py # 金标数据生成脚本
├── st # 系统测试
│ └── aclnnAbs
│ └── *.json # ST测试用例配置
└── ut # 单元测试
├── op_api
│ └── test_aclnn_abs.cpp # aclnn接口UT
└── op_host
├── test_abs_infershape.cpp # InferShape UT
└── arch35
└── test_abs_tiling_arch35.cpp # Tiling UT(arch35架构)
说明:
- atvoss 算子的
${op_name}_struct.h等价于标准算子的${op_name}_tiling_data.h,用于定义 TilingData 结构体;- atvoss 算子的
${op_name}_dag.h是算子计算过程的描述文件,通过 DAG(有向无环图)描述数据流,为 atvoss 框架特有文件;- atvoss 算子没有独立的
${op_name}_tiling_key.h文件,TilingKey 在 Tiling 实现中通过常量定义;- atvoss 框架的详细使用方式请参考 atvoss 仓说明。
全新算子分类的构建接入
若 ${op_class} 为全新算子分类,还需额外在 CMakeLists.txt 中添加 add_subdirectory(${op_class}),否则无法正常编译:
if(ENABLE_EXPERIMENTAL)
# genop新增experimental算子分类
# add_subdirectory(${op_class})
add_subdirectory(experimental/math)
else()
# genop新增非experimental算子分类
# add_subdirectory(${op_class})
add_subdirectory(math)
endif()
算子定义
算子定义需要完成两个交付件:README.md 和 ${op_name}_def.cpp。
交付件1:README.md
开发算子前需要先确定目标算子的功能和计算逻辑。以自定义 AddExample 算子为例,请参考 AddExample算子说明。其文档结构包括产品支持情况(Ascend 950PR/DT、Atlas A3、Atlas A2 系列)、功能说明(y = x1 + x2 加法计算)以及参数说明表格(输入 x1、x2,输出 y,均支持 FLOAT、INT32 类型,ND 格式)。
交付件2:${op_name}_def.cpp
算子信息库,定义算子的名称、输入输出、数据类型、Format 以及 AI Core 配置。完整实现见 add_example_def.cpp,核心要点如下:
class AddExample : public OpDef {
public:
explicit AddExample(const char* name) : OpDef(name)
{
this->Input("x1") // 输入x1定义
.ParamType(REQUIRED) // 必选输入
.DataType({ge::DT_FLOAT, ge::DT_INT32}) // 支持数据类型
.Format({ge::FORMAT_ND, ge::FORMAT_ND}) // 支持format格式
.UnknownShapeFormat({ge::FORMAT_ND, ge::FORMAT_ND}) // 未确定大小shape对应format格式
.AutoContiguous(); // 内存自动连续化
// x2 定义同上
this->Output("y")
.ParamType(REQUIRED)
.DataType({ge::DT_FLOAT, ge::DT_INT32})
.Format({ge::FORMAT_ND, ge::FORMAT_ND})
.UnknownShapeFormat({ge::FORMAT_ND, ge::FORMAT_ND})
.AutoContiguous();
OpAICoreConfig aicoreConfig;
aicoreConfig.DynamicCompileStaticFlag(true)
.DynamicFormatFlag(false)
.DynamicRankSupportFlag(true)
.DynamicShapeSupportFlag(true)
.NeedCheckSupportFlag(false)
.PrecisionReduceFlag(true)
.ExtendCfgInfo("opFile.value", "add_example"); // 指定的值会对应到kernel入口文件名.cpp
this->AICore().AddConfig("ascend910b", aicoreConfig); // 其他的soc版本补充部分配置项
this->AICore().AddConfig("ascend910_93", aicoreConfig); // 其他的soc版本补充部分配置项
this->AICore().AddConfig("ascend950", aicoreConfig); // 其他的soc版本补充部分配置项
}
};
OP_ADD(AddExample); // 添加算子信息库
其中 ExtendCfgInfo("opFile.value", "add_example") 将算子信息库与 op_kernel/add_example.cpp 内核入口文件绑定,是 Host 与 Device 侧衔接的关键配置。
Tiling实现
Tiling简介
由于 NPU 中 AI Core 内部存储空间有限,无法一次性将整个张量数据加载到计算单元中处理,因此需要将输入张量切分为多个小块(Tile),逐块进行计算,这一过程称为 Tiling。
用于指导数据切分的算法称为 Tiling 策略(或 Tiling 算法),它决定了如何将输入数据切分为多个计算块,并指导 Kernel 如何分配内存、调度计算任务。Tiling 与 Kernel 之间通过 TilingData 结构体进行信息传递。
代码实现
标准算子的 Tiling 一共需要三个交付件:${op_name}_tiling.cpp、${op_name}_tiling_key.h、${op_name}_tiling_data.h。
${op_name}_tiling.cpp放在${op_name}/op_host目录下;${op_name}_tiling_key.h和${op_name}_tiling_data.h放在${op_name}/op_kernel目录下;- 如果
${op_name}_tiling.cpp中需要引用${op_name}_tiling_data.h,请使用相对路径,例如:#include "../op_kernel/${op_name}_tiling_data.h"。
atvoss 算子的 Tiling 交付件与标准算子有所不同,通常包含:
${op_name}_tiling_arch{xx}.cpp和${op_name}_tiling_arch{xx}.h:放在${op_name}/op_host/arch{xx}目录下,按芯片架构分别实现 Tiling 逻辑;${op_name}_struct.h:放在${op_name}/op_kernel目录下,定义 TilingData 结构体(等价于标准算子的${op_name}_tiling_data.h),内部继承 atvoss 框架提供的基础结构体;- 无独立的
${op_name}_tiling_key.h文件,TilingKey 在 Tiling 实现中通过常量定义。
交付件1:${op_name}_tiling.cpp
Tiling 主要切分逻辑。完整实现见 add_example_tiling.cpp,整体骨架如下:
// ${op_name}_tiling.cpp
// 1.Tiling需要获取运行环境信息,包括可用核数、UB(Unified Buffer)大小,并将获取到的信息传递给CompileInfo,自动生成aclnn不调用该函数,直接返回ge::GRAPH_SUCCESS即可。
static ge::graphStatus TilingParse(gert::TilingParseContext* context)
{
return ge::GRAPH_SUCCESS;
// 若手写aclnn接口,可以按照下面步骤完善parse函数
// // 1.1获取环境信息
// auto compileInfo = context->GetCompiledInfo<CompileInfo>();
// OP_CHECK_NULL_WITH_CONTEXT(context, compileInfo);
// auto platformInfo = context->GetPlatformInfo();
// auto ascendcPlatform = platform_ascendc::PlatformAscendC(platformInfo);
// // 1.2获取可用核数
// compileInfo->totalCoreNum = ascendcPlatform.GetCoreNumAiv();
// // 1.3获取UB大小
// uint64_t ubSizePlatForm;
// ascendcPlatform.GetCoreMemSize(platform_ascendc::CoreMemType::UB, ubSizePlatForm);
// compileInfo->ubSize = static_cast<int64_t>(ubSizePlatForm);
// ...
// return ge::GRAPH_SUCCESS;
}
// 2.Tiling计算主入口
static ge::graphStatus TilingFunc(gert::TilingContext* context){
// 2.1获取平台信息
uint64_t ubSize;
int64_t coreNum;
OP_CHECK_IF(
GetPlatformInfo(context, ubSize, coreNum) != ge::GRAPH_SUCCESS, OP_LOGE(context, "GetPlatformInfo error"),
return ge::GRAPH_FAILED);
// 2.2获取输入信息
// 获取输入张量shape信息
auto inputX = context->GetInputShape(0);
OP_CHECK_NULL_WITH_CONTEXT(context, inputX);
// 如果输入shape是标量,转换为{1},否则保持原shape不变
auto inputShapeX = EnsureNotScalar(inputX->GetStorageShape());
// 获取输入张量的描述信息
auto inputDesc = context->GetInputDesc(0);
OP_CHECK_NULL_WITH_CONTEXT(context, inputDesc);
// 获取数据类型
dataType = inputDesc->GetDataType();
// 2.3计算Tiling参数(根据算子功能不同自行设计)
...
// 2.4设置TilingData信息
${op_name}TilingData* tiling = context->GetTilingData<${op_name}TilingData>();
OP_CHECK_NULL_WITH_CONTEXT(context, tiling);
OP_CHECK_IF(
memset_s(tiling, sizeof(${op_name}TilingData), 0, sizeof(${op_name}TilingData)) != EOK,
OP_LOGE(context, "set tiling data error"), return ge::GRAPH_FAILED);
tiling->totalLength = totalIdx;
tiling->tileNum = TILE_NUM;
// 2.5设置WorkspaceSize(可选)
size_t* currentWorkspace = context->GetWorkspaceSizes(1);
OP_CHECK_NULL_WITH_CONTEXT(context, currentWorkspace);
currentWorkspace[0] = WS_SYS_SIZE;
return ge::GRAPH_SUCCESS;
}
// 3.Tiling注册入口
IMPL_OP_OPTILING(${op_name}).Tiling(TilingFunc).TilingParse<CompileInfo>(TilingParse);
样例中函数空实现说明:
- TilingParse:图模式标准交付件,保留函数定义以满足框架调用规范,无实际逻辑时可置空。
- CompileInfo:图模式标准交付件,保留函数定义以满足框架调用规范,无实际逻辑时可置空。
真实样例的切分逻辑:在 add_example_tiling.cpp 中可以看到完整的四步实现——先通过 GetPlatformInfo 获取 ubSize 与 coreNum(ascendcPlatform.GetCoreNumAiv() 取 AI Vector 核数、GetCoreMemSize(CoreMemType::UB, ubSize) 取 UB 大小);再通过 GetShapeAttrsInfo 获取输入 shape(Ops::Base::EnsureNotScalar 处理标量、校验 4 维、校验 dtype 属于 {DT_FLOAT, DT_INT32});随后计算切分参数:
// 优先做核切分,尽量用更多的核并行计算
tiling->totalNum = totalIdx;
tiling->blockFactor = Ops::Base::CeilDiv(totalIdx, coreNum);
int64_t usedCoreNum = Ops::Base::CeilDiv(totalIdx, tiling->blockFactor);
// 计算ub切分,考虑最大同时使用的ub tensor数量,计算单个ub tensor可用大小
// 当前场景,2输入和1输出,考虑启用db,共需要6块ub tensor
int64_t ubCanUse = static_cast<int64_t>(ubSize);
int64_t ubBlockSize = Ops::Base::GetUbBlockSize(context);
tiling->ubFactor = Ops::Base::FloorAlign(Ops::Base::FloorDiv((ubCanUse / TYPE_SIZE), BUFFER_NUM), ubBlockSize);
context->SetBlockDim(usedCoreNum);
uint64_t tilingKey = 0;
// 区分dtype走不同得tiling key分支.
if (dataType == ge::DT_FLOAT) {
tilingKey = GET_TPL_TILING_KEY(ELEMENTWISE_TPL_SCH_MODE_0);
context->SetTilingKey(tilingKey);
} else if (dataType == ge::DT_INT32) {
tilingKey = GET_TPL_TILING_KEY(ELEMENTWISE_TPL_SCH_MODE_1);
context->SetTilingKey(tilingKey);
}
从源码结构看,这里体现了两个关键切分维度:核间切分(blockFactor,将总数据量按核数均分,优先使用更多核并行)与 核内切分(ubFactor,按 UB 容量与同时存活的 buffer 数量计算每个 tile 的处理长度)。注意注释中 "2输入和1输出、启用 double buffer 共需要 6 块 ub tensor" 的约束直接对应 BUFFER_NUM = 6 的常量设定,这与 Kernel 侧 AddExample 类中 BUFFER_NUM = 2 的 double buffer 流水设计(见下文)相互印证。
交付件2:${op_name}_tiling_key.h
TilingKey 是一个算子内为了区分不同实现而将 kernel 代码进行区分的方法,kernel 侧可以通过 TilingKey 来选择不同的算法逻辑。完整实现见 add_example_tiling_key.h:
// ${op_name}_tiling_key.h
ASCENDC_TPL_ARGS_DECL(
${op_name},
ASCENDC_TPL_UINT_DECL(schMode, 1, ASCENDC_TPL_UI_LIST, ELEMENTWISE_TPL_SCH_MODE_0, ELEMENTWISE_TPL_SCH_MODE_1));
ASCENDC_TPL_SEL(ASCENDC_TPL_ARGS_SEL(
ASCENDC_TPL_UINT_SEL(schMode, ASCENDC_TPL_UI_LIST, ELEMENTWISE_TPL_SCH_MODE_0, ELEMENTWISE_TPL_SCH_MODE_1)));
在真实实现中,ELEMENTWISE_TPL_SCH_MODE_0 与 ELEMENTWISE_TPL_SCH_MODE_1 分别定义为 0 和 1,对应 float 与 int32 两条计算路径。schMode 是模板参数,Tiling 侧通过 GET_TPL_TILING_KEY(...) 编码后调用 context->SetTilingKey(tilingKey) 下发,Kernel 侧通过 if constexpr 在编译期完成分支选择。
说明: 如需实现复杂参数组合完成分支选择(涉及多 TilingKey 场景),请参考《Ascend C算子开发接口》中"Utils API > Tiling模版编程 > 模版参数含义"。
交付件3:${op_name}_tiling_data.h
切分算法相关的参数(总数据量大小、每个核数据切块数量等)通过结构体存储。完整实现见 add_example_tiling_data.h:
// ${op_name}_tiling_data.h
struct AddExampleTilingData {
int64_t totalNum = 0; // 总数据量
int64_t blockFactor = 0; // 核间切分:每个核处理的数据长度
int64_t ubFactor = 0; // 核内切分:每个tile处理的数据长度
};
该结构体被 Tiling 侧(写)与 Kernel 侧(读)共享,是 Host 与 Device 之间传递切分策略的唯一桥梁。
Kernel实现
Kernel简介
Kernel 是算子在 NPU 执行的核心部分,负责张量数据的加载、计算和存储,是算子功能实现的最终载体。Kernel 的实现需要与 Tiling 策略紧密配合,根据 Tiling 提供的 TilingData、TilingKey 信息进行内存分配和计算调度。
Kernel 实现包括如下步骤,整个流程通过 Process 函数串联:
graph LR
H([核函数定义]) -->A([定义Kernel类])
A -->B([初始化函数<br>Init])
B -->C([主处理函数<br>Process])
subgraph C [主处理函数Process]
D([数据搬入<br>CopyIn]) -->E([计算<br>Compute]) -->F([数据搬出<br>CopyOut])
end
F -->G([Kernel执行完成])
代码实现
标准算子的 Kernel 一共需要两个交付件:${op_name}.cpp、${op_name}.h。
${op_name}.cpp为 kernel 的入口函数,只能放在${op_name}/op_kernel目录下;${op_name}.h文件可以按照不同 SoC 或模板放在对应目录下,例如${op_name}/op_kernel/arch22、${op_name}/op_kernel/arch35或${op_name}/op_kernel/impl等目录。
atvoss 算子的 Kernel 交付件与标准算子有所不同,通常包含:
${op_name}_apt.cpp:放在${op_name}/op_kernel目录下,为 Kernel 入口文件(apt 表示 atvoss port),包含核函数定义和调度逻辑,使用 atvoss 框架提供的ElementwiseSch等调度器;${op_name}_struct.h:放在${op_name}/op_kernel目录下,定义 TilingData 结构体;${op_name}_dag.h:放在${op_name}/op_kernel/arch{xx}目录下,通过 DAG 描述算子的计算过程,使用 atvoss 框架提供的计算原语(如Vec::CopyIn、Vec::Abs等)组合定义算子的数据流图。
交付件1:${op_name}.cpp
Kernel 入口文件,包含主函数和调度逻辑。完整实现见 add_example.cpp:
// 1、核函数定义
// schMode是一个模板参数,用于支持不同数据类型(如float和int32)的计算路径
// __global__ __aicore__表示该函数是个全局函数,可以在AI Core上执行
template <uint32_t schMode>
__global__ __aicore__ void add_example(GM_ADDR x, GM_ADDR y, GM_ADDR z, GM_ADDR workspace, GM_ADDR tiling){
....
// Tiling注册入口
REGISTER_TILING_DEFAULT(AddExampleTilingData);
// 宏方式获取TilingData
GET_TILING_DATA_WITH_STRUCT(AddExampleTilingData, tilingData, tiling);
// 根据TilingKey实例化Kernel对象并完成计算
if constexpr (schMode == static_cast<uint32_t>(AddExampleTilingKey::TILING_KEY_EXAMPLE_FLOAT)) { // float数据类型走该分支
NsAddExample::AddExample<float> op; // 算子Kernel实例获取
op.Init(x, y, z, &tilingData); // 算子Kernel实例初始化
op.Process(); // 算子Kernel实例执行
}
....
}
在真实实现中,入口函数通过 if constexpr 依据模板参数 schMode 在编译期展开两条路径,分别实例化 AddExample<float> 与 AddExample<int32_t>,对应 Tiling 侧下发的两个 TilingKey。
交付件2:${op_name}.h
定义 Kernel 头文件,包含函数声明、结构定义、逻辑实现等。完整实现见 add_example.h:
// 2、定义Kernel类
template <typename T>
class AddExample
{
public:
// 默认构造函数,__aicore__表示该函数在AI Core上运行
__aicore__ inline AddExample(){};
// 初始化函数,用于设置输入输出地址和Tiling切分信息计算
__aicore__ inline void Init(GM_ADDR x, GM_ADDR y, GM_ADDR z, const AddExampleTilingData* tilingData);
// 主处理函数,执行数据拷贝和计算
__aicore__ inline void Process();
private:
// 数据从GM拷贝到LM的函数
__aicore__ inline void CopyIn(int32_t progress);
// 数据从LM拷贝到GM的函数
__aicore__ inline void CopyOut(int32_t progress);
// 执行计算的函数,datalength表示当前处理的数据长度
__aicore__ inline void Compute(const int32_t dataLength);
private:
// 管道对象,用于管理数据流(拷贝和计算的流水线)
TPipe pipe_;
// 输入队列X,从GM拷贝到LM,BUFFER_NUM表示buffer数量,开启double buff达到流水并行,为2
TQue<QuePosition::VECIN, BUFFER_NUM> inputQueueX_;
// 输入队列Y,从GM拷贝到LM,BUFFER_NUM表示buffer数量,开启double buff达到流水并行,为2
TQue<QuePosition::VECIN, BUFFER_NUM> inputQueueY_;
// 输出队列Z,从LM拷贝到GM,BUFFER_NUM表示buffer数量,这里开启double buff达到流水并行,为2
TQue<QuePosition::VECOUT, BUFFER_NUM> outputQueueZ_;
// 输入X的GM地址
GlobalTensor<T> inputGMX_;
// 输入Y的GM地址
GlobalTensor<T> inputGMY_;
// 输出Z的GM地址
GlobalTensor<T> outputGMZ_;
// 总数据长度
int64_t blockLength_ = 0;
// 每个block被划分多少块
int64_t tileNum_ = 0;
// 每个tile处理数据长度
int64_t tileLength_ = 0;
...
};
// 3、初始化函数Init
template <typename T>
__aicore__ inline void AddExample<T>::Init(GM_ADDR x, GM_ADDR y, GM_ADDR z, const AddExampleTilingData* tilingData)
{
// 3.1初始化成员变量
blockLength_ = tilingData->totalLength / AscendC::GetBlockNum();
...
// 3.2初始化GM地址
inputGMX_.SetGlobalBuffer((__gm__ T*)x + blockLength_ * AscendC::GetBlockIdx(), blockLength_);
...
// 3.3初始化队列长度
pipe_.InitBuffer(inputQueueX_, BUFFER_NUM, tileLength_ * sizeof(T));
...
}
// 4、主处理函数Process
template <typename T>
__aicore__ inline void AddExample<T>::Process()
{
// 计算当前核处理数据循环次数
int32_t loopCount = tileNum_ * BUFFER_NUM;
for (int32_t i = 0; i < loopCount; i++) {
CopyIn(i); // 数据搬入
Compute(i); // 计算
CopyOut(i); // 数据搬出
}
}
...
真实样例中的数据流细节:add_example 的 Kernel 类中,Init 依据 blockFactor * GetBlockIdx() 计算当前核的 GM 起始偏移,并用 ubFactor * sizeof(T) 初始化各队列 buffer;CopyIn 使用 AscendC::DataCopyPad 配合 DataCopyParams(blockCount=1、blockLen=currentNum * sizeof(T))从 GM 搬运数据入 LM;Compute 通过 AscendC::Add(zLocal, xLocal, yLocal, currentNum) 完成向量加法后 EnQue 出队;CopyOut 将结果 DataCopyPad 回写 GM;Process 中 loopCount = (blockLength_ + ubLength_ - 1) / ubLength_,对最后一个 tile 单独计算 currentNum 以处理尾块。TPipe 与 TQue 的双缓冲机制让数据搬运与计算重叠执行,正是向量类算子性能的关键。
图模式适配
图模式一共需要三个交付件:${op_name}_graph_infer.cpp、${op_name}_infershape.cpp、${op_name}_proto.h。详细说明见图模式适配指南 graph_develop_guide.md。
其中 InferShape 的注册方式可在真实样例中看到,add_example_infershape.cpp 通过 IMPL_OP_INFERSHAPE(AddExample).InferShape(InferShapeAddExample) 完成注册,其 InferShapeAddExample 从输入 0 读取 shape 维度信息并逐一拷贝给输出 0 的 shape,实现"输出形状与输入一致"的推导逻辑。
aclnn适配
通常算子开发和编译完成后,会自动生成 aclnn 接口(一套基于 C 的 API),可直接在应用程序中调用 aclnn 接口实现算子调用。
为实现该调用方式,需提前生成算子对应的二进制包,增加二进制编译 json 文件。以 AddExample 算子为例:
在 scripts/kernel/binary_config/ascendc_config.json 中,注册算子的 NPU 型号和实现模式,输入实际的 name 和 compute_units 即可:
{"name":"AddExample", "compute_units": ["${soc_version}"], "auto_sync":true, "impl_mode" : "high_performance"}
真实的算子二进制配置示例可参考 examples/add_example/op_host/config/ascend910b/add_example_binary.json:其中按 op_type: AddExample 为 float32 与 int32 两种输入组合各生成一条 op_list 记录,每条记录包含 bin_filename(编译产物名)、inputs/outputs 的 name、index、dtype、format、paramType、动态 shape 标记(shape: [-2] 表示动态 shape)以及 format_match_mode: FormatAgnostic 等字段。这正是自动生成 aclnn 接口时用于匹配输入组合并定位二进制产物的依据。
编译部署
算子开发完成后,需对算子工程进行编译,生成自定义算子安装包 *.run,详细编译操作如下:
1. 准备工作
参考工程创建完成基础环境搭建,同时检查算子开发交付件是否完备、是否在对应算子分类目录下。
2. 配置环境变量
根据实际场景,选择合适的命令:
# 默认路径安装,以root用户为例(非root用户,将/usr/local替换为${HOME})
source /usr/local/Ascend/cann/set_env.sh
# 指定路径安装
# source ${install_path}/cann/set_env.sh
3. 编译自定义算子包
以 AddExample 算子为例,假设开发交付件在 examples 目录,完整代码参见 examples/add_example。若编译 experimental 目录下用户自定义算子,编译命令需增加编译参数 --experimental。
说明:编译过程依赖第三方开源软件,联网场景会自动下载,离线编译场景需要自行安装,具体参考 未联网编译。
进入项目根目录,执行如下编译命令:
# 编译指定算子,如 bash build.sh --pkg --ops=add_example -j16
bash build.sh --pkg --soc=${soc_version} --vendor_name=${vendor_name} --ops=${op_list} -j${n}
# 编译experimental目录下指定算子
bash build.sh --pkg --soc=${soc_version} --vendor_name=${vendor_name} --ops=${op_list} --experimental -j${n}
参数说明:
--soc:${soc_version}表示 NPU 型号。Atlas A2 系列产品使用ascend910b(默认),Atlas A3 系列产品使用ascend910_93,Ascend 950PR/Ascend 950DT 产品使用ascend950。--vendor_name(可选):${vendor_name}表示构建的自定义算子包名,默认名为custom。--ops(可选):${op_list}表示待编译算子,不指定时默认编译所有算子,格式形如--ops=add_example。--experimental(可选):若编译的算子为贡献算子,需配置--experimental。-j(可选):指定编译线程数,加快编译速度。
若提示如下信息,说明编译成功:
Self-extractable archive "cann-ops-math-${vendor_name}_linux-${arch}.run" successfully created.
4. 安装自定义算子包
执行以下命令进行安装:
# 安装run包
./build_out/cann-ops-math-${vendor_name}_linux-${arch}.run
自定义算子包安装在 ${ASCEND_HOME_PATH}/opp/vendors 路径中,${ASCEND_HOME_PATH} 表示 CANN 软件安装目录,可提前在环境变量中配置。
5. (可选)卸载自定义算子包
自定义算子包安装后在 ${ASCEND_HOME_PATH}/opp/vendors/custom_math/scripts 目录会生成 uninstall.sh,通过该脚本可卸载自定义算子包:
bash ${ASCEND_HOME_PATH}/opp/vendors/custom_math/scripts/uninstall.sh
算子验证
算子开发过程中,可通过如下方式进行验证:
- UT验证:验证交付件代码能否正常运行,无需 NPU 环境。
- aclnn调用验证:验证算子在 NPU 环境上的功能,需要 NPU 环境。
UT验证
主要交付件代码开发过程中,可通过 UT 验证方式进行快速验证,无需编译部署算子包。
UT 目录结构如下(需用户手动创建):
${op_name}
... # 其他交付件
└── tests # 测试交付件
└── ut # UT实现
├── op_host
│ └── test_${op_name}_tiling.cpp # Tiling UT实现
│ └── test_${op_name}_infershape.cpp # Infershape UT实现
└── op_kernel
└── test_${op_name}.cpp # Kernel UT实现
执行 UT 验证的命令请参考 算子调用。下面依次介绍各 UT 交付件的编写。
Infershape UT
Infershape UT 用于验证 Host 侧 Infershape 逻辑是否正确,在给定算子的输入后,Infershape 能否正确执行、输出是否符合预期,推荐在算子开发阶段同步补齐。详细实现参考 test_add_example_infershape.cpp。
1. 组织结构与命名建议
- 头文件:统一包含
iostream、gtest/gtest.h、infershape_context_faker.h、infershape_case_executor.h。 - 测试类:继承
testing::Test,实现SetUpTestCase/TearDownTestCase统一做数据准备与清理。 - 命名:测试类建议
${OpName}InfershapeTest,用例名建议test_case_xxx。
测试类示例:
class ${OpName}InfershapeTest : public testing::Test {
protected:
static void SetUpTestCase()
{
std::cout << "${OpName}InfershapeTest SetUp" << std::endl;
}
static void TearDownTestCase()
{
std::cout << "${OpName}InfershapeTest TearDown" << std::endl;
}
};
2. 用例基本流程
- 调用接口构造用例上下文。需要的参数主要为输入和输出的 shape/format/dtype。
- shape/format/dtype 可参考
${op_name}_def.cpp算子信息库; - 若某输入在信息库中标记为
ValueDepend,UT 中需同时准备该输入的真实数据值。
- shape/format/dtype 可参考
- 设定预期结果。
- 调用接口执行用例。
简化示例:
TEST_F(${OpName}InfershapeTest, test_case_xxx)
{
// 1.构造用例上下文
gert::InfershapeContextPara infershapeContextPara(
"${OpName}",
{
{{{1, -1, -1, 64}, {1, -1, -1, 64}}, ge::DT_FLOAT16, ge::FORMAT_ND}, // input tensor1
{{{1, -1, -1, 64}, {1, -1, -1, 64}}, ge::DT_FLOAT16, ge::FORMAT_ND}, // input tensor2
// 若输入为ValueDepend,需额外传入true和constValue这两个参数
// 其中constValue为自己定义的变量,如int constValue[2] = {2, 2}
// {{{32, 4, 4, 4}, {32, 4, 4, 4}}, ge::DT_FLOAT, ge::FORMAT_ND, true, constValue}
},
{
{{{}, {}}, ge::DT_FLOAT16, ge::FORMAT_ND}, // output tensor
}
);
// 2.设定预期结果
std::vector<std::vector<int64_t>> expectOutputShape = {
{1, -1, -1, 64},
};
// 3.调用接口执行用例
ExecuteTestCase(infershapeContextPara, ge::GRAPH_SUCCESS, expectOutputShape);
}
Tiling UT
Tiling UT 用于验证 Host 侧 Tiling 逻辑是否正确,在给定算子的输入后,Tiling 能否正确执行、输出是否符合预期,推荐在算子开发阶段同步补齐。详细实现参考 test_add_example_tiling.cpp。
1. 组织结构与命名建议
- 头文件:统一包含
iostream、gtest/gtest.h、tiling_context_faker.h、tiling_case_executor.h;若 tiling 头文件中已经定义 CompileInfo 结构体,则也需引入。 - 测试类:继承
testing::Test,实现SetUpTestCase/TearDownTestCase统一做数据准备与清理。 - 命名:测试类建议
${OpName}TilingTest,用例名建议test_case_xxx。
2. 用例基本流程
- 调用接口构造用例上下文。需要的参数主要为输入和输出的 shape/format/dtype、属性以及 compileInfo,可参考
${op_name}_def.cpp算子信息库。- shape/format/dtype 和属性可参考
${op_name}_def.cpp算子信息库; - 若某输入在信息库中标记为
ValueDepend,UT 中需同时准备该输入的真实数据值; - compileInfo 优先使用 tiling 头文件中声明的结构体,若 tiling 头文件没有声明,则在用例中声明。
- shape/format/dtype 和属性可参考
- 设定预期结果。
- 调用接口执行用例。
简化示例(真实样例见 test_add_example_tiling.cpp,其中 add_example_0 用例以 64 核、262144 字节 UB、4096 字节 tiling data 上限构造上下文,断言 expectTilingKey = 0 与 expectTilingData = "2048 32 10912 "):
TEST_F(${OpName}TilingTest, test_case_xxx)
{
// 声明结构体并初始化一个结构体变量
struct ${OpName}CompileInfo {
} compileInfo;
// 1.构造用例上下文
gert::TilingContextPara tilingContextPara(
"${OpName}",
{
{{{32, 4, 4, 4}, {32, 4, 4, 4}}, ge::DT_FLOAT, ge::FORMAT_ND}, // input tensor1
{{{32, 4, 4, 4}, {32, 4, 4, 4}}, ge::DT_FLOAT, ge::FORMAT_ND}, // input tensor2
// 若输入为ValueDepend,需额外传入true和constValue这两个参数
// 其中constValue为自己定义的变量,如int constValue[2] = {2, 2}
// {{{32, 4, 4, 4}, {32, 4, 4, 4}}, ge::DT_FLOAT, ge::FORMAT_ND, true, constValue}
},
{
{{{32, 4, 4, 4}, {32, 4, 4, 4}}, ge::DT_FLOAT, ge::FORMAT_ND}, // output tensor
},
{
// 属性
gert::TilingContextPara::OpAttr("${attr_name}", AnyValue::CreateFrom<std::string>("${attr_value}"))
},
&compileInfo,
64, // tiling阶段获取的核数
262144, // tiling阶段获取的ub大小,但实际获取的值比指定值少256字节
4096 // 指定tiling阶段中tiling data的最大值
);
// 2.设定预期结果
uint64_t expectTilingKey = 0;
string expectTilingData = "2048 32 10912 ";
std::vector<size_t> expectWorkspaces = {0};
// 3.调用接口执行用例
ExecuteTestCase(tilingContextPara, ge::GRAPH_SUCCESS, expectTilingKey, expectTilingData, expectWorkspaces);
}
Kernel UT
Kernel UT 用于验证 Device 侧 Kernel 逻辑是否正确,在给定输入/Tiling 参数后,Kernel 能否正确执行、输出是否符合预期,推荐在算子开发阶段同步补齐。详细实现参考 test_add_example.cpp。
1. 组织结构与命名建议
- 头文件:建议统一包含
gtest/gtest.h、tikicpulib.h、data_utils.h与 Tiling 头文件。- 直接引用
op_host/${op_name}_tiling.h; - 或在 UT 目录提供轻量适配头(如 examples/add_example/tests/ut/op_kernel/add_example_tiling.h);
- 若 Kernel 为模板函数,可在 UT 中直接
#include "../../../op_kernel/${op_name}.cpp"触发实例化(参考AddExample)。
- 直接引用
- 测试类:继承
testing::Test,实现SetUpTestCase/TearDownTestCase统一做数据准备与清理(如拷贝数据目录、chmod、生成 bin)。 - 命名:测试类建议
${OpName}KernelTest,用例名建议test_case_xxx。
2. 用例基本流程
- 设定输入 shape/format/dtype,初次上手可参考
${op_name}_def.cpp算子信息库;若某输入在信息库中标记为ValueDepend,UT 中需同时准备该输入的真实数据值。 - 准备输入/输出/Workspace/Tiling 缓冲区(
AscendC::GmAlloc)。 - 准备 Tiling 数据(手动构造或由 Tiling 函数生成)。
- 设置
ICPU_SET_TILING_KEY与AscendC::SetKernelMode。 - 使用
ICPU_RUN_KF执行 Kernel。 - 结果校验并释放资源(
AscendC::GmFree)。
简化示例:
extern "C" __global__ __aicore__ void ${op_name}(GM_ADDR x, GM_ADDR y, GM_ADDR z,
GM_ADDR workspace, GM_ADDR tiling);
TEST_F(${OpName}KernelTest, test_case_basic)
{
// 1.设定输入shape/format/dtype,必要时准备ValueDepend输入值
// 2.申请输入/输出/workspace/tiling内存
uint8_t* x = (uint8_t*)AscendC::GmAlloc(...);
uint8_t* y = (uint8_t*)AscendC::GmAlloc(...);
uint8_t* z = (uint8_t*)AscendC::GmAlloc(...);
uint8_t* workspace = (uint8_t*)AscendC::GmAlloc(...);
uint8_t* tiling = (uint8_t*)AscendC::GmAlloc(sizeof(${op_name}TilingData));
// 3.准备tiling数据(手动构造或由tiling函数生成)
auto* tilingData = reinterpret_cast<${op_name}TilingData*>(tiling);
tilingData->... = ...;
// 4.设置tiling key并执行kernel
ICPU_SET_TILING_KEY(tilingKey);
AscendC::SetKernelMode(KernelMode::AIV_MODE);
ICPU_RUN_KF(${op_name}, blockDim, x, y, z, workspace, tiling);
// 5.结果校验
EXPECT_EQ(..., ...);
// 6.释放资源
AscendC::GmFree(x);
AscendC::GmFree(y);
AscendC::GmFree(z);
AscendC::GmFree(workspace);
AscendC::GmFree(tiling);
}
3. Tiling 数据准备方式
- 手动构造:适合字段少、逻辑简单。
- 调用 Tiling 函数自动生成:适合字段多、依赖属性/shape 复杂。可复用
tests/ut/common/tiling_context_faker.h与tiling_case_executor.h。示例:
gert::TilingContextPara para("OpName",
{{{{2, 2, 2, 1}, {2, 2, 2, 1}}, ge::DT_FLOAT, ge::FORMAT_ND}},
{{{{2, 1, 2, 2}, {2, 1, 2, 2}}, ge::DT_FLOAT, ge::FORMAT_ND}},
{gert::TilingContextPara::OpAttr("attr", AnyValue::CreateFrom<int64_t>(1))},
&compileInfo);
TilingInfo tilingInfo;
ASSERT_TRUE(ExecuteTiling(para, tilingInfo));
uint8_t* tiling = (uint8_t*)AscendC::GmAlloc(tilingInfo.tilingDataSize);
std::memcpy(tiling, tilingInfo.tilingData.get(), tilingInfo.tilingDataSize);
ICPU_SET_TILING_KEY(tilingInfo.tilingKey);
uint32_t blockDim = tilingInfo.blockNum;
4. 数据生成与结果比对
- 可使用
tests/ut/op_kernel/data_utils.h的ReadFile/WriteFile读写二进制。 - 结合
gen_data.py/compare_data.py脚本生成与比对数据,可参考add_example的add_example_data目录:gen_data.py、compare_data.py。 - 简单算子可直接在 UT 中计算期望值并比对,浮点比较建议使用
EXPECT_NEAR/ASSERT_NEAR并设置合理容差。
aclnn调用验证
开发好的算子完成编译部署后,可通过 aclnn 方式验证功能,方法参考 算子调用方式。执行前需要导入环境变量:
export LD_LIBRARY_PATH=${ASCEND_HOME_PATH}/opp/vendors/${vendor_name}_math/op_api/lib:${LD_LIBRARY_PATH}
附录
自定义算子如需运行图模式,不需要 aclnn 适配,详细内容请参考 图模式开发指南。
附录:算子工程迁移
由于 Ascend/samples 工程与本项目工程有差异,在本项目创建工程后(参考工程创建),迁移请参考下表中的迁移方法。
| cann-ops | gitcode | 迁移方法 | 代码示例 |
|---|---|---|---|
| op_host/{op_name}.cpp | op_host/{op_name}_def.cpp | 将原有 op_host/{op_name}.cpp 中算子原型描述部分独立出来 | op_host/{op_name}_def.cpp |
| op_host/{op_name}.cpp | op_host/{op_name}_infershape.cpp | (可选)将原有 op_host/{op_name}.cpp 中 shape 推导部分独立出来 | op_host/{op_name}_infershape.cpp |
| op_host/{op_name}.cpp | op_host/{op_name}_tiling.cpp | 仅保留原有 op_host/{op_name}.cpp 中的 TilingFunc | op_host/{op_name}_tiling.cpp |
| op_host/{op_name}.cpp | op_graph/{op_name}_graph_infer.cpp | (可选)将原有 op_host/{op_name}.cpp 中类型推导部分独立出来 | op_graph/{op_name}_graph_infer.cpp |
| op_host/{op_name}_tiling.h | op_kernel/{op_name}_tiling_data.h | 将原有 op_host 目录下的宏定义 Tiling 结构体定义改成 C++ 标准定义 | op_kernel/{op_name}_tiling_data.h |
| op_kernel/{op_name}.cpp | op_kernel/{op_name}.h | 保留原有 op_host/{op_name}.cpp 中 kernel 实现的算子类定义部分 | op_kernel/{op_name}.h |
| op_kernel/{op_name}.cpp | op_kernel/{op_name}.cpp | 将原有 op_host/{op_name}.cpp 中 kernel 实现的核函数实现迁移至 cpp 文件,同时: 新增 REGISTER_TILING_DEFAULT 调用注册 Tiling 结构体,使用 GET_TILING_DATA_WITH_STRUCT 获取 TilingData; 添加 tiling 模板,支持模板参数的传入,根据模板参数的分支判断选择不同的 kernel 侧实现 |
op_kernel/{op_name}.cpp |
| op_kernel/tiling_key_{op_name}.h | op_kernel/{op_name}_tiling_key.h | 保留原有 op_kernel/tiling_key_{op_name}.h 中算子的模板参数定义,若不存在则新增定义模板参数和模板参数组合 | op_kernel/{op_name}_tiling_key.h |
op_host/{op_name}_def.cpp
将原有 ${op_name}.cpp 中算子信息库内容独立迁移至该文件,需要去掉 SetInferShape 和 SetTiling 内容。
// 原有${op_name}.cpp中算子信息库内容
namespace ops {
class AddCustom : public OpDef {
public:
explicit AddCustom(const char *name) : OpDef(name)
{
this->Input("x")
....
this->Output("z")
.ParamType(REQUIRED)
.DataType({ge::DT_FLOAT16, ge::DT_FLOAT})
.Format({ge::FORMAT_ND, ge::FORMAT_ND});
this->SetInferShape(ge::InferShape).SetInferDataType(ge::InferDataType); // 需要去掉SetInferShape
this->AICore()
.SetTiling(optiling::TilingFunc) // 需要去掉SetTiling
.AddConfig("ascend910")
.AddConfig("ascend310p")
.AddConfig("ascend310b")
.AddConfig("ascend910b");
}
};
OP_ADD(AddCustom);
} // namespace ops
// 迁移至op_host/{op_name}_def.cpp后,代码中无SetInferShape和SetTiling内容
namespace ops {
class AddCustom : public OpDef {
public:
explicit AddCustom(const char *name) : OpDef(name)
{
this->Input("x")
....
this->Output("z")
.ParamType(REQUIRED)
.DataType({ge::DT_FLOAT16, ge::DT_FLOAT})
.Format({ge::FORMAT_ND, ge::FORMAT_ND});
this->AICore()
.AddConfig("ascend910")
.AddConfig("ascend310p")
.AddConfig("ascend310b")
.AddConfig("ascend910b");
}
};
OP_ADD(AddCustom);
} // namespace ops
op_host/{op_name}_infershape.cpp
图模式场景需要适配该文件,将原有 ${op_name}.cpp 中 shape 推导部分独立迁至该文件,调用接口 IMPL_OP_INFERSHAPE 完成 InferShape 注册。
// 原有${op_name}.cpp中的InferShape
namespace ge {
static graphStatus InferShape(gert::InferShapeContext *context)
{
const gert::Shape *x1_shape = context->GetInputShape(0);
gert::Shape *y_shape = context->GetOutputShape(0);
*y_shape = *x1_shape;
return GRAPH_SUCCESS;
}
} // namespace ge
// 迁移至op_host/{op_name}_infershape.cpp后,调用接口IMPL_OP_INFERSHAPE完成InferShape注册
namespace ge {
static graphStatus InferShape(gert::InferShapeContext *context)
{
const gert::Shape *x1_shape = context->GetInputShape(0);
gert::Shape *y_shape = context->GetOutputShape(0);
*y_shape = *x1_shape;
return GRAPH_SUCCESS;
}
IMPL_OP_INFERSHAPE(AddCustom).InferShape(InferShape); // 在该文件中完成InferShape注册
} // namespace ge
op_host/{op_name}_tiling.cpp
将原有 ${op_name}.cpp 中 TilingFunc 迁移至该文件后,调用接口 IMPL_OP_OPTILING 完成 TilingFunc 注册。宏定义 TilingData 结构体改成标准 C++ 结构体后,TilingFunc 中对结构体成员变量不再使用 tiling.set_xxx 的方式进行赋值,而是直接对成员变量赋值。若是新增定义模板参数和模板参数组合,TilingFunc 中需要同时配置模板参数 tilingKey。可参考 add_example_tiling.cpp。
// 原有${op_name}.cpp中TilingFunc
namespace optiling {
const uint32_t BLOCK_DIM = 8;
const uint32_t DEFAULT_TILE_NUM = 8;
constexpr int MIN_LENGTH_FOR_SPLIT = 2048;
static ge::graphStatus TilingFunc(gert::TilingContext *context)
{
TilingData tiling;
uint32_t totalLength = context->GetInputShape(0)->GetOriginShape().GetShapeSize();
ge::DataType dtype_x = context->GetInputDesc(0)->GetDataType();
ge::DataType dtype_y = context->GetInputDesc(1)->GetDataType();
ge::DataType dtype_z = context->GetOutputDesc(0)->GetDataType();
....
tiling.set_totalLength(totalLength);
tiling.SaveToBuffer(context->GetRawTilingData()->GetData(), context->GetRawTilingData()->GetCapacity());
context->GetRawTilingData()->SetDataSize(tiling.GetDataSize());
const uint64_t tilingKey = GET_TPL_TILING_KEY(D_T_X, D_T_Y, D_T_Z, TILE_NUM, IS_SPLIT); // 模板参数tilingkey配置
context->SetTilingKey(tilingKey);
size_t *currentWorkspace = context->GetWorkspaceSizes(1);
currentWorkspace[0] = 0;
return ge::GRAPH_SUCCESS;
}
} // namespace optiling
// 迁移至op_host/{op_name}_tiling.cpp后,调用接口IMPL_OP_OPTILING完成TilingFunc注册,直接对结构体成员变量赋值
namespace optiling {
const uint32_t BLOCK_DIM = 8;
const uint32_t DEFAULT_TILE_NUM = 8;
constexpr int MIN_LENGTH_FOR_SPLIT = 2048;
static ge::graphStatus TilingFunc(gert::TilingContext *context)
{
// TilingData tiling;
TilingData* tiling = context->GetTilingData<TilingData>();
uint32_t totalLength = context->GetInputShape(0)->GetOriginShape().GetShapeSize();
ge::DataType dtype_x = context->GetInputDesc(0)->GetDataType();
ge::DataType dtype_y = context->GetInputDesc(1)->GetDataType();
ge::DataType dtype_z = context->GetOutputDesc(0)->GetDataType();
....
tiling->totalLength = totalLength; // 直接对结构体成员变量赋值
// tiling.set_totalLength(totalLength); // 不再使用tiling.set_xxx的方式进行赋值
// tiling.SaveToBuffer(context->GetRawTilingData()->GetData(), context->GetRawTilingData()->GetCapacity());
// context->GetRawTilingData()->SetDataSize(tiling.GetDataSize());
const uint64_t tilingKey = GET_TPL_TILING_KEY(D_T_X, D_T_Y, D_T_Z, TILE_NUM, IS_SPLIT); // 模板参数tilingkey配置
context->SetTilingKey(tilingKey);
size_t *currentWorkspace = context->GetWorkspaceSizes(1);
currentWorkspace[0] = 0;
return ge::GRAPH_SUCCESS;
}
IMPL_OP_OPTILING(AddCustom).Tiling(TilingFunc); // 在该文件中完成TilingFunc注册
} // namespace optiling
op_graph/{op_name}_graph_infer.cpp
图模式场景需要适配该文件,将原有 ${op_name}.cpp 中类型推导独立迁移至该文件后,调用接口 IMPL_OP 完成 InferDataType 注册。
// 原有${op_name}.cpp中InferDataType
namespace ge {
static graphStatus InferDataType(gert::InferDataTypeContext *context)
{
const auto inputDataType = context->GetInputDataType(0);
context->SetOutputDataType(0, inputDataType);
return ge::GRAPH_SUCCESS;
}
} // namespace ge
// 迁移至op_graph/{op_name}_graph_infer.cpp后,调用接口IMPL_OP完成InferDataType注册
namespace ge {
static graphStatus InferDataType(gert::InferDataTypeContext *context)
{
const auto inputDataType = context->GetInputDataType(0);
context->SetOutputDataType(0, inputDataType);
return ge::GRAPH_SUCCESS;
}
IMPL_OP(AddCustom).InferDataType(InferDataType); // 在该文件中完成InferDataType函数注册
} // namespace ge
op_kernel/{op_name}_tiling_data.h
// 原有op_host/{op_name}_tiling.h中的宏定义TilingData结构体
namespace optiling {
BEGIN_TILING_DATA_DEF(TilingData)
TILING_DATA_FIELD_DEF(uint32_t, totalLength);
END_TILING_DATA_DEF;
REGISTER_TILING_DATA_CLASS(XXX, TilingData)
} // namespace optiling
// 迁移至op_kernel/{op_name}_tiling_data.h后,改成C++标准结构体
struct TilingData {
uint32_t totalLength;
};
op_kernel/{op_name}.h
保留原有 op_host/{op_name}.cpp 中 kernel 实现的算子类定义部分。
op_kernel/{op_name}.cpp
// 原有op_kernel/{op_name}.cpp中的核函数实现
template<int D_T_X, int D_T_Y, int D_T_Z, int TILE_NUM, int IS_SPLIT>
__global__ __aicore__ void add_custom(GM_ADDR x, GM_ADDR y, GM_ADDR z, GM_ADDR workspace, GM_ADDR tiling)
{
GET_TILING_DATA(tiling_data, tiling);
if(D_T_X == ADD_TPL_FP32 && D_T_Y == ADD_TPL_FP32 && D_T_Z == ADD_TPL_FP32){
KernelAdd<float, float, float> op;
op.Init(x, y, z, tiling_data.totalLength, TILE_NUM);
op.Process1();
}else if(D_T_X == ADD_TPL_FP16 && D_T_Y == ADD_TPL_FP16 && D_T_Z == ADD_TPL_FP16){
KernelAdd<half, half, half> op;
if(IS_SPLIT == 0){
op.Init(x, y, z, tiling_data.totalLength, TILE_NUM);
op.Process1();
}else if(IS_SPLIT == 1){
op.Init(x, y, z, tiling_data.totalLength, TILE_NUM);
op.Process2();
}
}
}
// 迁移至op_kernel/{op_name}.cpp后,新增REGISTER_TILING_DEFAULT调用注册Tiling结构体,使用GET_TILING_DATA_WITH_STRUCT获取TilingData
template<int D_T_X, int D_T_Y, int D_T_Z, int TILE_NUM, int IS_SPLIT>
__global__ __aicore__ void add_custom(GM_ADDR x, GM_ADDR y, GM_ADDR z, GM_ADDR workspace, GM_ADDR tiling)
{
// GET_TILING_DATA(tiling_data, tiling);
REGISTER_TILING_DEFAULT(TilingData); // 新增REGISTER_TILING_DEFAULT调用注册TilingData结构体
GET_TILING_DATA_WITH_STRUCT(TilingData, tiling_data, tiling); // 宏GET_TILING_DATA_WITH_STRUCT获取TilingData
if(D_T_X == ADD_TPL_FP32 && D_T_Y == ADD_TPL_FP32 && D_T_Z == ADD_TPL_FP32){
KernelAdd<float, float, float> op;
op.Init(x, y, z, tiling_data.totalLength, TILE_NUM);
op.Process1();
}else if(D_T_X == ADD_TPL_FP16 && D_T_Y == ADD_TPL_FP16 && D_T_Z == ADD_TPL_FP16){
KernelAdd<half, half, half> op;
if(IS_SPLIT == 0){
op.Init(x, y, z, tiling_data.totalLength, TILE_NUM);
op.Process1();
}else if(IS_SPLIT == 1){
op.Init(x, y, z, tiling_data.totalLength, TILE_NUM);
op.Process2();
}
}
}
op_kernel/{op_name}_tiling_key.h
保留原有 op_kernel/tiling_key_{op_name}.h 中算子的模板参数定义,若不存在该文件,请参考 add_example_tiling_key.h 新增定义模板参数和模板参数组合。
附录:算子跨平台迁移
完成算子代码开发后,如需实现多平台间(如 Atlas A2/A3 等)的算子代码迁移,需考虑硬件结构差异引发的软件实现变更。您可以参考 算子跨平台迁移指导,该文档提供了常见的适配要点与方法论,并提供相关算子的适配样例。
小结
本文以 AddExample 算子为完整案例,贯通了 CANN ops-math 中 AI Core 算子的全生命周期:build.sh --genop 生成标准工程目录 → def.cpp 定义算子信息库 → Tiling 侧以 TilingData/TilingKey 完成核间与核内两级切分 → Kernel 侧通过 TPipe/TQue 双缓冲流水完成 CopyIn-Compute-CopyOut → 图模式与 aclnn 适配生成可调用接口 → build.sh --pkg 编译出 run 包并安装 → 通过 Infershape/Tiling/Kernel 三类 UT 与 aclnn 调用完成功能验证。对于同一算子族,还可借助 atvoss 框架以 DAG 方式声明计算逻辑、按架构分目录适配多平台,并参考算子工程迁移与跨平台迁移附录将存量算子快速纳入本工程。仓库中 examples/add_example 与 examples 目录下的其它算子样例,可作为继续深入学习的活教材。