RK平台摄像头驱动移植问题图谱：Sensor / MIPI / rkcif / rkisp / V4L2 全链路排查实战

最新推荐文章于 2026-06-21 19:21:05 发布

原创最新推荐文章于 2026-06-21 19:21:05 发布 · 402 阅读

6 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#网络 #音视频 #c语言 #开发语言 #udp

话题

#【多重好礼】OpenTiny NEXT 前端智能化系列直播征文活动

rockchip 专栏收录该内容

18 篇文章

订阅专栏

📺 B站嵌入式孙老师：博主个人介绍

📘 博主书籍-京东购买链接*：Yocto项目实战教程

📘 加博主微信，进技术交流群： jerrydev

RK平台摄像头驱动移植问题图谱：Sensor / MIPI / rkcif / rkisp / V4L2 全链路排查实战

在这里插入图片描述

在 Rockchip 平台做摄像头驱动移植时，最常见的问题不是单个驱动函数写错，而是整个 Camera Pipeline 中某个环节没有打通。一个完整的 RK 摄像头链路通常如下：

Sensor
  -> MIPI DPHY / CSI-2
  -> rkcif
  -> rkisp
  -> video node
  -> V4L2 / Media Controller
  -> App / v4l2-ctl / gst-launch / ffmpeg

其中任意一层异常，都可能最终表现成：

/dev/video 没有生成
media-ctl -p 看不到 sensor
VIDIOC_STREAMON failed
select timeout
MIPI_CSI2_ERR1
rkcif size err
图像花屏 / 偏色 / 黑屏
rkaiq 不加载 IQ 文件

因此，RK Camera Bring-up 的核心思路不是“看到哪个错误就改哪个地方”，而是要按链路分层排查：

供电 / 时钟 / GPIO
  -> I2C 通信
  -> Sensor probe
  -> Device Tree endpoint
  -> Media Controller 拓扑
  -> MIPI CSI-2 数据接收
  -> rkcif / rkisp 数据流
  -> V4L2 stream on
  -> Raw 图像
  -> ISP 调图

2. RK 摄像头整体链路

2.1 硬件数据链路

Sensor 输出图像数据
        |
        | MIPI CSI-2
        v
MIPI DPHY / CSI-2 Receiver
        |
        v
rkcif
        |
        v
rkisp
        |
        v
/dev/videoX

各模块职责如下：

模块	作用
Sensor	采集图像，输出 RAW/YUV 数据
MIPI DPHY	接收高速 MIPI 差分信号
CSI-2	解析 MIPI 包、lane、VC、Data Type
rkcif	接收并缓存前端数据
rkisp	ISP 图像处理，如 AE/AWB/AF、降噪、颜色校正
video node	提供 V4L2 设备节点
userspace	使用 media-ctl、v4l2-ctl、gst、ffmpeg 抓图或预览

2.2 软件控制链路

Device Tree
  -> I2C client
  -> Sensor driver probe
  -> clk / regulator / gpio / pinctrl
  -> v4l2 subdev
  -> async notifier
  -> media entity / pad / link
  -> video device

关键配置包括：

compatible
reg
clocks / clock-names
reset-gpios / pwdn-gpios
avdd / dovdd / dvdd regulators
power-domains
pinctrl
ports / endpoint / remote-endpoint
data-lanes
link-frequencies
mbus-code
module-index / facing / lens-name

3. 常见问题分类

RK Camera 移植问题可以按下面几类处理：

1. Sensor 驱动问题
2. Device Tree 配置问题
3. MIPI CSI-2 / DPHY / rkcif 问题
4. Media Controller / V4L2 链路问题
5. STREAMON 失败问题
6. ISP 图像与画质问题
7. 调试工具与排查流程问题

每类问题都有自己的典型现象和定位入口。

4. Sensor 驱动问题

4.1 Sensor probe 失败

典型现象

sensor probe failed
read chip id failed
i2c transfer failed
i2c read reg failed
Unexpected sensor id

或者内核启动后没有任何 sensor 日志。

常见原因

1. I2C 地址错误
2. I2C bus 选错
3. sensor 没有供电
4. MCLK 没有输出
5. RESET / PWDN GPIO 极性错误
6. 上电时序不满足 sensor datasheet
7. compatible 和驱动不匹配
8. 寄存器地址位宽或数据位宽错误

排查命令

查看 I2C 设备：

i2cdetect -y 3

查看 sensor 相关日志：

dmesg | grep -i sensor
dmesg | grep -i camera
dmesg | grep -i i2c

查看 GPIO：

cat /sys/kernel/debug/gpio

查看时钟：

cat /sys/kernel/debug/clk/clk_summary | grep -i cam
cat /sys/kernel/debug/clk/clk_summary | grep -i cif
cat /sys/kernel/debug/clk/clk_summary | grep -i xclk

查看 regulator：

cat /sys/kernel/debug/regulator/regulator_summary

4.2 I2C 地址问题

很多 sensor datasheet 会给出 8-bit I2C 地址，例如：

write address = 0x6c
read address  = 0x6d

但 Linux 设备树中 reg 一般填写 7-bit 地址：

0x6c >> 1 = 0x36

设备树应写：

camera@36 {
    compatible = "vendor,sensor";
    reg = <0x36>;
};

错误写法：

camera@6c {
    compatible = "vendor,sensor";
    reg = <0x6c>;
};

这会导致驱动访问错误地址，最终表现为：

i2c transfer failed
read chip id failed

4.3 Sensor 上电时序问题

典型 sensor 上电流程：

enable avdd
enable dovdd
enable dvdd
enable mclk
reset active
delay
pwdn inactive
delay
reset inactive
delay
read chip id

驱动中一般类似：

static int sensor_power_on(struct sensor *sensor)
{
    regulator_enable(sensor->avdd);
    regulator_enable(sensor->dovdd);
    regulator_enable(sensor->dvdd);

    clk_prepare_enable(sensor->xvclk);

    gpiod_set_value_cansleep(sensor->reset_gpio, 1);
    usleep_range(1000, 2000);

    gpiod_set_value_cansleep(sensor->pwdn_gpio, 0);
    usleep_range(5000, 6000);

    gpiod_set_value_cansleep(sensor->reset_gpio, 0);
    usleep_range(10000, 12000);

    return 0;
}

如果 RESET/PWDN 极性和硬件实际相反，sensor 会一直处于 reset 或 powerdown 状态。

设备树示例：

reset-gpios = <&gpio1 RK_PA0 GPIO_ACTIVE_LOW>;
pwdn-gpios  = <&gpio1 RK_PA1 GPIO_ACTIVE_HIGH>;

排查时需要结合原理图确认：

RESET 高有效还是低有效？
PWDN 高有效还是低有效？
上电后默认电平是多少？
驱动释放时是否符合 datasheet？

4.4 mode 参数错误

Sensor probe 成功后，如果 mode 配置错误，后续可能出现：

STREAMON timeout
rkcif size err
MIPI fs/fe mismatch
图像花屏
帧率不对

典型 mode 表：

static const struct sensor_mode supported_modes[] = {
    {
        .width = 1920,
        .height = 1080,
        .hts_def = 2200,
        .vts_def = 1125,
        .exp_def = 0x400,
        .max_fps = {
            .numerator = 10000,
            .denominator = 300000,
        },
        .bus_fmt = MEDIA_BUS_FMT_SBGGR10_1X10,
        .bpp = 10,
        .link_freq_idx = 0,
    },
};

重点核对：

width / height
hts / vts
fps
exp_def
link_freq
pixel_rate
bus_fmt
bpp
lane_num

常用计算关系：

pixel_rate = link_freq * 2 * lane_num / bits_per_pixel

例如：

link_freq = 456 MHz
lane_num = 2
bpp = 10

则：

pixel_rate = 456M * 2 * 2 / 10
           = 182.4 MHz

如果 pixel_rate、link_freq、lane_num、bpp 不匹配，MIPI 接收端很容易出现 timeout、size err 或帧同步异常。

5. Device Tree 配置问题

Device Tree 是 RK Camera 移植中出错率最高的部分。很多问题表面看是驱动问题，实际根因是 DTS 配错。

5.1 compatible 不匹配

驱动中：

static const struct of_device_id sensor_of_match[] = {
    { .compatible = "vendor,sensor123" },
    {},
};
MODULE_DEVICE_TABLE(of, sensor_of_match);

设备树必须一致：

compatible = "vendor,sensor123";

如果写成：

compatible = "vendor,sensor123-new";

驱动不会 probe。

排查：

dmesg | grep -i probe
cat /proc/device-tree/.../compatible

5.2 clocks / clock-names 错误

驱动中一般这样获取时钟：

sensor->xvclk = devm_clk_get(dev, "xvclk");

设备树需要对应：

clocks = <&cru CLK_CIF_OUT>;
clock-names = "xvclk";

如果写成：

clock-names = "mclk";

驱动会报：

failed to get xvclk

或者 sensor 没有 MCLK 输出。

5.3 regulator 配置错误

Sensor 常见三路电源：

AVDD  : analog power
DOVDD : IO power
DVDD  : digital core power

设备树示例：

avdd-supply  = <&vcc_camera_avdd>;
dovdd-supply = <&vcc_camera_dovdd>;
dvdd-supply  = <&vcc_camera_dvdd>;

驱动中：

static const char * const sensor_supply_names[] = {
    "avdd",
    "dovdd",
    "dvdd",
};

名字必须匹配。如果驱动要 "avdd"，设备树就必须写：

avdd-supply = <&xxx>;

不能写成：

vana-supply = <&xxx>;

除非驱动中就是按 vana 获取。

5.4 endpoint / remote-endpoint 配错

这是 /dev/video 不生成、media-ctl -p 看不到 sensor 的高频原因。

典型结构：

&i2c3 {
    status = "okay";

    camera@36 {
        compatible = "vendor,sensor123";
        reg = <0x36>;

        clocks = <&cru CLK_CIF_OUT>;
        clock-names = "xvclk";

        reset-gpios = <&gpio1 RK_PA0 GPIO_ACTIVE_LOW>;
        pwdn-gpios  = <&gpio1 RK_PA1 GPIO_ACTIVE_HIGH>;

        avdd-supply = <&vcc_camera_avdd>;
        dovdd-supply = <&vcc_camera_dovdd>;
        dvdd-supply = <&vcc_camera_dvdd>;

        port {
            sensor_out: endpoint {
                remote-endpoint = <&mipi_in_ucam0>;
                data-lanes = <1 2>;
                link-frequencies = /bits/ 64 <456000000>;
            };
        };
    };
};

&mipi_csi2 {
    status = "okay";

    ports {
        #address-cells = <1>;
        #size-cells = <0>;

        port@0 {
            reg = <0>;

            mipi_in_ucam0: endpoint {
                remote-endpoint = <&sensor_out>;
                data-lanes = <1 2>;
            };
        };

        port@1 {
            reg = <1>;

            mipi_out: endpoint {
                remote-endpoint = <&cif_mipi_in>;
            };
        };
    };
};

&rkcif {
    status = "okay";
};

&rkcif_mipi_lvds {
    status = "okay";

    port {
        cif_mipi_in: endpoint {
            remote-endpoint = <&mipi_out>;
        };
    };
};

关键点：

sensor_out 指向 mipi_in_ucam0
mipi_in_ucam0 指回 sensor_out

mipi_out 指向 cif_mipi_in
cif_mipi_in 指回 mipi_out

也就是 remote-endpoint 必须成对闭环。

排查：

dmesg | grep -i endpoint
dmesg | grep -i async
dmesg | grep -i notifier
media-ctl -p

6. Media Controller / V4L2 链路问题

6.1 Media Controller 基本概念

RK Camera 基于 Media Controller 管理拓扑，核心概念是：

entity
pad
link
pipeline

可以理解为：

entity : 一个模块，例如 sensor、mipi、rkcif、rkisp
pad    : 模块输入/输出端口
link   : entity 之间的连接
pipeline : 完整数据流路径

查看拓扑：

media-ctl -p

典型拓扑类似：

sensor 3-0036
  pad0: Source
    -> mipi-csi2 input

mipi-csi2
  pad0: Sink
  pad1: Source
    -> rkcif input

rkcif-mipi
  pad0: Sink
  pad1: Source
    -> rkisp input

rkisp
  pad0: Sink
  pad1: Source
    -> video0

6.2 media-ctl 看不到 sensor

现象

media-ctl -p

没有 sensor entity。

原因

1. sensor 没 probe
2. subdev 没注册
3. endpoint 配错
4. async notifier 没 complete
5. compatible 不匹配

解法

先确认 sensor probe：

dmesg | grep -i sensor

再确认 async notifier：

dmesg | grep -i async
dmesg | grep -i notifier

如果 sensor probe 成功但 media 中没有，多半是 endpoint 绑定失败。

6.3 link 未 enable

查看：

media-ctl -p

如果看到：

[DISABLED]

需要手动 enable：

media-ctl -l '"sensor 3-0036":0 -> "mipi-csi2":0 [1]'
media-ctl -l '"mipi-csi2":1 -> "rkcif-mipi":0 [1]'

实际 entity 名称要以 media-ctl -p 输出为准。

6.4 pad format 不一致

如果 sensor、mipi、cif、isp 的格式不一致，常见问题是：

STREAMON failed
rkcif size err
图像错位
花屏
颜色异常

查看：

media-ctl -p

设置格式：

media-ctl -V '"sensor 3-0036":0 [fmt:SBGGR10_1X10/1920x1080]'
media-ctl -V '"mipi-csi2":0 [fmt:SBGGR10_1X10/1920x1080]'
media-ctl -V '"rkcif-mipi":0 [fmt:SBGGR10_1X10/1920x1080]'

然后抓流：

v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=100

7. MIPI CSI-2 / DPHY / rkcif 问题

7.1 MIPI select timeout

现象

MIPI select timeout
wait stream timeout
select timeout

常见原因

1. sensor 没有真正出流
2. s_stream 没有写启动寄存器
3. data-lanes 配错
4. link-frequencies 配错
5. MIPI DPHY 没锁定
6. endpoint 链路没建立
7. sensor 输出格式与接收端不一致

排查顺序

先确认 sensor 是否 s_stream(1)
再确认 MIPI lane
再确认 link_freq / pixel_rate
再确认 pad format
最后看 MIPI 错误寄存器或内核日志

命令：

dmesg | grep -i stream
dmesg | grep -i mipi
dmesg | grep -i csi
dmesg | grep -i rkcif

7.2 SOT sync error

现象

MIPI_CSI2_ERR1: SOT sync error

含义

SOT 是 Start Of Transmission。SOT sync error 表示 MIPI 物理层同步失败。

常见原因

1. lane 顺序错误
2. lane 数量错误
3. lane 极性错误
4. MIPI 速率不匹配
5. settle timing 不合适
6. 硬件走线或排线异常

处理方法

重点检查设备树：

data-lanes = <1 2>;
link-frequencies = /bits/ 64 <456000000>;

如果硬件只接了 2 lane，设备树不能写 4 lane：

data-lanes = <1 2 3 4>;    // 错误

应改为：

data-lanes = <1 2>;        // 正确

7.3 fs / fe mismatch

现象

fs/fe mismatch
frame start / frame end mismatch

原因

1. 分辨率配置错误
2. hts / vts 配置错误
3. sensor 输出帧结构异常
4. HDR VC 通道配置错误
5. MIPI 数据中断

如果 sensor 是 HDR 模式，可能通过不同 VC 输出多路曝光数据。如果接收端按普通线性模式解析，就可能出现 fs/fe mismatch。

7.4 ECC / CRC error

现象

ECC error
CRC error

原因

1. MIPI 信号质量差
2. 速率过高
3. lane 配置错误
4. 排线接触不良
5. 电源不稳
6. sensor 输出 timing 不稳定

调试方法

可以尝试：

降低分辨率
降低 fps
降低 link_freq
减少数据速率
检查排线和硬件连接

如果降速后错误消失，通常说明原速率下信号质量或 timing 不满足。

7.5 rkcif size err

现象

rkcif size err
frame end err

原因

1. sensor 实际输出尺寸和配置尺寸不一致
2. media pad format 不一致
3. mbus_code 不一致
4. RAW bit depth 配错
5. crop / compose 配置错误

重点核对：

width
height
mbus_code
bpp
sensor mode
media pad format
v4l2 pix format

8. STREAMON 失败专题

STREAMON failed 是最常见、也最容易误判的问题。

8.1 用户层现象

v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=10

输出：

VIDIOC_STREAMON: failed
select timeout

或者：

stream on timeout

8.2 定位思路

/dev/video0 存在，只说明 video_device 注册成功，不代表 sensor 正在输出图像。

应按下面顺序检查：

1. sensor s_stream 是否被调用
2. sensor 是否写入 stream on 寄存器
3. media link 是否 enable
4. pad format 是否一致
5. MIPI 是否收到数据
6. rkcif 是否报 size err
7. vb2 buffer 是否正常 queue

8.3 抓流命令

普通测试：

v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=100

保存 raw：

v4l2-ctl -d /dev/video0 \
  --set-fmt-video=width=1920,height=1080,pixelformat=RG10 \
  --stream-mmap \
  --stream-count=10 \
  --stream-to=frame.raw

查看支持格式：

v4l2-ctl -d /dev/video0 --list-formats-ext

查看设备：

v4l2-ctl --list-devices

9. ISP 图像与画质问题

当链路已经通，能抓到 raw 或能预览，但画质异常，就进入 ISP 阶段。

9.1 Bayer 顺序错误

现象

画面偏绿
画面偏紫
颜色错乱
白平衡异常

原因

sensor 实际 Bayer pattern 与驱动配置不一致。

常见格式：

RGGB
BGGR
GBRG
GRBG

驱动中：

.bus_fmt = MEDIA_BUS_FMT_SBGGR10_1X10;

可尝试：

MEDIA_BUS_FMT_SRGGB10_1X10
MEDIA_BUS_FMT_SBGGR10_1X10
MEDIA_BUS_FMT_SGBRG10_1X10
MEDIA_BUS_FMT_SGRBG10_1X10

9.2 IQ 文件不匹配

现象

raw 正常
ISP 后颜色异常
曝光异常
噪声大
rkaiq 没有效果

排查

查看 IQ 文件：

ls /etc/iqfiles

查看 rkaiq 是否运行：

ps | grep rkaiq

查看日志：

dmesg | grep -i iq
logcat | grep -i rkaiq

设备树中常见字段：

rockchip,camera-module-index = <0>;
rockchip,camera-module-facing = "back";
rockchip,camera-module-name = "default";
rockchip,camera-module-lens-name = "default";

这些字段需要和 IQ 文件匹配，否则 rkaiq 可能加载不到正确 tuning 参数。

9.3 Raw 正常但预览异常

定位原则：

Raw 异常：优先查 sensor / MIPI / rkcif
Raw 正常，ISP 后异常：优先查 rkisp / rkaiq / IQ

可以先保存 raw：

v4l2-ctl -d /dev/video0 \
  --set-fmt-video=width=1920,height=1080,pixelformat=RG10 \
  --stream-mmap \
  --stream-count=1 \
  --stream-to=test.raw

再用 raw viewer 按不同 Bayer 顺序打开：

RGGB10
BGGR10
GBRG10
GRBG10

判断真实 Bayer pattern。

10. 推荐完整排查流程

10.1 第一阶段：硬件基础检查

cat /sys/kernel/debug/regulator/regulator_summary
cat /sys/kernel/debug/clk/clk_summary | grep -i cam
cat /sys/kernel/debug/gpio

确认：

AVDD / DVDD / DOVDD 正常
MCLK 正常
RESET / PWDN 正常
power-domain 正常

10.2 第二阶段：I2C 与 chip id

i2cdetect -y 3
dmesg | grep -i sensor

确认：

I2C 地址正确
驱动 probe 成功
chip id 正确

10.3 第三阶段：Device Tree 链路

检查：

compatible
reg
clocks
clock-names
reset-gpios
pwdn-gpios
regulators
ports
endpoint
remote-endpoint
data-lanes
link-frequencies

反编译 dtb：

dtc -I dtb -O dts -o out.dts xxx.dtb

10.4 第四阶段：Media 拓扑

media-ctl -p

确认：

sensor entity 存在
mipi entity 存在
rkcif / rkisp entity 存在
link enable
pad format 一致

10.5 第五阶段：设置格式并抓流

media-ctl -V '"sensor 3-0036":0 [fmt:SBGGR10_1X10/1920x1080]'
media-ctl -V '"mipi-csi2":0 [fmt:SBGGR10_1X10/1920x1080]'

v4l2-ctl -d /dev/video0 --stream-mmap --stream-count=100

10.6 第六阶段：分析 MIPI / rkcif 日志

dmesg | grep -i mipi
dmesg | grep -i csi
dmesg | grep -i rkcif
dmesg | grep -i rkisp

关注：

SOT sync error
ECC error
CRC error
fs/fe mismatch
size err
wait stream timeout
select timeout

10.7 第七阶段：ISP 与 IQ

ps | grep rkaiq
ls /etc/iqfiles
dmesg | grep -i iq

确认：

rkaiq 正常运行
IQ 文件存在
sensor name 匹配
module index 匹配
lens-name 匹配
Bayer 顺序正确

11. 典型案例

案例一：chip id 读取失败

现象

sensor 3-0036: read chip id failed

分析

此时还没有进入 MIPI 阶段，应优先检查基础链路：

I2C 地址
供电
MCLK
RESET/PWDN
寄存器地址位宽

解答

如果 datasheet 写：

write address = 0x6c
read address  = 0x6d

设备树应写：

reg = <0x36>;

同时确认：

cat /sys/kernel/debug/clk/clk_summary | grep -i cam
cat /sys/kernel/debug/regulator/regulator_summary
cat /sys/kernel/debug/gpio

案例二：probe 成功但没有 `/dev/video`

现象

sensor probe success

但：

ls /dev/video*

没有目标节点。

分析

sensor probe 成功只代表 I2C driver 加载成功，不代表 media pipeline 成功。

常见原因：

endpoint 配错
remote-endpoint 没成对
async notifier 没 complete
rkcif / rkisp 没启用

解答

检查：

media-ctl -p
dmesg | grep -i async
dmesg | grep -i endpoint

确认 DTS 中：

remote-endpoint = <&mipi_in_ucam0>;

和：

remote-endpoint = <&sensor_out>;

互相对应。

案例三：media-ctl 看不到 sensor

现象

media-ctl -p

输出没有 sensor。

解答

检查三点：

1. sensor 是否 probe 成功
2. sensor 是否注册 v4l2 subdev
3. endpoint 是否正确绑定

驱动中应有类似逻辑：

v4l2_i2c_subdev_init(&sensor->subdev, client, &sensor_subdev_ops);

sensor->subdev.flags |= V4L2_SUBDEV_FL_HAS_DEVNODE;
sensor->subdev.entity.function = MEDIA_ENT_F_CAM_SENSOR;

ret = media_entity_pads_init(&sensor->subdev.entity, 1, sensor->pads);

ret = v4l2_async_register_subdev_sensor(&sensor->subdev);

案例四：STREAMON timeout

现象

VIDIOC_STREAMON failed
select timeout

分析

有 video node，但没有收到帧。

优先检查：

sensor 是否真的 stream on
MIPI 是否有数据
media link 是否 enable
pad format 是否一致

解答

检查日志：

dmesg | grep -i stream
dmesg | grep -i mipi
dmesg | grep -i rkcif

如果 link disabled：

media-ctl -l '"sensor 3-0036":0 -> "mipi-csi2":0 [1]'

如果格式不一致：

media-ctl -V '"sensor 3-0036":0 [fmt:SBGGR10_1X10/1920x1080]'

案例五：MIPI SOT sync error

现象

MIPI_CSI2_ERR1: SOT sync error

分析

这是 MIPI 物理层同步问题。

重点检查：

data-lanes
lane 顺序
lane 极性
link_freq
settle timing
硬件排线

解答

如果硬件是 2 lane：

data-lanes = <1 2>;

不要写成：

data-lanes = <1 2 3 4>;

如果 lane 顺序和硬件原理图不一致，需要按实际接线调整。

案例六：rkcif size err

现象

rkcif size err

分析

接收端认为一帧的尺寸和配置不一致。

常见原因：

sensor 输出 1920x1080
但 media pad 设置成 1280x720

sensor 输出 RAW10
但后端按 RAW8 接收

sensor Bayer code 和 mbus_code 不一致

解答

统一全链路格式：

media-ctl -p

media-ctl -V '"sensor 3-0036":0 [fmt:SBGGR10_1X10/1920x1080]'
media-ctl -V '"mipi-csi2":0 [fmt:SBGGR10_1X10/1920x1080]'
media-ctl -V '"rkcif-mipi":0 [fmt:SBGGR10_1X10/1920x1080]'

案例七：图像偏色

现象

图像偏绿
图像偏紫
颜色不正常

分析

大概率是 Bayer 顺序错误。

解答

在驱动中切换：

MEDIA_BUS_FMT_SRGGB10_1X10
MEDIA_BUS_FMT_SBGGR10_1X10
MEDIA_BUS_FMT_SGBRG10_1X10
MEDIA_BUS_FMT_SGRBG10_1X10

同时确认 IQ 文件是否匹配该 sensor。

12. 快速故障速查表

现象	优先检查
sensor 不 probe	compatible、I2C 地址、供电、MCLK、GPIO
chip id 失败	I2C 地址、上电时序、reset/pwdn、寄存器位宽
无 `/dev/video`	async notifier、endpoint、rkcif/rkisp 状态
media-ctl 无 sensor	subdev 注册、remote-endpoint、port 层级
STREAMON failed	link enable、pad format、sensor stream、MIPI 数据
MIPI select timeout	sensor 未出流、lane 错、link_freq 错
SOT sync error	lane 顺序、lane 极性、速率、硬件连接
ECC / CRC error	信号质量、速率过高、电源、排线
rkcif size err	分辨率、mbus_code、bit depth、pad format
图像偏色	Bayer 顺序、IQ 文件
raw 正常 ISP 异常	rkaiq、IQ、module 信息、lens-name

13. 最终 Checklist

移植完成前建议逐项确认：

[ ] AVDD / DVDD / DOVDD 电源正常
[ ] MCLK 正常输出
[ ] RESET / PWDN 极性正确
[ ] I2C 地址为 7-bit 地址
[ ] chip id 读取成功
[ ] compatible 与驱动匹配
[ ] clock-names 与驱动一致
[ ] regulator supply 名称一致
[ ] endpoint / remote-endpoint 成对
[ ] data-lanes 与原理图一致
[ ] link-frequencies 与 sensor mode 一致
[ ] pixel_rate 计算合理
[ ] mbus_code 与 sensor 输出一致
[ ] width / height / fps 正确
[ ] hts / vts 正确
[ ] media graph 完整
[ ] link 已 enable
[ ] pad format 全链路一致
[ ] STREAMON 成功
[ ] MIPI 无 SOT / ECC / CRC 错误
[ ] rkcif 无 size err
[ ] raw 图正常
[ ] Bayer 顺序正确
[ ] rkaiq 正常启动
[ ] IQ 文件匹配

14. 总结

RK 平台 Camera 移植建议遵循一个原则：

先硬件，后软件；
先 I2C，后 MIPI；
先链路，后图像；
先 Raw，后 ISP；
先日志，后猜测。

实际排查时，不建议一开始就调 ISP，也不要只看应用层 v4l2-ctl 的错误。推荐按照下面链路推进：

电源 / 时钟 / GPIO
  -> I2C chip id
  -> sensor probe
  -> device tree endpoint
  -> media graph
  -> link enable
  -> pad format
  -> MIPI error
  -> rkcif / rkisp
  -> stream on
  -> raw capture
  -> rkaiq / IQ tuning

大多数 RK 摄像头问题最终会落在以下几类：

1. I2C 地址或上电时序错误
2. RESET / PWDN GPIO 极性错误
3. endpoint / remote-endpoint 没有成对
4. data-lanes / link_freq / pixel_rate 不匹配
5. mbus_code / Bayer 顺序错误
6. media pad format 不一致
7. IQ 文件和 module 信息不匹配

只要按模块拆解、按链路推进，RK Camera bring-up 的问题就能从“看日志猜问题”变成“根据现象定位层级，再用命令验证根因”。