CANN opbase 图场景 ACLNN 同步执行接口 CANN_OPS_OPB_SYN_EXEC_ACLNN 深度解析

CANN opbase 图场景 ACLNN 同步执行接口 CANN_OPS_OPB_SYN_EXEC_ACLNN 深度解析【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbaseCANN opbase 为算子的 Host 侧执行提供了CANN_OPS_OPB_SYN_EXEC_ACLNN宏用于在图Graph执行场景中同步调用任意 ACLNN 单算子 API其内部串行完成xxxGetWorkspaceSize一阶段与xxx二阶段两步执行。本文以 CANN_OPS_OPB_SYN_EXEC_ACLNN.md 为主线结合 op_fallback.h 与 op_fallback_internal.h 的源码实现详解其原型、参数、返回语义、底层调用链以及与异步版本 CANN_OPS_OPB_ASYN_EXEC_ACLNN 的区别帮助算子开发者直接复用该通用执行通道。功能说明图场景的 ACLNN 同步执行入口CANN_OPS_OPB_SYN_EXEC_ACLNN是 Aclnn 接口在图场景的通用执行接口同步接口内部串行调用两阶段执行Prepare 阶段一阶段回调aclnnApiGetWorkspaceSize计算算子执行所需的 Workspace 大小Execute 阶段二阶段在分配好的 Workspace 与当前 Stream 上回调aclnnApi真正下发算子。两阶段在同一调用栈内串行完成调用返回时算子的执行已同步下发到设备 Stream同步语义体现在“二阶段注册与执行不交给 GE 异步框架而是当场调用”这一行为上因此适合在图 Pass、图优化或算子直调等需要立即拿到执行结果的场景使用。从接口列表文档 op_common_api_introduction.md 可知该宏与CANN_OPS_OPB_ASYN_EXEC_ACLNN同属op_graph分类所属头文件均为op_common/op_graph/op_fallback.h。函数原型CANN_OPS_OPB_SYN_EXEC_ACLNN(ctx, aclnnApi, ...)需要特别说明的是这是一个宏而非真正的 C 函数其定义位于 op_fallback.h属于fallback命名空间采用 GNU 语句表达式({ ... })实现。宏展开后会在调用点形成一个表达式其值即为执行结果GRAPH_SUCCESS或GRAPH_FAILED。该设计使它可以像普通函数一样参与赋值与判断auto apiRet CANN_OPS_OPB_SYN_EXEC_ACLNN(hostApiCtx, aclnnScatterList, ...);同时宏通过字符串化#aclnnApi将传入的 API 名称自动拼接出aclnnScatterListGetWorkspaceSize与aclnnScatterList两个符号名用于后续动态符号查找这是调用方只需传一个aclnnApi即可完成两阶段调用的关键机制。参数说明参数名输入/输出说明ctx输入算子执行上下文OpExecuteContext用于分配 Workspace 和获取 Stream。aclnnApi输入待回调执行的 ACLNN 算子 API 名称如aclnnScatterList。...输入算子输入、输出及属性参数支持gert::Tensor、gert::Tensor列表、标量、属性等类型。ctx算子执行上下文ctx是图执行框架传入的OpExecuteContext宏内部通过它完成三件核心事情见 op_fallback.hctx-MallocWorkspace(workspace_size)按一阶段算出的尺寸分配 Workspacectx-GetStream()获取当前算子所在的设备 Stream供二阶段执行使用ctx-FreeWorkspace()二阶段执行结束后释放 Workspace。aclnnApiACLNN 算子 API 名称必须是进程内已加载的 ACLNN 单算子 API 符号名。宏会在此基础上自动派生两个符号aclnnApiGetWorkspaceSize一阶段计算 WorkspaceaclnnApi二阶段实际执行。示例中使用的aclnnScatterList会派生aclnnScatterListGetWorkspaceSize与aclnnScatterList两个符号进行查找。变参算子输入、输出与属性变参支持的类型由 op_fallback_internal.h 中的ConvertTypes/ConvertType系列模板决定实际转换规则如下调用方传入类型GE 侧转换后类型ACLNN 侧说明const gert::Tensor*aclTensor*读取 shape/strides/数据类型/设备地址调用aclCreateTensor构造见ConvertType(const gert::Tensor*)std::vectorconst gert::Tensor*aclTensorList*逐元素转换为aclTensor后聚合为张量列表标量如 floataclScalar*目前ConvertScalarType支持 float 标量映射为ACL_FLOAT标量其他类型属性等原样透传通用模板T ConvertType(T value)直接返回自身gert::Tensor到aclTensor的转换还会完成数据类型映射GetConvertTypeDT_FLOAT → ACL_FLOAT、DT_BF16 → ACL_BF16、DT_BOOL → ACL_BOOL、DT_INT64 → ACL_INT64、DT_INT32 → ACL_INT32、DT_UINT64 → ACL_UINT64、DT_UINT32 → ACL_UINT32、DT_INT8 → ACL_INT8、DT_UINT8 → ACL_UINT8、DT_INT4 → ACL_INT4、DT_FLOAT8_E4M3FN → ACL_FLOAT8_E4M3FN、DT_FLOAT8_E5M2 → ACL_FLOAT8_E5M2、DT_FLOAT4_E2M1 → ACL_FLOAT4_E2M1、DT_FLOAT4_E1M2 → ACL_FLOAT4_E1M2、DT_FLOAT8_E8M0 → ACL_FLOAT8_E8M0、DT_HIFLOAT8 → ACL_HIFLOAT8、DT_COMPLEX64 → ACL_COMPLEX64、DT_DOUBLE → ACL_DOUBLE其余类型默认映射为ACL_FLOAT16见 op_fallback_internal.h。转换产生的aclTensor、aclScalar、aclTensorList对象会在二阶段执行后通过aclDestroyTensor、aclDestroyScalar、aclDestroyTensorList释放ReleaseConvertTypes避免内存泄漏。返回值说明返回int类型GRAPH_SUCCESS两阶段执行成功GRAPH_FAILED执行失败。从宏实现看以下任一情况都会导致返回GRAPH_FAILED动态符号查找失败GetWorkspaceSize、执行函数或ResetCacheThreadLocal任一为空见 op_fallback.h一阶段GetWorkspaceSize调用返回非 0L46-L50Workspace 分配失败MallocWorkspace返回nullptrL54-L58二阶段执行函数返回非 0L68-L72。宏定义中static auto ret GRAPH_SUCCESS;保证了默认成功、仅在出错分支被改写最终语句表达式(ret);作为整体表达式的值返回。调用示例以下示例取自 CANN_OPS_OPB_SYN_EXEC_ACLNN.md仅作关键代码展示不支持直接拷贝运行auto apiRet CANN_OPS_OPB_SYN_EXEC_ACLNN(hostApiCtx, aclnnScatterList, geTenserListVar, indices, update, mask, reduce, *axis); OP_CHECK_IF(apiRet ! GRAPH_SUCCESS, OP_LOGE(hostApiCtx-GetNodeName(), apiRet faild:%d, apiRet), return GRAPH_FAILED);逐行解读hostApiCtx图场景的OpExecuteContext宏内部将使用它分配 Workspace、获取 Stream 并在结束后释放 WorkspaceaclnnScatterListACLNN 单算子 API 名宏自动派生aclnnScatterListGetWorkspaceSize与aclnnScatterList两个符号geTenserListVarstd::vectorconst gert::Tensor*类型的张量列表示例中作为第一个输入会被转换为aclTensorList*indices, update, maskgert::Tensor类型输入逐个转换为aclTensor*reduce算子属性或标量参数按类型原样透传或转换为标量*axis标量属性解引用后传入最终作为二阶段参数的一部分传给 ACLNN API返回值检查OP_CHECK_IF是 op_common log 模块的条件检查宏见 op_common/log/log.h当apiRet ! GRAPH_SUCCESS时打印OP_LOGE错误日志日志 TAG 为节点名hostApiCtx-GetNodeName()并执行return GRAPH_FAILED;。底层实现原理宏内部的完整调用链CANN_OPS_OPB_SYN_EXEC_ACLNN的实现op_fallback.h可拆解为以下步骤理解这条链路有助于排查图场景 ACLNN 执行问题1. 动态符号查找GetOpApiFuncAddr宏首次执行时通过GetOpApiFuncAddr按固定优先级查找三个符号ResetCacheThreadLocal、aclnnApiGetWorkspaceSize、aclnnApi见 op_fallback_internal.h先尝试从libcust_opapi.so自定义算子 API 库加载再从libopapi.so加载若两者都未命中则遍历libopapi_math.so、libopapi_nn.so、libopapi_cv.so、libopapi_transformer.so、libopapi_oam.so、libopapi_ras.so六个领域库逐一dlsymGetAclnnAddrByApiName。库句柄在进程生命周期内只加载一次并缓存后续调用只做符号查找避免重复dlopen开销。任一符号缺失都会打OP_LOGE日志并返回GRAPH_FAILED。2. 重置线程本地缓存通过动态查找到的ResetCacheThreadLocal函数指针执行ResetCacheThreadLocalFunc()L37-L38用于清理 ACLNN 线程本地缓存保证本次调用的参数缓存干净。3. 参数转换与一阶段调用构造workspace_size与executor两个输出变量的地址随变参一起经ConvertTypes完成类型转换gert::Tensor → aclTensor等用ConvertToOpApiFunc将查到的GetWorkspaceSize地址按转换后的参数类型序列重解释为函数指针再通过元组展开call调用一阶段得到 Workspace 大小L43-L45。4. Workspace 分配与 Stream 获取若workspace_size 0通过ctx-MallocWorkspace分配设备侧 Workspace失败即返回GRAPH_FAILED通过ctx-GetStream()取得当前aclrtStreamL60。5. 二阶段同步执行与资源释放构造 lambdaacl_call将opApiFuncAddr重解释为int (*)(void*, uint64_t, aclOpExecutor*, const aclrtStream)并立即调用即“同步执行”的本质——二阶段在当前线程栈内当场回调不注册给 GE 异步调度L61-L74执行结束后依次ReleaseConvertTypes销毁转换产生的 ACLNN 对象与ctx-FreeWorkspace()释放 Workspace二阶段返回非 0 时打印日志并返回GRAPH_FAILED。与异步版本 CANN_OPS_OPB_ASYN_EXEC_ACLNN 的对比op_graph 分类下提供同步与异步两个执行通道核心差异在于二阶段的归宿对比项CANN_OPS_OPB_SYN_EXEC_ACLNNCANN_OPS_OPB_ASYN_EXEC_ACLNN一阶段GetWorkspaceSize当场串行调用当场调用二阶段aclnnApi当场同步回调执行注册给 GE 的 context由框架异步执行Workspace 管理MallocWorkspace分配、执行后FreeWorkspacectx-SetWorkspaceSizes({workspace_size})设置大小交由框架分配参数生命周期执行完立即ReleaseConvertTypes释放构造OpApiParams并ctx-SetOpApiParamsWithDefaultDeleter托管由默认删除器延迟释放返回语义GRAPH_SUCCESS表示执行成功GRAPH_SUCCESS仅表示 Prepare 阶段准备成功二阶段尚未执行异步版本将转换后的参数收集到OpApiParams含converted_params、executor、op_api_func并注册到 context二阶段交给 GE 在合适的时机异步下发适合与图执行框架深度融合的场景同步版本则适合需要“调用返回即完成下发”的确定性执行路径。两版宏均定义于 op_fallback.h使用方式参数与返回值检查保持一致。约束与使用建议原文档约束说明为“无”即宏本身对输入参数的类型与数量没有额外限制凡是 ACLNN 单算子 API 支持的参数形态张量、张量列表、标量、属性均可直接传入使用前提是进程内已加载对应 ACLNN 算子的libopapi 系列动态库且符号aclnnApi与aclnnApiGetWorkspaceSize可被dlsym找到否则宏会打印aclnnfallback相关错误日志并返回GRAPH_FAILED宏依赖 GNU 语句表达式特性需在支持该扩展的编译环境如 GCC/Clang下使用调用前需按实际需要 include 头文件 op_fallback.h其内部已包含aclnn/aclnn_base.h、exe_graph/runtime/op_execute_context.h、exe_graph/runtime/tensor.h及 log 头文件op_common/log/log.h一般无需重复 include 这些依赖示例代码仅供理解调用方式实际使用时请结合具体算子 API 的参数顺序构造变参列表并按需进行返回值检查与日志打印。相关资源CANN_OPS_OPB_SYN_EXEC_ACLNN 接口文档本文关联文档CANN_OPS_OPB_ASYN_EXEC_ACLNN 异步版本文档宏定义实现同步/异步两版宏的完整源码参数转换与符号查找内部实现GetOpApiFuncAddr、ConvertTypes、GetConvertType等支撑函数op_graph 分类索引op_graph 接口文档入口op_common 接口总览op_graph 分类及所属头文件说明【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考