v4l2的结构体之videobuf2(vb2)

桃扇骨 2022-11-10 14:57 457阅读 0赞

# v4l2的结构体之videobuf2(vb2) #

## 简介 ##

videobuf2 用于连接 V4L2 驱动层与用户空间层，提供数据交流的通道，它可以分配并管理视频帧数据。videobuf 层实现了很多 ioctl 函数，包括 buffer 分配、入队、出队和数据流控制。

详细说明请见：https://yellowmax.blog.csdn.net/article/details/81054611

## 数据类型 ##

不是所有的视频设备都使用同一种类型的 buffer，事实上，buffer 类型可以概括为三种：

*  buffer 在虚拟地址以及物理地址上面都是分散的。几乎所有的用户空间 buffer 都是这种类型，在内核空间中，这种类型的 buffer 并不总是能够满足需要，因为这要求硬件可以进行分散的 DMA 操作。
 *  物理地址分散，虚拟地址连续。也就是通过 vmalloc 分配的 buffer，换句话说很难使用 DMA 来操作这些buffer。
 *  物理地址连续（虚拟地址不关心）。在分段式系统上面分配这种类型的 buffer 是不可靠的（分段式-也即页式系统上面有可能在长时间运行之后内存出现大量碎片，从而导致连续的内存空间很难获得，所以说不可靠），但是简单 DMA 控制器只能够适用于这种类型的 buffer。也有分段式的 DMA 操作，不过那种需要用到 IOMMU 来实现。  
    这三种类型的 buffer 对应的相关操作函数分别对应于 videobuf2-dma-sg.c,videobuf2-vmalloc.c,videobuf2-dma-contig.c。  
    根据buffer的不同，，需要用到的内核头文件也不同：

<media/videobuf-dma-sg.h>		/* 物理地址分散 */
    <media/videobuf-vmalloc.h>		/* vmalloc() 分配的buffer */
    <media/videobuf-dma-contig.h>	/* 物理地址连续 */

## 定义 ##

struct vb2\_queue  
该结构体可以当做是 videobuf2 的一个整体的抽象，要想使用 videobuf2 这个模块，就去初始化一个 vb2\_queue 结构体吧，它会帮助我们建立起一个基于 videobuf2 的数据流管理模块的。

struct vb2_queue {
    	unsigned int			type;//v4l2_buf_type 枚举类型，表明设备的 buffer 类型
    	unsigned int			io_modes;//vb2_io_modes 枚举类型，表明驱动支持哪一种 streaming，实际应用中 VB2_MMAP 类型的居多
    	struct device			*dev;
    	unsigned long			dma_attrs;
    	unsigned			bidirectional:1;
    	unsigned			fileio_read_once:1;
    	unsigned			fileio_write_immediately:1;
    	unsigned			allow_zero_bytesused:1;
    	unsigned		   quirk_poll_must_check_waiting_for_buffers:1;
    
       //可以与 video_device 共用一个 lock，
       //更推荐使用独立的 lock，独立的 lock 一定程度上可以减少锁竞争
    	struct mutex			*lock;
    	void				*owner;
    
    	const struct vb2_ops		*ops;//指向 vb2_ops
       //根据 buffer 类型「物理连续、vmalloc、物理分散的 sg-dma」
       //选择 vb2_dma_contig_memops，vb2_dma_sg_memops,vb2_vmalloc_memops 三种之一，
       //与我来说，最常用的就是第一个啦，当然也可以自己动手丰衣足食，不过常规使用那三个就能够满足了
    	const struct vb2_mem_ops	*mem_ops;
    	const struct vb2_buf_ops	*buf_ops;
    
       //一般指向驱动特定的结构体，也就是驱动自定义维护的结构体
    	void				*drv_priv;
     
       //自定义的 buffer 结构体大小，
       //自定义的 buffer 结构体必须将 vb2_v4l2_buffer 成员放在第一个。
       //可以在 vb2 的 queue 回调中通过 container_of 
       //来获取自定义的buffer结构体数据
    	unsigned int			buf_struct_size;
     
       //V4L2_BUF_FLAG_TIMESTAMP_MASK 或者 V4L2_BUF_FLAG_TSTAMP_SRC_MASK 类型的 flag 之一，
       //两种 flag 可以是或的关系同时存在，表明时间戳的类型，
       //一般使用 V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC 即可，
       //表明是递增类型的，它是在内核的 monotonic 时钟时间轴上面生成的时间戳
    	u32				timestamp_flags;
    	gfp_t				gfp_flags;
    	u32				min_buffers_needed;
    
    	struct device			*alloc_devs[VB2_MAX_PLANES];
    
    	/* private: internal use only */
    	struct mutex			mmap_lock;
    	unsigned int			memory;
    	enum dma_data_direction		dma_dir;
     
       //代表每个buffer
    	struct vb2_buffer		*bufs[VB2_MAX_FRAME];
       //分配的buffer个数
    	unsigned int			num_buffers;
    
    	struct list_head		queued_list;
    	unsigned int			queued_count;
    
    	atomic_t			owned_by_drv_count;
    	struct list_head		done_list;
    	spinlock_t			done_lock;
    	wait_queue_head_t		done_wq;
    
    	unsigned int			streaming:1;
    	unsigned int			start_streaming_called:1;
    	unsigned int			error:1;
    	unsigned int			waiting_for_buffers:1;
    	unsigned int			waiting_in_dqbuf:1;
    	unsigned int			is_multiplanar:1;
    	unsigned int			is_output:1;
    	unsigned int			copy_timestamp:1;
    	unsigned int			last_buffer_dequeued:1;
    
    	struct vb2_fileio_data		*fileio;
    	struct vb2_threadio_data	*threadio;
    
    #ifdef CONFIG_VIDEO_ADV_DEBUG
    	/*
    	 * Counters for how often these queue-related ops are
    	 * called. Used to check for unbalanced ops.
    	 */
    	u32				cnt_queue_setup;
    	u32				cnt_wait_prepare;
    	u32				cnt_wait_finish;
    	u32				cnt_start_streaming;
    	u32				cnt_stop_streaming;
    #endif
    };

示例：

/* Initialize videobuf2 queue */
    	vidq->type			= V4L2_BUF_TYPE_VIDEO_CAPTURE;
    	vidq->io_modes			= VB2_MMAP | VB2_DMABUF;
    	vidq->drv_priv			= video;
    	vidq->buf_struct_size		= sizeof(struct sun6i_csi_buffer);
    	vidq->ops			= &sun6i_csi_vb2_ops;
    	vidq->mem_ops			= &vb2_dma_contig_memops;
    	vidq->timestamp_flags		= V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC;
    	vidq->lock			= &video->lock;
    	/* Make sure non-dropped frame */
    	vidq->min_buffers_needed	= 3;
    	vidq->dev			= csi->dev;
    
    	ret = vb2_queue_init(vidq);
    	if (ret) {
    		v4l2_err(&csi->v4l2_dev, "vb2_queue_init failed: %d\n", ret);
    		goto clean_entity;
    	}

上面一顿操作之后要记得使用 vb2\_queue\_init 对 vb2\_queue 进一步初始化，里面主要是一大堆的 WARN\_ON 来对我们的设置进行检查，获取 v4l2\_buf\_ops 这个 vb2\_buf\_ops 类型的 buffer 操作函数，并且初始化一些锁与一个等待队列，该等待队列主要是用来等待 buffer 变为可 dequeue 状态。

struct vb2_ops
    struct vb2_ops {
    	int (*queue_setup)(struct vb2_queue *q,
    			   unsigned int *num_buffers, unsigned int *num_planes,
    			   unsigned int sizes[], struct device *alloc_devs[]);
    
        //释放所有在 ioctl 操作函数执行时被持有的锁；
        //该回调在 ioctl 需要等待一个新的 buffer 到达的时候被调用；
        //需要在阻塞访问的时候避免死锁。
    	void (*wait_prepare)(struct vb2_queue *q);
     
       //请求所有的在上面 wait_prepare 回调锁释放的锁；
       //需要在睡眠等待新的 buffer 到来之后继续运行。
    	void (*wait_finish)(struct vb2_queue *q);
    
        //在 MMAP 方式下，分配完 buffer 或者 USERPTR 情况下请求完 buffer 之后被调用一次，
       //（一个 buffer 调用一次）。如果该 ioctl 返回失败，将会导致 queue_setup 执行失败。
       //该函数的主要目的是让我们在 buffer 申请完毕之后对 buffer 做一些初始化工作，但是实际上好像并不是经常用到。
       //在该函数里面可以获取到 buffer 的 type，memory 类型，index，planesnum 等
    	int (*buf_init)(struct vb2_buffer *vb);
    	
       //每次 buffer 重新入队「就是在用户调用 QBUF 的时候」以及 VIDIOC_PREPARE_BUF 操作的时候被调用，
       //驱动可以做一些硬件操作「通常数据都是由硬件产生的」之前的初始化工作。
       //如果该回调返回失败，那么 buffer 将不会执行 queue 动作。
       //一般在这里需要设置 plane 的 payload，也就是每个 plane 的使用内存长度，
       //单位为 Byte，可以使用 vb2_set_plane_payload 来帮助完成
       //「在 omap3isp 例程当中该回调函数里面获取 buffer 的 dma 地址，
       //然后赋值给 buffer->dma 成员」。
       int (*buf_prepare)(struct vb2_buffer *vb);
       
       //每次 buffer 被取出的时候被调用，
       //并且是在 buffer 到达用户空间之前，
       //所以驱动可以访问/修改 buffer 的内容。
    	void (*buf_finish)(struct vb2_buffer *vb);
     
       //buffer 被释放之前调用一次，
       //每个 buffer 仅有一次，驱动可以在这里面做一些额外的操作。
    	void (*buf_cleanup)(struct vb2_buffer *vb);
    
       //进入 streaming 状态时被调用一次，一般情况下，
       //驱动在该回调函数执行之前，通过 buf_queue 回调来接收 buffer，
       //这里驱动需要把 buffer 放到驱动自己维护的一个 buffer 队列里面。
       //count 参数存放已经被 queue 的 buffer 数量，驱动可以由此获取它。
       //如果发生硬件错误，驱动可以通过该回调返回一个错误，
       //此时所有的buffer都会被归还给 videobuf2（调用 vb2_buffer_done(VB2_BUF_STATE_QUEUED)）。
       //如果需要设置开始 start_streaming 需要的 buffer 最小数量，
       //比如驱动只有在满足 buffer 数量大于等于 3 的时候才能够开启数据流，
       //那么就可以在该函数被调用之前设置 vb2_queue->min_buffers_needed 成员为自己想要的值，
       //此时该回调函数会在满足最小 buffer 数量之后才被调用。
    	int (*start_streaming)(struct vb2_queue *q, unsigned int count);
     
       //在 streaming 被禁止的时候调用，驱动需要关掉 DMA 或者等待 DMA 结束，
       //调用 vb2_buffer_done 来归还所有驱动持有的 buffers
       //（参数使用 VB2_BUF_STATE_DONE 或者 VB2_BUF_STATE_ERR），
       //可能需要用到 vb2_wait_for_all_buffers 来等待所有的 buffer，
       //该函数是用来等待所有的 buffer 被归还给 videobuf2 的。
    	void (*stop_streaming)(struct vb2_queue *q);
    
       //用来传递 vb（vb2_buffer 结构体） 给驱动，
       //驱动可以在这里开启硬件操作（DMA 等等）。
       //驱动填充 buffer 完毕之后需要调用 vb2_buffer_done 归还 buffer，
       //该函数总是在 VIDIOC_STREAMON 操作之后调用。
       //但是也有可能在 VIDIOC_STREAMON 之前被调用，
       //比如用户空间中 querybuf 之后的 queue 操作。
       //videobuf2 允许自定义一个 buffer 结构体而不是直接使用 vb2_buffer，
       //但是自定义的结构体的第一个成员必须是 vb2_v4l2_buffer 结构体，
       //该结构体的大小需要在 vb2_queue 的 buf_struct_size 成员中指定。
    	void (*buf_queue)(struct vb2_buffer *vb);
    };

示例：

static const struct vb2_ops sun6i_csi_vb2_ops = {
    	.queue_setup		= sun6i_video_queue_setup,
    	.wait_prepare		= vb2_ops_wait_prepare,
    	.wait_finish		= vb2_ops_wait_finish,
    	.buf_prepare		= sun6i_video_buffer_prepare,
    	.start_streaming	= sun6i_video_start_streaming,
    	.stop_streaming		= sun6i_video_stop_streaming,
    	.buf_queue		= sun6i_video_buffer_queue,
    };