RK 平台摄像头驱动移植问题详解：从 Sensor 到 MIPI、rkcif、rkisp、V4L2 的系统化排查方法

在 RK 平台上移植摄像头驱动时，最常见的现象往往不是某个单点错误，而是一条复杂链路中的某个环节没有打通。比如 Sensor 驱动没有 probe 成功，/dev/videoX 没有生成，media-ctl -p 看不到 sensor，抓图时出现 select timeout，MIPI 报 SOT sync error，rkcif 报 size err，或者 ISP 有图但偏色、花屏、发暗、噪声很大。

这些问题表面看起来不同，但本质上都离不开这条主链路：

Sensor
  ↓
MIPI DPHY / CSI-2
  ↓
rkcif
  ↓
rkisp
  ↓
V4L2 video node
  ↓
用户空间采集工具

这篇文章结合图中的 10 个模块，对 RK 平台摄像头驱动移植的理论基础、常见问题、根因分析和排查顺序做一次系统说明。

1. 整体链路与架构

图中第 1 部分是整个 RK 摄像头系统的基础链路。要理解 RK Camera 调试，首先要分清硬件链路、软件链路、V4L2 链路、用户空间链路和典型启动流程。

1.1 硬件链路

典型硬件链路如下：

Camera Sensor
  ↓
MIPI DPHY / CSI-2
  ↓
rkcif
  ↓
rkisp
  ↓
video node

其中各模块的作用如下：

一个关键认知是：Sensor 成功 probe 并不等于摄像头链路打通。Sensor 只是图像源头，后面还需要 MIPI、CIF、ISP、V4L2、vb2 共同工作，用户空间才能真正拿到图像帧。

1.2 软件链路

软件链路可以理解为：

I2C / Clock / GPIO / Regulator / Pinctrl

Sensor 驱动通常通过 I2C 配置寄存器，通过 GPIO 控制 reset 和 power down，通过 regulator 控制电源，通过 clock 提供 MCLK，通过 pinctrl 配置引脚复用。

摄像头移植中大量问题都发生在这些基础资源上，例如：

• I2C 地址错误；

• MCLK 没有输出；

• reset GPIO 极性写反；

• AVDD/DOVDD/DVDD 没有上电；

• pinctrl 配错导致 I2C 或 MIPI 引脚异常；

• 电源时序不满足 sensor datasheet。

所以调试 Camera 的第一原则是：

先确认供电、时钟、GPIO、I2C，再谈 V4L2 和 ISP。

1.3 V4L2 软件框架链路

V4L2 层面的链路是：

v4l2_subdev
  ↓
media controller
  ↓
video_device
  ↓
vb2

这几个概念非常重要：

当用户空间调用 v4l2-ctl 抓图时，最终要依赖 vb2 buffer 流程完成一帧 DMA，然后通过 DQBUF 返回给应用。

1.4 用户空间调试工具链

图中列出的常用工具包括：

media-ctl
v4l2-ctl
yavta
gst-launch
ffmpeg

它们的典型用途如下：

Camera bring-up 阶段最常用的两个命令是：

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

1.5 典型启动流程

一个摄像头从驱动加载到真正出图，大致流程如下：

probe
  ↓
注册 subdev
  ↓
异步绑定
  ↓
media 拓扑建立
  ↓
设置 format
  ↓
申请 buffer
  ↓
QBUF
  ↓
STREAMON
  ↓
DQBUF

如果任意一步失败，最终都可能表现为“抓不到图”或者 select timeout。

2. 驱动挂载失败 / Probe 失败

图中第 2 部分总结的是驱动挂载失败，也就是 Sensor driver 没有正常 probe，或者 probe 成功但后续 video/media 节点没有生成。

2.1 Sensor driver 未 probe

现象：

sensor driver 未 probe
dmesg 中没有 sensor 初始化日志
media-ctl -p 看不到 sensor entity
/dev/v4l-subdevX 没有对应 sensor 节点

常见原因包括：

1. I2C 地址错误；

2. I2C 总线配置错误；

3. MCLK 未输出；

4. RESET/PWDN 时序错误；

5. compatible 不匹配；

6. regulator 没有上电；

7. pinctrl 配置错误；

8. sensor 上电时序不满足要求。

排查命令：

i2cdetect -y 1
i2cget -y 1 0x36 0x00
dmesg | grep -i sensor
dmesg | grep -i i2c
cat /sys/kernel/debug/clk/clk_summary

重点检查：

I2C 是否有 ACK
MCLK 是否输出
reset/pwdn 电平是否正确
AVDD/DOVDD/DVDD 是否正常
compatible 是否和驱动 of_match_table 匹配

2.2 /dev/video 无节点

有时候 Sensor probe 成功，但 /dev/videoX 没有生成。

这种问题通常不是 Sensor 本身，而是后级链路没有完成。

可能原因：

device tree 端点没连好
async notifier 没 complete
video_device 没注册
rkcif/rkisp 没 probe
media graph 不完整

典型排查命令：

ls /dev/video*
ls /dev/media*
ls /dev/v4l-subdev*
dmesg | grep -i async
dmesg | grep -i video
media-ctl -d /dev/media0 -p

如果 sensor 已经 probe，但 media 拓扑不完整，要优先检查：

remote-endpoint 是否正确
ports/endpoint 是否写对
rkcif/rkisp 节点是否 enable
sensor 和 csi 是否绑定到同一个 media graph

2.3 media-ctl 看不到 Sensor

现象：

media-ctl -d /dev/media0 -p

输出中没有 Sensor entity。

常见原因：

subdev 未注册
async notifier 未绑定
endpoint 配置错误
驱动没有初始化 media_entity
media_entity_pads_init 没有调用

如果 Sensor probe 成功但 media graph 中没有出现，说明它没有正确加入 Media Controller 拓扑。

2.4 chip id 读取失败

Sensor 驱动通常会在 probe 阶段读取 chip id。如果 chip id 读失败，常见原因是：

I2C 地址错误
寄存器地址错误
供电失败
MCLK 未打开
reset/pwdn 状态错误
sensor 还没有完成上电稳定

注意：有些 sensor 的寄存器地址是 16bit，有些是 8bit；有些芯片 ID 分高低字节，有些需要连续读多个寄存器。如果寄存器读写函数实现错误，也会导致 chip id 失败。

3. Device Tree / 时钟 / 电源配置问题

图中第 3 部分是 RK 摄像头移植的高发区。很多驱动问题最终都可以追溯到 DTS 配置错误。

3.1 Device Tree 常见字段

摄像头 DTS 通常包含：

compatible
reg
clocks
clock-names
pinctrl
reset-gpios
pwdn-gpios
power-domains
dvdd-supply
avdd-supply
dovdd-supply
ports
endpoint
remote-endpoint
data-lanes
bus-type
link-frequencies
rotation
module-index
facing
lens-name

每个字段都不是摆设，任何一个字段错了，都可能导致 probe 失败、链路不完整或者 MIPI 接收异常。

3.2 常见 DTS 错误

图中列出的常见错误包括：

lane 数量不一致
remote-endpoint 没对上
link-freq 写错
GPIO 极性写错
缺少 clock
供电域 power-domain 配置错误

这些错误分别会导致不同问题：

3.3 Endpoint 是核心

MIPI Sensor 的 endpoint 典型写法如下：

port {
    sensor_out: endpoint {
        remote-endpoint = <&csi_in>;
        data-lanes = <1 2 3 4>;
        link-frequencies = /bits/ 64 <594000000>;
    };
};

这里最重要的三个字段是：

remote-endpoint
data-lanes
link-frequencies

remote-endpoint 决定 Sensor 接到哪个 CSI。
data-lanes 决定使用几条 MIPI data lane。
link-frequencies 决定 MIPI 链路速率配置。

如果这三者不正确，后面很容易出现 MIPI timeout、SOT sync、size err 等问题。

4. Sensor 驱动常见问题

图中第 4 部分是 Sensor 驱动本身的常见错误。

4.1 mode 表配置错误

Sensor 驱动通常会定义 mode 表，用来描述 sensor 支持的分辨率、帧率、输出格式和寄存器配置。

典型 mode 表包含：

width
height
hts
vts
fps
exp_def
link_freq
pixel_rate
mbus_code
bpp
lane_num
reg_list

常见错误包括：

width / height 写错
hts / vts 写错
fps 不匹配
link_freq / pixel_rate 不匹配
lane_num 不一致
mbus_code 错误

这些错误会导致：

rkcif size err
帧率异常
MIPI 速率异常
ISP 输入格式不对
图像偏色或花屏

4.2 gain / exposure / vblank / hblank 控件异常

Sensor 驱动通常会注册以下 V4L2 controls：

V4L2_CID_EXPOSURE
V4L2_CID_ANALOGUE_GAIN
V4L2_CID_VBLANK
V4L2_CID_HBLANK
V4L2_CID_PIXEL_RATE
V4L2_CID_LINK_FREQ

这些 control 不只是给应用层看的，它们也影响 ISP 3A 和 sensor 实际工作状态。

比如：

• VBLANK 会影响帧率；

• EXPOSURE 最大值通常要小于 VTS；

• PIXEL_RATE 会影响上层计算行时间；

• LINK_FREQ 会影响 MIPI DPHY 配置；

• GAIN 和 EXPOSURE 关系到图像亮度与噪声。

如果这些 control 配错，可能会出现画面过暗、过曝、帧率不对、MIPI 速率不匹配等问题。

4.3 s_power / s_stream 调用链异常

Sensor 真正开始输出图像，通常发生在 s_stream(1) 中。

典型流程：

power on
  ↓
写 mode 寄存器
  ↓
配置曝光 / 增益 / vblank
  ↓
打开 MIPI 输出
  ↓
stream on

如果 s_stream 中没有真正打开 MIPI 输出，就会出现：

STREAMON 成功
但是没有帧
select timeout
MIPI 没有数据

调试时建议在 s_stream 中增加日志：

sensor stream on
write mode regs done
start mipi output
sensor stream on done

4.4 HDR / 多曝光 / VC 配置错误

如果使用 HDR、DOL、多曝光或多 VC 输出，还需要检查：

VC 是否匹配
长短曝光帧顺序是否正确
FS/FE 是否匹配
rkisp 是否支持该 HDR 模式
rkcif 是否按正确 VC 接收

HDR 配错时，常见现象是：

fs/fe mismatch
size err
图像撕裂
曝光异常
无法出图

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

图中第 5 部分是摄像头调试中最常见也最难定位的一类问题。很多用户空间的 select timeout，底层根因其实是 MIPI 没有稳定收到数据。

5.1 典型错误现象

图中列出的典型错误包括：

MIPI select timeout
STREAMON timeout
MIPI_CSI2 ERR1: SOT sync error
fs/fe mismatch
ECC / CRC error
size err / frame end err
fifo overflow

这些错误分别表示不同层面的问题。

5.2 MIPI select timeout

MIPI select timeout 可以理解为用户空间或驱动在等待一帧数据完成时超时。

它并不是一个独立根因，而是一个结果。常见原因有：

Sensor 根本没有输出
MIPI lane 数错误
lane mapping 错误
link_freq / pixel_rate / mipi rate 不一致
settle timing 不合适
Sensor 输出格式与接收端 mbus 格式不一致
VC / HDR 路由错误
分辨率、hts、vts 配置错误
硬件排线、连接器、供电、时钟不稳定

5.3 SOT sync error

SOT 是 Start Of Transmission，表示 MIPI 高速传输开始同步。

如果出现：

MIPI_CSI2 ERR1: SOT sync error

说明 CSI RX 无法正确识别高速传输的起始同步。

常见原因：

MIPI lane 配置错误
clock lane 异常
Sensor 没有稳定输出
MIPI 速率过高
DPHY settle timing 不对
信号完整性差

如果所有 lane 都报 SOT sync，通常优先怀疑：

Sensor 未输出
clock lane 不正常
lane 数整体配置错误
link_freq/pixel_rate 配错
硬件连接问题

如果只有某一条 lane 报错，则更偏向：

单条 lane 连接问题
lane mapping 问题
PCB/排线信号问题

5.4 fs/fe mismatch

fs/fe mismatch 表示 Frame Start 和 Frame End 不匹配。

常见原因：

MIPI packet 丢失
VC 配置错误
HDR 多帧模式错误
Sensor 输出帧结构异常
MIPI 链路不稳定
CSI 解包异常

如果伴随 SOT sync、ECC、CRC 错误，通常说明 MIPI 物理链路或速率配置存在问题。

5.5 ECC / CRC error

ECC 和 CRC 是 CSI-2 packet 层的校验错误。

常见原因：

MIPI 信号质量差
速率太高
settle timing 不合适
lane mapping 错误
排线/连接器问题
Sensor 输出不稳定

如果低分辨率正常，高分辨率异常，优先怀疑：

MIPI 速率过高
信号完整性不足
DPHY timing 不匹配

5.6 rkcif size err

rkcif size err 是 RK 平台非常常见的错误。

它表示 rkcif 收到的图像尺寸与预期不一致。

可能原因包括：

Sensor 实际输出分辨率与驱动配置不一致
MIPI FS/FE 异常
mbus_code 错误
RAW10/RAW12/YUV 格式不一致
CSI packet 丢失
MIPI lane 不稳定
rkcif 输入格式配置错误

需要注意：

rkcif size err 很多时候不是 rkcif 自己的问题，而是上游 Sensor/MIPI 已经出错。

6. Media Controller / V4L2 链路问题

图中第 6 部分是 Media Controller 和 V4L2 链路问题。

6.1 Media Graph 不完整

现象：

media-ctl -p 看不到完整拓扑
/dev/media0 拓扑异常
sensor、csi、isp、video node 缺失

常见原因：

subdev 未绑定
async notifier 未 complete
endpoint 配置错误
media_entity 初始化失败
video_device 注册失败

排查命令：

media-ctl -d /dev/media0 -p
dmesg | grep -i async
dmesg | grep -i media

6.2 link 未 enable

Media Controller 中每条链路都由 link 表示。
典型链路如下：

Sensor source pad
  ↓
CSI sink pad
  ↓
CSI source pad
  ↓
ISP sink pad
  ↓
ISP source pad
  ↓
Video node sink pad

如果中间某条 link 没有 enable，数据就不会流通。

查看方式：

media-ctl -d /dev/media0 -p

重点看：

[ENABLED]
[DISABLED]

6.3 pad format 不一致

这是 RK Camera 调试中非常常见的问题。

比如合理的 RAW10 链路应该类似：

Sensor source pad: SRGGB10_1X10 / 1920x1080
CSI sink pad:      SRGGB10_1X10 / 1920x1080
CSI source pad:    SRGGB10_1X10 / 1920x1080
ISP sink pad:      SRGGB10_1X10 / 1920x1080
Video node:        NV12 / 1920x1080

如果某一级变成 RAW12、分辨率不一致或 Bayer 顺序不一致，就可能导致：

STREAMON 失败
size err
select timeout
花屏
偏色

常用命令：

media-ctl -d /dev/media0 -p
media-ctl -d /dev/media0 -V '"sensor":0 [fmt:SRGGB10_1X10/1920x1080]'
v4l2-ctl -d /dev/video0 --list-formats-ext
v4l2-ctl -d /dev/video0 --stream-mmap

7. ISP 图像调试与画质问题

图中第 7 部分主要描述有图之后的 ISP 画质问题。

能出图并不代表摄像头移植结束。
对于 RAW Sensor，真正的图像质量高度依赖 ISP 和 IQ 参数。

7.1 RAW 通了但颜色不对

常见现象：

画面偏绿
画面偏紫
颜色错乱
肤色异常

优先检查：

Bayer 顺序是否正确
mbus_code 是否正确
IQ 文件是否匹配
AWB 参数是否正确
CCM 是否合理

常见 Bayer 顺序包括：

RGGB
BGGR
GBRG
GRBG

如果 Bayer 顺序配置错误，画面通常会明显偏色。

7.2 AE / AWB / AF 异常

ISP 3A 包括：

常见问题：

画面过暗
画面过曝
白平衡漂移
对焦不清楚
曝光跳变

可能原因：

IQ 文件不匹配
曝光/增益 control 不正常
统计数据没有正确返回
模组 lens-name 不匹配
sensor delay 参数不对

7.3 DVP / MIPI 输入格式与 ISP 输入不一致

如果 rkcif 输出给 rkisp 的格式与 rkisp 期望输入不一致，可能出现：

黑屏
花屏
图像错位
颜色异常
ISP 无输出

这类问题通常要同时检查：

media-ctl 拓扑
pad format
rkcif 输入格式
rkisp input format
sensor mbus_code

7.4 调试思路

ISP 调试建议按这个顺序：

先确认 RAW 正常
再确认 Bayer 顺序
再确认 IQ 文件匹配
再调 AE/AWB/AF
最后调降噪、锐化、HDR、色彩

不要在 MIPI 还不稳定、RAW 还异常时直接调 IQ。
如果底层数据不对，调 ISP 只会掩盖问题。

8. 常见故障现象 → 根因速查表

图中第 8 部分给出了常见故障现象和根因速查。下面展开说明。

这个表格的核心作用是帮助工程师快速缩小范围。

例如：

• 如果 I2C 读不到，不要先查 ISP；

• 如果 SOT sync，不要先调 IQ；

• 如果偏色，不要先怀疑 MIPI；

• 如果 select timeout，要从 Sensor/MIPI/rkcif 往前倒推。

9. 排查流程与调试工具

图中第 9 部分给出了一个非常实用的排查流程，建议按照顺序推进。

9.1 第一步：上电检查

检查内容：

电源
时钟
GPIO
复位时序

常用工具：

gpio
regulator
debugfs
clk_summary

重点确认：

AVDD/DOVDD/DVDD 是否正常
MCLK 是否输出
reset 是否释放
pwdn 是否退出

9.2 第二步：I2C 读 ID

确认 Sensor 是否真正在线：

i2cdetect -y 1
i2cget -y 1 0x36 0x00

如果 chip id 不对，后面不用继续看 media 和 ISP，先解决 Sensor 上电和 I2C。

9.3 第三步：查看 probe 日志

dmesg | grep -i sensor
dmesg | grep -i probe
dmesg | grep -i chip

确认：

驱动是否匹配
chip id 是否正确
power_on 是否成功
subdev 是否注册

9.4 第四步：查看 media 拓扑

media-ctl -d /dev/media0 -p

确认：

sensor entity 是否存在
csi entity 是否存在
rkcif/rkisp 是否存在
video node 是否存在
link 是否 enabled
pad format 是否一致

9.5 第五步：检查 pad format

media-ctl -d /dev/media0 -p
media-ctl -d /dev/media0 -V
v4l2-ctl -d /dev/video0 --list-formats-ext

重点检查：

width
height
mbus_code
pixelformat
bytesperline
sizeimage

9.6 第六步：分析 MIPI / rkcif 错误日志

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

常见关键词：

MIPI_CSI2 ERR1
rkcif size err
wait stream timeout
select timeout
SOT sync
fs/fe mismatch
ECC
CRC
fifo overflow

9.7 第七步：STREAMON 测试

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

如果这里 timeout，要倒推：

vb2 是否完成 buffer
rkcif/rkisp 是否中断
MIPI 是否收到完整帧
Sensor 是否真正输出

9.8 第八步：抓帧验证

可以使用：

yavta
hexdump
ffplay
python

比如：

yavta -c10 -n4 -s 1920x1080 -f NV12 /dev/video0
hexdump -C test.raw | head
ffplay -f rawvideo -pixel_format nv12 -video_size 1920x1080 test.raw

9.9 第九步：ISP 调图

当 RAW 和基本链路稳定后，再进入 ISP 调图：

IQ tuning tool
AE/AWB/AF 调整
Bayer 顺序确认
降噪/锐化/HDR 调整

10. 快速检查清单 Checklist

图中第 10 部分是一个快速检查清单。可以作为每次 bring-up 的标准 checklist。

10.1 硬件与上电

电源正常：AVDD / DOVDD / DVDD
MCLK 正常输出
reset/pwdn GPIO 正确
I2C 可读 sensor chip id

10.2 Device Tree

endpoint / remote-endpoint 正确
MIPI lanes 一致
link-frequencies 正确
clock / regulator / pinctrl 配置完整

10.3 Media / V4L2

media graph 完整
link enabled
pad format 一致
/dev/videoX 存在
v4l2-ctl 能查询格式

10.4 MIPI / rkcif

无 MIPI 报错
无 select timeout
无 rkcif size err
无 fs/fe mismatch
能成功 STREAMON

10.5 ISP / 图像

RAW 正常
Bayer 顺序正确
ISP 输出正常
偏色/黑屏/白屏问题可定位

11. 高频问题关键词

图中列出的高频关键词包括：

I2C NACK
chip id fail
async notifier
media-ctl -p
SOT sync
size err
fs/fe mismatch
MIPI select timeout
STREAMON timeout
Bayer 顺序

这些关键词基本覆盖了 RK Camera bring-up 的主要问题。

11.1 I2C NACK

说明 Sensor 没有响应 I2C。优先查：

供电
MCLK
reset/pwdn
I2C 地址
I2C 总线
pinctrl

11.2 chip id fail

说明能访问 I2C，但读到的 ID 不对。优先查：

寄存器地址
读写函数
芯片型号
上电时序
sensor 是否真正退出 reset

11.3 async notifier

说明 subdev 异步绑定异常。优先查：

endpoint
remote-endpoint
ports
media graph
subdev 注册

11.4 SOT sync

说明 MIPI 高速传输同步异常。优先查：

lane 配置
clock lane
link_freq
pixel_rate
DPHY timing
硬件连接

11.5 size err

说明 rkcif 收到的图像尺寸异常。优先查：

分辨率
mbus_code
bit depth
FS/FE
MIPI packet
Sensor 实际输出模式

11.6 fs/fe mismatch

说明帧开始和帧结束不匹配。优先查：

VC
HDR
MIPI packet
Sensor 帧结构
链路稳定性

11.7 Bayer 顺序

说明 RAW 解码顺序问题。优先查：

RGGB
BGGR
GRBG
GBRG
mbus_code
IQ 文件

12. 总结：RK 摄像头调试的核心方法

RK 平台摄像头驱动移植要避免“看到一个错误就乱改”。
正确方式是按链路分层排查。

推荐顺序：

先硬件上电
再 I2C 读 ID
再看 probe
再看 media 拓扑
再看 link
再看 pad format
再看 MIPI
再看 rkcif
再看 rkisp
最后看 V4L2 buffer 和用户空间

遇到不同问题时，定位思路如下：

没有 sensor probe
  → 查 I2C、电源、MCLK、reset、compatible

没有 /dev/videoX
  → 查 async notifier、media graph、video_device 注册

media-ctl 看不到 sensor
  → 查 subdev 注册、endpoint、remote-endpoint

STREAMON 失败
  → 查 link、pad format、vb2 buffer

select timeout
  → 查 Sensor 是否输出、MIPI 是否正常、rkcif/rkisp 是否有中断

MIPI SOT sync
  → 查 lane、link_freq、pixel_rate、DPHY、硬件连接

rkcif size err
  → 查分辨率、mbus_code、FS/FE、Sensor 实际输出模式

有图但偏色
  → 查 Bayer 顺序、IQ、AWB、CCM

最终要形成一个工程直觉：

摄像头出图不是 Sensor 单独完成的，而是 Sensor、MIPI、rkcif、rkisp、Media Controller、V4L2、vb2 和用户空间工具共同完成的一条完整链路。

只有按层级逐步验证，才能快速定位 RK Camera bring-up 中的复杂问题。