AI Core算子开发全流程指南:基于CANN ops-math标准工程的算子开发实战

原创2026-09-18 18:47:241,999 阅读
文章标签:算子库人工智能深度学习高性能计算CANNAscend

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):

  1. 前提条件:参考项目 README.md 完成环境准备和源码下载。
  2. 工程创建:创建标准算子工程目录,方便后续算子编译和部署。
  3. 算子定义:明确算子功能说明与原型定义。
  4. Tiling 实现:实现 Host 侧算子 Tiling 函数。
  5. Kernel 实现:实现 Device 侧算子核函数。
  6. 图模式适配:让自定义算子支持运行图模式。
  7. aclnn 适配:自定义算子推荐通过 aclnn 接口调用,需完成二进制发布;如需入图,参考附录。
  8. 编译部署:通过工程编译脚本完成自定义算子的编译和安装。
  9. 算子验证:通过常见算子调用方式验证自定义算子功能。

工程创建

目录创建是算子开发的重要步骤,为后续代码编写、编译构建和调试提供统一的目录结构和文件组织方式。

使用 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 框架的算子,其目录结构与标准算子有所不同,主要体现在以下方面:

  1. TilingKey:atvoss 算子通常复用 atvoss 框架内置的 TilingKey 定义,不再单独提供 ${op_name}_tiling_key.h 文件,而是在 Tiling 实现中直接定义常量(如 constexpr uint64_t ABS_TILING_KEY_XXX = 101)。
  2. TilingData:atvoss 算子使用 ${op_name}_struct.h 替代标准算子的 ${op_name}_tiling_data.h,内部继承 atvoss 框架提供的基础结构体(如 EleBaseTilingData)。
  3. DAG描述:atvoss 算子使用 ${op_name}_dag.h 描述算子的计算过程(数据流图),通过组合框架提供的计算原语(如 Vec::CopyIn、Vec::Abs、Vec::Cast 等)定义算子的计算逻辑。
  4. 多平台支持: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架构)

说明:

  1. atvoss 算子的 ${op_name}_struct.h 等价于标准算子的 ${op_name}_tiling_data.h,用于定义 TilingData 结构体;
  2. atvoss 算子的 ${op_name}_dag.h 是算子计算过程的描述文件,通过 DAG(有向无环图)描述数据流,为 atvoss 框架特有文件;
  3. atvoss 算子没有独立的 ${op_name}_tiling_key.h 文件,TilingKey 在 Tiling 实现中通过常量定义;
  4. 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 交付件与标准算子有所不同,通常包含:

  1. ${op_name}_tiling_arch{xx}.cpp 和 ${op_name}_tiling_arch{xx}.h:放在 ${op_name}/op_host/arch{xx} 目录下,按芯片架构分别实现 Tiling 逻辑;
  2. ${op_name}_struct.h:放在 ${op_name}/op_kernel 目录下,定义 TilingData 结构体(等价于标准算子的 ${op_name}_tiling_data.h),内部继承 atvoss 框架提供的基础结构体;
  3. 无独立的 ${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);

样例中函数空实现说明:

  1. TilingParse:图模式标准交付件,保留函数定义以满足框架调用规范,无实际逻辑时可置空。
  2. 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 交付件与标准算子有所不同,通常包含:

  1. ${op_name}_apt.cpp:放在 ${op_name}/op_kernel 目录下,为 Kernel 入口文件(apt 表示 atvoss port),包含核函数定义和调度逻辑,使用 atvoss 框架提供的 ElementwiseSch 等调度器;
  2. ${op_name}_struct.h:放在 ${op_name}/op_kernel 目录下,定义 TilingData 结构体;
  3. ${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

算子验证

算子开发过程中,可通过如下方式进行验证:

  1. UT验证:验证交付件代码能否正常运行,无需 NPU 环境。
  2. 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. 用例基本流程

  1. 调用接口构造用例上下文。需要的参数主要为输入和输出的 shape/format/dtype。
    • shape/format/dtype 可参考 ${op_name}_def.cpp 算子信息库;
    • 若某输入在信息库中标记为 ValueDepend,UT 中需同时准备该输入的真实数据值。
  2. 设定预期结果。
  3. 调用接口执行用例。

简化示例:

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. 用例基本流程

  1. 调用接口构造用例上下文。需要的参数主要为输入和输出的 shape/format/dtype、属性以及 compileInfo,可参考 ${op_name}_def.cpp 算子信息库。
    • shape/format/dtype 和属性可参考 ${op_name}_def.cpp 算子信息库;
    • 若某输入在信息库中标记为 ValueDepend,UT 中需同时准备该输入的真实数据值;
    • compileInfo 优先使用 tiling 头文件中声明的结构体,若 tiling 头文件没有声明,则在用例中声明。
  2. 设定预期结果。
  3. 调用接口执行用例。

简化示例(真实样例见 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 头文件。
  • 测试类:继承 testing::Test,实现 SetUpTestCase/TearDownTestCase 统一做数据准备与清理(如拷贝数据目录、chmod、生成 bin)。
  • 命名:测试类建议 ${OpName}KernelTest,用例名建议 test_case_xxx。

2. 用例基本流程

  1. 设定输入 shape/format/dtype,初次上手可参考 ${op_name}_def.cpp 算子信息库;若某输入在信息库中标记为 ValueDepend,UT 中需同时准备该输入的真实数据值。
  2. 准备输入/输出/Workspace/Tiling 缓冲区(AscendC::GmAlloc)。
  3. 准备 Tiling 数据(手动构造或由 Tiling 函数生成)。
  4. 设置 ICPU_SET_TILING_KEY 与 AscendC::SetKernelMode。
  5. 使用 ICPU_RUN_KF 执行 Kernel。
  6. 结果校验并释放资源(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 目录下的其它算子样例,可作为继续深入学习的活教材。

登录后查看全文
ops-math