3. 摄像头驱动核心数据结构：struct video_device、struct v4l2_device、struct vb2_queue

在摄像头驱动开发中，三个核心数据结构构成了驱动与 V4L2 框架交互的基石：struct video_device 负责用户空间设备节点与文件操作，struct v4l2_device 负责顶层设备管理与子设备注册，struct vb2_queue 负责视频缓冲区的分配、管理与流控制。理解这三者的职责与协作关系，是编写稳定、可调试摄像头驱动的第一步。

3.1 struct video_device：用户空间与内核的桥梁

struct video_device 是 V4L2 框架中面向用户空间的核心结构体。它封装了设备节点（如 /dev/video0）的创建、文件操作函数集（v4l2_file_operations）以及设备能力信息。

3.1.1 结构体关键字段

3.1.2 初始化与注册流程

1. 分配与零初始化： 使用 video_device_alloc() 或静态分配后调用 v4l2_device_register()。
2. 设置 fops： 填充 v4l2_file_operations 结构体，至少实现 open、release、unlocked_ioctl。
3. 关联 v4l2_device： 将 v4l2_dev 指针指向已注册的顶层设备。
4. 关联 vb2_queue： 将 queue 指针指向已初始化的缓冲区队列。
5. 注册设备节点： 调用 video_register_device()，指定设备类型（如 VFL_TYPE_VIDEO）。

// 示例：video_device 初始化与注册
struct video_device *vdev;
struct v4l2_device *v4l2_dev;
struct vb2_queue *queue;

vdev = video_device_alloc();
if (!vdev)
    return -ENOMEM;

vdev->fops       = &camera_fops;
vdev->v4l2_dev   = v4l2_dev;
vdev->queue      = queue;
vdev->device_caps = V4L2_CAP_VIDEO_CAPTURE | V4L2_CAP_STREAMING;
strscpy(vdev->name, "camera-sensor0", sizeof(vdev->name));
vdev->release    = video_device_release;

ret = video_register_device(vdev, VFL_TYPE_VIDEO, -1);
if (ret) {
    video_device_release(vdev);
    return ret;
}

3.2 struct v4l2_device：顶层设备管理容器

struct v4l2_device 是 V4L2 驱动中的顶层管理结构体，负责协调多个子设备（如传感器、ISP、DMA 引擎）以及提供统一的调试接口。它通常嵌入在驱动自定义的全局设备结构体中。

3.2.1 结构体关键字段

3.2.2 注册与生命周期

1. 初始化： 调用 v4l2_device_register(struct device *parent, struct v4l2_device *v4l2_dev)。
2. 注册子设备： 通过 v4l2_device_register_subdev() 将传感器、ISP 等子设备加入链表。
3. 注销： 调用 v4l2_device_unregister()，自动注销所有子设备。

// 示例：v4l2_device 初始化
struct v4l2_device v4l2_dev;

// 嵌入在驱动私有结构体中
struct camera_device {
    struct v4l2_device v4l2_dev;
    struct video_device vdev;
    struct vb2_queue queue;
    // ... 其他驱动字段
};

static int camera_probe(struct platform_device *pdev)
{
    struct camera_device *cam;
    int ret;

    cam = devm_kzalloc(&pdev->dev, sizeof(*cam), GFP_KERNEL);
    if (!cam)
        return -ENOMEM;

    // 注册顶层 v4l2_device
    ret = v4l2_device_register(&pdev->dev, &cam->v4l2_dev);
    if (ret)
        return ret;

    // 后续初始化 video_device 和 vb2_queue ...
}

3.3 struct vb2_queue：视频缓冲区管理引擎

struct vb2_queue 是 V4L2 框架中负责缓冲区分配、入队、出队和流控制的引擎。它屏蔽了底层内存管理细节（用户态指针、DMA 连续、分散/聚集），为驱动提供统一的缓冲区操作接口。

3.3.1 结构体关键字段

3.3.2 核心回调函数

// 示例：vb2_queue 初始化与 ops 注册
static const struct vb2_ops camera_qops = {
    .queue_setup      = camera_queue_setup,
    .buf_prepare      = camera_buf_prepare,
    .buf_queue        = camera_buf_queue,
    .start_streaming  = camera_start_streaming,
    .stop_streaming   = camera_stop_streaming,
    .wait_prepare     = vb2_ops_wait_prepare,
    .wait_finish      = vb2_ops_wait_finish,
};

static int camera_init_queue(struct camera_device *cam)
{
    struct vb2_queue *q = &cam->queue;

    q->type            = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    q->io_modes        = VB2_MMAP | VB2_USERPTR | VB2_DMABUF;
    q->ops             = &camera_qops;
    q->mem_ops         = &vb2_dma_contig_memops;
    q->buf_struct_size = sizeof(struct camera_buffer);
    q->min_buffers_needed = 2;
    q->drv_priv        = cam;
    q->timestamp_flags = V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC;

    return vb2_queue_init(q);
}

3.4 三者协作关系：从设备打开到帧数据投递

下图展示了用户空间打开设备、请求缓冲区、启动流、投递帧数据的完整路径中，三个核心结构体的协作关系。

3.5 调试日志系统设计建议

基于上述三个核心结构体，建议在驱动中按以下层次部署调试日志：

• 设备节点层（video_device）： 在 open、release、ioctl 入口记录操作类型、参数和返回值。使用 dev_dbg(vdev->v4l2_dev->dev, ...) 确保日志关联到正确设备。
• 设备管理层（v4l2_device）： 在子设备注册/注销、控制参数变更时记录。使用 v4l2_info() 或 v4l2_dbg() 宏统一输出格式。
• 数据流层（vb2_queue）： 在 buf_queue、start_streaming、stop_streaming、buf_done 回调中记录缓冲区索引、状态和时间戳。使用 vb2_buffer_state() 辅助打印状态枚举。