📚 课程目录第3章 V4L2设备节点与枚举

3. V4L2设备节点与枚举：/dev/videoX节点含义、通过ioctl VIDIOC_QUERYCAP查询设备能力、枚举支持的格式与分辨率。

在V4L2框架下，用户空间程序与内核驱动交互的入口是字符设备节点。理解这些节点的命名规则、能力查询方法以及格式枚举流程，是Camera HAL层开发与调试的基础。本章将深入剖析/dev/videoX节点的含义，并通过实际ioctl调用演示如何获取设备能力与支持的格式列表。

3.1 /dev/videoX节点含义与设备拓扑

Linux内核为每个注册的V4L2设备在/dev目录下创建字符设备节点，主设备号为81，次设备号从0开始递增。常见的节点类型包括：

节点名称	设备类型	典型用途	次设备号范围
`/dev/videoX`	视频采集/输出设备	Camera传感器数据采集、视频输出	0-63
`/dev/vbiX`	垂直消隐期数据设备	电视卡图文数据、隐藏字幕	224-255
`/dev/radioX`	无线电调谐设备	FM/AM收音机	64-127
`/dev/swradioX`	软件定义无线电设备	SDR接收	192-223
`/dev/mediaX`	Media Controller设备	拓扑管理、Pipeline配置	动态分配

调试提示：在Camera HAL层调试中，最常操作的是/dev/videoX节点。对于多摄像头平台，/dev/video0通常对应主摄像头（如后置），/dev/video1对应前置或深度摄像头。但此映射并非绝对，需通过Media Controller拓扑或驱动日志确认。

下图展示了一个典型嵌入式Camera子系统的设备节点拓扑关系：

3.2 使用VIDIOC_QUERYCAP查询设备能力

在打开/dev/videoX节点后，第一个关键步骤是调用VIDIOC_QUERYCAP ioctl查询设备能力。该调用返回struct v4l2_capability结构体，包含驱动名称、设备名称、总线信息以及能力标志位。

3.2.1 核心数据结构

struct v4l2_capability {
    __u8  driver[16];   // 驱动名称，如 "uvcvideo"
    __u8  card[32];     // 设备名称，如 "UVC Camera (046d:0825)"
    __u8  bus_info[32]; // 总线信息，如 "usb-0000:00:14.0-1"
    __u32 version;      // 驱动版本号
    __u32 capabilities; // 设备能力标志位
    __u32 device_caps;  // 设备特定能力（内核3.3+）
    __u32 reserved[3];
};

3.2.2 关键能力标志位解析

标志位	值	含义
`V4L2_CAP_VIDEO_CAPTURE`	0x00000001	支持视频采集（从Camera获取帧）
`V4L2_CAP_VIDEO_OUTPUT`	0x00000002	支持视频输出（显示/编码器）
`V4L2_CAP_VIDEO_M2M`	0x00008000	支持Memory-to-Memory处理（如ISP）
`V4L2_CAP_STREAMING`	0x04000000	支持流式I/O（mmap/userptr/dmabuf）
`V4L2_CAP_EXT_PIX_FORMAT`	0x00200000	支持扩展像素格式描述
`V4L2_CAP_DEVICE_CAPS`	0x80000000	支持`device_caps`字段

3.2.3 查询代码示例

#include <stdio.h>
#include <fcntl.h>
#include <sys/ioctl.h>
#include <linux/videodev2.h>

int query_device_caps(const char *dev_path) {
    int fd = open(dev_path, O_RDWR);
    if (fd < 0) {
        perror("open");
        return -1;
    }

    struct v4l2_capability cap;
    if (ioctl(fd, VIDIOC_QUERYCAP, &cap) < 0) {
        perror("VIDIOC_QUERYCAP");
        close(fd);
        return -1;
    }

    printf("Driver: %s\n", cap.driver);
    printf("Card: %s\n", cap.card);
    printf("Bus info: %s\n", cap.bus_info);
    printf("Version: %u.%u.%u\n",
           (cap.version >> 16) & 0xFF,
           (cap.version >> 8) & 0xFF,
           cap.version & 0xFF);

    __u32 caps = cap.capabilities;
    if (caps & V4L2_CAP_VIDEO_CAPTURE)
        printf("  [+] VIDEO_CAPTURE\n");
    if (caps & V4L2_CAP_STREAMING)
        printf("  [+] STREAMING\n");
    if (caps & V4L2_CAP_VIDEO_M2M)
        printf("  [+] VIDEO_M2M\n");

    close(fd);
    return 0;
}

  HAL层调试要点：在Camera HAL的open()回调中，必须首先调用VIDIOC_QUERYCAP验证设备是否为预期的Capture设备。如果V4L2_CAP_VIDEO_CAPTURE标志未置位，应返回错误并记录日志，避免后续操作失败。

3.3 枚举支持的格式与分辨率

查询设备能力后，下一步是枚举设备支持的像素格式和分辨率组合。V4L2通过VIDIOC_ENUM_FMT和VIDIOC_ENUM_FRAMESIZES两个ioctl实现此功能。

3.3.1 枚举像素格式

使用VIDIOC_ENUM_FMT遍历设备支持的格式。每次调用前设置index字段，从0开始递增，直到返回EINVAL。

struct v4l2_fmtdesc fmt;
memset(&fmt, 0, sizeof(fmt));
fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

for (fmt.index = 0; ; fmt.index++) {
    if (ioctl(fd, VIDIOC_ENUM_FMT, &fmt) < 0)
        break;
    printf("Format %d: %s (0x%08x)\n",
           fmt.index, fmt.description, fmt.pixelformat);
}

3.3.2 枚举分辨率

对于每种支持的格式，使用VIDIOC_ENUM_FRAMESIZES枚举所有可用的分辨率组合。

struct v4l2_frmsizeenum frmsize;
memset(&frmsize, 0, sizeof(frmsize));
frmsize.pixel_format = V4L2_PIX_FMT_YUYV; // 指定格式

for (frmsize.index = 0; ; frmsize.index++) {
    if (ioctl(fd, VIDIOC_ENUM_FRAMESIZES, &frmsize) < 0)
        break;

    if (frmsize.type == V4L2_FRMSIZE_TYPE_DISCRETE) {
        printf("  [%dx%d]\n",
               frmsize.discrete.width,
               frmsize.discrete.height);
    } else if (frmsize.type == V4L2_FRMSIZE_TYPE_STEPWISE) {
        printf("  Stepwise: min %dx%d, max %dx%d, step %dx%d\n",
               frmsize.stepwise.min_width,
               frmsize.stepwise.min_height,
               frmsize.stepwise.max_width,
               frmsize.stepwise.max_height,
               frmsize.stepwise.step_width,
               frmsize.stepwise.step_height);
    }
}

3.3.3 格式枚举流程图

下图展示了完整的格式枚举流程：

3.4 常见调试问题与避坑指南

常见问题1：VIDIOC_QUERYCAP返回EPERM
原因：设备节点权限不足。Camera HAL进程通常需要media或camera用户组权限。
解决：检查ls -l /dev/video*的权限位，确保HAL进程在正确的用户组中运行。

常见问题2：枚举格式时返回ENOTTY
原因：ioctl类型不匹配。例如对Output设备使用V4L2_BUF_TYPE_VIDEO_CAPTURE。
解决：根据VIDIOC_QUERYCAP返回的device_caps判断设备类型，选择正确的buf_type。

调试技巧：使用v4l2-ctl --list-formats-ext命令行工具可以快速查看设备支持的格式和分辨率，用于对比HAL层枚举结果是否正确。

3.5 本章小结

本章详细介绍了V4L2设备节点的含义、通过VIDIOC_QUERYCAP查询设备能力的方法，以及枚举支持的格式与分辨率的完整流程。掌握这些基础操作是Camera HAL层开发的第一步，也是后续配置格式、申请缓冲区、启动数据流的前提。在实际调试中，建议将枚举结果与硬件规格书进行交叉验证，确保HAL层正确识别设备能力。