2. v4l2-compliance 工具介绍

v4l2-compliance 是 Linux 内核 V4L2 框架的官方合规性测试工具，由内核社区维护，用于验证 V4L2 设备驱动对 V4L2 规范（specification）的符合程度。它通过调用一系列 ioctl 接口，检查驱动在格式协商、缓冲区管理、流控制、裁剪/缩放、控制属性等方面的行为是否与内核期望一致。本章将深入分析该工具的源码结构、编译方法以及核心命令行参数的使用方式。

2.1 工具源码结构

v4l2-compliance 的源码位于 Linux 内核源码树的 tools/testing/selftests/media/v4l2-compliance/ 目录下，也可从 v4l-utils 仓库 独立获取。其核心源码文件及职责如下表所示：

下图展示了 v4l2-compliance 的源码模块调用关系与测试流程：

2.2 编译方法

v4l2-compliance 的编译有两种主流方式：作为内核 selftests 的一部分编译，或从 v4l-utils 独立编译。推荐使用后者，因为独立编译更灵活且不依赖完整内核源码树。

2.2.1 从 v4l-utils 仓库编译（推荐）

# 克隆 v4l-utils 仓库
git clone https://git.linuxtv.org/v4l-utils.git
cd v4l-utils

# 配置编译环境（需要 meson 和 ninja）
meson setup builddir
cd builddir

# 编译 v4l2-compliance（只编译该工具，不编译其他组件）
ninja v4l2-compliance

# 编译完成后，二进制位于 builddir/utils/v4l2-compliance
./utils/v4l2-compliance --help

2.2.2 作为内核 selftests 编译

# 进入内核源码树
cd /path/to/linux-kernel

# 配置 selftests
make -C tools/testing/selftests TARGETS=media

# 单独编译 v4l2-compliance
make -C tools/testing/selftests/media/v4l2-compliance

# 编译产物位于 tools/testing/selftests/media/v4l2-compliance/
ls -l tools/testing/selftests/media/v4l2-compliance/v4l2-compliance

2.3 基本命令行参数详解

v4l2-compliance 提供了丰富的命令行参数来控制测试范围、设备选择、输出格式等。以下是最核心的五个参数：-s、-m、-d、-c、-f。

2.3.1 -s（流式测试）

默认情况下，v4l2-compliance 只执行静态 ioctl 测试（如 QUERYCAP、ENUM_FMT、G/S_FMT 等），不涉及数据流。添加 -s 参数后，工具会执行完整的流式测试流程：

1. REQBUFS： 申请缓冲区（默认 4 个缓冲区）。
2. QUERYBUF： 查询每个缓冲区的状态和内存信息。
3. QBUF： 将所有缓冲区入队到驱动。
4. STREAMON： 启动视频流。
5. DQBUF： 出队缓冲区（等待驱动填充数据）。
6. STREAMOFF： 停止视频流。
7. REQBUFS(0)： 释放所有缓冲区。

2.3.2 -m（多平面模式）

V4L2 支持单平面（SINGLE_PLANE）和多平面（MULTI_PLANE）两种缓冲区模型。多平面模式用于 YUV 分量分离存储或元数据附加等场景。使用 -m 参数时，v4l2-compliance 会：

• 在 REQBUFS 时使用 V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE 或 V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE。
• 在 QBUF/DQBUF 时使用 struct v4l2_plane 数组。
• 检查驱动是否正确处理 V4L2_BUF_FLAG_MULTIPLANE 标志。

2.3.3 -d（指定设备）

默认情况下，v4l2-compliance 会扫描 /dev/video0 到 /dev/video63 以及 /dev/v4l-subdev* 等所有 V4L2 设备节点。使用 -d 可以精确指定单个设备：

# 测试 /dev/video2
v4l2-compliance -d /dev/video2 -s

# 测试 /dev/v4l-subdev1（子设备）
v4l2-compliance -d /dev/v4l-subdev1

2.3.4 -c（彩色输出）

添加 -c 参数后，测试结果会使用 ANSI 转义码着色：

• PASS： 绿色高亮
• FAIL： 红色高亮
• SKIP： 黄色高亮

在终端中，这能显著提升测试结果的可读性，尤其是在大量测试用例输出时。

2.3.5 -f（强制测试）

某些测试用例需要前置条件（如设备必须有视频输入、必须有音频输入等）。默认情况下，如果前置条件不满足，v4l2-compliance 会跳过该测试。使用 -f 后，即使前置条件不满足，也会执行测试并报告 FAIL（如果驱动返回错误）或 PASS（如果驱动优雅地返回 EINVAL 或 ENOTTY）。

下图展示了 v4l2-compliance 命令行参数与测试流程的对应关系：

2.4 参数组合使用示例

在实际测试中，通常需要组合多个参数来覆盖完整的测试场景。以下是一些典型组合：

2.5 测试输出解读

v4l2-compliance 的输出格式清晰，每行包含测试名称、测试结果和简要说明。以下是一个典型输出片段：

# v4l2-compliance -d /dev/video0 -s -c

v4l2-compliance SHA: 1234567890ab, 64 bits, 64-bit time_t

Compliance test for device /dev/video0:

Driver Info:
        Driver name      : uvcvideo
        Card type        : USB Camera
        Bus info         : usb-0000:00:14.0-1
        Driver version   : 6.1.0
        Capabilities     : 0x84a00001
                Video Capture
                Streaming
                Extended Pix Format
                Device Capabilities
        Required ioctls:
                VIDIOC_QUERYCAP: OK

        ...

        Streaming ioctls:
                VIDIOC_REQBUFS: OK
                VIDIOC_QUERYBUF: OK
                VIDIOC_QBUF: OK
                VIDIOC_DQBUF: OK
                VIDIOC_STREAMON: OK
                VIDIOC_STREAMOFF: OK

        ...

Total for /dev/video0: 45 PASS, 0 FAIL, 3 SKIP