4. V4L2 核心数据结构：struct video_device、struct v4l2_device、struct vb2_queue

在 V4L2 摄像头驱动中，三个核心数据结构构成了驱动框架的骨架：struct video_device 代表用户空间看到的设备节点，struct v4l2_device 是顶层管理容器，struct vb2_queue 负责视频缓冲区的管理与流转。理解这三者的关系与职责，是编写稳定、高效的摄像头驱动的第一步。

4.1 数据结构关系总览

下图展示了三个核心数据结构在驱动中的组织关系：

4.2 struct v4l2_device — 顶层容器

struct v4l2_device 是 V4L2 驱动的根对象，负责管理所有子设备、注册信息和全局状态。每个物理摄像头设备对应一个 v4l2_device 实例。

4.2.1 核心字段

4.2.2 初始化与注册

#include <media/v4l2-device.h>

struct v4l2_device v4l2_dev;

// 1. 初始化 v4l2_device
v4l2_device_init(&v4l2_dev, &pdev->dev);

// 2. 注册（通常在 probe 函数中）
v4l2_device_register(&pdev->dev, &v4l2_dev);

// 3. 注销（在 remove 函数中）
v4l2_device_unregister(&v4l2_dev);

4.3 struct video_device — 设备节点抽象

struct video_device 是用户空间通过 /dev/videoX 访问的接口抽象。它封装了文件操作、ioctl 处理和设备能力信息。

4.3.1 核心字段

4.3.2 注册流程

struct video_device vdev;

// 1. 分配并初始化 video_device
vdev = video_device_alloc();
if (!vdev)
    return -ENOMEM;

// 2. 设置文件操作和 ioctl 操作
vdev->fops = &my_fops;
vdev->ioctl_ops = &my_ioctl_ops;

// 3. 关联 v4l2_device 和 vb2_queue
vdev->v4l2_dev = &v4l2_dev;
vdev->queue = &vb2_q;

// 4. 设置设备能力
vdev->device_caps = V4L2_CAP_VIDEO_CAPTURE | V4L2_CAP_STREAMING;

// 5. 注册 video_device
video_register_device(vdev, VFL_TYPE_VIDEO, -1);

// 6. 注销（在 remove 中）
video_unregister_device(vdev);
video_device_release(vdev);

4.4 struct vb2_queue — 视频缓冲队列

struct vb2_queue 是 videobuf2 框架的核心，负责管理视频缓冲区的分配、入队、出队和 DMA 操作。它屏蔽了不同内存类型（V4L2_MEMORY_MMAP/USERPTR/DMABUF）的差异。

4.4.1 核心字段

4.4.2 struct vb2_ops 回调函数

4.4.3 初始化示例

struct vb2_queue vb2_q;

// 1. 初始化 vb2_queue 结构
vb2_q.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
vb2_q.io_modes = VB2_MMAP | VB2_USERPTR | VB2_DMABUF;
vb2_q.drv_priv = &my_dev;
vb2_q.buf_struct_size = sizeof(struct my_buffer);
vb2_q.ops = &my_vb2_ops;
vb2_q.mem_ops = &vb2_dma_contig_memops;
vb2_q.timestamp_flags = V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC;

// 2. 注册队列
vb2_queue_init(&vb2_q);

// 3. 关联到 video_device
vdev->queue = &vb2_q;

4.5 三者协作流程

下图展示了从用户空间请求到硬件 DMA 完成的完整数据流：

4.6 三者的关键差异对比

4.7 常见错误与避坑指南

4.8 本章小结

三个核心数据结构构成了 V4L2 摄像头驱动的基石：

• struct v4l2_device 作为顶层容器，管理设备生命周期和子设备。
• struct video_device 提供用户空间访问接口，封装文件操作和 ioctl。
• struct vb2_queue 负责缓冲区分配、DMA 传输和流控制。