--- title: aclnn开发接口列表 description: "无论是基于Ascend C自定义算子还是CANN内置算子，均可通过aclnn API（也称为Level2层接口）直调算子，无需提供IR（Intermediate Representation）定义。" url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/API/aolapi/atlasascendc_api_07_1042.html sourcePath: /source/zh/canncommercial/900/API/aolapi/atlasascendc_api_07_1042.html indexId: dff0c7bbb51599f092fc7eda3e71cfc4a0bf902dd37d9ea650b0b20254888eb570 --- # aclnn开发接口列表 无论是基于Ascend C自定义算子还是CANN内置算子，均可通过aclnn API（也称为Level2层接口）直调算子，无需提供IR（Intermediate Representation）定义。 为实现aclnn API直调算子，本章提供了开发aclnn API所需的底层框架能力接口（也称为nnopbase接口）和基础张量操作接口（也称为Level0层接口）。 #### 基本概念 - Level0层接口 简称L0层接口，表示调用单Kernel的Host侧API，提供了细颗粒API（单Kernel下发）和算子API开发的基础结构体（如Tensor定义等）和公共基础能力（如workspace复用、引擎调度等），上层应用或者L2层接口可通过L0接口的快速组装实现高性能计算。 L0接口返回值类型是Tensor的类型结构，如aclTensor*、std::tuple、aclTensorList*，最后一个参数固定为aclOpExecutor *executor，类型与名称均不可变，示例如下： 1 aclTensor* AddNd(aclTensor *x1, aclTensor *x2, aclOpExecutor *executor) L0接口命名空间为“namespace l0op”，接口名为“${op_type}${format}${dtype}”，其中${op_type}为算子名，${format}为算子输入/输出数据格式，${dtype}为算子输入/输出数据类型（对于非常规的输入/输出数据类型，需带上数据类型匹配关系）。调用示例如下： 1 2 3 l0op::AddNd //Add算子输入均按ND计算 l0op::MatMulNdFp162Fp32 //MatMul算子输入输出均按ND格式计算，并且2代表“To”，表示输入fp16、输出fp32 l0op::MatMulNzFp162Fp16 //MatMul算子输入输出均按NZ格式计算，并且2代表“To”，表示输入与输出都是fp16 - Level2层接口 简称L2层接口，是对L0层接口的高层级封装（内部通过调用单个或多个L0接口实现更灵活功能），表示更上层的Host侧API。该类接口提供单算子直调方式，屏蔽了算子内部实现逻辑，用户直接调用L2接口即可实现调用算子。 L2接口返回值类型是aclnnStatus，一般包括获取workspaceSize和算子执行“两段式接口”： ``` aclnnStatus aclnnXxxGetWorkspaceSize(const aclTensor *src, ..., aclTensor *out, ..., uint64_t *workspaceSize, aclOpExecutor **executor); aclnnStatus aclnnXxx(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream); ``` - aclnnXxxGetWorkspaceSize最后两个参数固定为(uint64_t *workspaceSize, aclOpExecutor **executor)，名称和类型均不可变。 - aclnnXxx接口参数固定为(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream)。 其中aclnnXxxGetWorkspaceSize为第一段接口，主要用于计算本次API调用过程中需要多少workspace内存，获取到本次计算所需的workspaceSize后，按照workspaceSize申请NPU内存，然后调用第二段接口aclnnXxx执行计算。“Xxx”表示对应的算子类型，如Add算子。 - workspace是指除输入/输出外，API在AI处理器上完成计算所需要的临时内存。 - 二阶段接口aclnnXxx(...)不能重复调用，如下调用方式会出现异常： 1 2 3 aclnnXxxGetWorkspaceSize(...) aclnnXxx(...) aclnnXxx(...) - 原地算子接口 表示在原地址进行更新操作的算子接口，其计算过程中输入和输出为同一地址，以减少不必要的内存占用。aclnn类原地算子接口名一般定义为：aclnnInplaceXxxGetWorkspaceSize（一阶段接口）、aclnnInplaceXxx（二阶段接口）。 #### 接口列表 - 框架能力接口：提供实现aclnn接口的基础能力接口，比如算子执行器（opExecutor）处理、数据类型/格式/shape等操作，具体如 表1 所示；此外还包括常用类和宏，具体参见 表2 、 表3 。此类接口的源码实现已在 CANN/opbase仓(https://gitcode.com/cann/opbase) 开放，可进一步了解详情。 - 基础张量操作接口：提供实现aclnn接口的基础张量操作接口，比如Tensor数据类型转换、shape重构等，具体如 表4 所示。此类接口的源码实现已在 CANN/ops-math仓(https://gitcode.com/cann/ops-math) 开放，可进一步了解详情。 - 头文件说明：使用上述接口时请按实际情况include依赖的头文件，头文件路径为${INSTALL_DIR}/include目录，其中${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。以root用户安装为例，安装后文件默认存储路径为：/usr/local/Ascend/cann。 为了更好地指导您应用本章接口，可以参考CANN开源社区(https://gitcode.com/cann)中“算子库项目”，部分算子的源码实现已开放，您可以基于本章接口进行定制化修改。 **表1 框架能力接口列表** | 接口分类 | 说明 | 所属头文件 | | --- | --- | --- | | bfloat16 | 详细介绍了bfloat16数据类型在CPU侧的实现类。 | aclnn/opdev/bfloat16.h | | common\_types | 详细介绍了aclTensor、aclScalar等基础的aclnn数据结构。 | aclnn/opdev/common\_types.h | | data\_type\_utils | 提供了DataType相关的基础接口，例如获取指定DataType的size等。 | aclnn/opdev/data\_type\_utils.h | | fast\_vector | 详细介绍了FastVector数据类型，该类型为aclnn中实现的高效vector数据结构。 说明：该头文件定义的接口均为预留接口，开发者无需关注。 | aclnn/opdev/fast\_vector.h | | format\_utils | 提供了Format相关的基础接口。 | aclnn/opdev/format\_utils.h | | fp16\_t | 详细介绍了float16数据类型在CPU侧的实现类。 | aclnn/opdev/fp16\_t.h | | framework\_op | 详细介绍了框架对外提供的从host侧到device侧拷贝能力。 | aclnn/opdev/framework\_op.h | | make\_op\_executor | 提供初始化aclOpExecutor的宏声明。 说明：该头文件定义的接口均为预留接口，开发者无需关注。 | aclnn/opdev/make\_op\_executor.h | | object | 详细介绍了aclnn中aclTensor等基础数据结构的基类Object类，用于重载实现new、delete方法。 | aclnn/opdev/object.h | | op\_arg\_def | 详细介绍了OpArgContext类，并对外提供OP\_INPUT等宏声明。 | aclnn/opdev/op\_arg\_def.h | | op\_cache | 详细介绍了OpExecCache及相关类，用于完成aclnn缓存，提升运行性能。 | aclnn/opdev/op\_cache.h | | op\_cache\_container | 详细介绍了带LRU淘汰机制的aclnn缓存容器。 | aclnn/opdev/op\_cache\_container.h | | op\_config | 提供了算子运行时相关的配置信息，如确定性计算开关等。 | aclnn/opdev/op\_config.h | | op\_def | 定义基础枚举及常量，例如精度模式OpImplMode等。 | aclnn/opdev/op\_def.h | | op\_dfx | 详细介绍了DfxGuard类，用于接口打印及上报profiling。 | aclnn/opdev/op\_dfx.h | | aclnn返回码 | 定义了aclnn错误码。 | aclnn/opdev/op\_errno.h | | op\_executor | 详细介绍了aclOpExecutor类。 | aclnn/opdev/op\_executor.h | | op\_log | 定义aclnn中日志打印宏。 | aclnn/opdev/op\_log.h | | platform | 详细介绍了PlatformInfo类，用于存放SOC平台信息。 | aclnn/opdev/platform.h | | pool\_allocator | 详细介绍了PoolAllocator类，用于实现aclnn内部的CPU内存池。 | aclnn/opdev/pool\_allocator.h | | shape\_utils | 提供了shape相关的基础操作，例如shape打印等。 | aclnn/opdev/shape\_utils.h | | small\_vector | 详细介绍了SmallVector类，该类为aclnn中实现的高效vector数据结构，主要针对已知数据量较小的场景。 | aclnn/opdev/small\_vector.h | | tensor\_view\_utils | 提供了对于View类的基础操作，例如判断aclTensor是否连续等。 | aclnn/opdev/tensor\_view\_utils.h | | data\_type\_utils | 提供了DataType相关的基础接口，例如判断指定DataType是否为整数类型等。 | aclnn/opdev/op\_common/data\_type\_utils.h | | aicpu\_args\_handler | 提供了AI CPU相关的组合计算任务的处理逻辑，例如拼接计算任务相关的参数等。 | aclnn/opdev/aicpu/aicpu\_args\_handler.h | | aicpu\_ext\_info\_handle | 提供了AI CPU相关的计算任务拓展参数的处理逻辑，例如拼接解析拓展参数的接口。 | aclnn/opdev/aicpu/aicpu\_ext\_info\_handle.h | | aicpu\_task | 提供了AI CPU任务设置、下发等逻辑，例如设置调用哪个AI CPU算子，设置算子输入、输出等接口。 | aclnn/opdev/aicpu/aicpu\_task.h | | aicpu\_utils | AI CPU任务需要的一些公共接口。 | aclnn/opdev/aicpu/aicpu\_utils.h | **表2 常用宏表** | 宏名称 | 说明 | 所属头文件 | | --- | --- | --- | | DFX\_IN | 在L2\_DFX\_PHASE\_1中，用于打包所有的host侧API输入参数。 | aclnn/opdev/op\_dfx.h | | DFX\_OUT | 在L2\_DFX\_PHASE\_1中，用于打包所有的host侧API输出参数。 | aclnn/opdev/op\_dfx.h | | L0\_DFX | 必须在host侧API L0接口中使用，用于接口及L0接口入参打印。 | aclnn/opdev/op\_dfx.h | | L2\_DFX\_PHASE\_1 | 必须在一阶段接口最前方调用，用于接口及一阶段入参打印。 | aclnn/opdev/op\_dfx.h | | L2\_DFX\_PHASE\_2 | 必须在二阶段接口最前方调用，用于接口打印。 | aclnn/opdev/op\_dfx.h | | OP\_TYPE\_REGISTER | 必须在L0接口最开始处使用，用于注册L0算子。 | aclnn/opdev/op\_dfx.h | | OP\_ATTR | ADD\_TO\_LAUNCHER\_LIST\_AICORE中，打包算子属性参数。 | aclnn/opdev/op\_arg\_def.h | | OP\_EMPTY\_ARG | ADD\_TO\_LAUNCHER\_LIST\_AICORE中，用于占位一个空的输入或输出。 | aclnn/opdev/op\_arg\_def.h | | OP\_INPUT | ADD\_TO\_LAUNCHER\_LIST\_AICORE中，打包算子输入aclTensor。 | aclnn/opdev/op\_arg\_def.h | | OP\_MODE | ADD\_TO\_LAUNCHER\_LIST\_AICORE中，打包算子运行选项，例如是否使能HF32。 | aclnn/opdev/op\_arg\_def.h | | OP\_OUTPUT | ADD\_TO\_LAUNCHER\_LIST\_AICORE中，打包算子输出aclTensor。 | aclnn/opdev/op\_arg\_def.h | | OP\_OUTSHAPE | ADD\_TO\_LAUNCHER\_LIST\_AICORE中，针对第三类算子，设置存放输出shape的aclTensor。 | aclnn/opdev/op\_arg\_def.h | | OP\_OPTION | ADD\_TO\_LAUNCHER\_LIST\_AICORE中，打包算子指定的精度模式。 | aclnn/opdev/op\_arg\_def.h | | OP\_WORKSPACE | ADD\_TO\_LAUNCHER\_LIST\_AICORE中，打包算子显式指定的workspace参数。 | aclnn/opdev/op\_arg\_def.h | | CREATE\_EXECUTOR | 创建一个UniqueExecutor对象，该对象为aclOpExecutor的生成工厂类。 | aclnn/opdev/make\_op\_executor.h | | INFER\_SHAPE | 针对指定算子，运行其infershape函数，推导输出shape。 | aclnn/opdev/make\_op\_executor.h | | ADD\_TO\_LAUNCHER\_LIST\_AICORE | 创建某个AICore算子的执行任务，并置入aclOpExecutor的执行队列，在二阶段时执行。 | aclnn/opdev/make\_op\_executor.h | | OP\_ATTR\_NAMES | String类型的vector，打包AI CPU算子的字符类型属性。 | aclnn/opdev/aicpu/aicpu\_task.h | | ADD\_TO\_LAUNCHER\_LIST\_AICPU | 创建某个AI CPU算子的执行任务，并置入aclOpExecutor的执行队列，在二阶段时执行。 | aclnn/opdev/aicpu/aicpu\_task.h | **表3 常用class和struct表** | class/struct名称 | 说明 | 所属头文件 | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | aclOpExecutor | 用于表示算子执行器，记录整个host侧API运行信息的上下文结构，如L2接口执行过程中的计算图、L0算子launch子任务、workspace地址和大小等信息。 该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见op\_executor。 | aclnn/opdev/op\_executor.h | | | | | | | | aclTensor | 用于表示一个张量对象，包括描述张量的shape、dtype、format、address等信息，数据可以放在host侧或device侧。 该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common\_types。 | aclnn/opdev/common\_type.h | | | | | | | | aclScalar | 用于表示一个标量对象，数据一般放在host侧。 该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common\_types。 | aclnn/opdev/common\_type.h | | | | | | | | aclTensorList | 用于表示一组aclTensor类型组成的列表对象。 该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common\_types。 | aclnn/opdev/common\_type.h | | | | | | | | aclScalarList | 用于表示一组aclScalar类型组成的列表对象。 该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common\_types。 | aclnn/opdev/common\_type.h | | | | | | | | aclBoolArray | 用于表示一个布尔类型的数组对象，数据一般放在host侧。 该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common\_types。 | aclnn/opdev/common\_type.h | | | | | | | | aclIntArray | 用于表示一个int64\_t类型的数组对象，数据一般放在host侧。 该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common\_types。 | aclnn/opdev/common\_type.h | | | | | | | | aclFloatArray | 用于表示一个fp32类型的数组对象，数据一般放在host侧。 该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common\_types。 | aclnn/opdev/common\_type.h | | | | | | | | aclFp16Array | 用于表示一个fp16类型的数组对象，数据一般放在host侧。 该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common\_types。 | aclnn/opdev/common\_type.h | | | | | | | | aclBf16Array | 用于表示一个bf16类型的数组对象，数据一般放在host侧。 该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common\_types。 | aclnn/opdev/common\_type.h | | | | | | | | SmallVector | 该类使用内部内存池实现vector容器，基础功能与C++标准库中std::vector容器相同，无需每次扩容都申请内存，避免影响性能。其定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见small\_vector。 op::FVector：本质是存储容量长度为8的SmallVector。 1 2 3 4 namespace op { template using FVector = op::internal::SmallVector>; } op:Strides：本质是存储容量长度为25的FVector，元素类型int64\_t，存储stride信息。 1 2 3 4 namespace op { constexpr uint64\_t MAX\_DIM\_NUM = 25; using Strides = FVector; } op::ShapeVector：本质是存储容量长度为25的FVector，元素类型int64\_t，存储shape信息。 1 2 3 4 namespace op { constexpr uint64\_t MAX\_DIM\_NUM = 25; using ShapeVector = FVector; } | 1 2 3 4 | namespace op { template using FVector = op::internal::SmallVector>; } | 1 2 3 4 | namespace op { constexpr uint64\_t MAX\_DIM\_NUM = 25; using Strides = FVector; } | 1 2 3 4 | namespace op { constexpr uint64\_t MAX\_DIM\_NUM = 25; using ShapeVector = FVector; } | aclnn/opdev/small\_vector.h | | 1 2 3 4 | namespace op { template using FVector = op::internal::SmallVector>; } | | | | | | | | | 1 2 3 4 | namespace op { constexpr uint64\_t MAX\_DIM\_NUM = 25; using Strides = FVector; } | | | | | | | | | 1 2 3 4 | namespace op { constexpr uint64\_t MAX\_DIM\_NUM = 25; using ShapeVector = FVector; } | | | | | | | | | OpExecMode | 用于表示算子运行模式的枚举类，定义参见OpExecMode。 | aclnn/opdev/op\_def.h | | | | | | | | OpImplMode | 用于表示算子精度模式的枚举类，定义参见OpImplMode。 | aclnn/opdev/op\_def.h | | | | | | | **表4 基础张量操作接口列表** | 接口名 | 说明 | 接口所属头文件 | | --- | --- | --- | | Cast | 将输入tensor转换为指定的数据类型。 | aclnn\_kernels/cast.h | | Contiguous | 将非连续tensor转换为连续tensor。 | aclnn\_kernels/contiguous.h | | ViewCopy | 将连续tensor搬运到连续或非连续tensor上。 | aclnn\_kernels/contiguous.h | | Pad | 将输入tensor按照paddings的大小对各个维度进行填充，填充值为0。 | aclnn\_kernels/pad.h | | Reshape | 将输入tensor x的shape转换成该函数的第二个参数shape。 | aclnn\_kernels/reshape.h | | Slice | 从输入tensor中提取所需的切片。 | aclnn\_kernels/slice.h | | Transpose | 将输入tensor x的shape按指定维度的排列顺序perm进行转置并输出。 | aclnn\_kernels/transpose.h | | TransData | 将输入tensor的format转换为指定的dstPrimaryFormat。 | aclnn\_kernels/transdata.h | | TransDataSpecial | 将输入tensor的format转换为指定的dstPrimaryFormat，与TransData类似。 | aclnn\_kernels/transdata.h | | ReFormat | 在指定format和输入x的维度相同时，将输入数据格式设置为目标format。 | aclnn\_kernels/transdata.h | | IsNullptr | 判断输入的指针是否为空。 | aclnn\_kernels/common/op\_error\_check.h |