AD9026芯片开发实录7----API中的Error 模块

        ADI官方提供了三个公共功能模块提供给用户使用，这三个模块分别是ERROR、LOGGING和HAL。

        该三个模块的源代码均位于官方发布的软件包的./c_src/common 路径下。ADI官方的代码规范是一个.c 文件会有两个.h 文件，其中一个头文件用来申明宏函数和对外接口和.c 文件的文件名同名，另一个头文件用来定义相关宏，枚举变量和结构体，一般用"_type.h"结尾，所以在"adi_error" 这个文件夹中，可以看到 "adi_common_error_types.h" 和 "adi_common_error.h" 这两个头文件。

        ERROR 模块在API的代码中使用特别频繁，几乎所有的API接口中，都会用到ERROR模块的接口。ERROR模块的主要作用是用来保存API的运行结果，以及做结果判断的简单后处理，比如出现错误后，是否return，同时ERROR模块统一定义了API函数的执行结果错误类型。

  ERROR模块顶层

        在概述中提到，ERROR模块的主要作用是用来保存API的运行结果和后处理，并能以最小的代价通知用户错误对应的等级。ADI官方对runtime 的error做了一层抽象，除了包含error的基本属性外，包括错误类型，错误源，错误简介等，还额外添加了错误行动（error action）的概念，这个概念比较重要，在后面介绍error的结构体定义的时候会详细说明。ERROR模块在功能上，顶层设计了三个对外接口，分别是错误判断，错误上报和错误清理，这三个接口均以宏的形式定义在上述的头文件中。

error 的抽象--error结构体定义

        通过ADI官方源代码中的error结构体定义可以进一步窥探到ADI对error 的抽象，具体定义如下：

typedef struct adi_common_ErrStruct
{    int32_t     errSource;    /*!< 错误return时的错误源 */    int32_t     errCode;      /*!< 返回的错误码 */    uint32_t    errLine;      /*!< 错误发生时所在源代码的行数 */    const char* errFunc;      /*!< 错误发生时的函数名 */    const char* errFile;      /*!< 错误发生时的文件名 */    const char* varName;      
/*!< 有错误的变量名称，一般用于入参检测或代码体中变量范围的检测 */    const char* errormessage; /*!< 错误的简要描述 */    int32_t     lastAction;   /*!< 上次错误时对应的 */    int32_t     newAction;    /*!< 新的错误行动 */    uint8_t     logEnable;    /*!< 错误日志使能 */} adi_common_ErrStruct_t;

这其中：

1. 错误源定义了错误的来源，目前ADI给出了4个来源，分别是API，API HAL层，设备的寄存器比特域，设备Hal层，也就是说，从错误源这里可以快速区分错误发生的代码层级和模块。参考宏定义adi_common_ErrSources_e，，客户也可以扩展自己模块的错误源，只需要不覆盖官方的定义即可。

2. 错误码给出了统一公共的错误代码，其范围是0x0000 - 0x0FFF，它的值会根据错误源的变化而变化，ADI官方定义了API这个错误源 的 六种基本的错误类型，分别为没有错误，无效入参，空指针，API执行失败，SPI通信失败和CPU crash，这个地方的设计区别于其他的API，错误码给出了错误的类型，其定义并不是负的整型数据，而是正的整型数据，具体定义如下：

#define ADI_COMMON_ERR_OK              0x00