X2MIPI / X2CSI 硬件与驱动移植

X2MIPI（X2CSI）用于将 USB-C、HD 或 DP 视频源转换为 MIPI CSI-2 输出，便于接入树莓派、NVIDIA Jetson、Rockchip 等 SoC 平台的 CSI 接收接口。本文整理硬件连接、驱动集成和平台移植要点。

资料、硬件与支持

设计资料、硬件 PCBA 购买与技术支持请通过 doc.ultrasemi.com 获取。

1、硬件介绍

X2MIPI 硬件支持多种视频输入到 MIPI CSI-2 输出的桥接应用：

USB-C to MIPI CSI
HD to MIPI CSI
DP to MIPI CSI

X2MIPI 正面

X2MIPI 侧面

硬件设计和平台适配时请重点确认：

CSI lane 数：常见配置为 2-lane 或 4-lane，需与 SoC 端设备树一致。
I2C 控制接口：驱动通过 I2C 访问桥接芯片，示例地址为 0x58。
设备树 compatible：平台驱动使用 compatible = "ultrasemi,lk-x2mipi"。
输入源与 EDID：可通过字符设备下发 EDID，并读取当前输入状态与分辨率信息。
时钟、电源、复位：不同平台需要按实际硬件连接补充对应资源。

2、驱动移植

驱动形态为 Linux I2C V4L2 subdev 驱动，核心功能包括：

视频输入时序检测与 V4L2 DV timings 查询。
根据设备树 endpoint 的 data-lanes 或 overlay 参数配置 MIPI CSI-2 输出。
V4L2 subdev 事件通知，用于输入源切换等场景。
通过 /dev/lk_x2mipi 更新 EDID，并读取输入状态。

2.1 树莓派移植

2.1.1 树莓派 3 移植

请使用 15Pin 0.1" 反向 FFC 连接至树莓派 3 CAMERA 接口。

X2MIPI 树莓派 3B+ 参考设计

建议使用 6.12 或更高版本 内核。

将整个 lk_x2mipi 目录克隆至树莓派，例如 /home/lk_x2mipi/RaspberryPi3。树莓派移植包适合在板端本地编译，典型目录如下：

text

lk_x2mipi/
├─ module/
│  ├─ Makefile
│  └─ lk_x2mipi.c
├─ overlay/
│  └─ lk_x2mipi-overlay.dts
└─ scripts/
   ├─ build.sh
   └─ install.sh

安装编译依赖：

bash

sudo apt update
sudo apt install -y bc bison flex libssl-dev make device-tree-compiler raspberrypi-kernel-headers
ls -l /lib/modules/$(uname -r)/build

编译并安装：

bash

cd lk_x2mipi/RaspberryPi3
chmod +x scripts/*.sh
./scripts/build.sh
sudo ./scripts/install.sh

编译产物包括 module/lk_x2mipi.ko 和 overlay/lk_x2mipi.dtbo。安装脚本会将模块安装到 /lib/modules/$(uname -r)/extra/，执行 depmod -a，并将 overlay 安装到 /boot/overlays/ 或 /boot/firmware/overlays/。

启用 overlay：

bash

sudo nano /boot/firmware/config.txt

在 /boot/firmware/config.txt（部分系统为 /boot/config.txt）中加入：

ini

camera_auto_detect=0
dtoverlay=lk_x2mipi

默认 overlay 为 2-lane CSI。接在 CAM0 时使用：

ini

dtoverlay=lk_x2mipi,cam0

硬件实际使用 4 条 CSI data lane 时启用：

ini

dtoverlay=lk_x2mipi,4lane

如需 media-controller 模式：

ini

dtoverlay=lk_x2mipi,media-controller=1

重启后使用通用验证命令检查驱动、media 拓扑和视频节点。若没有 /dev/video0，请确认系统实际加载的是 /boot/firmware/overlays/lk_x2mipi.dtbo，并重新执行编译和安装脚本覆盖旧文件。

通用验证命令：

bash

dmesg | grep -i lk_x2mipi
v4l2-ctl --list-devices
media-ctl -p

向桥接芯片写入 EDID：

bash

sudo dd if=/path/to/edid.bin of=/dev/lk_x2mipi bs=512 count=1
dmesg | grep -i "EDID updated"

读取当前分辨率、帧率、音频采样率和输入锁定状态：

bash

sudo dd if=/dev/lk_x2mipi bs=24 count=1 2>/dev/null | hexdump -C

当读取缓冲区不少于 24 字节时，驱动返回 6 个 int 字段：

顺序	字段	含义
0	`w`	当前检测到的宽度，单位像素
1	`h`	当前检测到的高度，单位像素
2	`fps`	帧率估算值
3	`audio_sample`	音频采样率，单位 Hz；无或未知时为 0
4	`change`	相对上一次读取的输入锁定状态是否变化，1 表示有变化
5	`rx_insert`	当前输入锁定或插入状态，1 表示有信号

2.1.2 树莓派 5 移植

请使用 15Pin 0.1" to 22Pin 0.05" 同向 FFC 连接至树莓派 5 CAM/DISP 接口。

注意事项：

验证时使用的树莓派版本信息：Linux raspberrypi 6.18.39+rpt-rpi-2712 #1 SMP PREEMPT Debian 1:6.18.39-1+rpt1 (2026-07-29) aarch64 GNU/Linux
建议使用 6.12 或更高版本 内核
使用树莓派 5 板上的 CAM/DISP 接口
树莓派 5 的 RP1-CFE 需匹配 MIPI 时钟频率；当前示例使用 297 MHz（1920×1080P@30）。若需改变速率，请同时修改 overlay/lk_x2mipi-overlay.dts 中的 link-frequencies，以及驱动源码 lk_x2mipi.c 中的 LK_X2MIPI_LINK_FREQ
主线内核将 UYVY_2X8 标记为 CSI-2 无效格式（并非按双字节传输）。使用前需用支持 UYVY_2X8 的驱动替换 RP1-CFE

将整个 lk_x2mipi 目录克隆至树莓派，例如 /home/lk_x2mipi/RaspberryPi5。典型目录结构：

text

raspberrypi5/
│
├─ rp1-cfe-downstream.ko    # 替换驱动
│
├─ module/
│  ├─ Makefile
│  └─ lk_x2mipi.c           # 模块源码（构建产物 lk_x2mipi.ko）
├─ overlay/
│  └─ lk_x2mipi-overlay.dts
└─ scripts/
   ├─ build.sh
   └─ install.sh

安装编译依赖：

bash

sudo apt update
sudo apt install -y bc bison flex libssl-dev make device-tree-compiler raspberrypi-kernel-headers
ls -l /lib/modules/$(uname -r)/build

替换驱动。以下命令会删除原有驱动，并替换为 raspberrypi5 文件夹下的 rp1-cfe-downstream.ko：

bash

sudo rm /lib/modules/$(uname -r)/kernel/drivers/media/platform/raspberrypi/rp1_cfe/rp1-cfe-downstream.ko.xz
sudo cp /home/lk_x2mipi/raspberrypi/raspberrypi5/rp1-cfe-downstream.ko /lib/modules/$(uname -r)/kernel/drivers/media/platform/raspberrypi/rp1_cfe/

更新模块依赖：

bash

sudo depmod -a

编译并安装：

bash

cd lk_x2mipi/RaspberryPi5
chmod +x scripts/*.sh
./scripts/build.sh
sudo ./scripts/install.sh

启用 overlay：

bash

sudo nano /boot/firmware/config.txt

在 /boot/firmware/config.txt（部分系统为 /boot/config.txt）中加入：

ini

camera_auto_detect=0
dtoverlay=lk_x2mipi

默认 overlay 为 2-lane CSI。接在 CAM0 时使用：

ini

dtoverlay=lk_x2mipi,cam0

硬件实际使用 4 条 CSI data lane 时启用：

ini

dtoverlay=lk_x2mipi,4lane

重启后验证：

bash

dmesg | grep -i lk_x2mipi
media-ctl -p
v4l2-ctl --list-devices

执行后会输出媒体 pipeline 信息，应能看到 rp1-cfe 及 /dev/video0。若没有 /dev/video0，列表里也没有 rp1-cfe，请检查 overlay 与 RP1-CFE 替换是否生效。

dtoverlay=lk_x2mipi 只会加载 /boot/firmware/overlays/lk_x2mipi.dtbo。若系统中存在旧版本文件，请在本仓库重新执行 ./scripts/build.sh 与 sudo ./scripts/install.sh 覆盖安装。

启动默认 MIPI 配置

驱动在 probe 成功后会自动执行一次 MIPI 配置，lane 数取自当前 overlay 的 endpoint 配置：

默认 dtoverlay=lk_x2mipi 时为 2-lane
启用 dtoverlay=lk_x2mipi,4lane 时为 4-lane

通过字符设备更新 EDID

驱动会创建字符设备：

/dev/lk_x2mipi

向该设备写入 EDID 二进制（最大 512 字节）即可下发到桥接芯片。例如：

bash

sudo dd if=/path/to/edid.bin of=/dev/lk_x2mipi bs=512 count=1

查看更新结果：

bash

dmesg | grep -i "EDID updated"

读取当前分辨率等信息（read）

对 /dev/lk_x2mipi 执行一次 read(2)，若缓冲区长度不小于 24 字节，驱动会填入与旧版 struct gsv_info 相同布局的 6 个 int（小端，与进程一致）：

顺序	含义
0	宽度 `w`（像素）
1	高度 `h`
2	帧率 `fps`（由像素时钟与总行列估算，四舍五入）
3	音频采样率 `audio_sample`（Hz；无 / 未知为 0）
4	`change`：相对上一次 read 的输入源锁定状态是否发生变化（1=有变化）
5	`rx_insert`：输入源锁定 / 插入状态（1=有信号）

无有效时序（例如未接源）时 read 仍成功，但前几个字段可能为 0。

示例（读取 24 字节并查看原始内容）：

bash

sudo dd if=/dev/lk_x2mipi bs=24 count=1 2>/dev/null | hexdump -C

配置 pipeline

设置 DV 时序，一般为 subdev2，否则改为实际序号：

bash

v4l2-ctl -d /dev/v4l-subdev2 --set-dv-bt-timings query

查询 media 设备号：

bash

M=$(for d in /dev/media*; do
  media-ctl -d $d -p 2>/dev/null | grep -q lk_x2mipi && echo $d && break
done)
echo MEDIA=$M

会显示所使用的 media 设备号。

重置 pipeline：

bash

sudo media-ctl -d $M -r

断开到 pisp-fe 的链接：

bash

sudo media-ctl -d $M -l "'csi2':4 -> 'pisp-fe':0 [0]"

启用 csi2 -> video0 的链接：

bash

sudo media-ctl -d $M -l "'csi2':4 -> 'rp1-cfe-csi2_ch0':0 [1]"

设置 csi2 sink pad 及 csi2 source pad 格式：

bash

sudo media-ctl -d $M -V "'csi2':0 [fmt:UYVY8_2X8/1920x1080 field:none colorspace:smpte170m]"
sudo media-ctl -d $M -V "'csi2':4 [fmt:UYVY8_2X8/1920x1080 field:none colorspace:smpte170m]"

抓取图像。可执行以下命令尝试抓取一帧：

bash

v4l2-ctl -d /dev/video0 --set-fmt-video=width=1920,height=1080,pixelformat=UYVY --stream-mmap=3 --stream-count=1 --stream-to=image_uyvy.yuv

查看文件信息：

bash

ls -l image_uyvy.yuv

分辨率 1920×1080 时，文件大小应为 4147200 字节。

2.2 Jetson 移植

X2MIPI NVIDIA Jetson 参考设计

Jetson/L4T 平台通常将驱动集成到目标内核源码树，目录可按 Kconfig + Makefile + C 方式组织：

text

jetson/
├─ Kconfig
├─ Makefile
└─ lk_x2mipi.c

内核集成步骤：

将驱动目录放入目标 Jetson 内核树的合适驱动子目录。
在上级 Kconfig 中添加驱动目录的 source。
在上级 Makefile 中添加子目录构建入口，例如 obj-y += lk_x2mipi/jetson/。
在内核配置中启用 CONFIG_VIDEO_LK_X2MIPI_JETSON=y 或 CONFIG_VIDEO_LK_X2MIPI_JETSON=m。

设备树需描述：

I2C 设备节点和 compatible = "ultrasemi,lk-x2mipi"。
器件地址 reg = <0x58>。
与 CSI 接收端的 endpoint 连接关系和 remote-endpoint。
data-lanes，用于选择 2-lane 或 4-lane MIPI 配置。
平台所需的时钟、电源、复位等资源。

部分 Jetson 平台直接加载模块时，VI 异步桥可能不会完成注册，表现为无法生成 /dev/video0。已完成 camera/VI 侧适配时，可显式打开 VI bridge：

bash

sudo /sbin/insmod ./lk_x2mipi.ko vi_bridge=1

长期使用前需结合目标 L4T 版本和 camera_common 集成方式验证稳定性。

2.3 RK 移植

X2MIPI Rockchip RV1126B 参考设计

Rockchip 平台可按通用 Linux 内核驱动方式集成，适用于 RV1126B 等具备 MIPI CSI 接收能力的平台：

text

linux/
├─ Kconfig
├─ Makefile
└─ lk_x2mipi.c

内核集成步骤：

将驱动目录放入目标内核树的视频或媒体驱动目录。
在上级 Kconfig 中添加驱动目录的 source。
在上级 Makefile 中添加子目录构建入口，例如 obj-y += lk_x2mipi/linux/。
在内核配置中启用 CONFIG_VIDEO_LK_X2MIPI=y 或 CONFIG_VIDEO_LK_X2MIPI=m。

设备树需包含：

compatible = "ultrasemi,lk-x2mipi" 的 I2C 节点。
器件地址 reg = <0x58>。
与 Rockchip CSI/D-PHY/ISP 接收链路匹配的 endpoint 连接关系。
data-lanes，驱动会在 probe 阶段读取并配置对应 MIPI lane 数。
平台实际使用的时钟、电源、复位、pinctrl 等资源。

X2MIPI / X2CSI 硬件与驱动移植 ​

1、硬件介绍 ​

2、驱动移植 ​

2.1 树莓派移植 ​

2.1.1 树莓派 3 移植 ​

2.1.2 树莓派 5 移植 ​

启动默认 MIPI 配置 ​

通过字符设备更新 EDID ​

读取当前分辨率等信息（read） ​

配置 pipeline ​

2.2 Jetson 移植 ​

2.3 RK 移植 ​

X2MIPI / X2CSI 硬件与驱动移植

1、硬件介绍

2、驱动移植

2.1 树莓派移植

2.1.1 树莓派 3 移植

2.1.2 树莓派 5 移植

启动默认 MIPI 配置

通过字符设备更新 EDID

读取当前分辨率等信息（read）

配置 pipeline

2.2 Jetson 移植

2.3 RK 移植