📚 课程目录第3章 V4L2 ioctl接口详解

3. V4L2 ioctl 接口详解：分发机制与核心命令处理流程

V4L2 驱动与用户空间应用程序之间的主要交互通道是 ioctl 系统调用。内核通过 v4l2_file_operations 结构体中的 unlocked_ioctl 回调函数，将用户空间的请求分发到对应的驱动处理函数。本章深入分析这一分发机制，并详细拆解 VIDIOC_QUERYCAP、VIDIOC_S_FMT 等核心 ioctl 命令的处理流程。

3.1 v4l2_file_operations 与 unlocked_ioctl 分发架构

在 Linux 内核中，V4L2 驱动通过注册 struct v4l2_file_operations 来提供设备文件的操作接口。该结构体定义在 include/media/v4l2-dev.h 中，其核心成员如下：

成员	类型	说明
`owner`	`struct module *`	模块所有者指针
`open`	`int (open)(struct file )`	设备打开回调
`release`	`int (release)(struct file )`	设备关闭回调
`read`	`ssize_t (read)(struct file , char __user , size_t, loff_t )`	读取视频数据（较少使用）
`write`	`ssize_t (write)(struct file , const char __user , size_t, loff_t )`	写入视频数据（较少使用）
`poll`	`__poll_t (poll)(struct file , struct poll_table_struct *)`	轮询等待数据就绪
`unlocked_ioctl`	`long (unlocked_ioctl)(struct file , unsigned int, unsigned long)`	核心 ioctl 分发入口（无大内核锁）
`mmap`	`int (mmap)(struct file , struct vm_area_struct *)`	内存映射，用于 DMA 缓冲区共享

关键点：现代 V4L2 驱动必须使用 unlocked_ioctl 而非 ioctl（后者持有大内核锁 BKL，已被废弃）。unlocked_ioctl 在调用时不持有 BKL，驱动需要自行保证并发安全。

下图展示了从用户空间 ioctl() 系统调用到驱动具体处理函数的完整分发路径：

3.2 unlocked_ioctl 分发机制详解

V4L2 框架提供了标准的 video_ioctl2() 函数作为 unlocked_ioctl 的默认实现。该函数内部维护了一张庞大的 ioctl 命令映射表，将命令码与对应的驱动回调函数关联起来。驱动开发者只需实现具体的 vidioc_* 回调函数，无需手动编写 switch-case 分发逻辑。

3.2.1 分发流程步骤

命令码解析：video_ioctl2() 从用户空间传入的 cmd 参数中提取命令类型和方向（_IOC_DIR、_IOC_TYPE、_IOC_NR）。
参数校验与拷贝：根据命令方向，从用户空间拷贝参数到内核空间。对于写命令（_IOC_WRITE），使用 copy_from_user()；对于读命令（_IOC_READ），分配内核缓冲区。
命令查找：在 v4l2_ioctl_ops 结构体数组中查找匹配的命令处理函数。
调用处理函数：执行对应的 vidioc_* 回调函数，传入已解析的参数。
结果回写：对于读命令，使用 copy_to_user() 将结果返回用户空间。

调试技巧：在 video_ioctl2() 入口处添加 printk 或 dev_dbg 打印命令码，可以快速定位用户空间发送了哪些 ioctl 命令。例如：dev_dbg(dev, "ioctl: cmd=0x%x\n", cmd);

3.3 核心 ioctl 命令处理流程

以下详细分析三个最常用的 V4L2 ioctl 命令的处理流程：VIDIOC_QUERYCAP、VIDIOC_S_FMT 和 VIDIOC_REQBUFS。

3.3.1 VIDIOC_QUERYCAP：查询设备能力

该命令是应用程序打开 V4L2 设备后发送的第一个 ioctl，用于获取设备的基本信息，包括驱动名称、设备类型（capture/output）、是否支持 streaming I/O 等。

步骤	操作	说明
1	用户空间调用 `ioctl(fd, VIDIOC_QUERYCAP, &cap)`	传入 `struct v4l2_capability` 结构体指针
2	内核拷贝 `cap` 结构体到内核空间	`copy_from_user()`
3	调用驱动 `vidioc_querycap()` 回调	驱动填充 `struct v4l2_capability` 字段
4	驱动设置 `driver`、`card`、`bus_info` 字符串	通常使用 `strscpy()` 安全拷贝
5	驱动设置 `capabilities` 标志位	如 `V4L2_CAP_VIDEO_CAPTURE`、`V4L2_CAP_STREAMING`
6	内核将结果拷贝回用户空间	`copy_to_user()`

典型驱动实现示例：

static int vidioc_querycap(struct file *file, void *priv,
                           struct v4l2_capability *cap)
{
    struct my_device *dev = video_drvdata(file);

    strscpy(cap->driver, "my_v4l2_drv", sizeof(cap->driver));
    strscpy(cap->card, "My Camera Module", sizeof(cap->card));
    snprintf(cap->bus_info, sizeof(cap->bus_info),
             "platform:%s", dev->pdev->name);

    cap->capabilities = V4L2_CAP_VIDEO_CAPTURE |
                        V4L2_CAP_STREAMING |
                        V4L2_CAP_READWRITE;

    return 0;
}

3.3.2 VIDIOC_S_FMT：设置图像格式

该命令用于设置视频采集或输出的图像格式，包括分辨率、像素格式（如 YUYV、NV12）、帧间隔等。这是图像裁剪和 YUV 转换流程中的关键配置点。

常见陷阱：驱动在 vidioc_s_fmt() 中必须对用户请求的格式进行有效性验证和硬件能力适配。如果硬件不支持请求的分辨率，驱动应调整到最接近的可用值，并更新 struct v4l2_format 中的 fmt.pix 字段返回给用户。

处理流程包含以下关键步骤：

参数提取：从 struct v4l2_format 中提取 width、height、pixelformat、field 等字段。
格式验证：检查像素格式是否在驱动支持的格式列表中。
分辨率裁剪：如果请求的分辨率超出硬件限制，进行向下取整对齐（例如对齐到 16 像素边界）。
硬件配置：将验证后的格式写入硬件寄存器，配置图像采集引擎。
更新驱动状态：保存当前格式到驱动私有数据结构中，供后续 DMA 传输和缓冲区管理使用。
回写结果：将实际配置的格式写回用户空间传入的结构体。

驱动实现示例：

static int vidioc_s_fmt(struct file *file, void *priv,
                        struct v4l2_format *f)
{
    struct my_device *dev = video_drvdata(file);
    struct v4l2_pix_format *pix = &f->fmt.pix;
    int ret;

    // 1. 验证像素格式
    ret = validate_pixel_format(pix->pixelformat);
    if (ret)
        return ret;

    // 2. 分辨率裁剪与对齐
    pix->width = clamp(pix->width, MIN_WIDTH, MAX_WIDTH);
    pix->height = clamp(pix->height, MIN_HEIGHT, MAX_HEIGHT);
    pix->width = round_down(pix->width, 16);
    pix->height = round_down(pix->height, 16);

    // 3. 计算 bytesperline 和 sizeimage
    pix->bytesperline = pix->width * get_bpp(pix->pixelformat) / 8;
    pix->sizeimage = pix->bytesperline * pix->height;

    // 4. 配置硬件寄存器
    config_hw_format(dev, pix);

    // 5. 更新驱动状态
    dev->fmt = *pix;

    return 0;
}

3.3.3 VIDIOC_REQBUFS：请求缓冲区

该命令用于申请 DMA 缓冲区，是 streaming I/O 模式的起点。用户空间通过该命令告知驱动需要多少个缓冲区，驱动负责分配物理连续或分散的 DMA 内存。

参数	说明	典型值
`count`	请求的缓冲区数量	3~8（取决于应用需求）
`type`	缓冲区类型	`V4L2_BUF_TYPE_VIDEO_CAPTURE`
`memory`	内存模型	`V4L2_MEMORY_MMAP` 或 `V4L2_MEMORY_DMABUF`

处理流程：

检查状态：如果 streaming 已启动，拒绝请求（返回 -EBUSY）。
释放旧缓冲区：如果之前已分配缓冲区，先释放所有旧缓冲区。
分配 DMA 缓冲区：调用 dma_alloc_coherent() 或 vb2_dma_contig_memops 分配物理连续内存。
初始化 videobuf2 队列：将分配的缓冲区注册到 vb2 框架中。
更新 count：如果硬件无法满足请求的数量，驱动可减少 count 值并返回实际分配的数量。

3.4 ioctl 命令处理流程总结

下图总结了三个核心 ioctl 命令在驱动中的处理路径和相互依赖关系：

3.5 调试与验证方法

实践建议：在驱动开发阶段，建议在 vidioc_s_fmt() 和 vidioc_reqbufs() 中添加详细的调试打印，输出用户请求的参数和驱动实际配置的参数。这有助于快速定位格式不匹配或缓冲区分配失败的问题。

常用的调试手段包括：

使用 trace-cmd 跟踪 ioctl 系统调用：trace-cmd record -e syscalls:sys_enter_ioctl -e syscalls:sys_exit_ioctl
在驱动中添加 dev_dbg 打印：输出命令码、参数值和返回值。
使用 v4l2-compliance 工具验证：该工具会发送标准的 ioctl 序列，检查驱动的行为是否符合 V4L2 规范。
检查 dmesg 输出：关注驱动打印的错误信息和警告。