5.6. 视频接入 - VIN

5.6.1. 模块描述

  • VIN 模块属于 HBN 框架的一部分, 包含 4 个 MIPI RX 和 4 个 SIF。

  • VIN 模块作为 HBN 框架的一个 Vnode,可以和其他 Vnode 连接起来形成 Vflow。

  • VIN 支持的参数规格,请参考 MIPI 基础规格 章节。

5.6.1.1. VIN 使用场景

VIN 支持 Offline 和 Online 连接到 ISP 模块, ISP 模块的 Pipeline 是时分复用的。

  • Offline 模式:Camera 通过 VIN Offline 连接到 ISP。

image-20250113-204225.png

  • Online 模式: Camera 通过 VIN Online 连接到 ISP。

image-20250113-204335.png

5.6.1.2. 场景推荐

  • 单路 Camera Sensor 场景下, VIN 到 ISP 的连接方式:优先选用 Online 模式,支持 Offline 模式。

  • 多路 Camera Sensor 场景下, VIN 到 ISP 的连接方式:只能选用 Offline 模式。

5.6.2. 参考示例

  • VIN 接入部分示例代码可以参考 sample_vin 章节

5.6.3. API 参考

API 接口 接口功能
hbn_vnode_open 打开 vnode
hbn_vnode_close 关闭 vnode
hbn_vnode_set_attr 设置 vnode 属性
hbn_vnode_set_ochn_attr 设置 VIN vnode 输出通道属性
hbn_vnode_get_ochn_attr 获取 VIN vnode 输出通道属性
hbn_vnode_set_ichn_attr 设置 VIN vnode 输入通道属性
hbn_vnode_get_ichn_attr 获取 VIN vnode 输入通道属性
hbn_vnode_set_ochn_buf_attr 设置 VIN vnode 输出 buffer 属性
hbn_vnode_start 启动 vnode
hbn_vnode_stop 停止 vnode
hbn_vnode_getframe 从 vnode 获取帧数据
hbn_vnode_sendframe 将帧数据传入 vnode
hbn_vnode_releaseframe 释放帧数据

5.6.4. 接口说明

5.6.4.1. hbn_vnode_open

【函数声明】

hobot_status hbn_vnode_open(hb_vnode_type vnode_type, uint32_t hw_id, int32_t ctx_id, hbn_vnode_handle_t *vnode_fd);

【功能描述】

初始化 vnode,打开 vnode 设备节点,并返回该模块的 vnode handle

【参数描述】

  • [IN] hb_vnode_type vnode_type : vnode 类型,对于 VIN,取值为 HB_VIN

  • [IN] uint32_t hw_id : 模块的硬件 id,对于 VIN,hw_id 取值为0

  • [IN] int32_t ctx_id : 模块的 context id,软件上的概念,可指定 context id 值,也可设置为 AUTO_ALLOC_ID,由 HBN 框架自动分配 context id

  • [OUT] hbn_vnode_handle_t *vnode_fd : 返回模块的 vnode handle

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

【兼容性】

硬件: X5

5.6.4.2. hbn_vnode_close

【函数声明】

void hbn_vnode_close(hbn_vnode_handle_t vnode_fd);

【功能描述】

关闭模块的设备节点。

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

【返回值】

【注意事项】

需要和 hbn_vnode_open 成对使用。

【兼容性】

硬件: X5

5.6.4.3. hbn_vnode_set_attr

【函数声明】

hobot_status hbn_vnode_set_attr(hbn_vnode_handle_t vnode_fd, void *attr);

【功能描述】

设置模块的基本属性。

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

  • [IN] void *attr:模块的基本属性结构体指针,对于 VIN,其属性结构体为 vin_attr_t

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

【兼容性】

硬件: X5

5.6.4.4. hbn_vnode_set_ochn_attr

【函数声明】

hobot_status hbn_vnode_set_ochn_attr(hbn_vnode_handle_t vnode_fd, uint32_t ochn_id, void *attr);

【功能描述】

设置模块的输出通道属性。

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

  • [IN] uint32_t ochn_id:模块的输出通道 id;

  • [IN] void *attr:模块的输出通道属性结构体指针。对于 VIN,输出通道属性结构体为 vin_ochn_attr_t

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

【兼容性】

硬件: X5

5.6.4.5. hbn_vnode_get_ochn_attr

【函数声明】

hobot_status hbn_vnode_get_ochn_attr(hbn_vnode_handle_t vnode_fd, uint32_t ochn_id, void *attr);

【功能描述】

获取模块的输出通道属性。

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

  • [IN] uint32_t ochn_id:模块的输出通道 id;

  • [OUT] void *attr:模块输出通道属性结构体指针。对于 VIN,输出通道属性结构体为 vin_ochn_attr_t

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

【兼容性】

硬件: X5

5.6.4.6. hbn_vnode_set_ichn_attr

【函数声明】

hobot_status hbn_vnode_set_ichn_attr(hbn_vnode_handle_t vnode_fd, uint32_t ichn_id, void *attr);

【功能描述】

设置模块的输入通道属性。

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

  • [IN] uint32_t ichn_id:模块的输入通道 id;

  • [IN] void *attr:模块的输入通道属性结构体指针。对于 VIN,输入通道属性结构体为 vin_ichn_attr_t

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

【兼容性】

硬件: X5

5.6.4.7. hbn_vnode_get_ichn_attr

【函数声明】

hobot_status hbn_vnode_get_ichn_attr(hbn_vnode_handle_t vnode_fd, uint32_t ichn_id, void *attr);

【功能描述】

获取模块的输入通道属性。

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

  • [IN] uint32_t ichn_id:模块的输入通道 id,对于 VIN,输入通道为0;

  • [OUT] void *attr:模块的输入通道属性结构体指针。对于 VIN,输入通道属性结构体为 vin_ichn_attr_t

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

【兼容性】

硬件: X5

5.6.4.8. hbn_vnode_set_ochn_buf_attr

【函数声明】

hobot_status hbn_vnode_set_ochn_buf_attr(hbn_vnode_handle_t vnode_fd, uint32_t ochn_id,
                     hbn_buf_alloc_attr_t *alloc_attr);

【功能描述】

设置输出通道 buffer 属性,包括 buffer 的数量以及 buffer 地址是否连续。

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

  • [IN] uint32_t ochn_id:模块的输出通道 id;

  • [IN] hbn_buf_alloc_attr_t *alloc_attr:buffer 分配属性;

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

【兼容性】

硬件: X5

5.6.4.9. hbn_vnode_start

【函数声明】

hobot_status hbn_vnode_start(hbn_vnode_handle_t vnode_fd);

【功能描述】

模块启动。

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

启动前需要先打开模块。

【兼容性】

硬件: X5

5.6.4.10. hbn_vnode_stop

【函数声明】

hobot_status hbn_vnode_stop(hbn_vnode_handle_t vnode_fd);

【功能描述】

模块停止。

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

【兼容性】

硬件: X5

5.6.4.11. hbn_vnode_getframe

【函数声明】

hobot_status hbn_vnode_getframe(hbn_vnode_handle_t vnode_fd, uint32_t ochn_id, uint32_t millisecondTimeout,
                hbn_vnode_image_t *out_img);

【功能描述】

获取模块输出通道的图像,阻塞型接口。

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

  • [IN] uint32_t ochn_id:模块的输出通道 id;

  • [IN] uint32_t millisecondTimeout:超时等待时间;

  • [OUT] hbn_vnode_image_t *out_img:输出图像 buffer 结构体地址;

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

【兼容性】

硬件: X5

5.6.4.12. hbn_vnode_sendframe

【函数声明】

hobot_status hbn_vnode_sendframe(hbn_vnode_handle_t vnode_fd, uint32_t ichn_id,
                 hbn_vnode_image_t *img);

【功能描述】

发送图像到模块的输入通道,会触发模块进行处理。阻塞型接口,等待硬件处理完再返回,默认超时时间为1秒

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

  • [IN] uint32_t ichn_id:模块的输入通道 id,对于 VIN,输入通道为0;

  • [IN] hbn_vnode_image_t *img:输入图像 buffer 地址;

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

【兼容性】

硬件: X5

5.6.4.13. hbn_vnode_releaseframe

【函数声明】

hobot_status hbn_vnode_releaseframe(hbn_vnode_handle_t vnode_fd, uint32_t ochn_id, hbn_vnode_image_t *img);

【功能描述】

释放图像 buffer,buffer 会归还到指定的输出通道。

【参数描述】

  • [IN] hbn_vnode_handle_t vnode_fd:模块的 vnode handle;

  • [IN] uint32_t ochn_id:模块的输出通道 id;

  • [IN] hbn_vnode_image_t *img:图像 buffer 结构体地址;

【返回值】

  • 成功,返回 HBN_STATUS_SUCESS 0

  • 失败:异常为负值错误码,参考返回值说明

【注意事项】

【兼容性】

硬件: X5

5.6.5. 数据结构

5.6.5.1. vin_attr_t

名称 类型 最小值 最大值 默认值 含义 必选
vin_node_attr vin_node_attr_t - - - vin node 属性描述
vin_attr_ex vin_attr_ex_t - - - vin node 增强属性描述
vin_ochn_attr[] vin_ochn_attr_t - - - vin node 输出通道属性描述
vin_ichn_attr vin_ichn_attr_t - - - vin node 输入通道属性描述
vin_ochn_buff_attr[] vin_ochn_buff_attr_t - - - vin node 输出 buffer 属性描述

5.6.5.2. vin_node_attr_t

名称 类型 最小值 最大值 默认值 含义 必选
cim_attr cim_attr_t - - - cim/sif 属性描述
lpwm_attr lpwm_attr_t - - - lpwm 属性描述,用于多 sensor 同步
vcon_attr vcon_attr_t - - - vcon 属性描述
flow_id uint32_t 0 - - pipeline id,可以不用设置

5.6.5.3. cim_attr_t

名称 类型 最小值 最大值 默认值 含义 必选
mipi_en uint32_t 0 1 0 使能 mipi,预留值,目前不需要配置
mipi_rx uint32_t 0 4 0 mipi rx 端口号
vc_index uint32_t 0 4 0 mipi virtual index
ipi_channel uint32_t 1 2 0 ipi channel number,
linear mode 为 1 ,
hdr dol2 mode 为 2
tpg_input cim_input_tpg_t - - - 预留使用
func cim_func_desc_t - - - cim/sif 高阶功能

5.6.5.4. cim_func_desc_t

名称 类型 最小值 最大值 默认值 含义 必选
enable_frame_id uint32_t 0 1 0 使能 frame id
set_init_frame_id uint32_t 0 - 0 frame id 初始赋值
time_stamp_en uint32_t - - - 使能时间戳
time_stamp_mode uint32_t 1 8 - 时间戳模式选择
1 :时间戳为 sensor 到达 sif 的时间
2 :时间戳 trigger 时间戳功能的时间,相当于 trigger source 的时间
其他:预留值
enable_pattern uint32_t - - - 预留值,无需使用
skip_frame uint32_t - - - 预留值,无需使用
input_fps uint32_t - - - 预留值,无需使用
output_fps uint32_t - - - 预留值,无需使用
skip_nums uint32_t - - - 预留值,无需使用
hw_extract_m uint32_t - - - 预留值,无需使用
hw_extract_n uint32_t - - - 预留值,无需使用
hdr_mode enum hdr_mode 0 2 0 设置值为 enum hdr_mode:
0: 无需 SoC ISP 做多帧合成
1: 需要 SoC 侧做两帧合成
2: 需要 SoC 侧做三帧合成(预留, X5 不支持)

5.6.5.5. vin_ochn_attr_t

名称 类型 最小值 最大值 默认值 含义 必选
ddr_en uint32_t 0 1 0 数据是否写到 DDR
roi_en uint32_t - - - 预留
emb_en uint32_t - - - 预留, sensor embedded data 是否写到 DDR
ochn_attr_type vin_ochn_attr_type_e - - - vin ochn 属性
VIN_BASIC_ATTR, // 默认,最基础的 vin 属性
VIN_EMB_ATTR,// sensor 带有 emb 输出
vin_basic_attr vin_basic_attr_t - - - vin basic 属性,下 ddr 需要设置
rawds_attr vin_rawds_attr_t - - - 预留
roi_attr vpm_commn_roi_data_desc - - - 预留
emb_attr vin_emb_attr_t - - - 预留, emb 需要设置

5.6.5.6. vin_basic_attr_t

名称 类型 最小值 最大值 默认值 含义 必选
pack_mode uint32_t - - - 预留
wstride uint32_t 0 - - cim/sif 下 ddr 的 wide stride, 16 字节对齐。
sensor raw8 为 width, raw10~raw16 为 2*width
vstride uint32_t - - - 预留
format uint32_t - - - 下 ddr 时需要设置

5.6.5.7. vin_ichn_attr_t

名称 类型 最小值 最大值 默认值 含义 必选
format uint32_t - - - vin format, sensor 输出 format
width uint32_t 0 8192 0 sensor 输出分辨率 宽度 pixel
height uint32_t 0 4096 0 sensor 输出分辨率 高度 pixel

5.6.5.8. vin_ochn_buff_attr_t

名称 类型 最小值 最大值 默认值 含义 必选
buffers_num uint32_t 0 - 0 cim/sif 下 ddr 的 buffer number,一般设置为 6
flags int64_t - - - 一般在程序设置为:
hbn_buf_alloc_attr_t.flags = HB_MEM_USAGE_CPU_READ_OFTEN 逻辑或
HB_MEM_USAGE_CPU_WRITE_OFTEN 逻辑或
HB_MEM_USAGE_CACHED

5.6.5.9. lpwm_attr_t

名称 类型 最小值 最大值 默认值 含义 必选
enable uint32_t 0 - 0 是否使能 LPWM
lpwm_chn_attr_t lpwm_chn_attr[LPWM_CHN_NUM] - - - - LPWM channel 属性配置
LPWM_CHN_NUM 值为 4

5.6.5.10. lpwm_chn_attr_t

名称 类型 最小值 最大值 默认值 含义 必选 输出 30hz,高电平 10us 参数
trigger_source uint32_t 0 10 0 触发源选择
0-3: pad_trigger_in,硬件 IO 输 入 PPS
4: enet_ptp_pps,预留
5: sw_trigger_in,软件触发
6: gps_trigger_in (TIME_SYNC2),硬件 IO 输入 PPS
7: mcu_trigger_in (TIME_SYNC1), 硬件 IO 输入 PPS
8: time_sync2_in (TIME_SYNC3),硬件 IO 输入 PPS
9: time_sync3_in (TIME_SYNC4),硬件 IO 输入 PPS
10: camera_1sec_pulse_out,预留
注:硬件 IO 对应的 pin 请在 pinlist 资料中查找。
trigger_mode uint32_t 0 1 0 触发机制 (1- 外界硬件触发, 0- 内部软件触发 )
trigger_mode 设置为 0 时,自动设置为软件触发,可以不选择 trigger_source
period uint32_t 2 us 1000000 us 0 周期,实际生效的周期时间为 (period + 1)us 33332
offset uint32_t 0 (1000000/period) us 0 源触发 LPWM 后, LPWM 经过 offset(us) 再输出方波。 11
时间生效的时间为: (1/24) * (offset * 24 + 3) us 向下取整。
duty_time uint32_t 0 (4096/period) us 0 有效高电平时间,实际生效的时间为 (duty_time + 1)us 9
threshold uint32_t 0 65535 us 0 缓慢同步功能阈值 0
adjust_step uint32_t 0 15 0 每次的调整时间 adjust_time = 2 ^ adjust_step 0

5.6.6. 返回值说明

错误码 宏定义 描述 常见原因及解决方法
0 HBN_STATUS_SUCESS 成功
1 HBN_STATUS_INVALID_NODE vnode 无效,找不到对应的 vnode
2 HBN_STATUS_INVALID_NODETYPE vnode 类型无效,找不到对应的 vnode 对于 VIN,vnode 类型为 HB_VIN
3 HBN_STATUS_INVALID_HWID 无效的硬件模块 id 对于 VIN,hw_id 取值为 0
4 HBN_STATUS_INVALID_CTXID 无效的 context id 可设置为 AUTO_ALLOC_ID,由 HBN 框架自动分配
5 HBN_STATUS_INVALID_OCHNID 无效的输出通道 id VIN 输出通道为 0
6 HBN_STATUS_INVALID_ICHNID 无效的输入通道 id VIN 仅支持1个输入通道
7 HBN_STATUS_INVALID_FORMAT 无效的格式
8 HBN_STATUS_INVALID_NULL_PTR 空指针
9 HBN_STATUS_INVALID_PARAMETER 无效的参数,版本检查失败
10 HBN_STATUS_ILLEGAL_ATTR 无效的参数
11 HBN_STATUS_INVALID_FLOW 无效的 flow,找不到对应的 flow
12 HBN_STATUS_FLOW_EXIST flow 已经存在
13 HBN_STATUS_FLOW_UNEXIST flow 不存在
14 HBN_STATUS_NODE_EXIST node 已经存在
15 HBN_STATUS_NODE_UNEXIST node 不存在
16 HBN_STATUS_NOT_CONFIG 预留
17 HBN_STATUS_CHN_NOT_ENABLED 通道未使能
18 HBN_STATUS_CHN_ALREADY_ENABLED 通道已使能
19 HBN_STATUS_ALREADY_BINDED node 已经绑定
20 HBN_STATUS_NOT_BINDED node 未绑定
21 HBN_STATUS_TIMEOUT 超时
22 HBN_STATUS_NOT_INITIALIZED 未初始化
23 HBN_STATUS_NOT_SUPPORT 通道不支持或未激活
24 HBN_STATUS_NOT_PERM 操作不允许
25 HBN_STATUS_NOMEM 内存不足
26 HBN_STATUS_INVALID_VNODE_FD 无效的 node 文件描述符
27 HBN_STATUS_INVALID_ICHNID_FD 无效的输入通道文件描述符
28 HBN_STATUS_INVALID_OCHNID_FD 无效的输出通道文件描述符
29 HBN_STATUS_OPEN_OCHN_FAIL 打开输出通道失败
30 HBN_STATUS_OPEN_ICHN_FAIL 打开输入通道失败
31 HBN_STATUS_JSON_PARSE_FAIL json 解析失败
32 HBN_STATUS_REQ_BUF_FAIL 请求 buffer 失败
33 HBN_STATUS_QUERY_BUF_FAIL 查询 buffer 信息失败
34 HBN_STATUS_SET_CONTROL_FAIL 模块控制、调节参数(如 ISP 效果参数)设置失败
35 HBN_STATUS_GET_CONTROL_FAIL 模块控制、调节参数(如 ISP 效果参数)获取失败
36 HBN_STATUS_NODE_START_FAIL node 开启失败
37 HBN_STATUS_NODE_STOP_FAIL node 停止失败
38 HBN_STATUS_NODE_POLL_ERROR node 通道 poll 错误
39 HBN_STATUS_NODE_POLL_TIMEOUT node 通道 poll 超时
40 HBN_STATUS_NODE_POLL_FRAME_DROP node 通道 poll 时发生丢帧
41 HBN_STATUS_NODE_POLL_HUP node 通道 poll 时描述符挂起
42 HBN_STATUS_NODE_ILLEGAL_EVENT node 通道 poll 时事件非法
43 HBN_STATUS_NODE_DEQUE_ERROR node 通道 dequeue buffer 错误
44 HBN_STATUS_ILLEGAL_BUF_INDEX 无效的 buffer 索引
45 HBN_STATUS_NODE_QUE_ERROR node 通道 queue buffer 错误
46 HBN_STATUS_FLUSH_FRAME_ERROR node 通道帧 flush 错误
47 HBN_STATUS_INIT_BIND_ERROR 用 json 解析并绑定时发生错误
48 HBN_STATUS_ADD_NODE_FAIL 向 flow 中添加 node 失败
49 HBN_STATUS_WRONG_CONFIG_ID 系统不支持的 node id
50 HBN_STATUS_BIND_NODE_FAIL flow 绑定 node 时发生错误
51 HBN_STATUS_INVALID_VERSION 底层驱动模块和上层库版本号不匹配错误
52 HBN_STATUS_GET_VERSION_ERROR 获取底层驱动模块版本号错误
53 HBN_STATUS_MEM_INIT_FAIL hbmem 内存初始化失败
54 HBN_STATUS_MEM_IMPORT_FAIL hbmem 内存引入失败
55 HBN_STATUS_MEM_FREE_FAIL hbmem 内存释放失败
56 HBN_STATUS_SYSFS_OPEN_FAIL 系统文件打开失败
57 HBN_STATUS_STRUCT_SIZE_NOT_MATCH hal 层结构体大小与 kernel 层不匹配
58 HBN_STATUS_RGN_UNEXIST 获取不到对应的 rgn 数据
59 HBN_STATUS_RGN_INVALID_OPERATION rgn 操作无效
60 HBN_STATUS_RGN_OPEN_FILE_FAIL rgn 模块打开文件失败
128 HBN_STATUS_ERR_UNKNOW 未知错误