4. Video设备注册

Video设备节点的注册是V4L2驱动从内核态向用户态暴露接口的关键步骤。错误的填充顺序、遗漏的初始化步骤或不当的调用时机，都会直接导致设备节点无法创建、ioctl调用失败，甚至在流式传输过程中引发丢帧。本节将深入剖析video_device结构体的每个关键字段、v4l2_device_register与video_register_device的调用契约，以及生产级错误处理模式。

4.1 video_device结构体：驱动与V4L2核心的契约

struct video_device是驱动开发者与V4L2框架之间的核心数据结构。它承载了设备节点的行为定义、文件操作回调、控制句柄以及索引信息。填充不完整或字段赋值错误，是导致注册失败和运行时异常的首要原因。

4.2 v4l2_device_register：顶层设备的注册时机

v4l2_device_register 是V4L2设备注册的入口点。它创建一个顶层 v4l2_device 实例，作为所有子设备（subdev）和video节点的父容器。调用时机必须早于任何子设备或video节点的注册。

/* 典型调用顺序：在probe函数中，首先注册v4l2_device */
static int camera_probe(struct platform_device *pdev)
{
    struct camera_dev *cam;
    int ret;

    cam = devm_kzalloc(&pdev->dev, sizeof(*cam), GFP_KERNEL);
    if (!cam)
        return -ENOMEM;

    /* 第1步：注册顶层v4l2_device */
    cam->v4l2_dev = devm_kzalloc(&pdev->dev, sizeof(*cam->v4l2_dev), GFP_KERNEL);
    if (!cam->v4l2_dev)
        return -ENOMEM;

    ret = v4l2_device_register(&pdev->dev, cam->v4l2_dev);
    if (ret < 0) {
        dev_err(&pdev->dev, "Failed to register v4l2_device: %d\n", ret);
        return ret;
    }

    /* 第2步：初始化子设备（如传感器、ISP） */
    /* ... */

    /* 第3步：初始化vb2队列 */
    /* ... */

    /* 第4步：填充并注册video_device */
    /* ... */

    return 0;
}

4.3 video_register_device：节点创建的精确时机

video_register_device 是最终创建设备节点的函数。调用时机必须满足以下前置条件：

• v4l2_device_register 已成功返回
• video_device 结构体所有关键字段已填充
• vb2_queue 已初始化并关联到 video_device->queue
• 所有硬件资源（时钟、GPIO、中断）已就绪

/* video_device填充与注册的完整示例 */
static int camera_setup_video_device(struct camera_dev *cam)
{
    struct video_device *vdev;
    int ret;

    vdev = devm_kzalloc(cam->v4l2_dev->dev, sizeof(*vdev), GFP_KERNEL);
    if (!vdev)
        return -ENOMEM;

    /* 填充fops和ioctl_ops */
    vdev->fops       = &camera_fops;
    vdev->ioctl_ops  = &camera_ioctl_ops;

    /* 设置设备能力 */
    vdev->device_caps = V4L2_CAP_VIDEO_CAPTURE | V4L2_CAP_STREAMING;

    /* 设置节点类型和方向 */
    vdev->vfl_type = VFL_TYPE_VIDEO;
    vdev->vfl_dir  = VFL_DIR_RX;

    /* 关联父级v4l2_device */
    vdev->v4l2_dev = cam->v4l2_dev;

    /* 关联vb2队列 */
    vdev->queue = &cam->vb2_queue;

    /* 关联控制句柄 */
    vdev->ctrl_handler = &cam->ctrl_handler;

    /* 设置release回调（必须！） */
    vdev->release = video_device_release_empty;

    /* 注册video设备 */
    ret = video_register_device(vdev, VFL_TYPE_VIDEO, -1);
    if (ret < 0) {
        dev_err(cam->v4l2_dev->dev,
                "Failed to register video device: %d\n", ret);
        return ret;
    }

    cam->vdev = vdev;
    dev_info(cam->v4l2_dev->dev,
             "Video device registered as /dev/video%d\n", vdev->num);

    return 0;
}

4.4 错误处理：生产级注册失败恢复模式

注册失败时，必须执行完整的错误回滚，否则会导致资源泄漏或后续设备注册失败。以下是一个完整的错误处理流程：

static int camera_probe(struct platform_device *pdev)
{
    struct camera_dev *cam;
    int ret;

    /* 分配设备结构体 */
    cam = devm_kzalloc(&pdev->dev, sizeof(*cam), GFP_KERNEL);
    if (!cam)
        return -ENOMEM;

    platform_set_drvdata(pdev, cam);

    /* 第1步：注册v4l2_device */
    ret = v4l2_device_register(&pdev->dev, &cam->v4l2_dev);
    if (ret) {
        dev_err(&pdev->dev, "v4l2_device_register failed: %d\n", ret);
        goto err_free_cam;
    }

    /* 第2步：初始化硬件（时钟、I2C、GPIO） */
    ret = camera_hw_init(cam);
    if (ret) {
        dev_err(&pdev->dev, "Hardware init failed: %d\n", ret);
        goto err_unregister_v4l2;
    }

    /* 第3步：初始化vb2队列 */
    ret = camera_setup_vb2_queue(cam);
    if (ret) {
        dev_err(&pdev->dev, "vb2 queue setup failed: %d\n", ret);
        goto err_hw_deinit;
    }

    /* 第4步：初始化控制句柄 */
    ret = camera_setup_ctrls(cam);
    if (ret) {
        dev_err(&pdev->dev, "Control setup failed: %d\n", ret);
        goto err_cleanup_queue;
    }

    /* 第5步：注册video_device */
    ret = camera_setup_video_device(cam);
    if (ret) {
        dev_err(&pdev->dev, "Video device setup failed: %d\n", ret);
        goto err_free_ctrls;
    }

    dev_info(&pdev->dev, "Camera driver initialized successfully\n");
    return 0;

err_free_ctrls:
    v4l2_ctrl_handler_free(&cam->ctrl_handler);
err_cleanup_queue:
    vb2_queue_release(&cam->vb2_queue);
err_hw_deinit:
    camera_hw_deinit(cam);
err_unregister_v4l2:
    v4l2_device_unregister(&cam->v4l2_dev);
err_free_cam:
    /* devm_kzalloc自动释放，无需手动kfree */
    return ret;
}

4.5 注册流程全景图：从probe到/dev/videoX

下图展示了从驱动probe到用户态可见的 /dev/videoX 节点的完整注册流程，以及每个阶段的关键检查点：

4.6 丢帧视角：注册阶段埋下的隐患

注册阶段的错误不会立即表现为丢帧，但会在流式传输阶段以各种形式暴露：