69.V4L2 Sub-device 驱动编写实战：Sensor 与 Lens 驱动的完整开发流程解析

V4L2 Sub-device 驱动编写实战：Sensor 与 Lens 驱动的完整开发流程解析

关键词：
V4L2、Sub-device、Sensor 驱动、Lens 驱动、I2C、media_entity、pad 配置、stream control、camera module bring-up、内核驱动开发

摘要：
在现代 Android 图像系统中，Sensor 与 Lens 作为 V4L2 子设备（Sub-device）存在，是图像管线中最底层的物理采集与控制组件。Sub-device 驱动的正确实现决定了整个 Camera Media Pipeline 的可用性与稳定性。本文基于实际工程案例，系统讲解如何为图像传感器（如 Sony IMX586）与马达镜头模块编写符合 V4L2 架构的 Sub-device 驱动，涵盖设备树配置、I2C 通信初始化、控制接口绑定、pad 配置与 stream 操作等核心技术点，并结合高通/MTK 主流平台的 bring-up 流程给出实战参考。

目录规划：

1. V4L2 Sub-device 驱动架构概述与开发接口说明
2. Sensor 驱动初始化流程：设备树解析、I2C 接入与 clk 电源管理
3. Lens 驱动实现：AF/VCM 模块的控制接口与 ioctl 封装
4. media_entity / pad 配置：构建可连接的 Graph 拓扑结构
5. stream_on/off 回调与 pipeline 激活路径实战解析
6. control_ops 注册与 AE/AF 等控制命令的处理方式
7. 平台移植经验：IMX586 / OV64B / GC5035 多模组对接案例
8. 调试策略与 bring-up 检查清单：从 probe 到 stream 成功闭环

第1章：V4L2 Sub-device 驱动架构概述与开发接口说明

1.1 Sub-device 的定义与作用

在 V4L2 架构中，Sub-device 是对 ISP pipeline 中“功能节点”的抽象，包括 Sensor、Lens、Flash、ISP Unit 等，其核心特征是：

• 不能直接通过 video_device 访问；
• 通过 media framework 的 media_entity 构建连接；
• 接收来自主 video pipeline 的 stream on/off 控制；
• 提供标准化的 v4l2_subdev_ops 接口供 pipeline 管理调用。

Sub-device 驱动通常以 platform 或 I2C 方式注册，遵循标准的设备模型。

1.2 驱动结构总览

Sub-device 驱动结构主要包括以下几个部分：

• probe/init 函数： 完成资源申请、clk 和 regulator 配置、I2C 接入等；
• v4l2_subdev_ops： 提供 core、video、pad、sensor 接口；
• media_entity_ops： 定义 media link 是否支持动态配置；
• v4l2_ctrl_handler： 注册 AE、AWB、Exposure 等控制项；
• stream control： 支持 s_stream() 控制 pipeline 启停；
• format negotiation： 支持 get_fmt / set_fmt 等接口设置图像输出格式。

1.3 Sub-device 驱动注册流程

常见注册流程如下（以 I2C 驱动为例）：

1. 设备树匹配：

&i2c1 {
    imx586@1a {
        compatible = "sony,imx586";
        reg = <0x1a>;
        ...
    };
};

2. 驱动 match 并注册：

static const struct i2c_device_id imx586_id[] = {
    { "imx586", 0 },
    { }
};

static const struct of_device_id imx586_of_match[] = {
    { .compatible = "sony,imx586", },
    { },
};

MODULE_DEVICE_TABLE(of, imx586_of_match);

static struct i2c_driver imx586_i2c_driver = {
    .driver = {
        .name = "imx586",
        .of_match_table = imx586_of_match,
    },
    .probe = imx586_probe,
    .id_table = imx586_id,
};

module_i2c_driver(imx586_i2c_driver);

3. subdev 初始化：

v4l2_i2c_subdev_init(&imx586->sd, client, &imx586_subdev_ops);
imx586->sd.entity.ops = &imx586_media_ops;
media_entity_pads_init(&imx586->sd.entity, 1, &imx586->pad);

4. control handler 注册：

v4l2_ctrl_handler_init(&imx586->ctrl_handler, 16);
v4l2_ctrl_new_std(&imx586->ctrl_handler, &imx586_ctrl_ops,
    V4L2_CID_EXPOSURE, 0, 1000, 1, 100);
imx586->sd.ctrl_handler = &imx586->ctrl_handler;

1.4 子设备间的连接与 pad 概念

每个 Sub-device 通常配置一个或多个 media pad，用于指定图像流的输入/输出方向。连接关系通过 media_create_pad_link() 建立：

media_entity_pads_init(&subdev->entity, 1, &subdev->pad);
subdev->pad.flags = MEDIA_PAD_FL_SOURCE;

最终构成的 media graph 可通过 media-ctl -p 查看其拓扑结构，实现动态配置与调试。

第2章：Sensor 驱动初始化流程：设备树解析、I2C 接入与 clk 电源管理

2.1 设备树节点配置要点

Sensor 节点必须配置如下关键参数，供驱动 probe 时解析：

imx586@1a {
    compatible = "sony,imx586";
    reg = <0x1a>;
    clocks = <&camcc CAM_CC_MCLK1>;
    clock-names = "xclk";
    vdddo-supply = <&vreg_l12>;
    vdda-supply = <&vreg_l10>;
    reset-gpios = <&tlmm 23 GPIO_ACTIVE_LOW>;
    orientation = <0>; // front=0, rear=1
    port {
        imx586_ep: endpoint {
            remote-endpoint = <&csiphy0_ep>;
            data-lanes = <1 2>;
            ...
        };
    };
};

2.2 驱动中解析设备树

驱动中通过 of_property_* 系列函数完成配置项解析：

priv->xvclk = devm_clk_get(&client->dev, "xclk");
priv->reset_gpio = devm_gpiod_get_optional(&client->dev, "reset", GPIOD_OUT_LOW);
priv->avdd = devm_regulator_get(&client->dev, "vdda");

注意事项：

• 电源必须依赖 regulator framework；
• clk 获取后必须 enable；
• GPIO 建议使用 devm 系列以避免泄露；
• 若支持 runtime pm，需在 stream on/off 中控制电源开关逻辑。

2.3 I2C 通信初始化与访问校验

Sensor 驱动通常以 I2C 为控制通道，通过 regmap 或裸 I2C 接口访问寄存器：

ret = i2c_smbus_read_byte_data(client, IMX586_CHIP_ID_H);
if (ret != EXPECTED_ID)
    return -ENODEV;

或使用 regmap：

priv->regmap = devm_regmap_init_i2c(client, &imx586_regmap_config);

常见问题：

• 地址位宽错误（8bit vs 16bit）；
• 寄存器访问失败常由电源未拉起或 sensor 未启动时钟引起；
• 若 Sensor 上电后不识别，可使用 i2cdetect 等外部工具确认总线通畅。

2.4 clk 与 regulator 控制时序

Sensor 模块常需要特定的上电顺序，如：

1. 拉高电源；
2. 打开时钟；
3. 拉高 reset；
4. 延迟一段时间；
5. 开始访问寄存器。

典型代码如下：

regulator_enable(priv->avdd);
clk_prepare_enable(priv->xvclk);
gpiod_set_value(priv->reset_gpio, 1);
msleep(10);

stream_off 时需倒序关闭资源，以确保电源管理合理、功耗可控。

第3章：Lens 驱动实现：AF/VCM 模块的控制接口与 ioctl 封装

3.1 VCM 自动对焦模块结构简介

VCM（Voice Coil Motor）是镜头中负责驱动对焦模组上下移动的核心元件，通常通过 I2C 进行位置控制。典型的 VCM 驱动芯片有：

• DW9714、DW9719（新思）；
• BU64297（ROHM）；
• LC898212（ALPS）等。

在 Linux V4L2 框架中，Lens 模块作为独立 Sub-device 存在，核心职责是：

• 提供对焦位置设置能力（absolute position）；
• 支持 region scanning、微调步进；
• 与 sensor、ISP 联动控制 AE/AWB/AFC 等算法。

3.2 驱动结构概览

Lens 驱动的主要结构与 sensor 类似，由以下几部分组成：

• probe() 处理设备树资源；
• v4l2_subdev_ops 注册核心操作接口（如 focus 设置）；
• v4l2_ctrl_ops 处理 ioctl 请求（如 V4L2_CID_FOCUS_ABSOLUTE ）；
• s_ctrl() 实现位置调节与功耗控制。

典型注册方式：

static struct v4l2_subdev_ops lens_ops = {
    .core = &lens_core_ops,
};

static int vcm_probe(struct i2c_client *client, ...)
{
    ...
    v4l2_i2c_subdev_init(&vcm->sd, client, &lens_ops);
    ...
}

3.3 支持 ioctl：focus control 注册与实现

使用标准控制 ID 注册控制接口：

v4l2_ctrl_new_std(&vcm->ctrl_handler, &vcm_ctrl_ops,
    V4L2_CID_FOCUS_ABSOLUTE, 0, MAX_FOCUS_POS, 1, INIT_POS);

其中 MAX_FOCUS_POS 由硬件特性决定，通常为 1023。

对应的 s_ctrl() 实现：

static int vcm_s_ctrl(struct v4l2_ctrl *ctrl)
{
    switch (ctrl->id) {
    case V4L2_CID_FOCUS_ABSOLUTE:
        return vcm_move_focus(ctrl->val);
    default:
        return -EINVAL;
    }
}

vcm_move_focus() 是硬件相关的 I2C 接口函数：

static int vcm_move_focus(u16 pos)
{
    u8 buf[2];
    buf[0] = (pos >> 8) & 0x3F;
    buf[1] = pos & 0xFF;
    return i2c_master_send(client, buf, 2);
}

3.4 动态功耗管理与 stream_on 配合

VCM 电机驱动需要低功耗控制，stream_off 后需断电或切 sleep：

static int vcm_s_stream(struct v4l2_subdev *sd, int enable)
{
    if (enable)
        return vcm_power_on();
    else
        return vcm_power_off();
}

通常还需定义 pm_runtime_ops 配合系统 suspend/resume。

第4章：media_entity / pad 配置：构建可连接的 Graph 拓扑结构

4.1 Media Controller 简介

V4L2 通过 media controller 构建图像通路，类似拓扑图描述硬件节点连接。其核心单位：

• media_entity ：代表一个设备实体（Sensor、Lens、ISP 等）；
• media_pad ：表示实体的输入/输出端口；
• media_link ：连接两个实体间的 pad，形成图像 pipeline。

这一结构确保了多模组、多 ISP 系统的动态可配置能力。

4.2 Sensor 与 Lens 的连接定义

驱动中，每个子设备需要声明 pad：

static struct media_pad sensor_pads[1] = {
    {
        .flags = MEDIA_PAD_FL_SOURCE,
    },
};

sensor->sd.entity.function = MEDIA_ENT_F_CAM_SENSOR;
media_entity_pads_init(&sensor->sd.entity, 1, sensor_pads);

Lens 通常为 MEDIA_ENT_F_LENS 类型：

lens->sd.entity.function = MEDIA_ENT_F_LENS;
media_entity_pads_init(&lens->sd.entity, 0, NULL);

注意 Lens 无数据流，因此无需 pad，但可被关联控制。

4.3 建立 media link 的路径逻辑

在 video_register_subdev() 之后，由 pipeline 管理组件（如平台 glue 层或 camss 管理）使用：

media_create_pad_link(&sensor->sd.entity, 0,
                      &isp->entity, CSI_PAD_SINK,
                      MEDIA_LNK_FL_ENABLED | MEDIA_LNK_FL_IMMUTABLE);

建立完成后：

• 可通过 media-ctl -p 查看完整图；
• 用户态配置需通过 media-ctl 指定路由路径。

4.4 多 Camera 模组拓扑构建参考

典型双摄构图：

+-------------+     +-------------+
|  Sensor A   | --> |   CSI A     |
+-------------+     +-------------+
                         |
                     +---+---+
                     |  ISP   |
                     +---+---+
                         |
+-------------+     +-------------+
|  Sensor B   | --> |   CSI B     |
+-------------+     +-------------+

通过 pad-link 构建上图路径，可实现：

• 前后摄切换；
• 主副摄同步采集；
• 多 ISP 管线融合；

第5章：stream_on/off 回调与 pipeline 激活路径实战解析

5.1 s_stream() 是什么

s_stream() 是 V4L2 Sub-device 驱动中核心的启动/关闭数据流控制接口，作用是控制 sensor 等子设备是否输出视频流，配合 ISP 管道完成整个 pipeline 的激活或关闭流程。

其典型定义：

static const struct v4l2_subdev_video_ops sensor_video_ops = {
    .s_stream = sensor_s_stream,
};

5.2 启动数据流的调用链

启动 camera 流程如下（以单 sensor 为例）：

应用层：VIDIOC_STREAMON
↓
V4L2 核心：vb2_ioctl_streamon()
↓
ISP 主设备：启动 DMA、请求缓冲队列
↓
Pipeline：调用 sensor 的 s_stream(true)
↓
Sensor 子设备：开始输出 MIPI 图像数据

其中 s_stream(true) 的作用：

• 控制 GPIO 拉高 Sensor 的 STANDBY；
• 发送启动命令到 Sensor；
• 启用时钟、电压等电源域；
• 初始化帧率、曝光、增益等默认值。

关闭流程为相反路径。

5.3 s_stream() 示例

static int imx586_s_stream(struct v4l2_subdev *sd, int on)
{
    struct imx586 *sensor = to_imx586(sd);

    if (on) {
        power_on(sensor);
        write_init_regs(sensor);
    } else {
        write_stop_stream(sensor);
        power_off(sensor);
    }

    return 0;
}

注意事项：

• 若 stream 失败，需正确 return 错误码；
• 多个 sensor 时，主链路通常是由 CSI 控制；
• 若在 ISP 平台上，需与 CSI 子模块配合启停。

5.4 多链路并发启动

复杂系统中，例如双摄同步（主副 sensor），需保证 s_stream() 执行顺序正确：

• 通常由 media framework 控制；
• 可在 glue 驱动层记录每个 stream 状态，全部准备好再启动 ISP。

第6章：control_ops 注册与 AE/AF 等控制命令的处理方式

6.1 控制命令概述

V4L2 中对 AE（自动曝光）、AF（自动对焦）、AWB（自动白平衡）等控制参数的设置通过 v4l2_ctrl_ops 实现，这些控制统一注册进 v4l2_ctrl_handler 并被应用层使用标准 ioctl 操作访问。

6.2 control 注册流程

在 probe 阶段：

v4l2_ctrl_handler_init(&sensor->ctrl_handler, 16);
v4l2_ctrl_new_std(&sensor->ctrl_handler, &ctrl_ops,
    V4L2_CID_EXPOSURE, 0, 10000, 1, 100);
v4l2_ctrl_new_std(&sensor->ctrl_handler, &ctrl_ops,
    V4L2_CID_GAIN, 0, 255, 1, 64);
sensor->sd.ctrl_handler = &sensor->ctrl_handler;

其中：

• min, max, step, default 是参数配置；
• ctrl_ops 中实现具体的 s_ctrl() 方法；
• 注册后 ioctl( VIDIOC_S_CTRL ) 即可使用。

6.3 实现 s_ctrl() 回调

static int sensor_s_ctrl(struct v4l2_ctrl *ctrl)
{
    switch (ctrl->id) {
    case V4L2_CID_EXPOSURE:
        return sensor_set_exposure(ctrl->val);
    case V4L2_CID_GAIN:
        return sensor_set_gain(ctrl->val);
    default:
        return -EINVAL;
    }
}

典型硬件函数：

static int sensor_set_exposure(u32 val)
{
    i2c_write_reg16(sensor, EXPO_REG, val);
}

6.4 自定义扩展控制项

如果需要非标准控制（如高速 AE 预判模式），可使用 v4l2_ctrl_new_custom() 注册扩展 ID 或使用私有 ioctl：

#define V4L2_CID_SENSOR_MODE (V4L2_CID_USER_BASE + 0x1000)

v4l2_ctrl_new_custom(&handler, &custom_ctrl, NULL);

自定义控制也必须定义在用户空间头文件中暴露，供 HAL 或应用访问。

6.5 控制同步策略

控制操作需要和 streaming 流程配合使用：

• 若在 stream_on 前设置参数，sensor 必须缓存并开流时应用；
• 若在 streaming 中动态修改，需确保 i2c 通道稳定；
• 某些平台支持 delayed control sync ，即通过帧头同步更新参数，需与 ISP 平台协议一致。

第7章：平台移植经验：IMX586 / OV64B / GC5035 多模组对接案例

7.1 Sensor 移植中的常见挑战

在实际 Camera 驱动开发中，不同 Sensor 模组虽然结构相似，但在平台对接过程中仍存在大量工程差异，典型如：

• 时钟频率 / mipi lane 数配置不一致；
• 驱动 I2C 地址或寄存器位宽不同；
• VCM 对焦控制协议差异；
• Device Tree 中端口描述方式变化；
• CSI 模块连接拓扑、路由节点需按平台区分。

7.2 IMX586 on QCOM 平台：典型高端模组部署

关键特征：

• 48MP 高分辨率，四像素合一输出；
• 通常使用 MIPI 4-lane，需配置 D-PHY；
• 寄存器宽度为 16bit 地址 + 8bit 数据。

适配流程要点：

• clocks 必须为 24MHz，需从 camcc 中正确绑定；
• reset / pwdn GPIO 需与 PMIC 引脚映射一致；
• QCOM 平台通过 CAMX XML 配置 ISP 路由链，需绑定 Sensor ID；
• HDR 模式需要配合平台 CSID 的 virtual channel 设置；
• V4L2 + CAMX 双栈模式时，需确保 dual registration 互不冲突。

7.3 OV64B on MTK 平台：对 exposure/Gain 控制严格

关键特征：

• 支持多段 HDR（Staggered exposure），需正确配置 sensor_mode ；
• regmap 支持 page select，部分寄存器分 bank 管理；
• MTK 平台通过 metadata 接口读回帧内 AE 数据。

适配流程要点：

• 必须严格按照 timing table 编程，多个 mode 需分开调试；
• MTK 的 cam_cal 区域配置 EEPROM、LCM_ID 等 Sensor OTP 信息，需同步 OTA 表；
• streaming on/off 时序敏感，建议加入调试帧延迟打印（帧数确认）；
• 若支持 PD 数据（相位检测），需配置对应 2A 路径接口；

7.4 GC5035 on Unisoc / Rockchip 平台：中低端模组实战部署

关键特征：

• 5MP 级别成本优化型 Sensor，适用于副摄、小模组；
• 不支持高阶 AE/AWB/HDR；
• 通常无需 ISP 内部的 AF、HDR 路径解析；
• 寄存器偏移量与寄存器初始化极其敏感。

适配流程要点：

• GPIO 电平需精确满足上下电 timing spec，通常对时序窗口严格；
• Unisoc 平台需通过 XML 映射 Sensor-ID 与通道对应；
• Rockchip 平台推荐使用 YAML 结构注册 camera.json；
• 对 stream 状态无 callback 支持，需靠 driver 自建计数同步 pipeline 状态；

第8章：调试策略与 bring-up 检查清单：从 probe 到 stream 成功闭环

8.1 Sensor bring-up 步骤总览

1. 设备树配置

   • 地址、时钟、GPIO、电源 rail 校准
   • CSI endpoint 绑定端口

2. 驱动 probe 调通

   • I2C 通信正常
   • Chip ID 可识别

3. stream on/off 正常

   • 电源域控制同步
   • s_stream 走通，无错误返回

4. ISP 正常接收

   • CSI 模块有同步信号
   • ISP log 中帧统计递增

5. 应用层图像显示

   • Camera HAL 收到帧数据
   • 无 crash、无花屏

8.2 调试命令与辅助工具清单

• i2cdetect -y 0 ：确认 sensor 地址是否识别；
• v4l2-ctl --all ：查看 video device 注册是否成功；
• media-ctl -p ：确认 media pad 拓扑是否创建；
• v4l2-ctl --stream-mmap ：尝试开启采集，验证 DMA 是否正常；
• dmesg | grep sensor ：追踪 probe 流程 log；
• cat /sys/class/video4linux/videoX/name ：确认节点是否匹配目标 sensor。

8.3 常见失败点与分析策略

本文转自 https://jc-performance.cn//online/4246_148655733.html，如有侵权，请联系删除。