2. v4l2-compliance 工具介绍：工具来源、版本历史、在驱动验证中的角色、基本使用方法
2.1 工具来源与项目背景
v4l2-compliance 是 Linux 内核 V4L2（Video for Linux 2）子系统官方提供的驱动合规性测试工具。它由内核社区维护，托管在 git://linuxtv.org/v4l-utils.git 仓库中，与 v4l-utils 工具集一同发布。
该工具的核心目标是对 V4L2 设备驱动进行全面的 API 合规性检查，确保驱动实现严格遵循 linux/media/v4l2-* 系列头文件定义的内核接口规范。任何偏离规范的行为都会被标记为 FAIL，从而在驱动合入主线前暴露问题。
关键事实： v4l2-compliance 不是第三方测试工具，而是内核社区官方认可的驱动验证标准。驱动在提交到 Linux 内核主线前，通常需要确保 v4l2-compliance 测试全部通过。
2.2 版本历史与演进
v4l2-compliance 自 2008 年左右随 v4l-utils 项目启动，经历了多个重要版本阶段。下表梳理了关键版本节点及其对应的功能变化：
| 版本区间 | 对应 v4l-utils 版本 | 主要变化与新增功能 |
|---|---|---|
| 0.x ~ 1.0 | 0.8.x ~ 1.0.x | 基础 ioctl 合规检查；支持 video、vbi、radio 设备类型 |
| 1.4 ~ 1.6 | 1.4.x ~ 1.6.x | 增加对 V4L2_CAP_* 能力标志的交叉验证；引入 --streaming 流式测试 |
| 1.8 ~ 1.10 | 1.8.x ~ 1.10.x | 支持 MEDIA_IOC_* media controller 接口测试；增加 --saturation 色彩空间验证 |
| 1.12 ~ 1.14 | 1.12.x ~ 1.14.x | 新增 --codec 编解码器测试；改进 --streaming 多平面格式支持 |
| 1.16 ~ 1.18 | 1.16.x ~ 1.18.x | 引入 --touch 触摸设备测试；增强 --event 事件订阅验证 |
| 1.20+ | 1.20.x ~ 当前 | 全面支持 V4L2_BUF_TYPE_META_CAPTURE 元数据；改进 --streaming 多队列并发测试 |
版本选择建议： 对于嵌入式驱动验证，建议使用 v4l-utils 1.16 及以上版本，以获得对 media controller 和编解码器设备的完整测试覆盖。使用
v4l2-compliance --version 可查看当前工具版本。
2.3 在驱动验证中的角色
v4l2-compliance 在 V4L2 驱动开发与验证流程中扮演多重角色，是连接驱动实现与内核规范的桥梁。其核心角色包括：
- 合规性裁判： 逐项检查驱动对 V4L2 API 的实现是否符合内核头文件定义，包括 ioctl 行为、数据结构填充、错误码返回等。
- 回归测试工具： 在驱动代码修改后，快速执行全量测试，确保新改动未破坏已有合规性。
- 跨平台验证基准： 同一套测试用例可在 x86、ARM、RISC-V 等不同架构上运行，提供一致的验证标准。
- 内核主线准入检查： 许多内核维护者要求驱动在提交前必须通过 v4l2-compliance 测试，作为代码审查的前置条件。
2.4 基本使用方法
2.4.1 安装与获取
v4l2-compliance 随 v4l-utils 工具集一起发布，可通过以下方式获取：
# 从发行版包管理器安装（推荐）
sudo apt-get install v4l-utils # Debian/Ubuntu
sudo yum install v4l-utils # RHEL/CentOS
sudo pacman -S v4l-utils # Arch Linux
# 从源码编译安装
git clone git://linuxtv.org/v4l-utils.git
cd v4l-utils
./autogen.sh
./configure
make
sudo make install2.4.2 基本命令格式
v4l2-compliance 的命令行格式如下：
v4l2-compliance [选项] [设备路径]常用选项说明：
| 选项 | 说明 | 示例 |
|---|---|---|
-d, --device |
指定 V4L2 设备节点路径 | -d /dev/video0 |
-s, --streaming |
执行流式传输测试（需要分配缓冲区并启动流） | -s |
-m, --media-device |
指定 media controller 设备路径 | -m /dev/media0 |
-e, --event |
测试事件订阅机制 | -e |
-c, --codec |
测试编解码器设备 | -c |
-t, --touch |
测试触摸设备 | -t |
-n, --no-warnings |
不显示警告信息 | -n |
-v, --verbose |
显示详细测试输出 | -v |
2.4.3 典型使用场景
以下列出驱动验证中最常用的几种调用方式：
# 1. 基本合规性测试（不进行流式传输）
v4l2-compliance -d /dev/video0
# 2. 完整测试（包含流式传输）
v4l2-compliance -d /dev/video0 -s
# 3. 测试 media controller 设备
v4l2-compliance -d /dev/video0 -m /dev/media0 -s
# 4. 测试编解码器设备
v4l2-compliance -d /dev/video0 -c -s
# 5. 测试所有 V4L2 设备（自动扫描）
v4l2-compliance -s
注意事项：
- 流式测试（
-s）会实际分配缓冲区并启动视频流，确保测试环境有足够的系统资源。 - 对于摄像头设备，流式测试可能需要物理信号输入，否则可能返回无信号错误。
- 测试 media controller 设备时，必须同时指定
-d和-m参数。
2.4.4 测试输出解读
v4l2-compliance 的输出包含测试套件名称、测试项、结果状态和汇总信息。典型输出格式如下：
# v4l2-compliance -d /dev/video0 -s
v4l2-compliance SHA: 1234567, 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 : 5.15.0
Capabilities : 0x84a00001
Required ioctls:
test VIDIOC_QUERYCAP: OK
test invalid ioctls: OK
...
Streaming ioctls:
test read/write: OK
test MMAP (no poll): OK
test MMAP (select): OK
test USERPTR (no poll): OK
test USERPTR (select): OK
Total: 43 tests, 0 failed, 0 warnings测试结果状态说明：
| 状态 | 含义 | 处理建议 |
|---|---|---|
| OK | 测试通过，驱动行为符合规范 | 无需处理 |
| FAIL | 测试失败，驱动行为偏离规范 | 必须修复，否则无法合入主线 |
| WARNING | 测试通过但存在潜在问题 | 建议检查并优化 |
| SKIPPED | 测试被跳过（设备不支持该功能） | 确认设备能力是否匹配 |
验证目标： 在驱动验证中，应追求
0 failed, 0 warnings 的测试结果。任何 FAIL 项都需要深入分析驱动代码，定位并修复问题。