简介：围绕瑞芯微平台图像信号处理驱动整理的一套 Linux 内核源码包，面向嵌入式影像开发、内核驱动学习及 RK 平台移植人员，可用于理解摄像头 ISP 驱动的设备树匹配、V4L2 子设备注册与平台驱动组织方式。包内共 17 个文件，以 C 源文件和头文件为主体，辅以 Makefile 与 Kconfig，压缩后约 96KB，体量轻便，适合放入内核源码树中对照阅读和裁剪。内容涉及 ISP 核心、图像源接口、寄存器定义、平台适配与版本信息等模块，能帮助读者梳理驱动分层、编译配置和板级适配思路，也可为排查 of_device_id 匹配及设备树节点配置提供参考。该代码包已有 1796 人学习，适合需要快速切入 RK ISP 驱动框架、积累移植与排错经验的中高级开发者。

1. 从一份 rkisp 驱动代码说起：Linux 摄像头链路到底难在哪

很多做嵌入式 Linux 的同行，第一次把摄像头模组接到板子上，打开/dev/video0能出图，就以为大功告成。真正开始调画质、调曝光、换 sensor、跑多路，才发现问题全在驱动里：图像偏绿、帧率上不去、切分辨率黑屏、ISP 参数写到一半就卡死。我手上这份 rkisp 驱动代码，就是一套能在 Linux 下把「sensor → MIPI → ISP → 视频节点」这条链路讲明白的源码。它解决的是「能出图但不知道为什么能出图」和「出不了图不知道从哪查」这两件事，适合已经会编译内核模块、想深入 V4L2 子设备模型的嵌入式驱动工程师和算法移植人员。

2. rkisp 的驱动骨架：media 拓扑、子设备与视频节点怎么串起来

rkisp 驱动不是单个字符设备，而是一整套基于 Linux media framework 的多节点结构。看懂骨架，比背寄存器表重要得多。这份代码里能清楚看到三条主线：platform 驱动注册、media 实体与 pad 连线、V4L2 子设备与 video 节点暴露。

2.1 从 probe 开始：设备树节点如何变成驱动实例

驱动入口是标准的 platform driver 匹配。设备树里 rkisp 节点通过compatible字符串匹配到驱动表，probe拿到 reg 地址、中断、clock、复位这些资源，然后逐块初始化。代码里这一段是最值得先读的，因为它决定后面所有节点的生命周期。

/* 简化自驱动 probe 主线，保留关键顺序 */ static int rkisp_probe(struct platform_device *pdev) { struct rkisp_device *dev; struct resource *res; int irq, ret; dev = devm_kzalloc(&pdev->dev, sizeof(*dev), GFP_KERNEL); if (!dev) return -ENOMEM; dev->dev = &pdev->dev; /* 1. 映射寄存器空间：ISP 控制寄存器基址 */ res = platform_get_resource(pdev, IORESOURCE_MEM, 0); dev->base = devm_ioremap_resource(&pdev->dev, res); if (IS_ERR(dev->base)) return PTR_ERR(dev->base); /* 2. 取中断号，稍后注册 ISP 帧完成中断 */ irq = platform_get_irq(pdev, 0); if (irq < 0) return irq; /* 3. 时钟与复位：先使能 clock，再解复位，顺序反了会读不到寄存器 */ ret = rkisp_clk_init(dev); if (ret) return ret; ret = rkisp_reset(dev); if (ret) return ret; /* 4. 初始化 media device 与 v4l2 device，建立拓扑 */ ret = rkisp_media_init(dev); if (ret) return ret; /* 5. 注册中断并完成 video 节点注册 */ ret = devm_request_irq(&pdev->dev, irq, rkisp_isr, 0, dev_name(&pdev->dev), dev); if (ret) return ret; return rkisp_register_video(dev); }

上面这段的关键不在写法，而在顺序。寄存器映射必须在时钟使能之前准备好基址，但真正访问寄存器要等 clock 和 reset 都到位；media 拓扑要在 video 节点注册之前建好，否则用户态枚举/dev/media0时看不到完整 pipeline。参数上注意platform_get_irq的第二个参数是中断索引，多中断的 SoC 上写错会拿到错误的中断号，表现为中断一直不来、帧永远不完成。

2.2 media 拓扑：entity、pad 和 link 的三层关系

Linux media 框架里，每个功能块是一个 entity，entity 上有若干个 pad，pad 之间用 link 连起来。rkisp 驱动把 sensor、mipi phy、isp 核心、视频输出节点都注册成 entity，然后在 probe 阶段或者异步绑定阶段建立 link。

从代码里能看出，isp 核心 entity 至少有一个 sink pad 接 mipi，一个 source pad 接输出。sink pad 的flags必须带MEDIA_PAD_FL_SINK，source 带MEDIA_PAD_FL_SOURCE。我见过最常见的翻车是把方向写反，拓扑看起来有连线，但v4l2-ctl --get-fmt-video拿到的格式永远是默认值，实际数据根本没流过来。

2.3 异步绑定：sensor 还没上电时驱动怎么等

摄像头链路里 sensor 驱动和 isp 驱动是分开加载的，谁先谁后不确定。rkisp 用v4l2_async_notifier解决这个问题：isp 注册 notifier，声明自己需要哪些 fwnode 对应的子设备，等 sensor 驱动 probe 完成并注册 subdev 后，notifier 回调才把 link 建起来。

/* 异步绑定核心流程，省略错误分支 */ static int rkisp_async_register(struct rkisp_device *dev) { struct v4l2_async_notifier *ntf = &dev->notifier; int ret; v4l2_async_notifier_init(ntf); /* 从设备树解析远端 endpoint，拿到 sensor 的 fwnode */ ret = v4l2_async_notifier_parse_fwnode_endpoints( dev->dev, ntf, sizeof(struct rkisp_async_subdev), NULL); if (ret) return ret; ntf->ops = &rkisp_async_ops; /* bound / complete 回调 */ ret = v4l2_async_notifier_register(&dev->v4l2_dev, ntf); if (ret) return ret; return 0; }

parse_fwnode_endpoints会顺着设备树里的port/endpoint找对端节点，这也是为什么设备树里 sensor 的 endpoint 必须和 isp 的 endpoint 用remote-endpoint互相指。绑定回调bound里做的是把 subdev 的 pad 和 isp 的 sink pad 连起来。排错时优先看dmesg | grep -i async，如果一直停在 waiting for subdev，多半是设备树 endpoint 没对上，或者 sensor 驱动压根没 probe 成功。

2.4 取流路径：从 vb2 队列到 DMA 写完一帧

视频节点注册用的是video_device+vb2_queue。用户态VIDIOC_REQBUFS申请缓冲区，VIDIOC_QBUF入队，VIDIOC_STREAMON后硬件开始 DMA。驱动里要处理的是：把 vb2 的 buffer 地址写进 ISP 的 DMA 寄存器，帧完成中断里把 buffer 还给 vb2。

/* 帧完成中断里归还 buffer 的核心逻辑 */ static irqreturn_t rkisp_isr(int irq, void *ctx) { struct rkisp_device *dev = ctx; struct rkisp_stream *stream; u32 status = readl(dev->base + ISP_INT_STATUS); /* 只处理帧结束中断，其他状态位先清掉防止重复触发 */ if (!(status & ISP_INT_FRAME_END)) goto out; stream = &dev->stream[RKISP_STREAM_MP]; /* 主通路 */ spin_lock(&stream->vb_lock); if (stream->cur_buf) { vb2_buffer_done(&stream->cur_buf->vb.vb2_buf, VB2_BUF_STATE_DONE); stream->cur_buf = NULL; } spin_unlock(&stream->vb_lock); out: writel(status, dev->base + ISP_INT_STATUS); /* 写 1 清中断 */ return IRQ_HANDLED; }

这段代码有两个容易忽略的点。一是中断状态寄存器通常写 1 清除，不清理会反复进中断，CPU 占用飙升但帧率不动。二是vb2_buffer_done必须在自旋锁保护下调用，因为用户态可能同时在 DQBUF，不加锁会偶发 buffer 状态错乱，现象就是取流跑几分钟后 DQBUF 超时。缓冲区数量一般给 4 个起步，太少会在高分辨率下丢帧，太多会占内存且首帧延迟变大。

3. 把驱动跑起来：编译、设备树与取流验证的完整操作

看懂骨架之后要落地。这一章按「编译 → 挂设备树 → 加载 → 取流 → 抓图」的顺序走一遍，每一步给出可执行的命令和判据。

3.1 编译：内核内建还是外部模块

rkisp 驱动依赖 media、v4l2、videobuf2 这些子系统，编译前先确认内核配置项打开。常见做法是把它做成模块，方便改完单独替换，不用整机重烧。

# 内核源码根目录下执行，确认关键配置已开 scripts/config --module CONFIG_VIDEO_ROCKCHIP_ISP scripts/config --enable CONFIG_MEDIA_CONTROLLER scripts/config --enable CONFIG_VIDEO_V4L2_SUBDEV_API scripts/config --enable CONFIG_VIDEOBUF2_DMA_CONTIG # 只编译该驱动所在目录，加快迭代 make M=drivers/media/platform/rockchip/rkisp -j$(nproc)

CONFIG_MEDIA_CONTROLLER必须开，否则 media 拓扑不存在，后面的media-ctl全都没法用。CONFIG_VIDEO_V4L2_SUBDEV_API决定能否从子设备节点直接读写格式，调 sensor 时离不了。编译产物是rkisp.ko，用modinfo看依赖，缺哪个补哪个，不要靠猜。

3.2 设备树：endpoint 与 clock 是最常错的两处

设备树要写两部分，一是 isp 节点本身，二是 sensor 与 isp 之间的 endpoint 连接。以下是结构示意，具体地址和中断号按实际 SoC 填。

&i2c1 { camera: camera@36 { compatible = "vendor,sensor-name"; reg = <0x36>; clocks = <&cru CLK_CAM0_OUT>; port { cam_out: endpoint { remote-endpoint = <&isp_in>; /* 必须指向 isp 的 sink */ ># 加载依赖与驱动 modprobe videodev modprobe rkisp # 查看 media 拓扑，确认 sensor -> isp -> video 链路存在 media-ctl -d /dev/media0 -p # 列出所有 video 节点，找到 isp 输出的那个 v4l2-ctl --list-devices

media-ctl -p的输出里重点看两件事：entity 是否齐全、link 是否 enabled。如果 sensor entity 存在但 link 是 disabled，用media-ctl -l手动使能再试。v4l2-ctl --list-devices用来区分哪个/dev/videoN是 ISP 主通路，哪个是参数节点，名字里一般带 isp 或 params。

3.4 取流与抓帧：把「有图」变成「可复现的有图」

确认拓扑后用标准 V4L2 工具取流，先定格式再取帧。

# 设置 ISP 输出节点格式：1920x1080，NV12 v4l2-ctl -d /dev/video0 \ --set-fmt-video=width=1920,height=1080,pixelformat=NV12 # 抓 10 帧存成文件，用于验证链路是否真的通 v4l2-ctl -d /dev/video0 \ --stream-mmap=4 --stream-count=10 --stream-to=/tmp/frame.raw # 转成可看的图，确认不是全绿或全黑 ffmpeg -f rawvideo -pix_fmt nv12 -s 1920x1080 \ -i /tmp/frame.raw -frames:v 1 /tmp/frame.png

--stream-mmap=4表示申请 4 个 mmap 缓冲区，和驱动里 vb2 队列数量对应。--stream-count=10抓完自动停，避免忘了停一直占设备。转出来的图如果整张偏绿，多半是 ISP 的格式配置和 sensor 实际输出 Bayer 排布不一致；全黑则优先查 MIPI lane 和 clock，而不是怀疑 ISP 算法。

3.5 参数节点：ISP 效果参数怎么下发

rkisp 除了视频节点还会暴露参数节点，用于下发 3A、去噪、gamma 这些配置。常见做法是用户态把参数结构体按帧写进参数 video 节点，驱动在帧开始中断里取用。

# 参数节点一般单独成设备，先确认是哪个 v4l2-ctl --list-devices | grep -A2 -i params # 用厂商工具或自写程序把参数 buffer 写入该节点 # 关键点：参数 buffer 要和帧序号对齐，否则生效滞后一帧

这里的坑是参数生效时机。如果参数在帧结束中断里写，实际作用到的是下一帧，调曝光时会感觉「反应慢半拍」。正确做法是参数入队在帧开始前完成，驱动侧在 start stream 时就把首帧参数准备好。

4. 排查清单：rkisp 取流失败时先看这五个地方

驱动调试最耗时间的不是写代码，是定位。下面几条都是实际踩过的，按「现象 → 原因 → 解决」记录，遇到问题按顺序过一遍，能省掉大半盲目试错。

4.1 现象：media 拓扑里 sensor 缺失

原因通常是 sensor 驱动没 probe 成功，或者设备树 endpoint 没对上。先dmesg | grep -i sensor看有没有 i2c 通信失败，再确认remote-endpoint双向都写了。解决方式是先用i2cdetect确认 sensor 在总线上有响应，再回头查设备树。

4.2 现象：STREAMON 成功但 DQBUF 一直超时

这是最典型的「链路通但没数据」。原因集中在 MIPI 接收端：lane 数配置和硬件不一致、clock lane 没进入高速模式、sensor 没真正开始出图。解决方式是读 CSI 的错误计数寄存器，如果错误计数在涨，基本锁定 lane 或时钟问题；如果计数为 0 但没帧，查 sensor 的流开启寄存器是否真的写成功。

4.3 现象：能出图但帧率只有预期的一半

原因多半是中断处理里做了太多事，或者缓冲区数量不够导致流水线断流。先看/proc/interrupts里 ISP 中断计数是否和帧率匹配，如果中断数远大于帧数，说明中断没清干净在反复触发。解决方式是把耗时逻辑移出中断上下文，中断里只做 buffer 归还，同时把 vb2 缓冲区从 2 个加到 4 个以上。

4.4 现象：切换分辨率后黑屏且无法恢复

原因是格式切换时没有正确 stop stream 再重新配置 DMA，旧 buffer 还挂在硬件上。解决方式是在set_fmt路径里先判断是否正在 streaming，是则强制 stop，再重新计算 stride 和 buffer size。stride 不对会导致图撕裂或者 DMA 越界，这类问题在 dmesg 里常表现为 iommu fault。

4.5 现象：多路同时取流时随机丢帧

原因是多路共用中断或共用 clock，资源竞争没有保护。先确认每路是否有独立的中断状态位，共用的话要在中断里按状态位分发。解决方式是给每路 stream 独立的锁，避免一路的 buffer 操作阻塞另一路，同时检查 DDR 带宽是否够两路 1080p 同时写。

5. 进阶验证：用寄存器回读和帧计数把黑匣子打开

调到最后会发现，很多问题靠 dmesg 是看不出来的，驱动安安静静，图就是不对。我一般会加一层轻量的自检：在帧完成中断里周期性回读关键寄存器，把帧计数和硬件状态一起打到 trace 里，出问题时直接看时间线，而不是靠猜。这份代码的结构很适合这么干，因为中断路径短、状态集中。

具体做法是定义一个调试开关，打开后每 N 帧打印一次 ISP 的输入尺寸、输出尺寸、当前 buffer 地址和错误状态位。注意不要在中断里直接printk，高频打印本身就会把帧率拖垮，用trace_printk或者环形缓冲记录，用户态再取出来看更稳。

/* 每 60 帧采样一次硬件状态，写入 trace 缓冲，不阻塞中断 */ static void rkisp_trace_state(struct rkisp_device *dev) { struct rkisp_stream *s = &dev->stream[RKISP_STREAM_MP]; if (!dev->debug_en) return; if (s->frame_id % 60) return; trace_printk("frame=%u in=%ux%u out=%ux%u err=0x%08x\n", s->frame_id, readl(dev->base + ISP_IN_WIDTH), readl(dev->base + ISP_IN_HEIGHT), readl(dev->base + ISP_OUT_WIDTH), readl(dev->base + ISP_OUT_HEIGHT), readl(dev->base + ISP_ERR_STATUS)); }

这段的价值在于把「图不对」这种主观判断变成可对比的数字。比如输入宽高和 sensor 配置不一致，说明格式没真正下发到硬件；输出宽高对但 err 非 0，说明 DMA 或裁剪环节有问题。trace_printk的输出通过/sys/kernel/debug/tracing/trace读取，对帧率影响远小于 printk。

配合寄存器回读，还可以做一个简单的自检脚本，取流前后各读一次关键寄存器做 diff，确认配置真的写进去了。很多「配置没生效」的问题，本质是写寄存器的时序不对，比如在 stream off 状态下写 DMA 地址，硬件根本不认。验证方法是先把 stream 停掉，写配置，回读确认值正确，再开流，这样能把配置问题和数据通路问题彻底分开。

另一个值得加的验证是帧计数与时间戳对齐。在中断里记ktime_get_ns()，用户态拿到 buffer 后用v4l2_buffer.timestamp对比，两者偏差应该在一帧周期以内。偏差过大说明 buffer 在队列里等了太久，通常是消费者太慢或者缓冲区太少。这个指标比看帧率更早暴露问题，帧率还没掉的时候，时间戳偏差往往已经先大了。

血泪经验是：不要等出问题才加日志，拿到一份新驱动代码，先把这套轻量 trace 和寄存器回读搭起来，后面每一次怀疑都有数据可查。从那以后我每次接手新的 ISP 驱动，都强制先跑一遍「拓扑枚举 + 寄存器回读 + 帧计数对齐」这三步，再开始调画质。希望帮到你。

本文还有配套的精品资源，点击获取