2026/9/18 20:15:59
FEATURED · 精选文章 
CANN opbase 算子日志接口实战OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON 参数列表大小校验报错指南【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase导读本文讲解 CANN opbase 算子库中面向算子与 aclnn 接口实现的日志上报宏OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON当算子的某个参数如dims、axes、actualSequenceLengthKV等列表型参数实际大小不合法、需要附带原因说明时用它一次性完成ERROR 级日志输出 EZ0038 错误码上报。读完本文你将掌握该宏的完整参数语义、在算子实现中的标准用法以及它底层如何串联日志记录DlogRecord与错误码上报REPORT_PREDEFINED_ERR_MSG的完整调用链并能正确区分它与不带原因的兄弟宏OP_LOGE_FOR_INVALID_LISTSIZE的适用场景。功能说明OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON用于记录并上报参数列表大小校验错误带原因。当算子的指定参数列表大小无效时输出ERROR 级别日志上报EZ0038错误码对应docs/zh/error_code/Operator-Errors/EZ0038-Invalid_Argument.md中定义的参数列表大小错误场景。该宏的典型适用对象是算子实现中接收列表/数组型参数如维度列表dims、坐标轴列表axes、序列长度列表等的合法性校验分支。与OP_LOGE_FOR_INVALID_LISTSIZE上报 EZ0025、带预期大小correctSize不同本宏不关心预期是多少而是让开发者直接通过reason参数描述出错原因适合预期值不易用单个字符串表达、或需要解释复杂约束的场景。函数原型OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON(entityName, paramName, incorrectSize, reason)该宏定义于 include/op_common/log/log.h仅供算子或 aclnn 实现内部使用头文件中明确标注此接口仅供算子或aclnn实现使用。调用前需要包含该日志头文件且工程依赖 opbase 公共库。参数说明参数名输入/输出说明entityName输入算子名称或 aclnn 接口名称支持 const char* 或 std::string 类型。paramName输入参数名称支持 const char* 或 std::string 类型。incorrectSize输入实际列表大小支持 const char* 或 std::string 类型。reason输入错误原因支持 const char* 或 std::string 类型。参数使用要点结合源码实现类型兼容性四个参数在宏内部都会被先构造为std::string见实现中的_safe_entityName_、_safe_paramName_、_safe_incorrectSize_、_safe_reason_临时变量因此传const char*、std::string乃至可隐式转换的字符串字面量均可incorrectSize 的格式化如果原始列表大小是整型需要先用std::to_string()转成字符串再传入这正是文档调用示例中std::to_string(listSize).c_str()的由来reason 的内容建议直接面向最终开发者展示建议写清楚约束条件与期望行为例如 When layout is TND, actualSequenceLengthKV must be input and contain one or more elements. 这类可读性强的原因描述。返回值说明无。约束说明无。该宏只负责记录日志与上报错误码不改变程序控制流——是否返回错误、返回什么错误码如ge::GRAPH_FAILED需要开发者在调用后自行处理参考下方调用示例中的return语句。调用示例关键代码示例如下仅供参考不支持直接拷贝运行。if (listSize maxListSize) { OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON(MyOp, dims, std::to_string(listSize).c_str(), exceeds max limit); return ge::GRAPH_FAILED; }示例解析MyOp为算子名实际开发中建议使用算子真实注册名或 aclnn 接口名便于日志检索dims为被校验的参数名std::to_string(listSize).c_str()将实际列表大小转为字符串exceeds max limit为自定义错误原因日志输出后随即return ge::GRAPH_FAILED终止校验失败路径保证报错与返回错误码成对出现。底层实现原理一条宏完成的日志 错误码双重上报从 log.h 源码 可以看到该宏实际展开为do { ... } while (0)包裹的语句块内部依次完成三件事#define OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON(entityName, paramName, incorrectSize, reason) \ do { \ std::string _safe_entityName_(entityName); \ std::string _safe_paramName_(paramName); \ std::string _safe_incorrectSize_(incorrectSize); \ std::string _safe_reason_(reason); \ OP_LOGE_LIBOPAPI_REPORT( \ _safe_entityName_.c_str(), \ Parameter %s of %s has incorrect element nums %s. Reason: %s., \ _safe_paramName_.c_str(), _safe_entityName_.c_str(), \ _safe_incorrectSize_.c_str(), _safe_reason_.c_str()); \ const std::vectorconst char* msgKey {paramName, op_name, incorrect_size, reason}; \ const std::vectorconst char* msgvalue {_safe_paramName_.c_str(), _safe_entityName_.c_str(), \ _safe_incorrectSize_.c_str(), _safe_reason_.c_str()}; \ REPORT_PREDEFINED_ERR_MSG(EZ0038, msgKey, msgvalue); \ } while (0)第 1 步参数安全化。先把四个入参分别拷贝到局部std::string避免外部参数在宏展开期间因表达式副作用或生命周期问题导致取值不一致。第 2 步ERROR 级日志输出。调用 OP_LOGE_LIBOPAPI_REPORT先通过CheckLogLevel(OP_MODULE_ID, DLOG_ERROR)判断模块OP_MODULE_ID 63的 ERROR 级日志是否使能使能后调用DlogRecord写日志日志前缀统一携带__FILE__、__LINE__、子模块名OP_SUBMOD_NAME默认为OPS_BASE、函数名__FUNCTION__、线程号Ops::Base::GetTid()内部通过syscall(__NR_gettid)获取以及OpName:[...]消息体固定为Parameter %s of %s has incorrect element nums %s. Reason: %s.四个占位符依次对应 paramName、entityName、incorrectSize、reason。第 3 步EZ0038 错误码上报。通过REPORT_PREDEFINED_ERR_MSG(EZ0038, msgKey, msgvalue)将结构化键值对paramName、op_name、incorrect_size、reason上报给上层错误码框架使错误能被框架统一捕获、归集与呈现。错误码 EZ0038 的完整定义配套错误码文档 docs/zh/error_code/Operator-Errors/EZ0038-Invalid_Argument.md 给出了报错格式与真实示例Parameter %s of %s has incorrect element nums %s. Reason: %s.真实报错示例Parameter actualSequenceLengthKV of FusedInferAttentionScore has incorrect element nums 0. Reason: When layout is TND, actualSequenceLengthKV must be input and contain one or more elements.对应解决方法检查列表大小是否正确即核对传入的列表型参数的元素个数是否满足算子约束。与兄弟宏 OP_LOGE_FOR_INVALID_LISTSIZE 的对比与选型同一族接口中还提供了不带原因、但带预期大小的版本 OP_LOGE_FOR_INVALID_LISTSIZE上报 EZ0025二者对比如下对比项OP_LOGE_FOR_INVALID_LISTSIZEOP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON上报错误码EZ0025EZ0038第 4 个参数correctSize预期列表大小reason错误原因描述日志消息... has incorrect element nums %s. It should be %s.... has incorrect element nums %s. Reason: %s.适用场景预期大小单一、可明确写出如必须为 1约束复杂、需要解释原因如与 layout 相关的条件性约束选型建议当校验规则是必须等于某固定值时优先用 EZ0025 版本日志自带期望值便于排查当校验失败原因是条件性的如某种布局下必须非空或期望值难以用单个数字表达时用本文的 EZ0038 版本携带 reason。使用场景与最佳实践列表型参数校验分支对dims、axes、actualSequenceLengthKV等元素个数敏感的列表/向量参数在获取GetSize()或等价接口后先做大小校验失败即调用本宏日志与返回成对出现宏本身不中断执行务必在宏后紧跟return ge::GRAPH_FAILED或算子约定的错误返回避免报错后继续执行错误原因可读性reason是最终面向使用者的文本建议采用约束条件 期望行为句式参考 EZ0038 文档中的 FusedInferAttentionScore 示例避免空泛表述日志可检索性entityName使用真实算子名/aclnn 接口名配合日志前缀中的OpName、文件行号、函数名与线程号可快速定位到具体算子的校验点同类接口互相配合除了列表大小opbase 还提供了形状OP_LOGE_FOR_INVALID_SHAPE*、dtypeOP_LOGE_FOR_INVALID_DTYPE*、formatOP_LOGE_FOR_INVALID_FORMAT*、数值OP_LOGE_FOR_INVALID_VALUE*、Tensor 个数OP_LOGE_FOR_INVALID_TENSORNUMS*等一整套 EZ0001-EZ0038 族错误宏均定义于 include/op_common/log/log.h校验风格可保持一致详见 log 接口索引 与 op_common 接口总览。相关资源宏定义与注释include/op_common/log/log.h底层日志宏实现include/op_common/log/log.hEZ0038 错误码说明docs/zh/error_code/Operator-Errors/EZ0038-Invalid_Argument.md无原因版本接口docs/zh/api/op_common/log/OP_LOGE_FOR_INVALID_LISTSIZE.mdlog 接口完整索引docs/zh/api/op_common/log/log.md【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CANN opbase 算子日志接口实战：OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON 参数列表大小校验报错指南
CANN opbase 算子日志接口实战OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON 参数列表大小校验报错指南【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase导读本文讲解 CANN opbase 算子库中面向算子与 aclnn 接口实现的日志上报宏OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON当算子的某个参数如dims、axes、actualSequenceLengthKV等列表型参数实际大小不合法、需要附带原因说明时用它一次性完成ERROR 级日志输出 EZ0038 错误码上报。读完本文你将掌握该宏的完整参数语义、在算子实现中的标准用法以及它底层如何串联日志记录DlogRecord与错误码上报REPORT_PREDEFINED_ERR_MSG的完整调用链并能正确区分它与不带原因的兄弟宏OP_LOGE_FOR_INVALID_LISTSIZE的适用场景。功能说明OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON用于记录并上报参数列表大小校验错误带原因。当算子的指定参数列表大小无效时输出ERROR 级别日志上报EZ0038错误码对应docs/zh/error_code/Operator-Errors/EZ0038-Invalid_Argument.md中定义的参数列表大小错误场景。该宏的典型适用对象是算子实现中接收列表/数组型参数如维度列表dims、坐标轴列表axes、序列长度列表等的合法性校验分支。与OP_LOGE_FOR_INVALID_LISTSIZE上报 EZ0025、带预期大小correctSize不同本宏不关心预期是多少而是让开发者直接通过reason参数描述出错原因适合预期值不易用单个字符串表达、或需要解释复杂约束的场景。函数原型OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON(entityName, paramName, incorrectSize, reason)该宏定义于 include/op_common/log/log.h仅供算子或 aclnn 实现内部使用头文件中明确标注此接口仅供算子或aclnn实现使用。调用前需要包含该日志头文件且工程依赖 opbase 公共库。参数说明参数名输入/输出说明entityName输入算子名称或 aclnn 接口名称支持 const char* 或 std::string 类型。paramName输入参数名称支持 const char* 或 std::string 类型。incorrectSize输入实际列表大小支持 const char* 或 std::string 类型。reason输入错误原因支持 const char* 或 std::string 类型。参数使用要点结合源码实现类型兼容性四个参数在宏内部都会被先构造为std::string见实现中的_safe_entityName_、_safe_paramName_、_safe_incorrectSize_、_safe_reason_临时变量因此传const char*、std::string乃至可隐式转换的字符串字面量均可incorrectSize 的格式化如果原始列表大小是整型需要先用std::to_string()转成字符串再传入这正是文档调用示例中std::to_string(listSize).c_str()的由来reason 的内容建议直接面向最终开发者展示建议写清楚约束条件与期望行为例如 When layout is TND, actualSequenceLengthKV must be input and contain one or more elements. 这类可读性强的原因描述。返回值说明无。约束说明无。该宏只负责记录日志与上报错误码不改变程序控制流——是否返回错误、返回什么错误码如ge::GRAPH_FAILED需要开发者在调用后自行处理参考下方调用示例中的return语句。调用示例关键代码示例如下仅供参考不支持直接拷贝运行。if (listSize maxListSize) { OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON(MyOp, dims, std::to_string(listSize).c_str(), exceeds max limit); return ge::GRAPH_FAILED; }示例解析MyOp为算子名实际开发中建议使用算子真实注册名或 aclnn 接口名便于日志检索dims为被校验的参数名std::to_string(listSize).c_str()将实际列表大小转为字符串exceeds max limit为自定义错误原因日志输出后随即return ge::GRAPH_FAILED终止校验失败路径保证报错与返回错误码成对出现。底层实现原理一条宏完成的日志 错误码双重上报从 log.h 源码 可以看到该宏实际展开为do { ... } while (0)包裹的语句块内部依次完成三件事#define OP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON(entityName, paramName, incorrectSize, reason) \ do { \ std::string _safe_entityName_(entityName); \ std::string _safe_paramName_(paramName); \ std::string _safe_incorrectSize_(incorrectSize); \ std::string _safe_reason_(reason); \ OP_LOGE_LIBOPAPI_REPORT( \ _safe_entityName_.c_str(), \ Parameter %s of %s has incorrect element nums %s. Reason: %s., \ _safe_paramName_.c_str(), _safe_entityName_.c_str(), \ _safe_incorrectSize_.c_str(), _safe_reason_.c_str()); \ const std::vectorconst char* msgKey {paramName, op_name, incorrect_size, reason}; \ const std::vectorconst char* msgvalue {_safe_paramName_.c_str(), _safe_entityName_.c_str(), \ _safe_incorrectSize_.c_str(), _safe_reason_.c_str()}; \ REPORT_PREDEFINED_ERR_MSG(EZ0038, msgKey, msgvalue); \ } while (0)第 1 步参数安全化。先把四个入参分别拷贝到局部std::string避免外部参数在宏展开期间因表达式副作用或生命周期问题导致取值不一致。第 2 步ERROR 级日志输出。调用 OP_LOGE_LIBOPAPI_REPORT先通过CheckLogLevel(OP_MODULE_ID, DLOG_ERROR)判断模块OP_MODULE_ID 63的 ERROR 级日志是否使能使能后调用DlogRecord写日志日志前缀统一携带__FILE__、__LINE__、子模块名OP_SUBMOD_NAME默认为OPS_BASE、函数名__FUNCTION__、线程号Ops::Base::GetTid()内部通过syscall(__NR_gettid)获取以及OpName:[...]消息体固定为Parameter %s of %s has incorrect element nums %s. Reason: %s.四个占位符依次对应 paramName、entityName、incorrectSize、reason。第 3 步EZ0038 错误码上报。通过REPORT_PREDEFINED_ERR_MSG(EZ0038, msgKey, msgvalue)将结构化键值对paramName、op_name、incorrect_size、reason上报给上层错误码框架使错误能被框架统一捕获、归集与呈现。错误码 EZ0038 的完整定义配套错误码文档 docs/zh/error_code/Operator-Errors/EZ0038-Invalid_Argument.md 给出了报错格式与真实示例Parameter %s of %s has incorrect element nums %s. Reason: %s.真实报错示例Parameter actualSequenceLengthKV of FusedInferAttentionScore has incorrect element nums 0. Reason: When layout is TND, actualSequenceLengthKV must be input and contain one or more elements.对应解决方法检查列表大小是否正确即核对传入的列表型参数的元素个数是否满足算子约束。与兄弟宏 OP_LOGE_FOR_INVALID_LISTSIZE 的对比与选型同一族接口中还提供了不带原因、但带预期大小的版本 OP_LOGE_FOR_INVALID_LISTSIZE上报 EZ0025二者对比如下对比项OP_LOGE_FOR_INVALID_LISTSIZEOP_LOGE_FOR_INVALID_LISTSIZE_WITH_REASON上报错误码EZ0025EZ0038第 4 个参数correctSize预期列表大小reason错误原因描述日志消息... has incorrect element nums %s. It should be %s.... has incorrect element nums %s. Reason: %s.适用场景预期大小单一、可明确写出如必须为 1约束复杂、需要解释原因如与 layout 相关的条件性约束选型建议当校验规则是必须等于某固定值时优先用 EZ0025 版本日志自带期望值便于排查当校验失败原因是条件性的如某种布局下必须非空或期望值难以用单个数字表达时用本文的 EZ0038 版本携带 reason。使用场景与最佳实践列表型参数校验分支对dims、axes、actualSequenceLengthKV等元素个数敏感的列表/向量参数在获取GetSize()或等价接口后先做大小校验失败即调用本宏日志与返回成对出现宏本身不中断执行务必在宏后紧跟return ge::GRAPH_FAILED或算子约定的错误返回避免报错后继续执行错误原因可读性reason是最终面向使用者的文本建议采用约束条件 期望行为句式参考 EZ0038 文档中的 FusedInferAttentionScore 示例避免空泛表述日志可检索性entityName使用真实算子名/aclnn 接口名配合日志前缀中的OpName、文件行号、函数名与线程号可快速定位到具体算子的校验点同类接口互相配合除了列表大小opbase 还提供了形状OP_LOGE_FOR_INVALID_SHAPE*、dtypeOP_LOGE_FOR_INVALID_DTYPE*、formatOP_LOGE_FOR_INVALID_FORMAT*、数值OP_LOGE_FOR_INVALID_VALUE*、Tensor 个数OP_LOGE_FOR_INVALID_TENSORNUMS*等一整套 EZ0001-EZ0038 族错误宏均定义于 include/op_common/log/log.h校验风格可保持一致详见 log 接口索引 与 op_common 接口总览。相关资源宏定义与注释include/op_common/log/log.h底层日志宏实现include/op_common/log/log.hEZ0038 错误码说明docs/zh/error_code/Operator-Errors/EZ0038-Invalid_Argument.md无原因版本接口docs/zh/api/op_common/log/OP_LOGE_FOR_INVALID_LISTSIZE.mdlog 接口完整索引docs/zh/api/op_common/log/log.md【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考  连接器：从 Project/Taskflow 到 DataFlow 血缘的完整映射指南)
