Xilinx V4L2 MIPI CSI-2 RX Driver
Page overview: This page describes the Linux V4L2 driver for the AMD/Xilinx MIPI CSI-2 RX Subsystem, including supported IP/driver features, kernel configuration, device tree binding, validation procedure, tested boards, known issues, change history, and related references. It is aligned with the MIPI CSI-2 Receiver Subsystem Product Guide (PG232) and the current linux-xlnx CSI-2 RX driver.
Table of Contents
Introduction
The MIPI CSI-2 RX Subsystem implements a receive interface for MIPI CSI-2 camera-sensor pipelines. It receives CSI-2 image data from a MIPI image source, decodes the stream, and outputs AXI4-Stream video data for downstream image-processing IP such as Demosaic, Gamma LUT, Video Processing Subsystem, and framebuffer components.
The MIPI CSI-2 Receiver Subsystem supports MIPI CSI-2 standard v3.0 operation with MIPI D-PHY v2.0 or MIPI C-PHY v2.0 physical-layer options, depending on the selected IP version, device, and subsystem configuration. The IP provides configurable CSI-2 receive features such as lane or trio selection at generation time, data type support for RAW/RGB/YUV formats, virtual-channel support, interrupt/status reporting, and an AXI4-Lite register interface when enabled.
This page documents the Linux V4L2 sub-device driver for the AMD/Xilinx MIPI CSI-2 RX Subsystem soft IP. The driver source is xilinx-csi2rxss.c. It registers a V4L2 sub-device node, for example /dev/v4l-subdev*, and participates in the Linux media-controller pipeline. For general V4L2 framework information, refer to the Linux V4L2 core documentation.
The driver exposes two media pads: a sink pad connected to the camera sensor or upstream CSI-2 source, and a source pad connected to the next video-processing element in the pipeline. The sink pad format is validated against the IP configuration and driver media-bus format mappings, then propagated to the source pad.
IP/Driver Features
IP Features | 2018.1 | 2018.2 | 2018.3 | 2019.1 | 2019.2 | 2020.1 | 2020.2 | 2021.1 | 2021.2 | 2026.1 |
|---|---|---|---|---|---|---|---|---|---|---|
IP version | 3.0 | 3.0 | 4.0 | 4.0 | 4.1 | 5.0 | 5.1 | 6.0 | ||
Compatible String |
|
| ||||||||
Support for 1 to 4 D-PHY lanes and 1 to 3 C-PHY trios | D-PHY supported | D-PHY or C-PHY mode selection supported by IP v6.0 | ||||||||
Line rates ranging from 80 to 4500 Mb/s | Supported by IP; maximum rate depends on device family, PHY mode, speed grade, and subsystem configuration. Refer to PG232 for exact limits. | |||||||||
Multiple Data Type support (RAW, RGB, YUV) | IP allows RAW6/7/8/10/12/14, RGB444/555/565/666/888, and YUV422 8 bpc. | IP adds RAW16/20 and YUV422 10 bpc support. Driver has mapped support for RAW8/10/12/16, YUV422 8/10, RGB888 variants, and Y8/Y10/Y12/Y16. | YUV420 8 bpc supported in driver. | Driver adds RGB888 format variants and monochrome formats for 8, 10, and 16 bits. | ||||||
AXI IIC support for Camera Control Interface (CCI) | NA | Removed | ||||||||
Filtering based on Virtual Channel Identifier | NA | VC0–VC3 supported by default; extended VCX status/event handling supports up to 16 virtual channels when CSI-2 v2.0 and VCX are enabled in the IP/device tree. | ||||||||
Support for 1, 2, 4, or 8 pixels per clock at the output | 1, 2, or 4 pixels per clock | 1, 2, 4, or 8 pixels per clock | ||||||||
AXI4-Lite interface for register access to configure different subsystem options | Yes; required by the Linux driver | |||||||||
Dynamic selection of active lanes within the configured lanes during subsystem generation | Supported by IP configuration/device tree. Runtime userspace lane selection through V4L2 controls is not supported in the current upstream-based Linux driver. | |||||||||
Interrupt generation to indicate subsystem status information | Yes; driver maintains event counters and reports status through log_status. | |||||||||
Internal D-PHY or C-PHY allows direct connection to image sources | Internal D-PHY | Internal D-PHY or C-PHY | ||||||||
Video Format Bridge support | Required by the current Linux driver; probe fails if Video Format Bridge is not enabled in the generated design/device tree. | |||||||||
Resource optimization (removed register interface) | NA | Not supported by the Linux driver | ||||||||
Update for 2021.1
From 2021.1 onward, the upstream driver is used.
The upstream driver does not include the earlier V4L2 controls. (Removed in upstream)
Pad 0 is the sink pad, and pad 1 is the source pad.
The driver uses the GPIO connected to the
video-aresetnpin for reset.If a buffer overflow occurs, the core is disabled.
The driver enumerates bus formats. (Removed in upstream)
Only the sink pad format can be set. If the source format is set, the driver returns the format configured on the sink pad.
When the short packet FIFO is not empty, the driver reads the short packet data and prints it to the debug log.
The driver keeps counters for all event types and prints them through log status.
During stream-on, the driver enables itself and calls the stream-on function of the source element driver, reducing reliance on the Xilinx video pipeline.
During stream-off, the core is disabled and a hard reset is applied through the GPIO connected to the
video-aresetnpin.
Missing Features / Known Issues / Limitations in Driver
Streamline buffer-full events indicate a design or pipeline issue. Check the generated design, throughput, and downstream back-pressure handling.
No separate Linux D-PHY or C-PHY driver is available. PHY handling is managed through the CSI-2 RX Subsystem driver and device-tree configuration.
When the D-PHY register interface is enabled, the driver only enables or disables the D-PHY. Runtime modification of other D-PHY parameters is not supported.
The driver has been validated with fixed clocks; dynamic clock changes are not tested.
Video Format Bridge must be enabled in the generated design and device tree. The current driver probe rejects operation without VFB.
Power suspend and resume flows are not tested.
Resource-optimized IP configurations with the register interface removed are not supported.
RAW20 is accepted as a CSI-2 v2.0 data type in device-tree validation, but the current driver has no RAW20 media-bus format mapping; end-to-end capture is not documented as supported.
RAW6, RAW7, RAW14, and RGB444/555/565/666 are recognized as CSI-2 data types, but currently have limited or no media-bus format mapping in the driver table.
Runtime active-lane selection through a V4L2 control is not supported in the current upstream-based driver. Active-lane capability is read from device tree/IP configuration.
Earlier custom event/control support for short packets, short-packet FIFO overflow, streamline buffer overflow notifications, and frame-count reporting was removed when the upstream driver was adopted.
Driver interrupt/error counters are still maintained and can be printed through log status.
Build and Enable the Driver
Enable the following kernel configuration options for the Xilinx video framework and the MIPI CSI-2 RX Subsystem driver. The driver also depends on the common clock framework and expects the generated device tree to provide the clocks named lite_aclk and video_aclk.
CONFIG_VIDEO_XILINX
CONFIG_VIDEO_XILINX_CSI2RXSSDevice Tree Binding and Example Pipeline
Device tree binding
The MIPI CSI-2 RX Subsystem node must match the hardware configuration generated by Vivado. The device tree describes the IP compatible string, register range, interrupts, clocks, reset GPIO, enabled PHY mode, Video Format Bridge setting, active lanes or trios, supported data types, and media graph endpoints.
Use the upstream binding file as the source of truth for required and optional properties: xlnx,csi2rxss.yaml.
In a complete camera pipeline, the CSI-2 RX sink endpoint must be connected to the camera sensor or upstream CSI-2 source endpoint using remote-endpoint. The CSI-2 RX source endpoint must then be connected to the next video-processing IP in the media graph, such as Demosaic, Gamma LUT, VPSS, or Framebuffer Write.
For board-specific changes, use a system-user.dtsi overlay on top of the generated pl.dtsi. The overlay should add or update the sensor node and connect the sensor endpoint to the MIPI CSI-2 RX Subsystem endpoint. See the attached system-user.dtsi for an overlay example and system.dts for an example of the final device tree.
Example validation pipeline
The driver has been validated with an IMX274 image sensor using the MIPI D-PHY interface. The example media pipeline receives RAW image data from the sensor, converts it through the video-processing blocks, writes frames to memory, reads them back, and sends the output to the MIPI DSI transmitter.
IMX274 sensor → MIPI CSI-2 RX → Demosaic → Gamma LUT → VPSS CSC → VPSS Scaler → Framebuffer Write → Memory → Framebuffer Read → MIPI DSI TXThe media graph must be described consistently in the device tree so that each block is linked to the next block through matching endpoints. After boot, use media-ctl -p to verify that the sensor, MIPI CSI-2 RX Subsystem, video-processing IP, and video node appear in the expected order before configuring formats or starting capture.
Test Procedure
This procedure validates the MIPI CSI-2 RX capture path using the example ZCU102 pipeline described above. The pipeline connects the MIPI CSI-2 RX Subsystem to Demosaic, Gamma LUT, VPSS CSC, VPSS Scaler, and Framebuffer Write IP.
The test setup uses an IMX274 sensor FMC card to capture image data and send the CSI-2 stream to the MIPI CSI-2 RX Subsystem.
Before running the commands, confirm that the media device, sub-device names, and video node names match your board. Use media-ctl -p to inspect the media graph and update the commands only if your generated design uses different entity names or device nodes.
Configure media formats
Use media-ctl to configure the media-bus format and resolution on the CSI-2 RX pads. The example below sets RAW8 Bayer data at 1920x1080 on the CSI-2 RX sink pad. Keep the format consistent with the connected sensor and downstream pipeline.
#Assuming the media device /dev/media1 has MIPI CSI2 Rx Subsystem entity name whose name is "a00f0000.csiss"
#To set RGGB RAW8 bayer data of size 1920x1080 on source pad
media-ctl -v -V '"a00f0000.csiss":0 [fmt:SRGGB8_1X8/1920x1080 field:none colorspace:srgb]' -d /dev/media1Run capture test with yavta
After the pad formats are configured, set up the full media pipeline and start video capture with yavta. The first two yavta commands are legacy examples for the sub-device controls and are marked as not applicable after 2020.2 in the command comments.
#Assume MIPI CSI2 Rx subsystem which is registered as /dev/v4l-subdev1
#To set the number of active lanes as 4 (NA after 2020.2)
yavta -w '0x0098c981 4' /dev/v4l-subdev1
#To see all the controls
yavta -l /dev/v4l-subdev1
#Need to setup the media pipeline and start capture of video stream
media-ctl -v -V '"IMX274":0 [fmt:SRGGB8/1920x1080@1/60 field:none colorspace:srgb]' -d /dev/media1
media-ctl -v -V '"a00f0000.csiss":0 [fmt:SRGGB8_1X8/1920x1080 field:none colorspace:srgb]' -d /dev/media1
media-ctl -v -V '"a0250000.v_demosaic":1 [fmt:RBG888_1X24/1920x1080 field:none colorspace:srgb]' -d /dev/media1
media-ctl -v -V '"a0270000.v_gamma":1 [fmt:RBG888_1X24/1920x1080 field:none colorspace:srgb]' -d /dev/media1
media-ctl -v -V '"a0240000.csc":1 [fmt:RBG888_1X24/1920x1080 field:none colorspace:srgb]' -d /dev/media1
media-ctl -v -V '"a0200000.scaler":0 [fmt:RBG888_1X24/1920x1080 field:none colorspace:srgb]' -d /dev/media1
media-ctl -v -V '"a0200000.scaler":1 [fmt:UYVY/1920x1080 field:none colorspace:srgb]' -d /dev/media1
#Now start streaming
yavta -n 3 -c10 -f UYVY -s 1920x1080 --skip 7 -F /dev/video4
Short-packet and event handling were validated using a custom application. The application opens the V4L2 sub-device and uses poll() on the returned file descriptor to receive short-packet and event notifications.
This custom application was required because standard test applications did not provide a poll()-based mechanism for V4L2 sub-device event testing.
Boards Supported
Driver has been tested on following boards:
ZCU102 Rev 1.0
VEK385 RevB
Platform note: PG232 documents broader device-family support for the MIPI CSI-2 RX Subsystem, including newer AMD adaptive SoC platforms depending on IP version and device selection. This Linux driver page list only boards that have been validated with this V4L2 driver and pipeline.
Known Issues
Related Links
Change log
2026.1
Summary
2025.2
No changes
2025.1
Summary
Fix kernel trace warning
Fix kernel doc warnings
Fix warnings for NULL_RETURNS
Add support for YUV 420 8bpc
Commits
2024.2
No changes
2024.1
No changes
2023.2
Summary
Add support for YUV420 8 BPC
Commit
2023.1
No changes
2022.2
No changes
2022.1
No changes
2021.2
No changes
2021.1
Summary
Fix warnings for NULL_RETURNS
Add YUV 420 8 bpc support
Upstream version being used
Commits
2020.2
Summary
Add support for YUV 420 8 bpc
Fix Coverity warnings
Commits
2020.1
Summary
I2C has been removed and DPHY is now at 4K offset. So IP and driver version has been set to 5.0
Set source pad format same as sink pad
Instead of 1, set default number of active lanes as max number of lanes
Commits
2019.2
Summary
Add support to reset IP using external GPIO and stop streaming in case of stream line buffer full condition.
Commits
c3e2148 v4l: xilinx: xcsi2rxss: Use external reset in a SLBF condition
2019.1
Summary
Add support for common clock framework
Add support for RAW16 format
Commits
2018.3
Summary
Add support for up to 16 virtual channel VCX when enabled in IP configuration
Fix to store format size to ensure link_validate passes.
Commits
2018.2
Summary
No changes
2018.1
Summary
Add xlnx,mipi-csi2-rx-subsystem-3.0 compatible string
Fix compilation issue due to framework change
Commits
2017.4
Summary
No changes
2017.3
Summary
Fix to handle failure case while creating a custom control
Commits
9921a92 v4l: xilinx: csi2rxss: Handle failing to create custom control
2017.2
Summary
Fix a crash caused by update to events counters
Commit
e3a7ef8 xcsi2rxss: Fix crash caused by update to event counter variable
2017.1
Summary
Fix to support changing the bayer phase at run time
Commit
56e9ba9 xcsi2rxss: Support bayer phase change at run-time
2016.4
Summary
No change
2016.3
Summary
The driver is added
Commits
4db32c67 xcsi2rxss: Add support for Xilinx CSI-2 Receiver Subsystem