V4L2 驱动开发读书笔记

前言：为什么需要V4L2？

在Linux世界里，一切皆文件。摄像头也不例外。但摄像头不是一个简单的文件，它产生的数据量巨大、对实时性要求极高。为了高效、标准地管理这类设备，内核开发者们设计了 Video4Linux2 (V4L2) 框架。

1. 宏观 - V4L2 的整体框架

V4L2 驱动类比为一个专业的跨国物流公司，专门负责在硬件（摄像头传感器）和软件（视频应用）之间高效地运输"视频数据"这个包裹。

上图清晰地展示了公司的组织架构：

用户空间 (User Space): 比如 ffplay、OBS 等应用程序。他们通过下达 open, ioctl 指令来委托业务。
内核空间 (Kernel Space): "物流公司"总部所在地。
V4L2 核心 (V4L2 Core): 公司的"中央调度系统"。它提供了标准化的业务流程和接口，确保所有分公司（驱动）都按统一规范运作。
V4L2 驱动 (V4L2 Driver): 我们的"分公司"。每个驱动都针对一款特定的摄像头硬件，负责执行具体的运输任务。

2. 核心基石 - 关键数据结构

物流公司需要标准化的工具来运作，V4L2 也是如此。它依赖于一套核心的数据结构。

2.1 框架定义的"标准工具"

以下这些结构体都是由 V4L2或Videobuf2框架定义的标准工具，我们作为驱动开发者，只需要学会如何使用它们，而不需要（也不能）修改它们的定义。

struct v4l2_device: 整个设备的"容器"。由V4L2框架定义，代表一个V4L2设备实例的整体。在驱动的 probe 函数中，我们通过 v4l2_device_register() 将它注册到内核，标志着我们设备实例的诞生。
struct video_device: "营业部"。同样在 probe 函数中，我们初始化它，将三本"操作手册" (fops, ioctl_ops) 挂载上去，然后通过 video_register_device() 将它注册，从而创建出 /dev/videoX 设备节点。
struct vb2_queue: "包裹调度中心"。在 probe 函数中，我们通过 vb2_queue_init() 初始化它，并将我们的"核心工作手册" (vb2_ops) 和"仓库管理手册" (vb2_mem_ops) 与之关联。

2.2 我们自己定义的"设备收纳盒"

为了方便管理，我们通常会自己定义一个结构体，将上述所有框架提供的"标准工具"都包含进去。这是一种标准的驱动设计模式。

c 复制代码

struct viv_dev {
	struct v4l2_device v4l2_dev;	/* V4L2 设备的核心结构体 (容器) */
	struct video_device vdev;		/* 代表 /dev/videoX 设备节点的结构体 ("营业部") */
	struct vb2_queue vb_queue;		/* Videobuf2 的缓冲区队列管理器 ("包裹调度中心") */
	struct mutex lock;				/* 互斥锁，用于保护该结构体中的数据 */
	// --- 以下是我们为驱动逻辑添加的自定义变量 ---
	struct mutex lock;              // 互斥锁
    unsigned int width;             // 当前宽度
    // ... 其他成员
};

这个结构体如何被传递：

在 probe 函数中，我们通过 video_set_drvdata(&dev->vdev, dev); 将它与"营业部"绑定。之后在 fops 或 ioctl_ops 的函数中，可以通过 video_drvdata(file) 找回它。
同样在 probe 中，我们通过 dev->vb_queue.drv_priv = dev; 将它与"包裹调度中心"绑定。之后在 vb2_ops 的函数中，可以通过 vb2_get_drv_priv(vq) 找回它。

2.3 深入理解"快递单"与"标准包裹"

这两个结构体是理解缓冲区管理的关键，它们的来源和作用有本质区别

struct v4l2_buffer: 由 V4L2框架定义，这是一个"信使"，专门用于在应用程序和内核驱动之间来回传递关于某个缓冲区的信息。它本身不包含数据，只包含描述信息。只在应用程序中使用。应用程序创建这个结构体的变量，填充它，然后作为 ioctl 的参数传递给内核。驱动代码中不会直接定义这个类型的变量。
c 复制代码
```
// 这是应用程序代码, 不是驱动代码
struct v4l2_buffer my_buffer;
my_buffer.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
my_buffer.memory = V4L2_MEMORY_MMAP;
my_buffer.index = 0;
// 将这个结构体的地址传递给内核
ioctl(fd, VIDIOC_QBUF, &my_buffer);
```
struct vb2_buffer: "标准包裹" 只在内核驱动代码中使用。它是 vb2 框架传递给我们驱动函数的"实体"。

3. ioctl调用流程

客户（应用程序）如何向物流公司（驱动）下达具体的指令？答案是 ioctl。

一个 ioctl 指指令的旅程如下：

应用程序发起 ioctl 系统调用。
请求进入内核，由 VFS (虚拟文件系统) 接收。

VFS 查阅驱动的"前台服务指南" (v4l2_file_operations)，将请求转交给 V4L2 核心的 video_ioctl2 分发函数。

c 复制代码

// --- VFS 的"前台服务指南" (v4l2_file_operations) ---
static const struct v4l2_file_operations viv_fops = {
	.owner = THIS_MODULE,
	// ... 其他文件操作 ...
	// 关键！将所有未知的ioctl请求都指向 V4L2 核心提供的分发函数
	.unlocked_ioctl = video_ioctl2,
};

video_ioctl2 根据指令码（如 VIDIOC_REQBUFS），在驱动的"ioctl命令手册" (v4l2_ioctl_ops) 中找到对应的处理函数。
最终，请求到达我们的驱动程序中具体的实现函数，驱动开始执行实际操作。

4. 驱动的灵魂 - 三本核心"操作手册" (ops)

V4L2 框架之所以强大，是因为它只定义流程，而将具体实现交由驱动来完成。驱动通过填充三本核心的"操作手册"（ops 结构体）来告诉框架如何与特定硬件协作。

struct v4l2_file_operations (fops): "前台服务指南"。

c 复制代码

static const struct v4l2_file_operations viv_fops = {
   .owner = THIS_MODULE,
   .open = v4l2_fh_open,
   .release = vb2_fop_release,
   .mmap = vb2_fop_mmap,
   .unlocked_ioctl = video_ioctl2,
};

struct vb2_ops: "核心工作手册"。

c 复制代码

static const struct vb2_ops viv_vb2_ops = {
   .queue_setup     = viv_queue_setup,
   .buf_queue       = viv_buf_queue,
   .start_streaming = viv_start_streaming,
   .stop_streaming  = viv_stop_streaming,
   // ...
};

struct vb2_mem_ops: "仓库管理手册"。
c 复制代码
```
dev->vb_queue.mem_ops = &vb2_vmalloc_memops;
```

5. 流动的生命线 - 三大核心场景分析

申请 Buffer (VIDIOC_REQBUFS)流程: 应用程序请求内核为视频流准备一片共享内存。
- 应用工程师做什么：应用工程师需要创建一个 v4l2_requestbuffers 结构体，填入期望的缓冲区数量、类型和内存模式，然后通过 ioctl 系统调用将其发送给内核。
  c 复制代码
```
struct v4l2_requestbuffers reqbuf = {0};
reqbuf.count = 4; // 希望申请4个缓冲区
reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
reqbuf.memory = V4L2_MEMORY_MMAP;

// 发起ioctl系统调用
if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) < 0) {
    perror("VIDIOC_REQBUFS failed");
    return -1;
}
```
- 驱动程序做什么：应用程序的 ioctl 调用会触发 V4L2 框架回调我们驱动中的 queue_setup 函数。驱动工程师的任务是在 queue_setup 中告诉 vb2 框架，根据当前设备配置，每个缓冲区应该分配多大。
  c 复制代码
```
static int viv_queue_setup(struct vb2_queue *vq, ...)
{
    struct viv_dev *dev = vb2_get_drv_priv(vq);
    *nplanes = 1;
    sizes[0] = dev->sizeimage; // 根据当前格式计算出的大小
    return 0;
}
```
将 Buffer 放入队列 (VIDIOC_QBUF):应用程序将一个空的缓冲区交还给驱动，让其可以用来填充数据。
- 应用工程师做什么：应用工程师需要创建一个 v4l2_buffer 结构体，填入类型、内存模式和要操作的缓冲区索引号，然后通过 ioctl 发送。
  c 复制代码
```
struct v4l2_buffer buf = {0};
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;
buf.index = i; // i 是缓冲区的索引 (0, 1, 2...)

if (ioctl(fd, VIDIOC_QBUF, &buf) < 0)
{
    perror("VIDIOC_QBUF failed");
    return -1;
}
```
- 驱动程序做什么：应用程序的 ioctl 调用会触发 V4L2 框架回调我们驱动中的 buf_queue 函数。驱动工程师只需调用 vb2_buffer_done 确认入队即可。
  c 复制代码
```
static void viv_buf_queue(struct vb2_buffer *vb)
{
    vb2_buffer_done(vb, VB2_BUF_STATE_QUEUED);
}
```

从队列中取出 Buffer (VIDIOC_DQBUF):应用程序获取一个已被驱动填充了视频数据的缓冲区。

应用工程师做什么：创建一个空的 v4l2_buffer 结构体，然后通过 ioctl 将其传递给内核。这个调用通常是阻塞的，直到驱动准备好一帧数据。

c 复制代码

struct v4l2_buffer buf = {0};
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
buf.memory = V4L2_MEMORY_MMAP;

// 这个调用会等待，直到有数据为止
if (ioctl(fd, VIDIOC_DQBUF, &buf) < 0) {
    perror("VIDIOC_DQBUF failed");
    return -1;
}
// 现在，buf 结构体被内核填满了信息 (index, bytesused, etc.)
// 我们可以处理数据了...

驱动程序做什么：这个流程的起点在驱动端！驱动工程师需要实现数据生成的逻辑。在我们的定时器回调中，驱动填充完数据后，必须调用 vb2_buffer_done 并传入 DONE 状态，这是整个数据流的"发动机"。

c 复制代码

// viv_cam.c (内核驱动)
static enum hrtimer_restart viv_timer_callback(struct hrtimer *timer)
{
    // ... 获取一个空闲的 buffer vb ...
    // 1. 调用我们的"传感器"填充数据
    viv_fill_buffer(dev, vb);
    // 2. 关键！上报数据完成。这一步会唤醒正在等待的应用程序。
    vb2_buffer_done(vb, VB2_BUF_STATE_DONE);
    // ... 重新调度定时器 ...
    return HRTIMER_RESTART;
}

6. 深度解析 - 多面手 vb2_buffer_done

这个函数是驱动与 vb2 框架沟通的"核心语言"，根据传入的状态码，其含义截然不同。

状态码	使用场景	驱动想表达的意思
VB2_BUF_STATE_DONE	硬件/软件填充数据完成后（中断、回调）	"数据好了，快来取！"
VB2_BUF_STATE_QUEUED	1. 简单驱动的 .buf_queue 回调 2. 复杂驱动的启动失败处理	1. "收到了，你来管吧。" 2. "任务取消，紧急归还！"
VB2_BUF_STATE_ERROR	数据传输/处理发生不可逆错误时	"这个缓冲区坏了，还给你！"