CANN opbase 算子开发公共宏与基础类完全指南从 INFER_SHAPE 到 ADD_TO_LAUNCHER_LIST 的 aclnn 算子编排实战【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbaseCANN opbase算子库基础框架库为开发者提供了一套以宏与基础类为核心的算子开发范式用于在 aclnn 两级 APIaclnn_Xxx_GetWorkspaceSize与aclnn_Xxx_中完成算子注册、形状推导、任务入队、参数封装与耗时统计。本文以 docs/en/api/nnopbase/opdev/common_macros_and_classes/common_macros_and_classes.md 所列的 21 个公共宏与类为骨架结合仓库源码逐一定义、逐条讲解使用约束并给出可直接复用的代码示例。读完本文你将能够熟练用OP_INPUT/OP_OUTPUT/OP_ATTR等参数宏描述算子签名用INFER_SHAPEADD_TO_LAUNCHER_LIST_AICORE/ADD_TO_LAUNCHER_LIST_AICPU完成 AI Core 与 AI CPU 两类算子的任务编排用L0_DFX/L2_DFX_PHASE_1/L2_DFX_PHASE_2接入两级 API 的 Profiling 统计并通过OpExecMode与OpImplMode精确控制算子执行与精度模式。一、宏与类全景一张图看懂 21 个公共设施公共宏与类按职责可划分为四组各自服务于 aclnn 算子开发流水线的不同阶段分组宏/类职责算子参数描述OP_INPUT、OP_OUTPUT、OP_ATTR、OP_WORKSPACE、OP_OUTSHAPE、OP_OPTION、OP_MODE、OP_EMPTY_ARG、OP_ATTR_NAMES将算子输入、输出、属性、工作区、输出形状等参数统一封装为 OpArg供后续推导与入队使用任务编排INFER_SHAPE、ADD_TO_LAUNCHER_LIST_AICORE、ADD_TO_LAUNCHER_LIST_AICPU、CREATE_EXECUTOR、OP_TYPE_REGISTER完成 L0 算子类型注册、形状推导、创建执行器并生成 AI Core / AI CPU 执行任务两级 API 的 ProfilingL0_DFX、L2_DFX_PHASE_1、L2_DFX_PHASE_2、DFX_IN、DFX_OUT在 L0 API 与 L2 两级 API 的入口采集耗时统计并打印入参模式枚举OpExecMode、OpImplMode定义算子执行模式与实现精度模式的位掩码枚举供OP_MODE/OP_OPTION引用从源码结构看上述设施的核心定义分布在四个头文件中参数封装宏在 op_arg_def.h形状推导与 AI Core 入队宏在 make_op_executor.hL0/L2 的 DFX 宏与算子类型注册宏在 op_dfx.hAI CPU 入队宏与OP_ATTR_NAMES在 aicpu_task.h。后续各节将逐组展开。二、算子参数封装宏把算子签名翻译成 OpArgADD_TO_LAUNCHER_LIST_AICORE、ADD_TO_LAUNCHER_LIST_AICPU与INFER_SHAPE都接收以op_args...形式传入的参数描述宏这些描述宏的实际定义见 op_arg_def.h为#define OP_INPUT(x...) op::OpInput(std::make_tuple(x)) #define OP_OUTPUT(x...) op::OpOutput(std::make_tuple(x)) #define OP_ATTR(x...) op::OpAttr(std::make_tuple(x)) #define OP_WORKSPACE(x...) op::OpWorkspace(std::make_tuple(x)) #define OP_OUTSHAPE(x...) op::OpOutshape(std::tupleaclTensor*, uint64_t(x)) #define OP_OPTION(x...) op::OpOption(std::make_tuple(x)) #define OP_EMPTY_ARG op::EMPTY_OP_ARG #define OP_MODE(x...) op::OpMode(std::make_tuple(x))可以看到每个宏本质上是用std::make_tuple把参数列表打包进对应的 OpArg 包装类型最终汇入OpArgContextOpArgContext的实现在 op_arg_def.cpp 中维护例如AppendOpWorkspaceArg会先检查是否已存在 workspace 参数再追加避免重复。OP_INPUT 与 OP_OUTPUT封装输入输出张量OP_INPUT(x...)封装算子的输入支持aclTensor与aclTensorList两种类型OP_OUTPUT(x...)封装算子的输出同样支持aclTensor与aclTensorList。// 封装 Add 算子的两个输入 self 与 other OP_INPUT(self, other); // 封装 Add 算子的输出 addOut OP_OUTPUT(addOut);重要限制若算子包含既非aclTensor也非aclTensorList的输入或输出参数必须调用aclOpExecutor::ConvertToTensor将参数转换为aclTensor后再封装否则无法进入统一的张量处理流程。OP_ATTR 与 OP_ATTR_NAMES属性参数的两种封装方式OP_ATTR(x...)封装算子原型中的属性参数例如// 封装算子的两个属性dstType 与 sqrtMode OP_ATTR(dstType, sqrtMode);OP_ATTR_NAMES则专用于 AI CPU 算子用于封装属性的名称列表其类型为::op::FVectorstd::string见 aicpu_task.h默认值为空FVector即OP_ATTR_NAMES()// 封装 AI CPU 算子的三个属性名Tindices、T、use_locking OP_ATTR_NAMES({Tindices, T, use_locking});二者的分工差异值得注意AI Core 算子通过ADD_TO_LAUNCHER_LIST_AICORE入队时不需要显式传属性名而 AI CPU 算子通过ADD_TO_LAUNCHER_LIST_AICPU入队时必须额外提供attrNames参数这与 AI CPU 算子属性在任务侧按名称检索的机制有关。OP_WORKSPACE显式声明算子工作区OP_WORKSPACE(x...)封装算子显式指定的 workspace 参数表示算子计算所需的设备内存支持aclTensor与aclTensorList类型。从 op_arg_def.cpp 的实现看workspace 参数会以OPARG_ACLTENSOR_LIST类型的 OpArg 追加到OP_WORKSPACE_ARG槽位且同一上下文只允许一个 workspace 参数存在。// 封装算子的 workspace 参数 a OP_WORKSPACE(a);OP_OUTSHAPE动态输出形状回写OP_OUTSHAPE(x...)用于存储算子输出形状的 aclTensor典型场景如 NonZero 这类输出形状依赖输入数据的算子。其参数由两部分构成第一个参数是用于存放输出张量形状的 aclTensoroutShapeTensor第二个参数是需要更新形状的输出的索引。格式限制一次只能更新一个输出张量的形状outShapeTensor 的形状为(9 * 待更新张量数量,)每个输出张量的形状占用 9 个元素第 1 个元素表示维度数其余 8 个元素依次表示各维度取值。// 将输出形状存入 outShapeTensor并更新索引为 0 的输出张量形状 OP_OUTSHAPE({outShapeTensor, 0});若需同时更新多个输出张量的形状例如索引 0、3、4在 Host 侧统一分配INT64类型、FORMAT_ND格式的 outShapeTensor并多次调用OP_OUTSHAPE// Host 侧3 个输出张量需要更新故分配 27 个元素 Shape outShapeShape{27}; auto outShapeTensor executor-AllocTensor(outShapeShape, DataType::DT_INT64, Format::FORMAT_ND); aclnnStatus ret ADD_TO_LAUNCHER_LIST_AICORE( xxx, OP_INPUT(...), OP_OUTPUT(...), OP_ATTR(...), OP_OUTSHAPE({outShapeTensor, 0}), OP_OUTSHAPE({outShapeTensor, 3}), OP_OUTSHAPE({outShapeTensor, 4}), );内核侧按 9 元素一组回写形状信息第 0/9/18 位写维度数其后写各维数值// Kernel 侧依次写三个输出张量的形状 __aicore__ inline void CopyOutShape(uint64_t dimNums1, uint64_t *dimNums2, uint64_t dimNums3) { LocalTensoruint64_t shapeTensor shapeBuf_.Getuint64_t(); shapeTensor.SetValue(0, 1); // 第一个输出张量的维度信息 shapeTensor.SetValue(1, dimNums1); // 第一个输出张量第一维的形状值 shapeTensor.SetValue(9, 1); // 第二个输出张量的维度信息 shapeTensor.SetValue(10, *(dimNums2)); // 第二个输出张量第一维的形状值 shapeTensor.SetValue(11, *(dimNums21)); // 第二个输出张量第二维的形状值 shapeTensor.SetValue(18, 1); // 第三个输出张量的维度信息 shapeTensor.SetValue(19, dimNums3); // 第三个输出张量第一维的形状值 ... DataCopyPad(...); }OP_OPTION 与 OP_MODE精度模式与执行模式OP_OPTION(x...)封装算子的实现精度模式取值见 OpImplModeOP_MODE(x...)封装算子的执行模式决定计算过程中是否启用 HF32 数据类型取值见 OpExecMode默认值为0Default模式。// 将算子精度模式设为高精度模式 OP_OPTION(IMPL_MODE_HIGH_PRECISION); // 封装算子执行模式为默认模式 OP_MODE(OP_EXEC_MODE_DEFAULT);OP_EMPTY_ARG占位空参数OP_EMPTY_ARG无参数用于在算子没有某个可选参数槽位时显式占位例如有输入而无属性时用于对齐参数槽位。OP_EMPTY_ARG三、任务编排宏形状推导、注册与入队OP_TYPE_REGISTERL0 算子类型注册OP_TYPE_REGISTER(kernelName)用于注册一个 L0 算子生成算子名与对应的TypeID必须放在 L0 API 的开头。从 op_dfx.h 的实现看该宏会生成名为kernelName##OpTypeId()的内联函数内部通过op::GenOpTypeId(#kernelName, ...)为算子分配全局唯一的 TypeID并基于算子名生成内部资源描述被宏展开后生成的KERNEL_NAME##OpTypeId()正是INFER_SHAPE与ADD_TO_LAUNCHER_LIST_AICORE取算子类型 ID 的入口。namespace l0op { OP_TYPE_REGISTER(Abs); ... }CREATE_EXECUTOR创建 UniqueExecutorCREATE_EXECUTOR()创建UniqueExecutor对象它是aclOpExecutor的工厂类。源码实现为#define CREATE_EXECUTOR() UniqueExecutor(__func__)见 make_op_executor.h即以当前函数名L2 API 名构造 UniqueExecutor。// 创建 executor auto uniqueExecutor CREATE_EXECUTOR();使用限制该宏必须在aclOpExecutor使用之前调用在 L2 第一阶段 APIaclnn_Xxx_GetWorkspaceSize返回前必须调用ReleaseTo将 executor 移交给 L2 API 入参中的 executor才能让第二阶段 API 复用同一个执行上下文。INFER_SHAPE运行形状推导INFER_SHAPE(KERNEL_NAME, op_args...)对指定算子执行InferShape推导输出形状。其源码实现见 make_op_executor.h会先通过GetOpArgContext(op_args)汇总参数然后调用InferShape(KERNEL_NAME##OpTypeId(), ...)分别传入OP_INPUT_ARG、OP_OUTPUT_ARG、OP_ATTR_ARG三组 OpArg若上下文为空则返回ACLNN_ERR_PARAM_NULLPTR。// 推导 BatchMatMulV3 算子的输出形状 INFER_SHAPE(BatchMatMulV3, OP_INPUT(x1, x2, bias, nullptr), OP_OUTPUT(bmmOut), OP_ATTR(adjX1, adjX2, offsetX, opImplModeEnum));使用限制若算子需要INFER_SHAPE该宏必须放在ADD_TO_LAUNCHER_LIST_AICORE之前调用对于 AI CPU 算子则放在ADD_TO_LAUNCHER_LIST_AICPU之前。宏内部实际会依次展开并调用下列参数宏OP_INPUT(x...) OP_OUTPUT(x...) OP_ATTR(x...) OP_WORKSPACE(x...) OP_OUTSHAPE(x...) OP_OPTION(x...) OP_EMPTY_ARG OP_MODE(x...)ADD_TO_LAUNCHER_LIST_AICORE创建 AI Core 执行任务ADD_TO_LAUNCHER_LIST_AICORE(KERNEL_NAME, op_args...)创建 AI Core 算子的执行任务并放入aclOpExecutor执行队列任务在第二阶段 APIaclnn_Xxx_被调用时真正执行。参数输入/输出说明KERNEL_NAME输入算子名例如Addop_args...输入算子参数包括 OP_INPUT、OP_OUTPUT 和 OP_ATTR 等源码实现见 make_op_executor.h会调用CreatAiCoreKernelLauncher(#KERNEL_NAME, KERNEL_NAME##OpTypeId(), executor, opArgCtx)完成 launcher 创建与入队。头文件中特别警告宏参数是右值且会被移动不要在参数中直接放置右值否则第二次使用时右值已为空。// 为 Add 算子创建执行任务Add 是算子名self 与 other 是输入addOut 是输出 ADD_TO_LAUNCHER_LIST_AICORE(Add, OP_INPUT(self, other), OP_OUTPUT(addOut));ADD_TO_LAUNCHER_LIST_AICPU创建 AI CPU 执行任务ADD_TO_LAUNCHER_LIST_AICPU(KERNEL_NAME, attrNames, opArgs...)创建 AI CPU 算子的执行任务与 AI Core 版本相比多出attrNames参数用于声明算子属性名。参数输入/输出说明KERNEL_NAME输入算子名例如AddattrNames输入算子属性名见 OP_ATTR_NAMESopArgs...输入算子参数源码实现见 aicpu_task.h调用CreatAicpuKernelLauncher(KERNEL_NAME##OpTypeId(), space, executor, attrNames, opArgCtx)其中space为AicpuTaskSpace类型的任务空间。宏内部会依次调用OP_ATTR_NAMES OP_INPUT(x...) OP_OUTPUT(x...) OP_ATTR(x...)// 为 IndexPut 算子创建执行任务accumulate 是属性名与属性参数selfRef、values、masks、indices 是输入out 是输出 ADD_TO_LAUNCHER_LIST_AICPU(IndexPut, OP_ATTR_NAMES({accumulate}), OP_INPUT(selfRef, values, masks, indices), OP_OUTPUT(out), OP_ATTR(accumulate));四、两级 API 的 DFX 宏Profiling 与入参打印DFX_IN 与 DFX_OUT封装两级 API 入参DFX_IN(...)与DFX_OUT(...)分别封装 L2 第一阶段 APIaclnn_Xxx_GetWorkspaceSize的输入参数与输出参数均为可变长参数。源码实现极为简洁见 op_dfx.h#define DFX_IN(...) std::make_tuple(__VA_ARGS__) #define DFX_OUT(...) std::make_tuple(__VA_ARGS__)// Add 算子的三个输入参数self、other、alpha DFX_IN(self, other, alpha); // Add 算子的输出参数out DFX_OUT(out);L2_DFX_PHASE_1 与 L2_DFX_PHASE_2L2 两级 API 的耗时统计L2_DFX_PHASE_1(APIName, IN, OUT)在 L2 第一阶段 API 开头调用采集该 API 的耗时统计并打印输入参数。APIName为 Host 侧 L2 API 名如aclnnAbsIN/OUT分别由 DFX_IN 与 DFX_OUT 封装。源码实现见 op_dfx.h包含三重动作先用static_assert(op::ValidDfxName(...))在编译期校验 API 名与函数名的匹配关系再调用CheckPhase1Params校验 executor 与 workspaceSize 参数失败即返回ACLNN_ERR_PARAM_NULLPTR并InitL2Phase1Context初始化上下文最后尝试从缓存中命中GetFromCache命中则直接返回ACLNN_SUCCESS从而跳过重复推导。// 采集 abs 算子 L2 第一阶段 API 的耗时并打印入参 L2_DFX_PHASE_1(aclnnAbs, DFX_IN(self), DFX_OUT(out));L2_DFX_PHASE_2(APIName)在 L2 第二阶段 APIaclnn_Xxx_开头调用同样通过static_assert校验名称并InitL2Phase2Context初始化上下文// 采集 abs 算子 L2 第二阶段 API 的耗时 L2_DFX_PHASE_2(aclnnAbs);使用限制两个宏都必须在对应 API 的最开头调用且L2_DFX_PHASE_1的输入参数必须与 L2 API 实参严格一致否则耗时统计可能不准确。L2_DFX_PHASE_1宏展开后内部调用#define DFX_IN(...) std::make_tuple(__VA_ARGS__) #define DFX_OUT(...) std::make_tuple(__VA_ARGS__)L0_DFXL0 API 的延迟统计L0_DFX(profilingName, ...)采集 L0 API 的延迟统计Profiling并打印输入参数。profilingName是 Host 侧 L0 API 名如AddAiCore...是该 L0 API 的可变长输入参数。源码实现见 op_dfx.h同样以static_assert校验名称、InitL0Context初始化上下文再通过L0_OP_PROF构造OpDfxGuard完成耗时采集与参数打印。// 采集 L0 API AddAiCore 的延迟统计并打印参数 L0_DFX(AddAiCore, self, other, addOut);使用限制三条红线L0_DFX必须放在 L0 函数的第一行位置不当会导致统计不准或未定义错误在 L0 函数中使用该宏时不要用花括号包裹宏否则同样可能导致统计不准或未定义错误禁止递归或嵌套调用使用了L0_DFX宏的 L0 API以避免延迟统计逻辑冲突。五、OpExecMode 与 OpImplMode执行模式与精度模式枚举OpExecMode算子执行模式OpExecMode枚举指示算子的运行模式定义如下enum class OpExecMode : uint32_t { // ExecMode 支持按位或运算 OP_EXEC_MODE_DEFAULT 0, OP_EXEC_MODE_HF32T 1, OP_EXEC_MODE_RESERVED 0xFFFFFFFF };OP_EXEC_MODE_DEFAULT0默认模式不启用 HF32OP_EXEC_MODE_HF32T1启用 HF32 数据类型参与计算OP_EXEC_MODE_RESERVED0xFFFFFFFF保留值。该枚举由 OP_MODE 引用且注释明确 ExecMode 支持按位或运算多个模式可通过位或组合。OpImplMode算子实现精度模式OpImplMode枚举指示算子的精度模式定义如下enum class OpImplMode : uint32_t { // ImplMode 支持按位或运算 IMPL_MODE_DEFAULT 0x1, IMPL_MODE_HIGH_PERFORMANCE 0x2, IMPL_MODE_HIGH_PRECISION 0x4, IMPL_MODE_SUPER_PERFORMANCE 0x8, IMPL_MODE_SUPPORT_OUT_OF_BOUND_INDEX 0x10, IMPL_MODE_ENABLE_FLOAT32_EXECUTION 0x20, IMPL_MODE_ENABLE_HI_FLOAT32_EXECUTION 0x40, IMPL_MODE_KEEP_FP16 0x80, IMPL_MODE_RESERVED 0xFFFFFFFF };各取值含义取值含义IMPL_MODE_DEFAULT0x1默认模式IMPL_MODE_HIGH_PERFORMANCE0x2高性能模式IMPL_MODE_HIGH_PRECISION0x4高精度模式IMPL_MODE_SUPER_PERFORMANCE0x8极致性能模式IMPL_MODE_SUPPORT_OUT_OF_BOUND_INDEX0x10支持越界索引IMPL_MODE_ENABLE_FLOAT32_EXECUTION0x20启用 Float32 执行IMPL_MODE_ENABLE_HI_FLOAT32_EXECUTION0x40启用高精度 Float32 执行IMPL_MODE_KEEP_FP160x80保持 FP16 精度IMPL_MODE_RESERVED0xFFFFFFFF保留值该枚举由 OP_OPTION 引用。由于取值采用 2 的幂且支持按位或运算可在一次OP_OPTION调用中组合多个模式例如同时声明高性能与支持越界索引。六、完整调用链L2 两级 API 中宏的协作次序将上述宏串起来一个典型 aclnn 算子的两级 API 骨架如下以 L0 函数内联调用为例namespace l0op { // L0 函数先注册算子类型再采集 L0 延迟 aclnnStatus AddL0(executor, self, other, addOut) { OP_TYPE_REGISTER(Add); // 生成 AddOpTypeId() 并注册 TypeID L0_DFX(AddAiCore, self, other, addOut); // 必须在第一行 ... } } // namespace l0op // L2 第一阶段 API aclnnStatus aclnn_Add_GetWorkspaceSize(self, other, alpha, addOut, executor, workspaceSize) { auto uniqueExecutor CREATE_EXECUTOR(); // 1. 创建 UniqueExecutor L2_DFX_PHASE_1(aclnnAdd, DFX_IN(self, other, alpha), DFX_OUT(addOut)); // 2. 采集耗时并查缓存 INFER_SHAPE(Add, OP_INPUT(self, other), OP_OUTPUT(addOut), OP_ATTR(alpha)); // 3. 推导输出形状 ADD_TO_LAUNCHER_LIST_AICORE(Add, OP_INPUT(self, other), OP_OUTPUT(addOut)); // 4. 创建 AI Core 执行任务 executor-ReleaseTo(...); // 5. 移交 executor return ACLNN_SUCCESS; } // L2 第二阶段 API aclnnStatus aclnn_Add(executor, workspaceAddr, workspaceSize, stream) { L2_DFX_PHASE_2(aclnnAdd); // 采集第二阶段耗时 ... }调用次序的硬性约束归纳如下OP_TYPE_REGISTER必须先于一切使用KERNEL_NAME##OpTypeId()的宏执行CREATE_EXECUTOR必须先于aclOpExecutor的任何使用且在 L2 第一阶段返回前ReleaseToINFER_SHAPE必须先于ADD_TO_LAUNCHER_LIST_AICORE/ADD_TO_LAUNCHER_LIST_AICPUL0_DFX必须位于 L0 函数第一行且不得被花括号包裹、不得嵌套L2_DFX_PHASE_1/L2_DFX_PHASE_2必须位于各自 API 的开头。七、易错点与最佳实践小结右值陷阱ADD_TO_LAUNCHER_LIST_AICORE的参数会被移动move第二次使用同一右值时内容已为空参数应使用左值变量形状回写格式OP_OUTSHAPE的 outShapeTensor 必须满足(9 * 张量数,)布局内核侧按 9 元素一组写入维度数写在组首非张量参数转换输入输出中混入非aclTensor/aclTensorList类型时先ConvertToTensor再封装DFX 位置敏感L0/L2 的 DFX 宏对位置极其敏感放错位置只表现为统计偏差或未定义行为调试成本高务必按规范放在函数首行模式按位或OpExecMode与OpImplMode均支持按位或组合模式时直接使用|连接各枚举值。以上宏与类的完整定义位于仓库头文件 op_arg_def.h、make_op_executor.h、op_dfx.h 与 aicpu_task.h 中开发者可结合源码对照阅读每个宏的独立参考文档均列于 common_macros_and_classes.md 索引页按需跳转查阅即可。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CANN opbase 算子开发公共宏与基础类完全指南从 INFER_SHAPE 到 ADD_TO_LAUNCHER_LIST 的 aclnn 算子编排实战【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbaseCANN opbase算子库基础框架库为开发者提供了一套以宏与基础类为核心的算子开发范式用于在 aclnn 两级 APIaclnn_Xxx_GetWorkspaceSize与aclnn_Xxx_中完成算子注册、形状推导、任务入队、参数封装与耗时统计。本文以 docs/en/api/nnopbase/opdev/common_macros_and_classes/common_macros_and_classes.md 所列的 21 个公共宏与类为骨架结合仓库源码逐一定义、逐条讲解使用约束并给出可直接复用的代码示例。读完本文你将能够熟练用OP_INPUT/OP_OUTPUT/OP_ATTR等参数宏描述算子签名用INFER_SHAPEADD_TO_LAUNCHER_LIST_AICORE/ADD_TO_LAUNCHER_LIST_AICPU完成 AI Core 与 AI CPU 两类算子的任务编排用L0_DFX/L2_DFX_PHASE_1/L2_DFX_PHASE_2接入两级 API 的 Profiling 统计并通过OpExecMode与OpImplMode精确控制算子执行与精度模式。一、宏与类全景一张图看懂 21 个公共设施公共宏与类按职责可划分为四组各自服务于 aclnn 算子开发流水线的不同阶段分组宏/类职责算子参数描述OP_INPUT、OP_OUTPUT、OP_ATTR、OP_WORKSPACE、OP_OUTSHAPE、OP_OPTION、OP_MODE、OP_EMPTY_ARG、OP_ATTR_NAMES将算子输入、输出、属性、工作区、输出形状等参数统一封装为 OpArg供后续推导与入队使用任务编排INFER_SHAPE、ADD_TO_LAUNCHER_LIST_AICORE、ADD_TO_LAUNCHER_LIST_AICPU、CREATE_EXECUTOR、OP_TYPE_REGISTER完成 L0 算子类型注册、形状推导、创建执行器并生成 AI Core / AI CPU 执行任务两级 API 的 ProfilingL0_DFX、L2_DFX_PHASE_1、L2_DFX_PHASE_2、DFX_IN、DFX_OUT在 L0 API 与 L2 两级 API 的入口采集耗时统计并打印入参模式枚举OpExecMode、OpImplMode定义算子执行模式与实现精度模式的位掩码枚举供OP_MODE/OP_OPTION引用从源码结构看上述设施的核心定义分布在四个头文件中参数封装宏在 op_arg_def.h形状推导与 AI Core 入队宏在 make_op_executor.hL0/L2 的 DFX 宏与算子类型注册宏在 op_dfx.hAI CPU 入队宏与OP_ATTR_NAMES在 aicpu_task.h。后续各节将逐组展开。二、算子参数封装宏把算子签名翻译成 OpArgADD_TO_LAUNCHER_LIST_AICORE、ADD_TO_LAUNCHER_LIST_AICPU与INFER_SHAPE都接收以op_args...形式传入的参数描述宏这些描述宏的实际定义见 op_arg_def.h为#define OP_INPUT(x...) op::OpInput(std::make_tuple(x)) #define OP_OUTPUT(x...) op::OpOutput(std::make_tuple(x)) #define OP_ATTR(x...) op::OpAttr(std::make_tuple(x)) #define OP_WORKSPACE(x...) op::OpWorkspace(std::make_tuple(x)) #define OP_OUTSHAPE(x...) op::OpOutshape(std::tupleaclTensor*, uint64_t(x)) #define OP_OPTION(x...) op::OpOption(std::make_tuple(x)) #define OP_EMPTY_ARG op::EMPTY_OP_ARG #define OP_MODE(x...) op::OpMode(std::make_tuple(x))可以看到每个宏本质上是用std::make_tuple把参数列表打包进对应的 OpArg 包装类型最终汇入OpArgContextOpArgContext的实现在 op_arg_def.cpp 中维护例如AppendOpWorkspaceArg会先检查是否已存在 workspace 参数再追加避免重复。OP_INPUT 与 OP_OUTPUT封装输入输出张量OP_INPUT(x...)封装算子的输入支持aclTensor与aclTensorList两种类型OP_OUTPUT(x...)封装算子的输出同样支持aclTensor与aclTensorList。// 封装 Add 算子的两个输入 self 与 other OP_INPUT(self, other); // 封装 Add 算子的输出 addOut OP_OUTPUT(addOut);重要限制若算子包含既非aclTensor也非aclTensorList的输入或输出参数必须调用aclOpExecutor::ConvertToTensor将参数转换为aclTensor后再封装否则无法进入统一的张量处理流程。OP_ATTR 与 OP_ATTR_NAMES属性参数的两种封装方式OP_ATTR(x...)封装算子原型中的属性参数例如// 封装算子的两个属性dstType 与 sqrtMode OP_ATTR(dstType, sqrtMode);OP_ATTR_NAMES则专用于 AI CPU 算子用于封装属性的名称列表其类型为::op::FVectorstd::string见 aicpu_task.h默认值为空FVector即OP_ATTR_NAMES()// 封装 AI CPU 算子的三个属性名Tindices、T、use_locking OP_ATTR_NAMES({Tindices, T, use_locking});二者的分工差异值得注意AI Core 算子通过ADD_TO_LAUNCHER_LIST_AICORE入队时不需要显式传属性名而 AI CPU 算子通过ADD_TO_LAUNCHER_LIST_AICPU入队时必须额外提供attrNames参数这与 AI CPU 算子属性在任务侧按名称检索的机制有关。OP_WORKSPACE显式声明算子工作区OP_WORKSPACE(x...)封装算子显式指定的 workspace 参数表示算子计算所需的设备内存支持aclTensor与aclTensorList类型。从 op_arg_def.cpp 的实现看workspace 参数会以OPARG_ACLTENSOR_LIST类型的 OpArg 追加到OP_WORKSPACE_ARG槽位且同一上下文只允许一个 workspace 参数存在。// 封装算子的 workspace 参数 a OP_WORKSPACE(a);OP_OUTSHAPE动态输出形状回写OP_OUTSHAPE(x...)用于存储算子输出形状的 aclTensor典型场景如 NonZero 这类输出形状依赖输入数据的算子。其参数由两部分构成第一个参数是用于存放输出张量形状的 aclTensoroutShapeTensor第二个参数是需要更新形状的输出的索引。格式限制一次只能更新一个输出张量的形状outShapeTensor 的形状为(9 * 待更新张量数量,)每个输出张量的形状占用 9 个元素第 1 个元素表示维度数其余 8 个元素依次表示各维度取值。// 将输出形状存入 outShapeTensor并更新索引为 0 的输出张量形状 OP_OUTSHAPE({outShapeTensor, 0});若需同时更新多个输出张量的形状例如索引 0、3、4在 Host 侧统一分配INT64类型、FORMAT_ND格式的 outShapeTensor并多次调用OP_OUTSHAPE// Host 侧3 个输出张量需要更新故分配 27 个元素 Shape outShapeShape{27}; auto outShapeTensor executor-AllocTensor(outShapeShape, DataType::DT_INT64, Format::FORMAT_ND); aclnnStatus ret ADD_TO_LAUNCHER_LIST_AICORE( xxx, OP_INPUT(...), OP_OUTPUT(...), OP_ATTR(...), OP_OUTSHAPE({outShapeTensor, 0}), OP_OUTSHAPE({outShapeTensor, 3}), OP_OUTSHAPE({outShapeTensor, 4}), );内核侧按 9 元素一组回写形状信息第 0/9/18 位写维度数其后写各维数值// Kernel 侧依次写三个输出张量的形状 __aicore__ inline void CopyOutShape(uint64_t dimNums1, uint64_t *dimNums2, uint64_t dimNums3) { LocalTensoruint64_t shapeTensor shapeBuf_.Getuint64_t(); shapeTensor.SetValue(0, 1); // 第一个输出张量的维度信息 shapeTensor.SetValue(1, dimNums1); // 第一个输出张量第一维的形状值 shapeTensor.SetValue(9, 1); // 第二个输出张量的维度信息 shapeTensor.SetValue(10, *(dimNums2)); // 第二个输出张量第一维的形状值 shapeTensor.SetValue(11, *(dimNums21)); // 第二个输出张量第二维的形状值 shapeTensor.SetValue(18, 1); // 第三个输出张量的维度信息 shapeTensor.SetValue(19, dimNums3); // 第三个输出张量第一维的形状值 ... DataCopyPad(...); }OP_OPTION 与 OP_MODE精度模式与执行模式OP_OPTION(x...)封装算子的实现精度模式取值见 OpImplModeOP_MODE(x...)封装算子的执行模式决定计算过程中是否启用 HF32 数据类型取值见 OpExecMode默认值为0Default模式。// 将算子精度模式设为高精度模式 OP_OPTION(IMPL_MODE_HIGH_PRECISION); // 封装算子执行模式为默认模式 OP_MODE(OP_EXEC_MODE_DEFAULT);OP_EMPTY_ARG占位空参数OP_EMPTY_ARG无参数用于在算子没有某个可选参数槽位时显式占位例如有输入而无属性时用于对齐参数槽位。OP_EMPTY_ARG三、任务编排宏形状推导、注册与入队OP_TYPE_REGISTERL0 算子类型注册OP_TYPE_REGISTER(kernelName)用于注册一个 L0 算子生成算子名与对应的TypeID必须放在 L0 API 的开头。从 op_dfx.h 的实现看该宏会生成名为kernelName##OpTypeId()的内联函数内部通过op::GenOpTypeId(#kernelName, ...)为算子分配全局唯一的 TypeID并基于算子名生成内部资源描述被宏展开后生成的KERNEL_NAME##OpTypeId()正是INFER_SHAPE与ADD_TO_LAUNCHER_LIST_AICORE取算子类型 ID 的入口。namespace l0op { OP_TYPE_REGISTER(Abs); ... }CREATE_EXECUTOR创建 UniqueExecutorCREATE_EXECUTOR()创建UniqueExecutor对象它是aclOpExecutor的工厂类。源码实现为#define CREATE_EXECUTOR() UniqueExecutor(__func__)见 make_op_executor.h即以当前函数名L2 API 名构造 UniqueExecutor。// 创建 executor auto uniqueExecutor CREATE_EXECUTOR();使用限制该宏必须在aclOpExecutor使用之前调用在 L2 第一阶段 APIaclnn_Xxx_GetWorkspaceSize返回前必须调用ReleaseTo将 executor 移交给 L2 API 入参中的 executor才能让第二阶段 API 复用同一个执行上下文。INFER_SHAPE运行形状推导INFER_SHAPE(KERNEL_NAME, op_args...)对指定算子执行InferShape推导输出形状。其源码实现见 make_op_executor.h会先通过GetOpArgContext(op_args)汇总参数然后调用InferShape(KERNEL_NAME##OpTypeId(), ...)分别传入OP_INPUT_ARG、OP_OUTPUT_ARG、OP_ATTR_ARG三组 OpArg若上下文为空则返回ACLNN_ERR_PARAM_NULLPTR。// 推导 BatchMatMulV3 算子的输出形状 INFER_SHAPE(BatchMatMulV3, OP_INPUT(x1, x2, bias, nullptr), OP_OUTPUT(bmmOut), OP_ATTR(adjX1, adjX2, offsetX, opImplModeEnum));使用限制若算子需要INFER_SHAPE该宏必须放在ADD_TO_LAUNCHER_LIST_AICORE之前调用对于 AI CPU 算子则放在ADD_TO_LAUNCHER_LIST_AICPU之前。宏内部实际会依次展开并调用下列参数宏OP_INPUT(x...) OP_OUTPUT(x...) OP_ATTR(x...) OP_WORKSPACE(x...) OP_OUTSHAPE(x...) OP_OPTION(x...) OP_EMPTY_ARG OP_MODE(x...)ADD_TO_LAUNCHER_LIST_AICORE创建 AI Core 执行任务ADD_TO_LAUNCHER_LIST_AICORE(KERNEL_NAME, op_args...)创建 AI Core 算子的执行任务并放入aclOpExecutor执行队列任务在第二阶段 APIaclnn_Xxx_被调用时真正执行。参数输入/输出说明KERNEL_NAME输入算子名例如Addop_args...输入算子参数包括 OP_INPUT、OP_OUTPUT 和 OP_ATTR 等源码实现见 make_op_executor.h会调用CreatAiCoreKernelLauncher(#KERNEL_NAME, KERNEL_NAME##OpTypeId(), executor, opArgCtx)完成 launcher 创建与入队。头文件中特别警告宏参数是右值且会被移动不要在参数中直接放置右值否则第二次使用时右值已为空。// 为 Add 算子创建执行任务Add 是算子名self 与 other 是输入addOut 是输出 ADD_TO_LAUNCHER_LIST_AICORE(Add, OP_INPUT(self, other), OP_OUTPUT(addOut));ADD_TO_LAUNCHER_LIST_AICPU创建 AI CPU 执行任务ADD_TO_LAUNCHER_LIST_AICPU(KERNEL_NAME, attrNames, opArgs...)创建 AI CPU 算子的执行任务与 AI Core 版本相比多出attrNames参数用于声明算子属性名。参数输入/输出说明KERNEL_NAME输入算子名例如AddattrNames输入算子属性名见 OP_ATTR_NAMESopArgs...输入算子参数源码实现见 aicpu_task.h调用CreatAicpuKernelLauncher(KERNEL_NAME##OpTypeId(), space, executor, attrNames, opArgCtx)其中space为AicpuTaskSpace类型的任务空间。宏内部会依次调用OP_ATTR_NAMES OP_INPUT(x...) OP_OUTPUT(x...) OP_ATTR(x...)// 为 IndexPut 算子创建执行任务accumulate 是属性名与属性参数selfRef、values、masks、indices 是输入out 是输出 ADD_TO_LAUNCHER_LIST_AICPU(IndexPut, OP_ATTR_NAMES({accumulate}), OP_INPUT(selfRef, values, masks, indices), OP_OUTPUT(out), OP_ATTR(accumulate));四、两级 API 的 DFX 宏Profiling 与入参打印DFX_IN 与 DFX_OUT封装两级 API 入参DFX_IN(...)与DFX_OUT(...)分别封装 L2 第一阶段 APIaclnn_Xxx_GetWorkspaceSize的输入参数与输出参数均为可变长参数。源码实现极为简洁见 op_dfx.h#define DFX_IN(...) std::make_tuple(__VA_ARGS__) #define DFX_OUT(...) std::make_tuple(__VA_ARGS__)// Add 算子的三个输入参数self、other、alpha DFX_IN(self, other, alpha); // Add 算子的输出参数out DFX_OUT(out);L2_DFX_PHASE_1 与 L2_DFX_PHASE_2L2 两级 API 的耗时统计L2_DFX_PHASE_1(APIName, IN, OUT)在 L2 第一阶段 API 开头调用采集该 API 的耗时统计并打印输入参数。APIName为 Host 侧 L2 API 名如aclnnAbsIN/OUT分别由 DFX_IN 与 DFX_OUT 封装。源码实现见 op_dfx.h包含三重动作先用static_assert(op::ValidDfxName(...))在编译期校验 API 名与函数名的匹配关系再调用CheckPhase1Params校验 executor 与 workspaceSize 参数失败即返回ACLNN_ERR_PARAM_NULLPTR并InitL2Phase1Context初始化上下文最后尝试从缓存中命中GetFromCache命中则直接返回ACLNN_SUCCESS从而跳过重复推导。// 采集 abs 算子 L2 第一阶段 API 的耗时并打印入参 L2_DFX_PHASE_1(aclnnAbs, DFX_IN(self), DFX_OUT(out));L2_DFX_PHASE_2(APIName)在 L2 第二阶段 APIaclnn_Xxx_开头调用同样通过static_assert校验名称并InitL2Phase2Context初始化上下文// 采集 abs 算子 L2 第二阶段 API 的耗时 L2_DFX_PHASE_2(aclnnAbs);使用限制两个宏都必须在对应 API 的最开头调用且L2_DFX_PHASE_1的输入参数必须与 L2 API 实参严格一致否则耗时统计可能不准确。L2_DFX_PHASE_1宏展开后内部调用#define DFX_IN(...) std::make_tuple(__VA_ARGS__) #define DFX_OUT(...) std::make_tuple(__VA_ARGS__)L0_DFXL0 API 的延迟统计L0_DFX(profilingName, ...)采集 L0 API 的延迟统计Profiling并打印输入参数。profilingName是 Host 侧 L0 API 名如AddAiCore...是该 L0 API 的可变长输入参数。源码实现见 op_dfx.h同样以static_assert校验名称、InitL0Context初始化上下文再通过L0_OP_PROF构造OpDfxGuard完成耗时采集与参数打印。// 采集 L0 API AddAiCore 的延迟统计并打印参数 L0_DFX(AddAiCore, self, other, addOut);使用限制三条红线L0_DFX必须放在 L0 函数的第一行位置不当会导致统计不准或未定义错误在 L0 函数中使用该宏时不要用花括号包裹宏否则同样可能导致统计不准或未定义错误禁止递归或嵌套调用使用了L0_DFX宏的 L0 API以避免延迟统计逻辑冲突。五、OpExecMode 与 OpImplMode执行模式与精度模式枚举OpExecMode算子执行模式OpExecMode枚举指示算子的运行模式定义如下enum class OpExecMode : uint32_t { // ExecMode 支持按位或运算 OP_EXEC_MODE_DEFAULT 0, OP_EXEC_MODE_HF32T 1, OP_EXEC_MODE_RESERVED 0xFFFFFFFF };OP_EXEC_MODE_DEFAULT0默认模式不启用 HF32OP_EXEC_MODE_HF32T1启用 HF32 数据类型参与计算OP_EXEC_MODE_RESERVED0xFFFFFFFF保留值。该枚举由 OP_MODE 引用且注释明确 ExecMode 支持按位或运算多个模式可通过位或组合。OpImplMode算子实现精度模式OpImplMode枚举指示算子的精度模式定义如下enum class OpImplMode : uint32_t { // ImplMode 支持按位或运算 IMPL_MODE_DEFAULT 0x1, IMPL_MODE_HIGH_PERFORMANCE 0x2, IMPL_MODE_HIGH_PRECISION 0x4, IMPL_MODE_SUPER_PERFORMANCE 0x8, IMPL_MODE_SUPPORT_OUT_OF_BOUND_INDEX 0x10, IMPL_MODE_ENABLE_FLOAT32_EXECUTION 0x20, IMPL_MODE_ENABLE_HI_FLOAT32_EXECUTION 0x40, IMPL_MODE_KEEP_FP16 0x80, IMPL_MODE_RESERVED 0xFFFFFFFF };各取值含义取值含义IMPL_MODE_DEFAULT0x1默认模式IMPL_MODE_HIGH_PERFORMANCE0x2高性能模式IMPL_MODE_HIGH_PRECISION0x4高精度模式IMPL_MODE_SUPER_PERFORMANCE0x8极致性能模式IMPL_MODE_SUPPORT_OUT_OF_BOUND_INDEX0x10支持越界索引IMPL_MODE_ENABLE_FLOAT32_EXECUTION0x20启用 Float32 执行IMPL_MODE_ENABLE_HI_FLOAT32_EXECUTION0x40启用高精度 Float32 执行IMPL_MODE_KEEP_FP160x80保持 FP16 精度IMPL_MODE_RESERVED0xFFFFFFFF保留值该枚举由 OP_OPTION 引用。由于取值采用 2 的幂且支持按位或运算可在一次OP_OPTION调用中组合多个模式例如同时声明高性能与支持越界索引。六、完整调用链L2 两级 API 中宏的协作次序将上述宏串起来一个典型 aclnn 算子的两级 API 骨架如下以 L0 函数内联调用为例namespace l0op { // L0 函数先注册算子类型再采集 L0 延迟 aclnnStatus AddL0(executor, self, other, addOut) { OP_TYPE_REGISTER(Add); // 生成 AddOpTypeId() 并注册 TypeID L0_DFX(AddAiCore, self, other, addOut); // 必须在第一行 ... } } // namespace l0op // L2 第一阶段 API aclnnStatus aclnn_Add_GetWorkspaceSize(self, other, alpha, addOut, executor, workspaceSize) { auto uniqueExecutor CREATE_EXECUTOR(); // 1. 创建 UniqueExecutor L2_DFX_PHASE_1(aclnnAdd, DFX_IN(self, other, alpha), DFX_OUT(addOut)); // 2. 采集耗时并查缓存 INFER_SHAPE(Add, OP_INPUT(self, other), OP_OUTPUT(addOut), OP_ATTR(alpha)); // 3. 推导输出形状 ADD_TO_LAUNCHER_LIST_AICORE(Add, OP_INPUT(self, other), OP_OUTPUT(addOut)); // 4. 创建 AI Core 执行任务 executor-ReleaseTo(...); // 5. 移交 executor return ACLNN_SUCCESS; } // L2 第二阶段 API aclnnStatus aclnn_Add(executor, workspaceAddr, workspaceSize, stream) { L2_DFX_PHASE_2(aclnnAdd); // 采集第二阶段耗时 ... }调用次序的硬性约束归纳如下OP_TYPE_REGISTER必须先于一切使用KERNEL_NAME##OpTypeId()的宏执行CREATE_EXECUTOR必须先于aclOpExecutor的任何使用且在 L2 第一阶段返回前ReleaseToINFER_SHAPE必须先于ADD_TO_LAUNCHER_LIST_AICORE/ADD_TO_LAUNCHER_LIST_AICPUL0_DFX必须位于 L0 函数第一行且不得被花括号包裹、不得嵌套L2_DFX_PHASE_1/L2_DFX_PHASE_2必须位于各自 API 的开头。七、易错点与最佳实践小结右值陷阱ADD_TO_LAUNCHER_LIST_AICORE的参数会被移动move第二次使用同一右值时内容已为空参数应使用左值变量形状回写格式OP_OUTSHAPE的 outShapeTensor 必须满足(9 * 张量数,)布局内核侧按 9 元素一组写入维度数写在组首非张量参数转换输入输出中混入非aclTensor/aclTensorList类型时先ConvertToTensor再封装DFX 位置敏感L0/L2 的 DFX 宏对位置极其敏感放错位置只表现为统计偏差或未定义行为调试成本高务必按规范放在函数首行模式按位或OpExecMode与OpImplMode均支持按位或组合模式时直接使用|连接各枚举值。以上宏与类的完整定义位于仓库头文件 op_arg_def.h、make_op_executor.h、op_dfx.h 与 aicpu_task.h 中开发者可结合源码对照阅读每个宏的独立参考文档均列于 common_macros_and_classes.md 索引页按需跳转查阅即可。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
