transmit

transmit模块提供数据传输功能，支持文件、内存、Flash和OTA升级包等多种传输类型，支持上位机与下位机之间的上行和下行数据传输，并提供传输回调机制和自定义消息处理能力。

头文件清单

#include <middleware/utils/transmit.h>

接口清单

接口名称	功能简述
uapi_transmit_init	初始化数据传输模块
uapi_transmit_deinit	去初始化数据传输模块
uapi_transmit_host_start	作为上位机启动一次传输
uapi_transmit_host_stop	作为上位机主动停止传输
uapi_transmit_device_stop	作为下位机停止所有传输
uapi_transmit_device_register_result_hook	统一使用uapi_transmit_device_register_hook注册回调函数，本函数逐步废弃
uapi_transmit_device_register_hook	作为下位机注册传输回调函数
uapi_transmit_register_msg_proc_hook	注册用户自定义的传输消息处理函数
uapi_transmit_unregister_msg_proc_hook	去注册用户自定义的传输消息处理函数

Functions

uapi_transmit_init

函数声明

errcode_t uapi_transmit_init(void);

头文件清单

#include <middleware/utils/transmit.h>

功能说明

初始化数据传输模块，完成传输控制块清零、定时器初始化、DIAG服务注册等操作
作为数据传输模块的初始化入口，其他传输接口基于本接口完成后的状态运行
重复调用时若模块已初始化则直接返回成功，不会重复初始化

前置条件

DIAG模块已初始化完成，DIAG服务可用
传输模块未被初始化，或已通过uapi_transmit_deinit去初始化

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	初始化成功
Other	其他错误码，参考errcode_t	定时器初始化失败或DIAG服务注册失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DFX_SUPPORT_TRANSMIT_FILE	功能宏	支持数据传输功能	n(核心为APPS时为y)

uapi_transmit_deinit

函数声明

errcode_t uapi_transmit_deinit(void);

头文件清单

#include <middleware/utils/transmit.h>

功能说明

去初始化数据传输模块，停止所有传输任务，释放缓冲区，注销DIAG服务，清零传输控制块
调用后传输模块不可用，如需再次使用须重新调用uapi_transmit_init初始化
若模块未初始化则直接返回成功

前置条件

传输模块已通过uapi_transmit_init初始化完成

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	去初始化成功
Other	其他错误码，参考errcode_t	内部操作失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DFX_SUPPORT_TRANSMIT_FILE	功能宏	支持数据传输功能	n(核心为APPS时为y)

uapi_transmit_host_start

函数声明

errcode_t uapi_transmit_host_start(transmit_type_t transmit_type, uint16_t channel_id, transmit_cfg_info_t *cfg_info, transmit_callback_t *callback);

头文件清单

#include <middleware/utils/transmit.h>

功能说明

作为上位机启动一次传输，不论上行还是下行均由上位机启动
支持文件、内存、Flash、OTA升级包等多种传输类型，通过transmit_type参数指定
传输过程中通过callback回调函数通知传输结果、进度、启动等事件
使用此函数需打开CONFIG_DFX_SUPPORT_DIAG_UP_MACHINE宏

前置条件

传输模块已通过uapi_transmit_init初始化完成
CONFIG_DFX_SUPPORT_DIAG_UP_MACHINE宏已开启
DIAG连接已建立，channel_id对应的通道可用

入参

名称	参数类型	详细说明	约束取值范围
transmit_type	transmit_type_t	传输类型	- TRANSMIT_TYPE_FILE_UPSTREAM - TRANSMIT_TYPE_RESERVED - TRANSMIT_TYPE_FILE_DOWNSTREAM - TRANSMIT_TYPE_OTA_IMG_DOWNSTREAM - TRANSMIT_TYPE_MEMORY_UPSTREAM - TRANSMIT_TYPE_MEMORY_DOWNSTREAM - TRANSMIT_TYPE_FLASH_UPSTREAM - TRANSMIT_TYPE_FLASH_DOWNSTREAM - TRANSMIT_TYPE_OTA_IMG_UPSTREAM
channel_id	uint16_t	传输所使用的通道ID	参考 diag_frame_fid_t
cfg_info	transmit_cfg_info_t *	要传输的数据的配置信息（如文件名、地址、长度等）	非NULL
callback	transmit_callback_t *	传输回调函数	非NULL

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	传输请求成功发起
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	cfg_info或callback为NULL，或transmit_type超出有效范围
ERRCODE_NOT_SUPPORT(0x80000002)	不支持	CONFIG_DFX_SUPPORT_DIAG_UP_MACHINE未开启
ERRCODE_MALLOC(0x80000005)	内存分配失败	内存不足，无法分配参数结构体

参考案例

middleware/utils/dfx/diag/diag_system_cmd/diag_cmd_dfx_case.c

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DFX_SUPPORT_TRANSMIT_FILE	功能宏	支持数据传输功能	n(核心为APPS时为y)
CONFIG_DFX_SUPPORT_DIAG_UP_MACHINE	功能宏	支持上位机传输功能	n

uapi_transmit_host_stop

函数声明

errcode_t uapi_transmit_host_stop(transmit_type_t transmit_type, uint16_t channel_id);

头文件清单

#include <middleware/utils/transmit.h>

功能说明

作为上位机主动停止传输，上位机可在传输过程中主动停止指定类型和通道的传输
使用此函数需打开CONFIG_DFX_SUPPORT_DIAG_UP_MACHINE宏
若指定类型和通道不存在匹配的传输项，返回参数无效错误

前置条件

传输模块已通过uapi_transmit_init初始化完成
CONFIG_DFX_SUPPORT_DIAG_UP_MACHINE宏已开启
已通过uapi_transmit_host_start启动了对应类型和通道的传输

入参

名称	参数类型	详细说明	约束取值范围
transmit_type	transmit_type_t	传输类型	- TRANSMIT_TYPE_FILE_UPSTREAM - TRANSMIT_TYPE_RESERVED - TRANSMIT_TYPE_FILE_DOWNSTREAM - TRANSMIT_TYPE_OTA_IMG_DOWNSTREAM - TRANSMIT_TYPE_MEMORY_UPSTREAM - TRANSMIT_TYPE_MEMORY_DOWNSTREAM - TRANSMIT_TYPE_FLASH_UPSTREAM - TRANSMIT_TYPE_FLASH_DOWNSTREAM - TRANSMIT_TYPE_OTA_IMG_UPSTREAM
channel_id	uint16_t	传输所使用的通道ID	参考 diag_frame_fid_t

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	停止传输请求成功发起
ERRCODE_NOT_SUPPORT(0x80000002)	不支持	CONFIG_DFX_SUPPORT_DIAG_UP_MACHINE未开启

参考案例

middleware/utils/dfx/diag/diag_system_cmd/diag_cmd_dfx_case.c

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DFX_SUPPORT_TRANSMIT_FILE	功能宏	支持数据传输功能	n(核心为APPS时为y)
CONFIG_DFX_SUPPORT_DIAG_UP_MACHINE	功能宏	支持上位机传输功能	n

uapi_transmit_device_stop

函数声明

errcode_t uapi_transmit_device_stop(void);

头文件清单

#include <middleware/utils/transmit.h>

功能说明

作为下位机主动停止所有传输，在正常传输流程中传输停止由上位机控制，但在特殊情况下（如连接中断）下位机可主动停止
停止下位机上的所有传输任务，包括源端和目的端

前置条件

传输模块已通过uapi_transmit_init初始化完成
存在正在进行的传输任务或需要清理的传输项

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	停止所有传输成功
Other	其他错误码，参考errcode_t	内部操作失败

参考案例

middleware/utils/dfx/diag/diag_system_cmd/diag_cmd_dfx_case.c

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DFX_SUPPORT_TRANSMIT_FILE	功能宏	支持数据传输功能	n(核心为APPS时为y)

uapi_transmit_device_register_result_hook

函数声明

errcode_t uapi_transmit_device_register_result_hook(transmit_callback_t *callback);

头文件清单

#include <middleware/utils/transmit.h>

功能说明

统一使用uapi_transmit_device_register_hook注册回调函数，本函数逐步废弃
内部直接调用uapi_transmit_device_register_hook实现

前置条件

传输模块已通过uapi_transmit_init初始化完成
callback指针非NULL

入参

名称	参数类型	详细说明	约束取值范围
callback	transmit_callback_t *	传输回调函数	非NULL

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	注册成功
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	callback为NULL

参考案例

middleware/utils/dfx/diag/diag_system_cmd/diag_cmd_dfx_case.c

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DFX_SUPPORT_TRANSMIT_FILE	功能宏	支持数据传输功能	n(核心为APPS时为y)

uapi_transmit_device_register_hook

函数声明

errcode_t uapi_transmit_device_register_hook(transmit_callback_t *callback);

头文件清单

#include <middleware/utils/transmit.h>

功能说明

作为下位机注册传输回调函数，包括传输结果回调、进度上报回调、传输开始回调
注册的回调函数在下位机接收到传输数据时被调用
重复注册会覆盖之前的回调函数

前置条件

传输模块已通过uapi_transmit_init初始化完成
callback指针非NULL

入参

名称	参数类型	详细说明	约束取值范围
callback	transmit_callback_t *	传输回调函数	非NULL

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	注册成功
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	callback为NULL

参考案例

middleware/chips/3322/dfx/dfx_channel.c

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DFX_SUPPORT_TRANSMIT_FILE	功能宏	支持数据传输功能	n(核心为APPS时为y)

uapi_transmit_register_msg_proc_hook

函数声明

errcode_t uapi_transmit_register_msg_proc_hook(uint32_t msg_id_start, uint32_t msg_id_end, transmit_msg_proc_hook hook);

头文件清单

#include <middleware/utils/transmit.h>

功能说明

注册用户自定义的传输消息处理函数，用于在传输线程中添加自定义消息及处理函数
使用此函数需打开CONFIG_DFX_SUPPORT_TRANSMIT_FILE_HOOK宏，且必须单独创建传输线程，不能复用dfx_msg线程
消息ID范围不能与已注册的范围重叠，最多支持注册10个消息处理函数

前置条件

传输模块已通过uapi_transmit_init初始化完成
CONFIG_DFX_SUPPORT_TRANSMIT_FILE_HOOK宏已开启
传输线程已单独创建，未复用dfx_msg线程

入参

名称	参数类型	详细说明	约束取值范围
msg_id_start	uint32_t	自定义消息的起始ID	小于msg_id_end
msg_id_end	uint32_t	自定义消息的结束ID	大于msg_id_start
hook	transmit_msg_proc_hook	自定义消息处理函数	非NULL

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	注册成功
ERRCODE_FAIL(0xFFFFFFFF)	执行失败	msg_id_start >= msg_id_end、hook为NULL、消息ID范围重叠或注册数量已满
ERRCODE_NOT_SUPPORT(0x80000002)	不支持	CONFIG_DFX_SUPPORT_TRANSMIT_FILE_HOOK未开启

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DFX_SUPPORT_TRANSMIT_FILE	功能宏	支持数据传输功能	n(核心为APPS时为y)
CONFIG_DFX_SUPPORT_TRANSMIT_FILE_HOOK	功能宏	支持文件传输回调功能	y

uapi_transmit_unregister_msg_proc_hook

函数声明

errcode_t uapi_transmit_unregister_msg_proc_hook(transmit_msg_proc_hook hook);

头文件清单

#include <middleware/utils/transmit.h>

功能说明

去注册用户自定义的传输消息处理函数，用于移除已注册的自定义处理函数
使用此函数需打开CONFIG_DFX_SUPPORT_TRANSMIT_FILE_HOOK宏
若指定hook未注册则返回失败

前置条件

传输模块已通过uapi_transmit_init初始化完成
CONFIG_DFX_SUPPORT_TRANSMIT_FILE_HOOK宏已开启
hook对应的处理函数已通过uapi_transmit_register_msg_proc_hook注册

入参

名称	参数类型	详细说明	约束取值范围
hook	transmit_msg_proc_hook	自定义消息处理函数	已注册的有效hook

返回值

返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	去注册成功
ERRCODE_FAIL(0xFFFFFFFF)	执行失败	指定hook未注册
ERRCODE_NOT_SUPPORT(0x80000002)	不支持	CONFIG_DFX_SUPPORT_TRANSMIT_FILE_HOOK未开启

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DFX_SUPPORT_TRANSMIT_FILE	功能宏	支持数据传输功能	n(核心为APPS时为y)
CONFIG_DFX_SUPPORT_TRANSMIT_FILE_HOOK	功能宏	支持文件传输回调功能	y

Type definitions

transmit_result_hook

typedef errcode_t (*transmit_result_hook)(errcode_t result, uintptr_t usr_data);

使用说明

作为transmit_callback_t的result_hook成员类型，用于传输结果回调

调用时机

传输完成时由传输模块调用，通过result参数传递传输结果

transmit_start_hook

typedef errcode_t (*transmit_start_hook)(uint16_t channel_id, uintptr_t usr_data);

使用说明

作为transmit_callback_t的start_hook成员类型，用于传输开始回调

调用时机

传输开始时由传输模块调用，通过channel_id参数传递传输通道ID

transmit_msg_proc_hook

typedef errcode_t (*transmit_msg_proc_hook)(uint32_t msg_id, const uint8_t *msg, uint32_t msg_len);

使用说明

作为uapi_transmit_register_msg_proc_hook和uapi_transmit_unregister_msg_proc_hook的hook参数类型，用于自定义消息处理

调用时机

在传输线程中收到自定义消息时调用，通过msg_id传递消息ID，msg传递消息内容，msg_len传递消息长度

transmit_report_schedule_hook

typedef errcode_t (*transmit_report_schedule_hook)(const uint32_t progress, uintptr_t schedule_usr_data);

使用说明

作为transmit_callback_t的schedule_hook成员类型，用于传输进度上报回调

调用时机

传输进度更新时由传输模块调用，通过progress参数传递当前进度

Enumerations

transmit_type_t

typedef enum {
    TRANSMIT_TYPE_FILE_UPSTREAM      = 0,
    TRANSMIT_TYPE_RESERVED           = 1,
    TRANSMIT_TYPE_FILE_DOWNSTREAM    = 2,
    TRANSMIT_TYPE_OTA_IMG_DOWNSTREAM = 3,
    TRANSMIT_TYPE_MEMORY_UPSTREAM    = 4,
    TRANSMIT_TYPE_MEMORY_DOWNSTREAM  = 5,
    TRANSMIT_TYPE_FLASH_UPSTREAM     = 6,
    TRANSMIT_TYPE_FLASH_DOWNSTREAM   = 7,
    TRANSMIT_TYPE_OTA_IMG_UPSTREAM   = 8,
    TRANSMIT_TYPE_MAX,
} transmit_type_t;

枚举成员	取值	描述
TRANSMIT_TYPE_FILE_UPSTREAM	0	文件数据上行(下位机->上位机)，即下位机作为源端(读文件)
TRANSMIT_TYPE_RESERVED	1	保留类型(为兼容旧的工具而保留)
TRANSMIT_TYPE_FILE_DOWNSTREAM	2	文件数据下行(上位机->下位机)，即下位机作为目的端(写文件)
TRANSMIT_TYPE_OTA_IMG_DOWNSTREAM	3	升级包数据下行(上位机->下位机)，即下位机作为目的端(写升级包)
TRANSMIT_TYPE_MEMORY_UPSTREAM	4	内存数据上行(下位机->上位机)，即下位机作为源端(读内存)
TRANSMIT_TYPE_MEMORY_DOWNSTREAM	5	内存数据下行(上位机->下位机)，即下位机作为目的端(写内存)
TRANSMIT_TYPE_FLASH_UPSTREAM	6	Flash数据上行(下位机->上位机)，即下位机作为源端(读Flash)
TRANSMIT_TYPE_FLASH_DOWNSTREAM	7	Flash数据下行(上位机->下位机)，即下位机作为目的端(写Flash)
TRANSMIT_TYPE_OTA_IMG_UPSTREAM	8	升级包数据上行(下位机->上位机)，即下位机作为源端(读升级包)
TRANSMIT_TYPE_MAX	9	传输类型数量

Structures

transmit_addr_info

typedef struct {
    uintptr_t host_start_addr;
    uintptr_t device_start_addr;
} transmit_addr_info;

成员说明

成员名称	数据类型	描述
host_start_addr	uintptr_t	上位机上的Flash或memory数据的起始地址
device_start_addr	uintptr_t	下位机上的Flash或memory数据的起始地址

transmit_file_info

typedef struct {
    const char *host_file_name;
    const char *device_file_name;
} transmit_file_info;

成员说明

成员名称	数据类型	描述
host_file_name	const char *	上位机上的文件名称（包含路径）
device_file_name	const char *	下位机上文件名称（包含路径）

transmit_cfg_info_t

typedef struct {
    union {
        transmit_addr_info addr_info;
        transmit_file_info file_info;
    } data;
    uint32_t total_size;
    uint16_t data_block_number;
    uint16_t data_block_size;
    bool re_transmit;
} transmit_cfg_info_t;

成员说明

成员名称	数据类型	描述
data.addr_info	transmit_addr_info	Flash或memory数据地址信息
data.file_info	transmit_file_info	文件名称信息
total_size	uint32_t	要传输的数据长度
data_block_number	uint16_t	每组传输次数，0表示默认值DEFAULT_TRANSMIT_BLOCK_NUMBER(8)
data_block_size	uint16_t	每次传输数据大小，0表示默认值DEFAULT_TRANSMIT_BLOCK_SIZE(0x100)
re_transmit	bool	是否需要断点续传

transmit_callback_t

typedef struct {
    transmit_result_hook result_hook;
    uintptr_t result_usr_data;
    transmit_report_schedule_hook schedule_hook;
    uintptr_t schedule_usr_data;
    transmit_start_hook start_hook;
    uintptr_t start_usr_data;
} transmit_callback_t;

成员说明

成员名称	数据类型	描述
result_hook	transmit_result_hook	传输结果回调函数
result_usr_data	uintptr_t	传输结果回调函数用户数据
schedule_hook	transmit_report_schedule_hook	传输进度向上位机上报回调函数
schedule_usr_data	uintptr_t	传输进度向上位机上报回调函数用户数据
start_hook	transmit_start_hook	传输开始回调函数
start_usr_data	uintptr_t	传输开始回调函数用户数据