简介

基本概念

Level0接口

简称L0接口，表示基础Kernel的API，这些API直接调用亲和芯片的Kernel。

L0接口返回值类型是Tensor类型结构，如aclTensor*、std::tuple<aclTensor*, aclTensor*>、aclTensorList*，最后参数固定为aclOpExecutor *executor，类型与名称均不可变，示例如下：

        
             aclTensor* AddNd(aclTensor *x1, aclTensor *x2, aclOpExecutor *executor)

L0接口命名空间为“namespace l0op”，接口名为“${op_type}${format}${dtype}”，其中${op_type}为算子名，${format}为算子输入/输出数据格式，${dtype}为算子输入/输出数据类型。调用示例如下：

        
             l0op::AddNd                               //Add算子输入都是按ND计算
l0op::MatMulNdFp162Fp32                   //MatMul算子输入输出都按ND格式计算，并且输入是fp16，输出是fp32

Level2接口
简称L2接口，表示更高一层的API（也称为Host API），可以调用多个L0接口实现更灵活的功能，同时对标框架API功能，便于框架适配和脚本迁移。

L2接口返回值类型是aclnnStatus，一般定义为“两段式接口”：
```
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内存；获取到本次API计算需要的workspace大小后，按照workspaceSize大小申请昇腾AI处理器内存，然后调用二阶段接口aclnnXxx完成计算。
- workspace是指除输入/输出外，API在昇腾AI处理器上完成计算所需要的临时内存。
- 二阶段接口aclnnXxx(...)不能重复调用，如下调用方式会出现异常：
```
aclnnXxxGetWorkspaceSize(...)
aclnnXxx(...)
aclnnXxx(...)
```
broadcast关系
broadcast（广播）描述了算子在运算期间如何处理具有不同形状的数组。在某些情况下，较小的数组可以“广播至”较大的数组，使两者shape互相兼容。更多关于广播技术的介绍可以参考NumPy官网。

整体说明

本章主要介绍单算子API执行涉及的框架基础接口、宏、类等，还包括基础核函数接口（即Level0接口）。详细阐述了函数原型、函数功能、参数说明、约束与限制、调用示例等，指导开发者快速自定义NN（Neural Network）基础类和融合类算子（一般以aclnn为前缀）或者对CANN内置的NN类算子进行定制化修改，以支撑各式各样的AI业务。

调用单算子API执行相关的接口时，开发者需要根据实际情况include依赖的头文件，各头文件路径如下：

框架能力接口头文件一般在${INSTALL_DIR}/runtime/include目录下，内容如表1所示。
基础核函数接口头文件一般在${INSTALL_DIR}/opp/include目录下，内容如表2所示。

其中${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。例如，若安装的Ascend-cann-toolkit软件包，则安装后文件存储路径为：$HOME/Ascend/ascend-toolkit/latest。

表1 框架能力接口列表
接口分类	说明	接口所属头文件
bfloat16	详细介绍了bfloat16数据类型在CPU侧的实现类。	aclnn/opdev/bfloat16.h
common_types	详细介绍了aclTensor、aclScalar等基础的aclnn数据结构。	aclnn/opdev/common_type.h
data_type_utils	提供了DataType相关的基础接口，例如获取指定DataType的size等。	aclnn/opdev/data_type_utils.h
预留接口，开发者无需关注。	详细介绍了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
预留接口，开发者无需关注。	对外提供初始化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_def	定义基础枚举及常量，例如精度模式OpImplMode等。	aclnn/opdev/op_def.h
op_dfx	详细介绍了DfxGuard类，用于接口打印及上报profiling。	aclnn/opdev/op_dfx.h
参见《算子加速库接口参考》中“NN算子接口 > 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_uitls	AI CPU任务需要的一些公共接口。	aclnn/opdev/aicpu/aicpu_uitls.h

表2 基础核函数接口列表
接口名	说明	接口所属头文件
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类似。
ReFormat	在指定format和输入x的维度相同时，将输入数据格式设置为目标format。
IsNullptr	判断输入的指针是否为空。	aclnn_kernels/common/op_error_check.h

常用宏和类

表3 常用宏表
宏名称	宏说明	宏所属头文件
DFX_IN	在L2_DFX_PHASE_1中，用于打包所有的host侧API输入参数。	aclnn/opdev/op_dfx.h
DFX_OUT	在L2_DFX_PHASE_1中，用于打包所有的host侧API输出参数。
L0_DFX	必须在host侧API L0接口中使用，用于接口及L0接口入参打印。
L2_DFX_PHASE_1	必须在一阶段接口最前方调用，用于接口及一阶段入参打印。
L2_DFX_PHASE_2	必须在二阶段接口最前方调用，用于接口打印。
OP_TYPE_REGISTER	必须在L0接口最开始处使用，用于注册L0算子。
OP_ATTR	ADD_TO_LAUNCHER_LIST_AICORE中，打包算子属性参数。	aclnn/opdev/op_arg_def.h
OP_EMPTY_ARG	ADD_TO_LAUNCHER_LIST_AICORE中，用于占位一个空的输入或输出。
OP_INPUT	ADD_TO_LAUNCHER_LIST_AICORE中，打包算子输入aclTensor。
OP_MODE	ADD_TO_LAUNCHER_LIST_AICORE中，打包算子运行选项，例如是否使能HF32。
OP_OUTPUT	ADD_TO_LAUNCHER_LIST_AICORE中，打包算子输出aclTensor。
OP_OUTSHAPE	ADD_TO_LAUNCHER_LIST_AICORE中，针对第三类算子，设置存放输出shape的aclTensor。
OP_OPTION	ADD_TO_LAUNCHER_LIST_AICORE中，打包算子指定的精度模式。
OP_WORKSPACE	ADD_TO_LAUNCHER_LIST_AICORE中，打包算子显式指定的workspace参数。
CREATE_EXECUTOR	创建一个UniqueExcutor对象，该对象为aclOpExecutor的生成工厂类。	aclnn/opdev/make_op_executor.h
INFER_SHAPE	针对指定算子，运行其infershape函数，推导输出shape。
ADD_TO_LAUNCHER_LIST_AICORE	创建某个AICore算子的执行任务，并置入aclOpExecutor的执行队列，在二阶段时执行。
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

表4 常用类表
类名称	类说明	类所属头文件
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。
aclTensorList	用于表示一组aclTensor类型组成的列表对象。该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common_types。
aclScalarList	用于表示一组aclScalar类型组成的列表对象。该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common_types。
aclBoolArray	用于表示一个布尔类型的数组对象，数据一般放在host侧。该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common_types。
aclIntArray	用于表示一个int64_t类型的数组对象，数据一般放在host侧。该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common_types。
aclFloatArray	用于表示一个fp32类型的数组对象，数据一般放在host侧。该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common_types。
aclFp16Array	用于表示一个fp16类型的数组对象，数据一般放在host侧。该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common_types。
aclBf16Array	用于表示一个bf16类型的数组对象，数据一般放在host侧。该类定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见common_types。
SmallVector	该类使用内部内存池实现vector容器，基础功能与C++标准库中std::vector容器相同，无需每次扩容都申请内存，避免影响性能。其定义的成员变量为私有类型，开发者无需关注，定义的成员函数参见small_vector。 op::FVector：本质是存储容量长度为8的SmallVector。 namespace op { template<typename T, size_t N = 8> using FVector = op::internal::SmallVector<T, N, op::internal::PoolAllocator<T>>; } op:Strides：本质是存储容量长度为25的FVector，元素类型int64_t，存储stride信息。 namespace op { constexpr uint64_t MAX_DIM_NUM = 25; using Strides = FVector<int64_t, MAX_DIM_NUM>; } op::ShapeVector：本质是存储容量长度为25的FVector，元素类型int64_t，存储shape信息。 namespace op { constexpr uint64_t MAX_DIM_NUM = 25; using ShapeVector = FVector<int64_t, MAX_DIM_NUM>; }	aclnn/opdev/small_vector.h
OpExecMode	用于表示算子运行模式的枚举类，定义参见OpExecMode。	aclnn/opdev/op_def.h
OpImplMode	用于表示算子精度模式的枚举类，定义参见OpImplMode。	aclnn/opdev/op_def.h

父主题： 单算子API执行相关接口