4、嵌入式 Linux 摄像头驱动：V4L2 框架理解错误，ioctl 调用顺序混乱，buffer 管理不当

V4L2，全称 Video for Linux 2。说白了，它就是 Linux 下视频设备的统一接口标准。我见过太多新手，一上来就对着摄像头设备文件 /dev/video0 猛调 ioctl，结果画面出不来，或者出来是花的。

为什么会这样？因为 V4L2 有严格的「状态机」机制。你想想看，摄像头从休眠到工作，中间要经历好几个阶段。跳过任何一个，驱动都会给你脸色看。

4.1 V4L2 框架的核心思想

V4L2 把摄像头抽象成一个「设备节点」。应用程序通过 open()、ioctl()、mmap()、poll() 这些标准接口来操作它。但关键在于，ioctl 的调用顺序是有严格要求的。

我个人习惯把 V4L2 的初始化流程画成一张流程图。嗯，这里我简单列一下核心步骤：

  1. 打开设备：open("/dev/video0", O_RDWR)
  2. 查询能力：VIDIOC_QUERYCAP，确认设备是否支持视频捕获
  3. 设置格式：VIDIOC_S_FMT，告诉摄像头你要的分辨率和像素格式
  4. 申请缓冲区：VIDIOC_REQBUFS，向驱动要内存
  5. 查询并映射缓冲区：VIDIOC_QUERYBUF + mmap()
  6. 入队缓冲区：VIDIOC_QBUF，把空缓冲区还给驱动
  7. 开始采集：VIDIOC_STREAMON
  8. 出队缓冲区：VIDIOC_DQBUF，拿到填满数据的帧
⚠️ 常见错误： 很多人跳过 VIDIOC_QUERYCAP，或者先调 STREAMON 再 QBUF。我在项目中遇到过，有个同事把 REQBUFS 和 QBUF 的顺序搞反了，结果摄像头一直报 EIO 错误，查了两天才发现。

4.2 ioctl 调用顺序混乱的典型场景

我总结了几种最常见的「顺序错误」：

错误场景 后果 正确做法
先 STREAMON 再 QBUF 驱动没有缓冲区可用，直接返回错误 先 QBUF 把所有缓冲区入队，再 STREAMON
先 DQBUF 再 QBUF 队列为空，DQBUF 会阻塞或返回 EAGAIN 确保至少有一个缓冲区在队列中
未 QUERYCAP 直接 S_FMT 设备可能不支持你设置的格式，但驱动不报错 先查能力，再设格式
重复 REQBUFS 内存泄漏，或者驱动崩溃 只在初始化时申请一次

你想想看，驱动就像一个流水线工人。你还没把空箱子（缓冲区）放到传送带上，就让他开机（STREAMON），他拿什么装产品？

4.3 Buffer 管理不当的坑

Buffer 管理是 V4L2 编程中最容易出问题的地方。我见过最离谱的，是有人把 mmap 出来的指针直接 free 掉了——嗯，后果可想而知，段错误。

这里有几个关键点：

  • 缓冲区数量：我建议至少申请 4 个缓冲区。太少会导致丢帧，太多会浪费内存。4 个是个不错的平衡点。
  • 缓冲区生命周期：每个缓冲区在 QBUF 和 DQBUF 之间切换。你拿到 DQBUF 后，要尽快处理数据，然后马上 QBUF 还回去。
  • 内存映射：mmap 返回的地址不要跨线程乱用。我习惯用一个结构体把 fd、buf_index、start、length 打包在一起管理。

💡 我的经验： 在嵌入式设备上，mmap 的缓冲区通常位于物理连续内存中。如果你发现摄像头采集的画面有「条纹」或「撕裂」，多半是缓冲区地址不对齐。检查一下 VIDIOC_QUERYBUF 返回的 m.offset 和 length 是否合理。

4.4 一个完整的初始化代码片段

下面是我常用的初始化流程。注意看 ioctl 的调用顺序：

int fd = open("/dev/video0", O_RDWR);
if (fd < 0) { perror("open"); return -1; }

// 1. 查询能力
struct v4l2_capability cap;
ioctl(fd, VIDIOC_QUERYCAP, &cap);
if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) {
    fprintf(stderr, "设备不支持视频捕获\n");
    close(fd);
    return -1;
}

// 2. 设置格式
struct v4l2_format fmt;
memset(&fmt, 0, sizeof(fmt));
fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
fmt.fmt.pix.width = 640;
fmt.fmt.pix.height = 480;
fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
ioctl(fd, VIDIOC_S_FMT, &fmt);

// 3. 申请缓冲区
struct v4l2_requestbuffers req;
memset(&req, 0, sizeof(req));
req.count = 4;
req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
req.memory = V4L2_MEMORY_MMAP;
ioctl(fd, VIDIOC_REQBUFS, &req);

// 4. 查询并映射每个缓冲区
for (int i = 0; i < req.count; i++) {
    struct v4l2_buffer buf;
    memset(&buf, 0, sizeof(buf));
    buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    buf.memory = V4L2_MEMORY_MMAP;
    buf.index = i;
    ioctl(fd, VIDIOC_QUERYBUF, &buf);

    buffers[i].start = mmap(NULL, buf.length,
                            PROT_READ | PROT_WRITE,
                            MAP_SHARED, fd, buf.m.offset);
    buffers[i].length = buf.length;
}

// 5. 入队所有缓冲区
for (int i = 0; i < req.count; i++) {
    struct v4l2_buffer buf;
    memset(&buf, 0, sizeof(buf));
    buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    buf.memory = V4L2_MEMORY_MMAP;
    buf.index = i;
    ioctl(fd, VIDIOC_QBUF, &buf);
}

// 6. 开始采集
enum v4l2_buf_type type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
ioctl(fd, VIDIOC_STREAMON, &type);

📌 小提示： 每次 ioctl 调用后，记得检查返回值。很多驱动在出错时不会打印日志，全靠 errno 告诉你问题。我曾经因为没检查 VIDIOC_S_FMT 的返回值，在某个 sensor 上用了不支持的格式，画面一直是绿的——查了半天才发现。

4.5 避坑指南

最后，我把自己踩过的坑整理成几条原则：

  • 顺序不能乱：OPEN → QUERYCAP → S_FMT → REQBUFS → QUERYBUF → mmap → QBUF → STREAMON → DQBUF → 处理 → QBUF → ... → STREAMOFF
  • 缓冲区要循环：永远保持至少一个缓冲区在驱动队列里。否则驱动会因为没有缓冲区而停止采集。
  • 错误处理要到位：每个 ioctl 都检查返回值。特别是 DQBUF，它可能返回 EAGAIN（非阻塞模式）或 EIO（硬件错误）。
  • 关闭前要清理：先 STREAMOFF，再 munmap，最后 close。顺序反了可能导致内核崩溃。

我曾经在一个项目中，因为忘记在退出前 STREAMOFF，导致下次打开设备时驱动状态混乱，摄像头死活不出图。重启设备才恢复——嗯，从那以后我写了个专门的 cleanup 函数，每次退出都调用。

V4L2 其实不复杂，只要你尊重它的「状态机」规则，它就会乖乖工作。记住：顺序就是一切。

← 上一章 📖 返回目录 下一章 →