V4L2 摄像头驱动开发入门：从 ioctl 到视频流

V4L2（Video4Linux2）是 Linux 内核里统一的视频设备接口，摄像头、采集卡、TV tuner 都走这一套 API。跟很多”用起来很魔法”的框架不一样，V4L2 的用户态编程模型其实很直白：一切都是对 /dev/videoN 这个字符设备做 ioctl。

设备节点与能力查询

插上一个 UVC 摄像头，v4l2-ctl --list-devices 能看到对应的 /dev/video0。打开之后第一件事永远是查能力：

1
int fd = open("/dev/video0", O_RDWR);
2

3
struct v4l2_capability cap;
4
ioctl(fd, VIDIOC_QUERYCAP, &cap);
5

6
if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) {
7
    // 这个设备不支持视频采集（可能只是 metadata 节点）
8
    return -1;
9
}
10
if (!(cap.capabilities & V4L2_CAP_STREAMING)) {
11
    // 不支持 mmap/DMA streaming，只能退化到 read()
12
}

一个物理摄像头往往对应好几个 /dev/videoN 节点（视频流、metadata、有时还有单独的控制节点），VIDIOC_QUERYCAP 是区分它们的第一步。

协商格式

V4L2 不允许你”随便要一个格式”，得先 TRY_FMT/S_FMT 协商：

1
struct v4l2_format fmt = {0};
2
fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
3
fmt.fmt.pix.width = 1280;
4
fmt.fmt.pix.height = 720;
5
fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
6
fmt.fmt.pix.field = V4L2_FIELD_NONE;
7

8
if (ioctl(fd, VIDIOC_S_FMT, &fmt) < 0) {
9
    perror("VIDIOC_S_FMT"); // 驱动可能会静默改成它支持的最接近格式
10
}
11
// 关键：驱动改过之后要用 fmt 里回填的实际值，不能假设申请的就是拿到的

常见格式：YUYV（未压缩，体积大但 CPU 友好）、MJPEG（USB 摄像头常见，省带宽）、 NV12（很多硬件编码器偏好的格式）。UVC 摄像头通常两种都支持，高分辨率高帧率往往只有 MJPEG 能撑住 USB2.0 的带宽。

申请缓冲区：mmap 还是 userptr

现代 V4L2 采集不用 read()（那是兼容模式，有拷贝开销），标准做法是让内核分配一组缓冲区，用户态 mmap 过来直接读，零拷贝：

1
struct v4l2_requestbuffers req = {0};
2
req.count = 4;
3
req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
4
req.memory = V4L2_MEMORY_MMAP;
5
ioctl(fd, VIDIOC_REQBUFS, &req);
6

7
void *buffers[4];
8
size_t buf_len[4];
9
for (int i = 0; i < req.count; i++) {
10
    struct v4l2_buffer buf = {0};
11
    buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
12
    buf.memory = V4L2_MEMORY_MMAP;
13
    buf.index = i;
14
    ioctl(fd, VIDIOC_QUERYBUF, &buf);
15

16
    buffers[i] = mmap(NULL, buf.length, PROT_READ | PROT_WRITE,
17
                       MAP_SHARED, fd, buf.m.offset);
18
    buf_len[i] = buf.length;
19
}

除了 MMAP，还有 USERPTR（用户自己分配内存交给内核）和 DMABUF（跟 GPU/编码器之间传递缓冲区不做拷贝，现代摄像头 + 硬件编码管线的标配）。

抓帧循环

把所有缓冲区先入队（QBUF），开流，然后就是标准的”出队 - 处理 - 入队”循环：

1
for (int i = 0; i < req.count; i++) {
2
    struct v4l2_buffer buf = {0};
3
    buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
4
    buf.memory = V4L2_MEMORY_MMAP;
5
    buf.index = i;
6
    ioctl(fd, VIDIOC_QBUF, &buf);
7
}
8

9
enum v4l2_buf_type type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
10
ioctl(fd, VIDIOC_STREAMON, &type);
11

12
while (capturing) {
13
    fd_set fds;
14
    FD_ZERO(&fds);
15
    FD_SET(fd, &fds);
16
    select(fd + 1, &fds, NULL, NULL, NULL); // 也可以用 poll/epoll
17

18
    struct v4l2_buffer buf = {0};
19
    buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
20
    buf.memory = V4L2_MEMORY_MMAP;
21
    ioctl(fd, VIDIOC_DQBUF, &buf); // 拿到一帧，buf.index 指向哪块内存
22

23
    process_frame(buffers[buf.index], buf.bytesused);
24

25
    ioctl(fd, VIDIOC_QBUF, &buf); // 处理完还回去，驱动可以继续往里写
26
}
27

28
ioctl(fd, VIDIOC_STREAMOFF, &type);

这就是整个 V4L2 采集的骨架——libv4l2、GStreamer 的 v4l2src、甚至 FFmpeg 的 -f v4l2 输入，底层都是这一套 ioctl 序列，区别只在错误处理和格式协商的完善程度。

跟 libcamera 的关系

新一点的板子（尤其是手机 ISP、树莓派新款摄像头）会发现 V4L2 不够用了——复杂的 ISP pipeline（去噪、自动曝光、多路 sensor）没法用一个 /dev/videoN 表达清楚。 libcamera 就是为了解决这个问题出现的上层框架，底下仍然是 V4L2 + media controller API，但把 pipeline 编排这层复杂度封装掉了。简单摄像头直接用 V4L2 完全够用，复杂 ISP 场景才需要 libcamera。