X2MIPI / X2CSI Hardware and Driver Porting

X2MIPI, also referred to as X2CSI, bridges USB-C, HDMI, or DP video sources to MIPI CSI-2 output so they can be connected to CSI receivers on Raspberry Pi, NVIDIA Jetson, Rockchip, and other SoC platforms. This page covers hardware notes, driver integration, and platform porting checkpoints.

Resources, Hardware, and Support

Design resources, hardware PCBA purchase, and technical support are available through doc.ultrasemi.com.

1. Hardware Introduction

X2MIPI hardware supports several video-input to MIPI CSI-2 bridge applications:

• USB-C to MIPI CSI
• HDMI to MIPI CSI
• DP to MIPI CSI

During hardware design and platform adaptation, confirm the following items:

• CSI lane count: common configurations are 2-lane or 4-lane, and the SoC device tree must match the hardware.
• I2C control interface: the driver accesses the bridge chip through I2C; the example address is 0x58.
• Device-tree compatible string: the platform driver uses compatible = "ultrasemi,lk-x2mipi".
• Input source and EDID: EDID can be written through a character device, and current input status and resolution can be read back.
• Clock, power, and reset resources: add platform-specific resources according to the actual hardware connection.

2. Driver Porting

The driver is a Linux I2C V4L2 subdev driver. Key functions include:

• Video input timing detection and V4L2 DV timings query.
• MIPI CSI-2 output configuration based on device-tree endpoint data-lanes or overlay parameters.
• V4L2 subdev event notification for source-change scenarios.
• EDID update and input-status readback through /dev/lk_x2mipi.

Common validation commands:

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

Write EDID to the bridge chip:

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

Read the current resolution, frame rate, audio sample rate, and input-lock status:

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

When the read buffer is at least 24 bytes, the driver returns six int fields:

Index	Field	Meaning
0	w	Detected width in pixels
1	h	Detected height in pixels
2	fps	Estimated frame rate
3	audio_sample	Audio sample rate in Hz; 0 when unavailable or unknown
4	change	Whether input-lock status changed since the previous read; 1 means changed
5	rx_insert	Current input lock or insertion status; 1 means signal present

2.1 Raspberry Pi Porting

The Raspberry Pi package is intended for local compilation on the target board. A typical layout is:

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

Install build dependencies:

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

Build and install:

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

The build outputs are module/lk_x2mipi.ko and overlay/lk_x2mipi.dtbo. The install script places the module under /lib/modules/$(uname -r)/extra/, runs depmod -a, and installs the overlay to /boot/overlays/ or /boot/firmware/overlays/.

Enable the overlay in /boot/firmware/config.txt; on some systems the file is /boot/config.txt:

camera_auto_detect=0
dtoverlay=lk_x2mipi

The default overlay uses 2-lane CSI. Use the following when connected to CAM0:

dtoverlay=lk_x2mipi,cam0

Enable 4-lane mode only when the hardware actually connects four CSI data lanes:

dtoverlay=lk_x2mipi,4lane

Enable media-controller mode when required:

dtoverlay=lk_x2mipi,media-controller=1

After reboot, run the common validation commands to check the driver, media topology, and video node. If /dev/video0 is missing, confirm that the system loads /boot/firmware/overlays/lk_x2mipi.dtbo, then rebuild and reinstall to replace any older overlay file.

2.2 Jetson Porting

On Jetson/L4T platforms, the driver is usually integrated into the target kernel source tree with a Kconfig + Makefile + C layout:

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

Kernel integration steps:

1. Place the driver directory under a suitable driver path in the target Jetson kernel tree.
2. Add the driver directory source entry to the parent Kconfig.
3. Add the subdirectory build entry to the parent Makefile, for example obj-y += lk_x2mipi/jetson/.
4. Enable CONFIG_VIDEO_LK_X2MIPI_JETSON=y or CONFIG_VIDEO_LK_X2MIPI_JETSON=m in the kernel configuration.

The device tree should describe:

• An I2C device node with compatible = "ultrasemi,lk-x2mipi".
• Device address reg = <0x58>.
• Endpoint connection to the CSI receiver and the corresponding remote-endpoint.
• data-lanes, used to select 2-lane or 4-lane MIPI configuration.
• Platform-specific clock, power, and reset resources.

On some Jetson platforms, loading the module directly may not complete VI async bridge registration, so /dev/video0 may not appear. After the camera/VI side has been adapted, the VI bridge path can be enabled explicitly:

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

Validate stability against the target L4T version and camera_common integration before using this as the long-term loading method.

2.3 RK Porting

Rockchip platforms can use the generic Linux kernel driver integration flow. This applies to RV1126B and other Rockchip SoCs with a MIPI CSI receiver:

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

Kernel integration steps:

1. Place the driver directory under the target kernel media or video driver tree.
2. Add the driver directory source entry to the parent Kconfig.
3. Add the subdirectory build entry to the parent Makefile, for example obj-y += lk_x2mipi/linux/.
4. Enable CONFIG_VIDEO_LK_X2MIPI=y or CONFIG_VIDEO_LK_X2MIPI=m in the kernel configuration.

The device tree should include:

• An I2C node with compatible = "ultrasemi,lk-x2mipi".
• Device address reg = <0x58>.
• Endpoint connections matching the Rockchip CSI/D-PHY/ISP receive pipeline.
• data-lanes; the driver reads this value during probe and configures the MIPI lane count accordingly.
• Platform-specific clock, power, reset, and pinctrl resources.

After deploying the kernel, device tree, and image, run the common validation commands to confirm driver loading, media topology, and video-node creation.