X2MIPI / X2CSI 硬件与驱动移植
X2MIPI（X2CSI）用于将 USB-C、HDMI 或 DP 视频源转换为 MIPI CSI-2 输出，便于接入树莓派、NVIDIA Jetson、Rockchip 等 SoC 平台的 CSI 接收接口。本文整理硬件连接、驱动集成和平台移植要点。
资料、硬件与支持
设计资料、硬件 PCBA 购买与技术支持请通过 doc.ultrasemi.com 获取。
1、硬件介绍
X2MIPI 硬件支持多种视频输入到 MIPI CSI-2 输出的桥接应用：
- USB-C to MIPI CSI
- HDMI to MIPI CSI
- DP to MIPI CSI
硬件设计和平台适配时请重点确认：
- 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，并读取输入状态。
通用验证命令：
dmesg | grep -i lk_x2mipi
v4l2-ctl --list-devices
media-ctl -p向桥接芯片写入 EDID：
sudo dd if=/path/to/edid.bin of=/dev/lk_x2mipi bs=512 count=1
dmesg | grep -i "EDID updated"读取当前分辨率、帧率、音频采样率和输入锁定状态：
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 树莓派移植
树莓派移植包适合在树莓派本地编译，典型目录如下：
lk_x2mipi/
├─ module/
│ ├─ Makefile
│ └─ lk_x2mipi.c
├─ overlay/
│ └─ lk_x2mipi-overlay.dts
└─ scripts/
├─ build.sh
└─ install.sh安装编译依赖：
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编译并安装：
cd /home/pi/lk_x2mipi
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/。
在 /boot/firmware/config.txt（部分系统为 /boot/config.txt）中启用：
camera_auto_detect=0
dtoverlay=lk_x2mipi默认 overlay 为 2-lane CSI。接在 CAM0 时使用：
dtoverlay=lk_x2mipi,cam0硬件实际使用 4 条 CSI data lane 时启用：
dtoverlay=lk_x2mipi,4lane如需 media-controller 模式：
dtoverlay=lk_x2mipi,media-controller=1重启后使用通用验证命令检查驱动、media 拓扑和视频节点。若没有 /dev/video0，请确认系统实际加载的是 /boot/firmware/overlays/lk_x2mipi.dtbo，并重新执行编译和安装脚本覆盖旧文件。
2.2 Jetson 移植
Jetson/L4T 平台通常将驱动集成到目标内核源码树，目录可按 Kconfig + Makefile + C 方式组织：
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：
sudo /sbin/insmod ./lk_x2mipi.ko vi_bridge=1长期使用前需结合目标 L4T 版本和 camera_common 集成方式验证稳定性。
2.3 RK 移植
Rockchip 平台可按通用 Linux 内核驱动方式集成，适用于 RV1126B 等具备 MIPI CSI 接收能力的平台：
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 等资源。
完成内核、设备树和镜像部署后，使用通用验证命令确认驱动加载、media 拓扑和视频节点是否正常。