How to Debug a GMSL2 Driver for Linux
The fastest reliable way to debug a GMSL2 driver on Linux is to test one boundary at a time: power and clocks, local I2C, GMSL2 control channel, remote serializer/sensor access, sensor streaming, GMSL2 video, deserializer CSI-2 output, Linux media topology, and V4L2 buffers. Find the last stage that works consistently and investigate the next stage instead of changing the whole camera stack at once.
This workflow applies to embedded Linux camera systems including NVIDIA Jetson and NXP platforms. RidgeRun provides custom V4L2 camera-driver development and lists GMSL2 among tested serializer/deserializer technologies.
RidgeRun has worked with several GMSL2 configurations, for more than 30 different customers over the last 8 years. Chips we have used before are:
| Chip | Type |
|---|---|
| MAX9295A | GMSL2 CSI-2 Serializer |
| MAX9296A | Quad GMSL2 CSI-2 Deserializer |
| MAX96712 | Quad GMSL2 CSI-2 Deserializer |
| MAX96714 | Single GMSL2/GMSL1 CSI-2 Deserializer |
| MAX96716A | Dual GMSL2 CSI-2 Deserializer |
| MAX96717 | GMSL2 CSI-2 Serializer |
| MAX96724 | Quad GMSL2/GMSL1 CSI-2 Deserializer |
| MAX96792A | Dual GMSL3/GMSL2 CSI-2 Deserializer |
| MAX96793 | GMSL3/GMSL2 CSI-2 Serializer |
RidgeRun has experience with more than 50 camera drivers and complex serializer/deserializer camera architectures.
Layered Failure Model
1 Power / reset / clock
|
2 Local I2C
|
3 Deserializer
|
4 GMSL2 control channel
|
5 Serializer + sensor
|
6 Sensor stream-on
|
7 GMSL2 video
|
8 Deserializer CSI-2 output
|
9 SoC CSI receiver / media graph
|
10 V4L2 buffers
|
11 Application
Always ask: What is the last boundary proven to work?
Step 0: Document the topology
Before starting, document the intended topology:
- Serializer 7-bit I²C address per link
- Deserializer 7-bit I²C address
- Sensors/Cameras 7-bit I²C address
- Pixel or tunnel mode configuration
- Expected active links and pipes
- Stream IDs
- Serializer CSI-2 input, resolution, format and virtual channel
- Deserializer CSI-2 output, MIPI configuration, pipes mapping, port enabled, output controller/PHY/lane count, expected link rate
Document the full data and configuration paths will help to have everything mapped of how it should work and how the configuration has to be done.
Step 1: Power, Reset, and Clock
Verify deserializer, serializer, and sensor rails; sensor reference clock; reset/power-down GPIOs; sequencing delays; cable; and connector.
A sensor can respond over I2C while still being unable to generate valid video.
Step 2: Local I2C
To validate the camera is connected, we can use i2cdetect tool (assuming the camera, serializer and deserializer are connected via I2C). A sample command is:
sudo i2cdetect -r -y <bus>
Be cautious with devices that do not tolerate arbitrary scans. Prefer known register reads or driver diagnostics where appropriate.
An address shown as `UU` commonly means a kernel driver has claimed it. In a example use case, the output looks like:
user:~$ sudo i2cdetect -y -r 4
0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- 1a UU UU UU -- --
20: 20 -- -- -- -- -- -- UU -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- UU UU UU -- -- -- -- -- -- -- -- -- -- -- --
50: 50 -- -- -- -- -- -- -- 58 -- -- -- -- -- -- --
60: 60 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- --
Where the chips addresses are as follows:
- MAX96724 GMSL2 Deserializer: 0x27
- MAX96717 GMSL2 Serializers: 0x41, 0x42,x 0x43
- Sony IMX900 camera: 0x1b, 0x1d
- Sony IMX477 camera: 0x1c
Step 3: GMSL2 Control Channel
Prove:
Host -> Deserializer -> GMSL2 control -> Serializer -> Sensor
| Check | Expected |
|---|---|
| Deserializer ID | Correct and repeatable. |
| Control link | Reaches required state. |
| Serializer ID | Remote access works. |
| Sensor ID | Correct after repeated cold boots. |
If serializer access works but sensor access fails, check downstream I2C, sensor reset/clock, address, and translation.
Address-Collision Symptoms
Suspect I2C aliasing/translation when:
- Camera A works only with Camera B disconnected.
- Camera availability changes with startup order.
- Enabling a second link makes the first sensor disappear.
- Reads appear to reach the wrong camera.
Step 4: Confirm Sensor Stream-On
A readable chip ID does not prove video output.
Check mode table, PLL/clocking, frame/line length, CSI lanes, data type, stream-on write, and sensor fault state.
If available, use a known sensor test pattern to separate imaging problems from digital transport.
Step 5: Separate GMSL2 Link and Video Health
A locked link can still carry no useful video.
Inspect device-specific status for link lock, errors, incoming video detection, video-pipe enable, stream mapping, data type, VC, and CSI transmitter state.
Remote I2C works + no video: check sensor stream and serializer CSI input Video detected + no CSI output: check deserializer pipe/routing/output CSI output active + capture timeout: check host receiver/media graph/timing
Step 6: Verify CSI-2 End to End
Confirm lane count, lane mapping/polarity, data type, bits per pixel, link frequency, resolution, timing, and virtual channel at every boundary.
For multiple cameras:
Sensor A -> Link A -> Pipe 0 -> VC0 -> Receiver Sensor B -> Link B -> Pipe 1 -> VC1 -> Receiver Sensor C -> Link C -> Pipe 2 -> VC2 -> Receiver Sensor D -> Link D -> Pipe 3 -> VC3 -> Receiver
Do not confuse CSI-2 virtual-channel IDs with Linux/V4L2 stream identifiers.
Step 7: Inspect the Linux Media Graph
v4l2-ctl --list-devices media-ctl -d /dev/media0 -p
Look for expected sensor/bridge entities, CSI receiver, processing blocks, capture node, enabled links, pad formats, and routes.
A `/dev/videoX` node does not prove the intended camera path is complete.
Step 8: Inspect V4L2 Formats and Controls
v4l2-ctl -d /dev/video0 --all v4l2-ctl -d /dev/video0 --list-formats-ext v4l2-ctl -d /dev/video0 --list-ctrls
Check width, height, pixel format, frame interval, exposure/gain ranges, blanking, and pixel rate for inconsistencies.
Step 9: Minimal Capture
Remove application complexity:
v4l2-ctl -d /dev/video0 \
--set-fmt-video=width=1920,height=1536,pixelformat=RG12 \
--stream-mmap --stream-count=10 \
--stream-to=/tmp/v4l2_capture.raw
Then:
v4l2-compliance -d /dev/video0
If minimal V4L2 works but GStreamer fails, investigate the userspace pipeline rather than changing SerDes configuration.
Step 10: Capture Kernel Logs During Stream-On
dmesg -w
Record messages at probe, stream-on, first buffer, failure/timeout, and stream-off.
Interpret platform-specific CSI errors against the exact BSP/kernel source rather than assuming the same meaning across SoCs.
Step 11: Use Test Patterns to Shorten the Pipeline
Deserializer pattern works, remote camera fails: investigate sensor / serializer / GMSL input. Deserializer pattern also fails: investigate CSI output / host receiver / media graph.
Use test patterns only when their configuration is independently known to be valid.
Step 12: Multi-Camera Debugging
| Test | Purpose |
|---|---|
| Camera A only | Known-good baseline. |
| Camera B only | Independent link/addressing. |
| A + B | Routing/shared resources. |
| Reverse start order | Ordering dependencies. |
| Stop A while B runs | Shared-resource teardown. |
| Repeated start/stop | State leaks/races. |
Then expand to the target camera count while monitoring dropped frames, receiver errors, link errors, frame rate, and system load.
Symptom-to-Layer Guide
| Symptom | Next checks |
|---|---|
| Deserializer does not probe | Local power, reset, I2C, device tree. |
| Serializer does not respond | Control channel, remote power, cable, address. |
| Sensor does not respond | Sensor rails, clock, reset, downstream I2C, aliasing. |
| Sensor probes; no video | Stream-on, mode table, serializer CSI input. |
| Video detected; no CSI output | Pipe, routing, data type, VC, transmitter. |
| CSI active; V4L2 timeout | Host receiver, lanes, graph, timing, format. |
| One stream works; multiple fail | VC mapping, address collisions, bandwidth, shared state. |
| Frames corrupted | Bit depth, format, lane errors, timing, stride. |
| V4L2 works; GStreamer fails | Caps, memory type, conversion, downstream elements. |
Create a Reproducible Bug Report
Board / carrier: SoC: BSP: Kernel: Sensor: Serializer: Deserializer: Camera count: Resolution: Frame rate: Pixel format: CSI lanes: Virtual channels: I2C addressing model: Working: [ ] local deserializer [ ] GMSL2 control [ ] serializer [ ] sensor [ ] sensor stream-on [ ] GMSL2 video [ ] deserializer CSI output [ ] media graph [ ] V4L2 buffers First failing stage: Kernel messages: Reproduction steps:
This separates sensor, SerDes, device-tree, receiver, and application failures.
Platform-Specific Follow-Up
For Jetson, continue with How to Create a GMSL2 Driver for NVIDIA Jetson, Software Services for NVIDIA Jetson, and V4L2 drivers available for Jetson SoCs.
For i.MX95, continue with How to Create a GMSL2 Driver for NXP i.MX95 and NXP i.MX95 Technical Guide/Video Capture.
GMSL serializer/deserializer Linux driver and MAX96705 MAX9286 GMSL SERDES Linux Drivers contain useful historical GMSL1 validation examples but should not be used as GMSL2 register-programming references.
Key Takeaways
- Debug from the last proven boundary.
- Prove power and remote I2C before video.
- Link lock does not guarantee CSI-2 or V4L2 capture.
- Verify data type, lanes, VC, timing, and routing end to end.
- Remove GStreamer complexity until minimal V4L2 works.
- Validate each camera alone before multi-camera tests.
- Use `media-ctl`, `v4l2-ctl`, `v4l2-compliance`, and kernel logs systematically.
Frequently Asked Questions
- Why does GMSL2 lock but Linux captures no frames?
- Check sensor stream-on, serializer CSI input, deserializer video detection/routing, CSI output, virtual channel, host receiver, and media graph. Link lock verifies only one layer.
- Why can I read the sensor over I2C but not capture video?
- I2C uses the control path; video uses the sensor, serializer, GMSL2 link, deserializer, CSI-2 receiver, and capture engine. A working control path does not prove the video path.
- Which Linux tools are useful?
- Use `dmesg`, `media-ctl`, `v4l2-ctl`, and `v4l2-compliance`, together with device-specific SerDes diagnostics.
Related Pages
- How to Create a GMSL2 Driver for NVIDIA Jetson
- How to Create a GMSL2 Driver for NXP i.MX95
- V4L2 driver for camera sensor or capture chip
- RidgeRun Linux Camera Drivers
- V4L2 drivers available for Jetson SoCs
- NXP i.MX95 Technical Guide/Video Capture
- GMSL serializer/deserializer Linux driver
For direct inquiries, please refer to the contact information available on our Contact page. Alternatively, you may complete and submit the form provided at the same link. We will respond to your request at our earliest opportunity.
Links to RidgeRun Resources and RidgeRun Artificial Intelligence Solutions can be found in the footer below.
ARTIFICIAL INTELLIGENCE
