CANN opbase 算子参数值校验日志宏 OP_LOGE_FOR_INVALID_VALUE 使用指南

CANN opbase 算子参数值校验日志宏 OP_LOGE_FOR_INVALID_VALUE 使用指南【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase导读OP_LOGE_FOR_INVALID_VALUE是 CANN opbase 基础框架库为算子与 aclnn 接口实现提供的参数值校验日志宏用于在算子的某个参数取值与预期不符时输出 ERROR 级别日志并同步上报 EZ0024 预定义错误码。本指南围绕该宏的功能说明、函数原型、参数语义、底层实现与调用示例展开帮助算子开发者在宿主侧Host的参数合法性检查场景中用一行代码完成日志打印 错误码上报的标准化错误处理。功能说明在算子实现尤其是 Shape 推导、Tiling 计算等 Host 侧逻辑中经常需要对算子参数Attribute 或输入参数的取值范围、枚举值进行合法性校验。当校验失败时如果只写普通的printf或裸的OP_LOGE往往存在两个问题日志格式不统一、错误信息无法被上层框架结构化解析。OP_LOGE_FOR_INVALID_VALUE解决的就是这个问题它记录并上报参数值校验错误。当算子的指定参数值与预期不符时该宏会输出一条 ERROR 级别日志带文件名、行号、函数名、线程 ID、算子名等上下文信息通过REPORT_PREDEFINED_ERR_MSG(EZ0024, ...)上报 EZ0024 预定义错误码将参数名、算子名、错误值、正确值四个字段以键值对形式写入错误消息供上层框架解析与定位。该宏属于仅供算子或 aclnn 实现使用的接口声明与实现在 include/op_common/log/log.h 中。函数原型OP_LOGE_FOR_INVALID_VALUE(entityName, paramName, incorrectValue, correctValue)宏的使用方式与函数一致调用时直接传入四个参数即可不需要加分号外的额外处理。该宏在 include/op_common/log/log.h#L733-L747 中的完整定义如下#define OP_LOGE_FOR_INVALID_VALUE(entityName, paramName, incorrectValue, correctValue) \ do { \ std::string _safe_entityName_(entityName); \ std::string _safe_paramName_(paramName); \ std::string _safe_incorrectValue_(incorrectValue); \ std::string _safe_correctValue_(correctValue); \ OP_LOGE_LIBOPAPI_REPORT(_safe_entityName_.c_str(), \ Parameter %s of %s has incorrect value %s. It should be %s., \ _safe_paramName_.c_str(), _safe_entityName_.c_str(), \ _safe_incorrectValue_.c_str(), _safe_correctValue_.c_str());\ const std::vectorconst char* msgKey {param_name, op_name, incorrect_value, correct_value}; \ const std::vectorconst char* msgvalue {_safe_paramName_.c_str(), _safe_entityName_.c_str(), \ _safe_incorrectValue_.c_str(), _safe_correctValue_.c_str()}; \ REPORT_PREDEFINED_ERR_MSG(EZ0024, msgKey, msgvalue); \ } while (0)从定义可以看出宏体被do { ... } while (0)包裹可以安全地用在if/else分支中不会产生悬挂 else 问题四个参数都会先被拷贝为局部std::string再通过.c_str()传入日志与错误上报接口避免传入临时对象或字面量时产生悬垂指针日志与错误码上报共用同一组格式化参数保证日志里写的和错误码里报的完全一致。参数说明参数名输入/输出说明entityName输入算子名称或 aclnn 接口名称支持const char*或std::string类型。paramName输入参数名称支持const char*或std::string类型。incorrectValue输入实际参数值支持const char*或std::string类型。correctValue输入预期参数值支持const char*或std::string类型。返回值说明无。宏仅负责输出日志与上报错误码不改变程序返回值。约束说明无。该宏对使用场景无特殊限制但按照其设计意图应仅在参数值校验失败的分支中调用。日志输出与错误码上报的底层链路日志格式OP_LOGE_FOR_INVALID_VALUE内部调用OP_LOGE_LIBOPAPI_REPORT定义在 include/op_common/log/log.h#L106-L115其格式化模板为[文件名:行号][OP_SUBMOD_NAME][函数名][线程ID] OpName:[算子名] Parameter %s of %s has incorrect value %s. It should be %s.其中OP_SUBMOD_NAME默认值为OPS_BASEinclude/op_common/log/log.h#L52-L54线程 ID 通过syscall(__NR_gettid)获取include/op_common/log/log.h#L56-L60。日志级别为DLOG_ERROR值为 3见 include/op_common/log/log.h#L38-L40输出前会先通过CheckLogLevel检查日志开关避免在关闭 ERROR 日志的场景下产生额外开销。错误码 EZ0024宏上报的错误码为EZ0024对应的消息模板与解决建议见 docs/zh/error_code/Operator-Errors/EZ0024-Invalid_Argument.mdParameter %s of %s has incorrect value %s. It should be %s.占位符%s的含义依次为参数名、算子名或接口名、错误值、正确值。上报时以键值对形式携带四个字段param_name、op_name、incorrect_value、correct_value便于上层错误管理框架如op_error_manager结构化解析与聚合去重。与普通日志宏的差异与OP_LOGE上报 EZ9999 通用错误码见 include/op_common/log/log.h#L1076-L1080相比OP_LOGE_FOR_INVALID_VALUE携带了EZ0024 专属错误码能够精确表达参数值错误这一错误类别而不是落入笼统的内部错误。这也是 opbase 在 include/op_common/log/log.h 中维护 EZ0008~EZ0038 一整套通用参数校验宏General Parameter Validation Macros见 include/op_common/log/log.h#L285-L288的初衷针对形状、维度、size、format、dtype、value、stride、list size 等不同维度给出语义明确的错误码实现错误信息标准化。调用示例以下示例来自原文档展示了对算子参数进行范围校验的典型用法。关键代码示例如下仅供参考不支持直接拷贝运行// 预期输出: Parameter sp of AttentionUpdate has incorrect value 17. It should be // in range of [1, 16]. if (sp_ 1 || sp_ 16) { OP_LOGE_FOR_INVALID_VALUE(AttentionUpdate, sp, std::to_string(sp_), in range of [1, 16]); return ge::GRAPH_FAILED; }将示例扩展为更贴近真实算子实现的完整形态// 对枚举类参数做取值校验 if (update_type_ ! 0 update_type_ ! 1) { // 预期输出: Parameter update_type of AttentionUpdate has incorrect value 2. // It should be 0 or 1. OP_LOGE_FOR_INVALID_VALUE(AttentionUpdate, update_type, std::to_string(update_type_), 0 or 1); return ge::GRAPH_FAILED; } // 对字符串参数做取值校验 if (paddingMode ! SAME paddingMode ! VALID) { OP_LOGE_FOR_INVALID_VALUE(Conv2D, paddingMode, paddingMode, SAME or VALID); return ge::GRAPH_FAILED; }实践要点incorrectValue建议通过std::to_string()将数值转成字符串或直接传入已格式化的字符串日志接口统一按%s打印避免类型不匹配correctValue既可以描述具体的预期值如0 or 1也可以描述取值范围如in range of [1, 16]描述越精确用户越容易快速修复宏不改变返回值调用后仍需显式return错误码如ge::GRAPH_FAILED建议与OP_CHECK_IF等组合使用OP_CHECK_IF定义见 include/op_common/log/log.h#L1082-L1088。仓库中的实际使用场景在本仓库源码中同族宏OP_LOGE_FOR_INVALID_VALUE_WITH_REASON上报 EZ0026被大量用于 reduce 模板 Tiling 参数校验例如 src/op_common/atvoss/reduce/reduce_tiling.cpp#L389-L415 对vectorCoreNum、ubSize、cacheLineSize、ubBlockSize、vRegSize等 Tiling 关键参数的合法性检查以及同文件 src/op_common/atvoss/reduce/reduce_tiling.cpp#L972-L1020 中对ubSize、basicBlock的校验。其调用模式与本宏完全一致if (ubSize_ 0) { OP_LOGE_FOR_INVALID_VALUE_WITH_REASON(context_-GetNodeName(), ubSize, std::to_string(ubSize_), larger than 0); return false; }可见if校验失败 → 调用日志宏 → 返回错误是 opbase 内部统一的参数校验范式。其中entityName可以直接使用context_-GetNodeName()动态获取当前算子名无需硬编码。相关宏对比该宏属于 log 接口家族的一员完整的接口清单见 docs/zh/api/op_common/log/log.md。与参数值校验相关的三个宏对比如下宏上报错误码语义适用场景OP_LOGE_FOR_INVALID_VALUEEZ0024单参数值错误带正确值校验失败时能明确给出预期值/范围OP_LOGE_FOR_INVALID_VALUE_WITH_REASONEZ0026单参数值错误带失败原因能解释为什么非法例如超出硬件支持上限OP_LOGE_FOR_INVALID_VALUES_WITH_REASONEZ0027多参数值错误带失败原因多个参数同时校验、一起上报各宏的详细说明分别见 docs/zh/api/op_common/log/OP_LOGE_FOR_INVALID_VALUE.md、docs/zh/api/op_common/log/OP_LOGE_FOR_INVALID_VALUE_WITH_REASON.md 与 docs/zh/api/op_common/log/OP_LOGE_FOR_INVALID_VALUES_WITH_REASON.md。如果校验的是形状、维度、size、format、dtype 而非取值应改用同族宏OP_LOGE_FOR_INVALID_SHAPEEZ0008、OP_LOGE_FOR_INVALID_SHAPEDIMEZ0011、OP_LOGE_FOR_INVALID_SHAPESIZEEZ0014、OP_LOGE_FOR_INVALID_FORMATEZ0017、OP_LOGE_FOR_INVALID_DTYPEEZ0019等各宏定义均位于 include/op_common/log/log.h定义处注释中标注了对应的错误码。使用建议与错误码文档联动排查当线上出现 EZ0024 错误码时可直接对照 docs/zh/error_code/Operator-Errors/EZ0024-Invalid_Argument.md 中的报错示例与解决方法来定位问题——检查参数值是否正确。保持参数语义一致entityName应使用对外可见的算子名或 aclnn 接口名动态场景可用context_-GetNodeName()不要使用内部类名否则用户难以理解报错归属。优先使用专用宏凡是参数类校验失败优先使用带 EZ 错误码的专用宏而不是裸OP_LOGE以便错误码上报链路能够按类别聚合统计。校验失败立即返回宏只负责记录与上报真正的中断逻辑return必须由调用方完成避免只打日志不报错的静默失败。【免费下载链接】opbase本项目是CANN算子库的基础框架库为算子提供公共依赖文件和基础调度能力。项目地址: https://gitcode.com/cann/opbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考