Matrix653 BSP 接口

更新时间：
2024-02-26
下载文档

Matrix653 BSP 接口

本节介绍 Matrix653 分时分区操作系统为 BSP 提供的健康监控相关 API。

健康监控相关功能在操作系统内核中进行实现，一部分接口在操作系统初始化过程中可以调用，一部分封装后被相应的 APEX 服务调用而后提供给分区级应用程序进行使用。相关操作接口如下表所示：

API描述
_mx_health_monitor_unit_init健康监控模块初始化
_mx_partition_init_hm分区内健康监控相关资源初始化
_mx_hm_report_app_message汇报应用信息
_mx_hm_retrieve_app_message获取应用信息
_mx_hm_create_error_handler创建分区内错误处理进程
_mx_hm_raise_app_error上报应用错误
_mx_hm_get_error_status获取应用错误状态
_mx_hm_config_error_handler配置错误处理进程
_mx_hm_enable_error_handler使能错误处理进程
_mx_hm_raise_module_error上报模块错误
_mx_hm_raise_bsp_error上报 BSP 错误
_mx_hm_raise_partition_exception在分区内上报异常
_mx_hm_raise_deadline_missed_error上报进程截止时间错误
_mx_hm_raise_exception上报 CPU 异常
_mx_hm_error_description获取错误 ID 描述
_mx_hm_state_description获取系统状态描述

_mx_health_monitor_unit_init

  • 描述：初始化健康监控模块

  • 函数原型：

extern void _mx_health_monitor_unit_init (
    /*in */ const MX_BOARD_CONFIG_TYPE          *board_config,
    /*in */ const MX_CORE_MODULE_CONFIG_TYPE    *module_config);
  • 参数：
输入/输出参数描述
[in]board_config指向板级配置的指针
[in]module_config指向核心模块配置数据的指针

下述代码均出自

$(MATRIX653_SDK_PATH)/libmatrix653/src/include/matrix653/mx_config_types.h

板级配置由开发者针对不同的板卡编写不同的板级配置参数，在操作系统初始化资源时作为参数被配置，操作系统初始化时调用如下所示。

void mx_bsp_init (void)
{
… …

    /* 第一个参数为板级配置 */
mx_init(&__mx_board_config, MX_NULL);

    … …
    mx_start();
}

模块配置由 integrator 中的健康监控表手动配置，在操作系统资源初始化时被加载配置，模块配置中与健康监控相关的如下成员需要配置：

typedef struct {
    … …

    /* 健康监控 */
    union {
        MX_UINT64                                address;
        MX_HEALTH_MONITORING_CONFIG_TYPE         *pointer;
} health_monitoring_config;

    … …
} MX_STRUCT_PACK_STRUCT MX_CORE_MODULE_CONFIG_TYPE;

_mx_partition_init_hm

  • 描述：初始化分区内健康监控相关资源

  • 函数原型：

extern RETURN_CODE_TYPE _mx_partition_init_hm (
    /*in */ MX_PARTITION_TYPE           *current_partition,
    /*in */ MX_INIT_TYPE                init);
  • 参数：
输入 / 输出参数描述
[in]current_partition指向当前分区的指针
[in]init是否初始化

下述代码出自

$(MATRIX653_SDK_PATH)/libmatrix653/src/include/matrix653/mx_config_types.h

分区配置由 integrator 中的健康监控表手动配置，在操作系统资源初始化时被加载配置，分区配置（current_partition）需定义如下成员：

struct _MX_PARTITION_TYPE {
    … …

    /* 健康监控 */
    const MX_PARTITION_HM_CONFIG_TYPE          *hm_config;
    const MX_MULTI_PARTITION_HM_CONFIG_TYPE    *multi_partition_hm_config;

   … …
};

_mx_hm_report_app_message

  • 描述：该接口在内核中进行实现，对应的 APEX 服务 REPORT_APPLICATION_MESSAGE 中会调用该 API，作用是向健康监控处理函数发送带有程序运行地址的消息

  • 函数原型：

extern RETURN_CODE_TYPE _mx_hm_report_app_message (
    /*in */   MESSAGE_ADDR_TYPE             message_addr,
    /*in */   MESSAGE_SIZE_TYPE             length);
  • 参数：
输入 / 输出参数描述
[in]message_addr错误消息字符串地址
[in]length错误消息字符串长度
  • 使用：在分区级应用程序中调用相应的 APEX 服务 REPORT_APPLICATION_MESSAGE()。

_mx_hm_retrieve_app_message

  • 描述：该接口在内核中进行实现，对应的扩展 APEX 服务 RETRIEVE_APP_MESSAGE 中会调用该 API，作用是获取应用信息，从 HM 函数检索消息。

  • 函数原型：

extern RETURN_CODE_TYPE _mx_hm_retrieve_app_message (
    /*in */   MESSAGE_ADDR_TYPE        message_addr,
    /*in */   MESSAGE_SIZE_TYPE        buffer_length,
    /*out*/   MESSAGE_SIZE_TYPE        *length);
  • 参数：
输入 / 输出参数描述
[in]message_addr错误消息字符串地址
[in]buffer_length检索缓冲区大小
[out]length检索到的消息长度
  • 使用：在分区级应用程序中调用相应的 APEX 服务 RETRIEVE_APP_MESSAGE ()。

_mx_hm_create_error_handler

  • 描述：该接口在内核中进行实现，对应的 APEX 服务 CREATE_ERROR_HANDLE 中会调用该 API，作用是创建分区内错误处理进程。

  • 函数原型：

extern RETURN_CODE_TYPE _mx_hm_create_error_handler (
    /*in */   MX_PARTITION_TYPE        *current_partition,
    /*in */   SYSTEM_ADDRESS_TYPE      entry_point,
    /*in */   SYSTEM_ADDRESS_TYPE      argument,
    /*in */   STACK_SIZE_TYPE          stack_size);
  • 参数：
输入 / 输出参数描述
[in]current_partition当前分区
[in]entry_point错误处理程序进程入口点
[in]argument错误处理进程参数
[in]stack_size错误处理进程堆栈大小
  • 使用：在分区级应用程序中调用相应的 APEX 服务 CREATE_ERROR_HANDLE ()。

_mx_hm_raise_app_error

  • 描述：该接口在内核中进行实现，对应的 APEX 服务 RAISE_APPLICATION_ERROR 中会调用该 API，作用是上报应用错误，该服务请求允许正在运行的进程为特定的错误代码调用错误处理程序进程。

  • 函数原型：

extern RETURN_CODE_TYPE _mx_hm_raise_app_error (
    /*in */ MX_ERROR_ID_TYPE                error_id,
    /*in */ MESSAGE_ADDR_TYPE               message_addr,
    /*in */ ERROR_MESSAGE_SIZE_TYPE         length,
    /*in */ void                            *return_address);
  • 参数：
输入 / 输出参数描述
[in]error_id错误 ID
[in]message_addr错误消息字符串地址
[in]length错误消息字符串长度
[in]return_address程序运行地址
  • 使用：在分区级应用程序中调用相应的 APEX 服务 RAISE_APPLICATION_ERROR ()。

_mx_hm_get_error_status

  • 描述：该接口在内核中进行实现，对应的 APEX 服务 GET_ERROR_SATUS() 中会调用该 API，作用是获取应用错误状态（例如：故障进程的标识符、错误代码、错误地址和错误消息）。

  • 函数原型

extern RETURN_CODE_TYPE _mx_hm_get_error_status (
    /*out*/   ERROR_STATUS_TYPE            *error_status);
  • 参数：
输入 / 输出参数描述
[out]error_status错误状态
  • 使用：在分区级应用程序中调用相应的 APEX 服务 GET_ERROR_SATUS()。

_mx_hm_config_error_handler

  • 描述：该接口在内核中进行实现，对应的APEX服务 CONFIGURE_ERROR_HANDLER() 中会调用该 API，作用是配置错误处理进程。

  • 函数原型：

extern RETURN_CODE_TYPE _mx_hm_config_error_handler (
    /*in */  MX_PARTITION_TYPE                       *current_partition,
    /*in*/   ERROR_HANDLER_CONCURRENCY_CONTROL_TYPE  concurrency_control,
    /*in */  PROCESSOR_CORE_ID_TYPE                  processor_core_id);
  • 参数：
输入 / 输出参数描述
[in]current_partition当前分区
[in]concurrency_control是否并发控制
[in]processor_core_id错误处理程序进程绑核 ID
  • 使用：在分区级应用程序中调用相应的 APEX 服务 CONFIGURE_ERROR_HANDLER()。

_mx_hm_enable_error_handler

  • 描述：该接口在内核中进行实现，对应的 APEX 扩展服务 ENABLE_ERROR_HANDLER() 中会调用该 API，作用是注册错误处理进程并且能够被调用以便处理在当前分区初始化阶段（COLD_START 或 WARM_START 模式）发生的错误。

  • 函数原型：

extern RETURN_CODE_TYPE _mx_hm_enable_error_handler (
    /*in */   MX_PARTITION_TYPE           *current_partition);
  • 参数：
输入 / 输出参数描述
[in]current_partition当前分区
  • 使用：在分区级应用程序中调用相应的 APEX 服务 ENABLE_ERROR_HANDLER()。

_mx_hm_raise_module_error

  • 描述：上传模块错误

  • 函数原型：

extern void _mx_hm_raise_module_error (
    /*in */  const char         *info1,
    /*in */  const char         *info2,
    /*in */  const char         *info3,
    /*in */  const char         *info4) MX_NO_RETURN;
  • 参数：
输入/输出参数描述
[in]info1打印信息 1
[in]info2打印信息 2
[in]info3打印信息 3
[in]info4打印信息 4
  • 使用：在 bsp 中调用该接口后，会打印出指定信息，并且关机。示例如下图所示：

_mx_hm_raise_bsp_error

  • 描述：上报 BSP 错误。

  • 函数原型：

extern RETURN_CODE_TYPE _mx_hm_raise_bsp_error (
    /*in */ MX_ERROR_ID_TYPE                error_id,
    /*in */ MESSAGE_ADDR_TYPE               message_addr,
    /*in */ ERROR_MESSAGE_SIZE_TYPE         length,
    /*in */ void                            *extra_parameter);
  • 参数：
输入 / 输出参数描述
[in]error_id错误 ID
[in]message_addr错误消息字符串地址
[in]length错误消息字符串长度
[in]extra_parameter扩展参数
  • 使用：首先需要在模块健康监控表（模块初始化）定义错误及其恢复动作，如下图所示：

若未定义错误就调用该 API 就会导致操作系统无法识别该错误，则会出现如下图情况：

如正常定义错误及其恢复动作后，操作系统则会识别到该 API 触发的错误，继而采取相应的恢复动作，使用效果如下图所示：

_mx_hm_raise_partition_exception

  • 描述：在分区内上报异常

  • 函数原型：

extern RETURN_CODE_TYPE _mx_hm_raise_partition_exception (
    /*in */ MX_ERROR_ID_TYPE                error_id,
    /*in */ void                            *return_address,
    /*in */ MX_PARTITION_TYPE               *partition,
    /*in */ MX_PROCESS_TYPE                 *process,
    /*in */ MESSAGE_ADDR_TYPE               message_addr,
    /*in */ ERROR_MESSAGE_SIZE_TYPE         length,
    /*in */ void                            *extra_parameter);
  • 参数：
输入 / 输出参数描述
[in]error_id错误 ID
[in]Return_address程序运行地址
[in]Partition指向分区指针
[in]process指向进程指针
[in]Message_addr消息地址
[in]Length消息长度
[in]Extra_parameter额外参数地址
  • 使用：只能在分区运行时被调用。

_mx_hm_raise_deadline_missed_error

  • 描述：上报进程截至时间到错误

  • 函数原型：

extern RETURN_CODE_TYPE _mx_hm_raise_deadline_missed_error (
    /*in */ MX_PARTITION_TYPE           *partition,
    /*in */ MX_PROCESS_TYPE             *process);
  • 参数：
输入 / 输出参数描述
[in]partition指向分区控制块的指针
[in]process指向进程的指针
  • 使用：在内核处理 Tick 中断时调用。

_mx_hm_raise_exception

  • 描述：上报 CPU 异常

  • 函数原型：

extern RETURN_CODE_TYPE _mx_hm_raise_exception (
    /*in */ MX_ERROR_ID_TYPE                error_id,
    /*in */ void                            *return_address,
    /*in */ MX_ARCH_REG_CONTEXT_TYPE        *reg_context);
  • 参数：
输入 / 输出参数描述
[in]error_id错误 ID
[in]return_address程序运行地址
[in]reg_contextCPU寄存器上下文
  • 使用：调用之后，分区会输出打印信息，而后会关机。

_mx_hm_error_description

  • 描述：获取错误 ID 及其文字描述

  • 函数原型：

extern const char *_mx_hm_error_description (
    /*in */ MX_ERROR_ID_TYPE        error_id);
  • 参数：
输入 / 输出参数描述
[in]error_id错误 ID
  • 使用：当想要看当前系统发生了什么错误，即可在系统启动初始化时调用该函数获取错误 ID 即可分析出其错误，示例如下图所示：

_mx_hm_state_description

  • 描述：获取系统状态描述

  • 函数原型：

extern const char *_mx_hm_state_description (
    /*in */ MX_STATE_ID_TYPE        state_id);
  • 参数：
输入 / 输出参数描述
[in]state_id状态ID
  • 使用：在bsp中调用即可获取系统状态描述，使用示例如下图所示：
上一篇
Matrix653 实现
下一篇
APEX 服务
文档内容是否对您有所帮助？
有帮助
没帮助
Copyright © 2024 ACOINFO. All Rights Reserved. 京ICP备20010248号备案号京公网安备11010802043204号