22. 错误上报接口

本章节描述错误上报接口，用于注册和上报各类预定义与自定义的错误信息。

• 使用须知
• int32_t ReportInnerErrMsg(const char_t *file_name, const char_t *func, uint32_t line, const char *error_code, const char_t *format, ...)：用于上报CANN预定义好的内部错误信息，同时也会上报调用处的一些信息，如文件名、函数名以及行号。
• int32_t ReportPredefinedErrMsg(const char *error_code, ...)：用于上报CANN预定义好的用户类错误信息。
• int32_t ReportUserDefinedErrMsg(const char *error_code, const char *format, ...)：用于开发者上报自定义错误码，推荐使用U码段，比如EU0001。
• int32_t RegisterFormatErrorMessage(const char *error_msg, size_t error_msg_len)：按照规定的json格式，调用本接口给CANN注册预定义的错误码信息后，再调用ReportPredefinedErrMsg接口上报错误码。

使用须知

该部分接口仅在定制开发CANN组件及自定义算子开发场景下使用。本文介绍这部分接口的功能、参数等，仅为了便于您了解这部分接口在CANN开放代码中的作用，进而更好地使用或修改CANN开放代码。

错误上报接口头文件和库文件路径：

• include的头文件所在路径（该头文件中的接口，其命名空间为ge）：${INSTALL_DIR}/include/base/err_msg.h
• 依赖的库文件所在路径：${INSTALL_DIR}/lib64/liberror_manager.so

${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。以root用户安装为例，安装后文件默认存储路径为：/usr/local/Ascend/cann。

ReportInnerErrMsg

int32_t ReportInnerErrMsg(const char_t *file_name, const char_t *func, uint32_t line, const char *error_code, const char_t *format, ...)

产品支持情况

• Ascend 950PR/Ascend 950DT：支持

• Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持

• Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持

• Atlas 200I/500 A2 推理产品：支持

• Atlas 推理系列产品：支持

• Atlas 训练系列产品：支持

• IPV350：不支持

函数功能

用于上报CANN预定义好的内部错误信息，同时也会上报调用处的一些信息，如文件名、函数名以及行号。

当使用该接口时，如果用户提供的格式化字符串长度超过1024（包括末尾的\0），接口将返回错误码-1，表示失败。例如，如果格式化字符串为“Error:%s”，且传入的字符串长度为1000，加上“Error:”和末尾的“\0”，总长度为1007，接口调用成功。然而，如果传入的字符串长度为1020，加上“Error:”和末尾的“\0”，总长度变为1027，超过1024，接口调用失败。

针对该接口，还提供了封装该接口的宏REPORT_INNER_ERR_MSG，宏定义如下：

#define REPORT_INNER_ERR_MSG(error_code, format, ...) \
    (void)ge::ReportInnerErrMsg(__FILE__, __FUNCTION__, __LINE__, (error_code), (format), ##__VA_ARGS__)

参数说明

参数名	输入/输出	说明
file_name	输入	文件名，表示用户在哪个文件中调用ReportInnerErrMsg接口，固定配置为__FILE__。
func	输入	函数名，表示用户在哪个函数中调用ReportInnerErrMsg接口，固定配置为__FUNCTION__。
line	输入	行号，表示用户在哪一行中调用ReportInnerErrMsg接口，固定配置为__LINE__。
error_code	输入	CANN预定义好的内部错误。 错误码以6位字符形式体现，例如E19999，其中，第1位表示级别，分为E、W、I，分别表示错误、告警、提示类；第2位表示模块；后4位表示错误码，9000~9999为内部错误码。
format	输入	错误信息。 在调用格式化函数时，format中参数的类型、个数必须与实际参数类型、个数保持一致。
...	输入	format中的可变参数，根据错误信息添加。

返回值

无

ReportPredefinedErrMsg

• 不带参数的错误码信息：

  int32_t ReportPredefinedErrMsg(const char *error_code)
  

• 带参数的错误码信息：

  int32_t ReportPredefinedErrMsg(const char *error_code, const std::vector<const char *> &key, const std::vector<const char *> &value)
  

产品支持情况

• Ascend 950PR/Ascend 950DT：支持

• Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持

• Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持

• Atlas 200I/500 A2 推理产品：支持

• Atlas 推理系列产品：支持

• Atlas 训练系列产品：支持

• IPV350：不支持

函数功能

用于上报CANN预定义好的用户类错误信息。

针对该接口，还提供了封装该接口的宏REPORT_PREDEFINED_ERR_MSG，宏定义如下：

#define REPORT_PREDEFINED_ERRMSG_CHOOSER(_1, _2, _3, NAME, ...) NAME
#define REPORT_PREDEFINED_ERRMSG_1PARAMS(error_code) error_message::ReportPredefinedErrMsg(error_code)
#define REPORT_PREDEFINED_ERRMSG_3PARAMS(error_code, key, value)                                                       \
  error_message::ReportPredefinedErrMsg((error_code), (key), (value))
#define REPORT_PREDEFINED_ERR_MSG(...)                                                                                 \
  REPORT_PREDEFINED_ERRMSG_CHOOSER(__VA_ARGS__, REPORT_PREDEFINED_ERRMSG_3PARAMS, ,                                    \
                                   REPORT_PREDEFINED_ERRMSG_1PARAMS)(__VA_ARGS__)

参数说明

参数名	输入/输出	说明
error_code	输入	错误码以6位字符形式体现，例如E10001，其中，第1位表示级别，分为E、W、I，分别表示错误、告警、提示类；第2位表示模块；后4位表示错误码，0000~8999为用户类错误。 CANN预定义好的用户类错误可参见《故障处理》中的错误码参考。
key	输入	预定义的参数。 每个错误码支持的参数可查看error_code.json文件中的Arglist字段。
value	输入	参数key中参数对应的实际值。 这些实际值会替换error_code.json文件中ErrMessage字段的占位符，得到最终的错误码信息。

返回值

• 0：成功。
• -1：失败。

ReportUserDefinedErrMsg

int32_t ReportUserDefinedErrMsg(const char *error_code, const char *format, ...)

产品支持情况

• Ascend 950PR/Ascend 950DT：支持

• Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持

• Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持

• Atlas 200I/500 A2 推理产品：支持

• Atlas 推理系列产品：支持

• Atlas 训练系列产品：支持

• IPV350：不支持

函数功能

用于开发者上报自定义错误码，推荐使用U码段，比如EU0001。

推荐是6位字符形式，对于像空格、非6位字符、以8888或9999结尾等不推荐的形式，函数内部会以错误码EU0000进行上报。

当使用该接口时，如果用户提供的格式化字符串长度超过1024（包括末尾的\0），接口将返回错误码-1，表示失败。例如，如果格式化字符串为“Error:%s”，且传入的字符串长度为1000，加上"Error:"和末尾的"\0"，总长度为1007，接口调用成功。然而，如果传入的字符串长度为1020，加上"Error:"和末尾的"\0"，总长度变为1027，超过1024，接口调用失败。

参数说明

参数名	输入/输出	说明
error_code	输入	用户自定义的错误码。
format	输入	错误码对应的错误信息。
...	输入	format中的可变参数，表示format中占位符对应的变量值。

返回值

• 0：成功。
• -1：失败。

RegisterFormatErrorMessage

int32_t RegisterFormatErrorMessage(const char *error_msg, size_t error_msg_len)

产品支持情况

• Ascend 950PR/Ascend 950DT：支持

• Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持

• Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持

• Atlas 200I/500 A2 推理产品：支持

• Atlas 推理系列产品：支持

• Atlas 训练系列产品：支持

• IPV350：不支持

函数功能

按照规定的json格式，调用本接口给CANN注册预定义的错误码信息后，再调用ReportPredefinedErrMsg接口上报错误码。

同时为了方便使用，封装了宏REG_FORMAT_ERROR_MSG，用户可直接使用该宏注册，该宏直接定义静态变量注册，进程加载时就会完成注册。

#define REG_FORMAT_ERROR_MSG(error_msg, error_msg_len) \
  REG_FORMAT_ERROR_MSG_UNIQ_HELPER((error_msg), (error_msg_len), __COUNTER__)
#define REG_FORMAT_ERROR_MSG_UNIQ_HELPER(error_msg, error_msg_len, counter) \
  REG_FORMAT_ERROR_MSG_UNIQ((error_msg), (error_msg_len), counter)
#define REG_FORMAT_ERROR_MSG_UNIQ(error_msg, error_msg_len, counter) \
  static const auto register_error_msg_##counter ATTRIBUTE_USED = []() -> int32_t { \
    return error_message::RegisterFormatErrorMessage((error_msg), (error_msg_len)); \
  }()

参数说明

参数名	输入/输出	说明
error_msg	输入	错误码信息，可一次注册多个错误码。 错误码信息需按json格式组织，示例请参见调用示例。
error_msg_len	输入	error_msg长度，不包含末尾的'\0'。

返回值

• 0：成功。
• -1：失败。

调用示例

error_msg错误码信息需按照json格式组织，error_info_list是一个包含错误信息对象的数组，至少需要包含一个元素，其中各字段含义如下：

• errClass：错误分类。
• errTitle：错误标题。
• ErrCode：错误码。注意不要与当前已有的错误码重复，已有的错误码请参见《故障处理》中的错误码参考。
• ErrMessage：错误消息，可以包含格式化占位符(%s)。
• Arglist：参数列表，用于说明ErrMessage中占位符对应的参数，参数列表长度与ErrMessage里格式化占位符个数必须相等。
• suggestion：建议信息，包含：
  • Possible Cause：可能的原因。
  • Solution：解决方法。

#include <string>
#include "base/err_msg.h"

const std::string error_msg = R"(
{
    "error_info_list": 
    [
        {
            "errClass": "GE Errors",
            "errTitle": "Invalid_Dynamic_Shape_Argument",
            "ErrCode": "E10018",
            "ErrMessage": "Value [%s] for shape [%s] is invalid. When [--dynamic_batch_size] is included, only batch size N can be -1 in [--input_shape].",
            "Arglist": "shape,index",
            "suggestion": {
                "Possible Cause": "When [--dynamic_batch_size] is included, only batch size N can be -1 in the shape.",
                "Solution": "Try again with a valid [--input_shape] argument. Make sure that non-batch size axes are not -1."
            }
        },        
        {
           "errClass": "GE Errors",
           "errTitle": "Invalid_--input_shape_Argument",
           "ErrCode": "E10019",
           "ErrMessage": "When [--dynamic_image_size] is included, only the height and width axes can be -1 in [--input_shape].",
           "Arglist": "",
           "suggestion": {
                "Possible Cause": "When [--dynamic_image_size] is included, only the height and width axes can be -1 in the shape.",
                "Solution": "Try again with a valid [--input_shape] argument. Make sure that axes other than height and width are not -1."
            }
        }
    ]
}
)";

REG_FORMAT_ERROR_MSG(error_msg.c_str(), error_msg.size());