4. V4L2 文件操作接口：struct v4l2_file_operations

V4L2 框架通过标准的 Linux 文件操作接口（file_operations）与用户空间交互。struct v4l2_file_operations 是 V4L2 驱动开发者需要实现的核心回调集合，它封装了 open、release、ioctl、mmap、poll 等关键操作。本章将深入剖析每个回调的实现要点、数据流路径以及常见陷阱。

4.1 struct v4l2_file_operations 结构体解析

该结构体定义在 include/media/v4l2-dev.h 中，是 V4L2 设备节点（如 /dev/video0）的操作函数表。与通用的 struct file_operations 不同，V4L2 版本专门针对视频设备的特点进行了优化，增加了 mmap 和 unlocked_ioctl 等专用接口。

4.2 open 回调实现要点

open 是用户空间访问设备节点的入口。V4L2 驱动在 open 中需要完成以下工作：

1. 获取视频设备结构体：通过 video_devdata(file) 从 file 指针获取 struct video_device。
2. 初始化文件句柄私有数据：分配 struct v4l2_fh 或自定义句柄结构体，并通过 video_device->fh 或 file->private_data 关联。
3. 检查设备权限：根据打开模式（O_RDONLY/O_WRONLY/O_RDWR）验证是否支持对应的视频流方向。
4. 硬件初始化：上电、复位传感器、配置时钟等。
5. 引用计数管理：调用 v4l2_device_get 或模块引用计数增加。

static int my_v4l2_open(struct file *file)
{
    struct video_device *vdev = video_devdata(file);
    struct my_device *dev = video_get_drvdata(vdev);
    struct my_fh *fh;

    /* 1. 检查设备是否可用 */
    if (!dev || !dev->registered)
        return -ENODEV;

    /* 2. 分配文件句柄私有数据 */
    fh = kzalloc(sizeof(*fh), GFP_KERNEL);
    if (!fh)
        return -ENOMEM;

    /* 3. 初始化 V4L2 文件句柄 */
    v4l2_fh_init(&fh->vfh, vdev);
    file->private_data = fh;

    /* 4. 初始化队列和缓冲区状态 */
    INIT_LIST_HEAD(&fh->buf_list);
    spin_lock_init(&fh->buf_lock);

    /* 5. 硬件上电 */
    my_power_up(dev);

    /* 6. 添加文件句柄到设备句柄列表 */
    v4l2_fh_add(&fh->vfh);

    return 0;
}

4.3 release 回调实现要点

release 是 open 的逆操作，必须确保所有资源被正确释放，尤其是正在进行的视频流和 DMA 缓冲区。

• 停止视频流：如果设备正在 streaming，调用 vb2_streamoff 或自定义停止函数。
• 释放缓冲区：清空待处理缓冲区队列，归还 DMA 内存。
• 关闭硬件：下电、关闭时钟、释放中断。
• 移除文件句柄：调用 v4l2_fh_del() 和 v4l2_fh_exit()。
• 释放私有数据：kfree 之前分配的句柄结构体。

static int my_v4l2_release(struct file *file)
{
    struct my_fh *fh = file->private_data;
    struct video_device *vdev = video_devdata(file);
    struct my_device *dev = video_get_drvdata(vdev);

    /* 1. 停止所有正在进行的流 */
    if (fh->streaming)
        my_stop_streaming(dev, fh);

    /* 2. 释放缓冲区资源 */
    my_free_buffers(dev, fh);

    /* 3. 硬件下电 */
    my_power_down(dev);

    /* 4. 移除 V4L2 文件句柄 */
    v4l2_fh_del(&fh->vfh);
    v4l2_fh_exit(&fh->vfh);

    /* 5. 释放私有数据 */
    kfree(fh);
    file->private_data = NULL;

    return 0;
}

4.4 unlocked_ioctl 回调实现要点

unlocked_ioctl 是 V4L2 驱动的命令处理中心。标准做法是将所有 VIDIOC_* 命令转发到 video_ioctl2 通用处理函数，该函数会自动分发到对应的 v4l2_ioctl_ops 回调。

static long my_v4l2_ioctl(struct file *file, unsigned int cmd, unsigned long arg)
{
    /* 直接委托给 V4L2 核心框架处理 */
    return video_ioctl2(file, cmd, arg);
}

驱动开发者通常不需要在 unlocked_ioctl 中编写大量 switch-case，而是实现 struct v4l2_ioctl_ops 中的具体回调：

4.5 mmap 回调实现要点

mmap 用于将内核空间的视频缓冲区直接映射到用户空间，避免数据拷贝。V4L2 驱动通常使用 videobuf2 框架的 vb2_mmap 辅助函数。

static int my_v4l2_mmap(struct file *file, struct vm_area_struct *vma)
{
    struct my_fh *fh = file->private_data;
    struct my_device *dev = video_drvdata(file);

    /* 委托给 vb2 核心的 mmap 实现 */
    return vb2_mmap(&dev->vb2_queue, vma);
}

如果手动实现 mmap，需要关注以下要点：

• 验证缓冲区索引：从 vma->vm_pgoff 计算用户请求的缓冲区编号和平面偏移。
• 设置 VM_IO 和 VM_DONTEXPAND：标记该 VMA 为 IO 映射区域，禁止自动扩展。
• 提供 fault 回调：对于非连续内存（如 scatter-gather 缓冲区），需要实现 vm_operations_struct 的 fault 方法。
• DMA 一致性：使用 dma_mmap_coherent 或 dma_mmap_attrs 确保缓存一致性。

4.6 poll 回调实现要点

poll 回调支持用户空间的 select/poll/epoll 机制，用于非阻塞等待视频帧就绪。V4L2 驱动通常使用 vb2_poll 标准实现。

static __poll_t my_v4l2_poll(struct file *file, struct poll_table_struct *wait)
{
    struct my_fh *fh = file->private_data;
    struct my_device *dev = video_drvdata(file);

    /* 委托给 vb2 核心的 poll 实现 */
    return vb2_poll(&dev->vb2_queue, file, wait);
}

手动实现 poll 的核心逻辑：

1. 注册等待队列：调用 poll_wait(file, &dev->poll_wait, wait) 将进程添加到设备的等待队列。
2. 检查缓冲区状态：如果捕获队列中有已填充的缓冲区（DQBUF 可用），返回 EPOLLIN | EPOLLRDNORM。
3. 检查输出状态：对于输出设备，如果输出队列有空闲缓冲区（QBUF 可用），返回 EPOLLOUT | EPOLLWRNORM。
4. 错误处理：如果设备发生错误，返回 EPOLLERR。

4.7 文件操作接口的完整注册流程

将上述回调注册到 V4L2 设备的标准流程如下：

static const struct v4l2_file_operations my_v4l2_fops = {
    .owner          = THIS_MODULE,
    .open           = my_v4l2_open,
    .release        = my_v4l2_release,
    .unlocked_ioctl = my_v4l2_ioctl,
    .mmap           = my_v4l2_mmap,
    .poll           = my_v4l2_poll,
};

static int my_probe(struct platform_device *pdev)
{
    struct video_device *vdev;

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

    /* 设置文件操作接口 */
    vdev->fops = &my_v4l2_fops;
    vdev->v4l2_dev = &dev->v4l2_dev;
    vdev->queue = &dev->vb2_queue;
    vdev->device_caps = V4L2_CAP_VIDEO_CAPTURE | V4L2_CAP_STREAMING;

    /* 注册视频设备 */
    if (video_register_device(vdev, VFL_TYPE_VIDEO, -1) < 0) {
        video_device_release(vdev);
        return -EINVAL;
    }

    return 0;
}

4.8 常见问题与调试方法

通过正确实现 struct v4l2_file_operations 的五个核心回调，驱动开发者可以为用户空间提供标准、高效的视频设备访问接口。在实际开发中，强烈建议复用 videobuf2 框架提供的标准实现（vb2_mmap、vb2_poll），它们已经过充分测试并处理了各种边界情况。