dfx

DFX诊断模块提供Diag命令注册与解注册、报文上报（单包/多包、同步/异步、关键/普通优先级）、消息上报、应答处理注册、命令执行及统计量对象管理等能力，支持本地与远端报文识别，为系统诊断与维护提供基础接口。

头文件清单

#include <middleware/utils/diag.h>
#include <middleware/utils/diag_log.h>

接口清单

接口名称	功能简述
uapi_diag_register_cmd	注册diag命令处理函数
uapi_diag_unregister_cmd	解注册diag命令处理函数
uapi_diag_report_packet	上报单个DIAG报文给DIAG客户端
uapi_diag_report_packets_critical	上报多个关键DIAG报文给DIAG客户端
uapi_diag_report_packets_normal	上报多个普通DIAG报文给DIAG客户端
uapi_diag_report_sys_msg	上报消息给DIAG客户端
uapi_diag_register_ind	注册diag应答处理函数
uapi_diag_run_cmd	根据命令ID执行diag命令处理函数
uapi_diag_register_stat_obj	注册统计量对象

Functions

uapi_diag_register_cmd

diag_register_cmd uapi diag register cmd uapi_diag_register_cmd

函数声明

errcode_t uapi_diag_register_cmd(const diag_cmd_reg_obj_t *cmd_tbl, uint16_t cmd_num);

头文件

#include <middleware/utils/diag.h>

功能说明

• 注册diag命令处理函数到DIAG子系统，使新命令可被DIAG客户端调用
• 命令注册表必须声明为常量数组并传入此接口，cmd_num不能为0
• 注册过程中会进行中断锁定保护，保证并发安全

前置条件

• DIAG子系统已初始化完成
• cmd_tbl不为NULL，且指向的命令表已正确填充min_id、max_id和fn_input_cmd字段

入参

名称	参数类型	详细说明	约束取值范围
cmd_tbl	const diag_cmd_reg_obj_t *	diag命令注册表指针	不为NULL
cmd_num	uint16_t	命令条数	大于0

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x0)	注册成功	命令表校验通过且有空闲槽位
ERRCODE_FAIL(0xFFFFFFFF)	注册失败	命令表校验失败或无空闲槽位

uapi_diag_unregister_cmd

diag_unregister_cmd uapi diag unregister cmd uapi_diag_unregister_cmd

函数声明

errcode_t uapi_diag_unregister_cmd(const diag_cmd_reg_obj_t *cmd_tbl, uint16_t cmd_num);

头文件

#include <middleware/utils/diag.h>

功能说明

• 解注册已注册的diag命令处理函数，将命令表从DIAG子系统中移除
• 解注册时需要传入与注册时相同的cmd_tbl和cmd_num参数
• 解注册过程中会进行中断锁定保护，保证并发安全

前置条件

• DIAG子系统已初始化完成
• cmd_tbl和cmd_num与注册时一致

入参

名称	参数类型	详细说明	约束取值范围
cmd_tbl	const diag_cmd_reg_obj_t *	diag命令注册表指针	不为NULL
cmd_num	uint16_t	命令条数	大于0

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x0)	解注册成功	命令表找到并成功移除
ERRCODE_FAIL(0xFFFFFFFF)	解注册失败	命令表校验失败或未找到匹配项

uapi_diag_report_packet

diag_report_packet uapi diag report packet uapi_diag_report_packet

函数声明

errcode_t uapi_diag_report_packet(uint16_t cmd_id, diag_option_t *option, const uint8_t *packet, uint16_t packet_size, bool sync);

头文件

#include <middleware/utils/diag.h>

功能说明

• 上报单个DIAG通道报文给DIAG客户端
• 支持同步和异步两种上报方式：同步方式阻塞等待发送完成，异步方式通过OS队列缓存后发送不阻塞
• 通过option参数识别报文是本地报文还是远端报文

前置条件

• DIAG子系统已使能且连接状态正常
• packet指向的缓冲区在同步模式下调用期间保持有效

入参

名称	参数类型	详细说明	约束取值范围
cmd_id	uint16_t	报文上报ID	-
option	diag_option_t *	option选项，识别本地/远端报文	可为NULL，NULL时使用默认目标地址
packet	const uint8_t *	数据包地址	不为NULL
packet_size	uint16_t	数据包大小（单位：字节）	大于0
sync	bool	上报方式	true：同步上报；false：异步上报

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x0)	上报成功	DIAG已使能且报文发送成功
ERRCODE_FAIL(0xFFFFFFFF)	上报失败	DIAG未使能或未连接

uapi_diag_report_packets_critical

diag_report_packets_critical uapi diag report packets critical uapi_diag_report_packets_critical

函数声明

errcode_t uapi_diag_report_packets_critical(uint16_t cmd_id, diag_option_t *option, uint8_t **packet, uint16_t *packet_size, uint8_t pkt_cnt);

头文件

#include <middleware/utils/diag.h>

功能说明

• 上报多个关键DIAG报文给DIAG客户端，报文以关键优先级发送
• 关键报文在传输链路中享有优先保障
• 通过option参数识别报文是本地报文还是远端报文

前置条件

• DIAG子系统已使能且连接状态正常
• packet和packet_size数组指针有效，且pkt_cnt不超过DIAG_PKT_DATA_ID_MAX-1

入参

名称	参数类型	详细说明	约束取值范围
cmd_id	uint16_t	报文上报ID	-
option	diag_option_t *	option选项，识别本地/远端报文	可为NULL，NULL时使用默认目标地址
packet	uint8_t **	指向数据指针数组的指针	不为NULL
packet_size	uint16_t *	指向数据包大小数组的指针	不为NULL
pkt_cnt	uint8_t	数据包个数	大于0

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x0)	上报成功	DIAG已使能且报文发送成功
ERRCODE_FAIL(0xFFFFFFFF)	上报失败	DIAG未使能或pkt_cnt超过限制

uapi_diag_report_packets_normal

diag_report_packets_normal uapi diag report packets normal uapi_diag_report_packets_normal

函数声明

errcode_t uapi_diag_report_packets_normal(uint16_t cmd_id, diag_option_t *option, uint8_t **packet, uint16_t *packet_size, uint8_t pkt_cnt);

头文件

#include <middleware/utils/diag.h>

功能说明

• 上报多个普通DIAG报文给DIAG客户端，报文以普通优先级发送
• 通过option参数识别报文是本地报文还是远端报文
• 与关键报文接口的区别在于传输优先级不同

前置条件

• DIAG子系统已使能且连接状态正常
• packet和packet_size数组指针有效，且pkt_cnt不超过DIAG_PKT_DATA_ID_MAX-1

入参

名称	参数类型	详细说明	约束取值范围
cmd_id	uint16_t	报文上报ID	-
option	diag_option_t *	option选项，识别本地/远端报文	可为NULL，NULL时使用默认目标地址
packet	uint8_t **	指向数据指针数组的指针	不为NULL
packet_size	uint16_t *	指向数据包大小数组的指针	不为NULL
pkt_cnt	uint8_t	数据包个数	大于0

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x0)	上报成功	DIAG已使能且报文发送成功
ERRCODE_FAIL(0xFFFFFFFF)	上报失败	DIAG未使能或pkt_cnt超过限制

uapi_diag_report_sys_msg

diag_report_sys_msg uapi diag report sys msg uapi_diag_report_sys_msg

函数声明

errcode_t uapi_diag_report_sys_msg(uint32_t module_id, uint32_t msg_id, const uint8_t *buf, uint16_t buf_size, uint8_t level);

头文件

#include <middleware/utils/diag.h>

功能说明

• 上报消息给DIAG客户端，携带模块ID、消息ID和日志级别
• 内部通过rom_api注册的回调函数实现消息路由
• 日志级别用于过滤，仅当日志级别满足使能条件时才会上报

前置条件

• DIAG子系统已初始化且rom_api已注册回调函数
• 日志级别需满足模块的日志过滤条件

入参

名称	参数类型	详细说明	约束取值范围
module_id	uint32_t	模块ID	-
msg_id	uint32_t	消息ID	-
buf	const uint8_t *	上报内容	-
buf_size	uint16_t	内容大小（单位：字节）	-
level	uint8_t	日志级别	-

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x0)	上报成功	rom_api回调函数执行成功
ERRCODE_FAIL(0xFFFFFFFF)	上报失败	rom_api回调函数未注册或执行失败

uapi_diag_register_ind

diag_register_ind uapi diag register ind uapi_diag_register_ind

函数声明

errcode_t uapi_diag_register_ind(const diag_cmd_reg_obj_t *cmd_tbl, uint16_t cmd_num);

头文件

#include <middleware/utils/diag.h>

功能说明

• 注册diag应答处理函数到DIAG子系统
• 应答注册表必须声明为常量数组并传入此接口
• 注册后DIAG客户端的应答报文将路由到对应的处理函数

前置条件

• DIAG子系统已初始化完成
• cmd_tbl不为NULL，且指向的命令表已正确填充

入参

名称	参数类型	详细说明	约束取值范围
cmd_tbl	const diag_cmd_reg_obj_t *	注册应答表指针	不为NULL
cmd_num	uint16_t	应答个数	大于0

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x0)	注册成功	应答表注册成功
ERRCODE_FAIL(0xFFFFFFFF)	注册失败	注册失败

uapi_diag_run_cmd

diag_run_cmd uapi diag run cmd uapi_diag_run_cmd

函数声明

errcode_t uapi_diag_run_cmd(uint16_t cmd_id, uint8_t *data, uint16_t data_size, diag_option_t *option);

头文件

#include <middleware/utils/diag.h>

功能说明

• 根据命令ID执行对应的diag命令处理函数
• 通过option参数识别报文是本地报文还是远端报文
• 命令ID需在已注册的命令表范围内

前置条件

• DIAG子系统已初始化完成
• 命令ID对应的处理函数已通过uapi_diag_register_cmd注册

入参

名称	参数类型	详细说明	约束取值范围
cmd_id	uint16_t	命令ID	在已注册命令表的min_id~max_id范围内
data	uint8_t *	数据内容	-
data_size	uint16_t	数据大小（单位：字节）	-
option	diag_option_t *	option选项，识别本地/远端报文	-

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x0)	执行成功	命令ID匹配且处理函数执行成功
ERRCODE_FAIL(0xFFFFFFFF)	执行失败	命令ID未匹配到处理函数

uapi_diag_register_stat_obj

diag_register_stat_obj uapi diag register stat obj uapi_diag_register_stat_obj

函数声明

errcode_t uapi_diag_register_stat_obj(const diag_sys_stat_obj_t *stat_obj_tbl, uint16_t obj_num);

头文件

#include <middleware/utils/diag.h>

功能说明

• 注册统计量对象到DIAG子系统，注册后可通过DIAG命令查询统计量数据
• 统计量注册表必须声明为常量数组并传入此接口
• 注册过程中会进行中断锁定保护，保证并发安全

前置条件

• DIAG子系统已初始化完成
• stat_obj_tbl不为NULL，且指向的统计量表已正确填充id、array_cnt、stat_packet_size和stat_packet字段

入参

名称	参数类型	详细说明	约束取值范围
stat_obj_tbl	const diag_sys_stat_obj_t *	统计量注册表指针	不为NULL
obj_num	uint16_t	统计量个数	大于0

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x0)	注册成功	统计量表校验通过且有空闲槽位
ERRCODE_FAIL(0xFFFFFFFF)	注册失败	无空闲槽位

Structures

diag_option_t

typedef struct {
    diag_addr peer_addr;        /*!< 地址 */
    uint8_t pad[3];             /*!< 预留字段 */
} diag_option_t;

成员说明

成员名称	数据类型	描述
peer_addr	diag_addr	对端地址
pad	uint8_t[3]	预留字段

diag_cmd_reg_obj_t

typedef struct {
    uint16_t min_id;               /*!< Diag最小命令ID */
    uint16_t max_id;               /*!< Diag最大命令ID */
    diag_cmd_f fn_input_cmd;      /*!< Diag命令处理函数 */
} diag_cmd_reg_obj_t;

成员说明

成员名称	数据类型	描述
min_id	uint16_t	Diag最小命令ID
max_id	uint16_t	Diag最大命令ID
fn_input_cmd	diag_cmd_f	Diag命令处理函数

diag_sys_stat_obj_t

typedef struct {
    uint16_t id;                 /*!< 统计量ID */
    uint16_t array_cnt;          /*!< 统计量数量 */
    uint32_t stat_packet_size;   /*!< 每个统计量的大小 */
    void *stat_packet;           /*!< 指向统计量的指针 */
} diag_sys_stat_obj_t;

成员说明

成员名称	数据类型	描述
id	uint16_t	统计量ID
array_cnt	uint16_t	统计量数量
stat_packet_size	uint32_t	每个统计量的大小（单位：字节）
stat_packet	void *	指向统计量的指针

Type definitions

diag_addr

typedef uint8_t diag_addr;

使用说明

用于diag_option_t结构体的peer_addr成员，标识对端地址。

diag_cmd_f

typedef errcode_t (*diag_cmd_f)(uint16_t cmd_id, void *cmd_param, uint16_t cmd_param_size, diag_option_t *option);

使用说明

用于diag_cmd_reg_obj_t结构体的fn_input_cmd成员，作为diag命令处理函数指针类型。

调用时机

当DIAG子系统收到DIAG客户端下发的命令且命令ID落在已注册的min_id~max_id范围内时，由DIAG子系统回调调用。

Macros

DIAG_OPTION_INIT_VAL

#define DIAG_OPTION_INIT_VAL {0, {0, 0, 0}}