Ten capture attempts, one clean file, and the same interrupt line in every failing log: that is the signature of a D-PHY lane alignment error on a CSI receiver fed through a SerDes pair. The link is not broken — a broken lane fails every capture — but the receiver is timing its lane sampling from numbers that do not match the link. This guide is for engineers bringing up multi-camera CSI paths on embedded boards. It explains what the alignment error means, ranks the likely causes with a test for each, works the SerDes pixel clock calculation for a 1.6 GHz two-lane link, and ends with the clock-pinning sequence and a ten-run capture test that proves the fix.
What a D-PHY lane alignment error actually tells you
MIPI CSI-2 over D-PHY carries image data in high-speed bursts, and every burst opens with a sync sequence that the transmitter places on each data lane as part of the start of transmission. The receiver's lane interface expects all data lanes of a partition to enter the burst together. It raises a lane alignment error when some lanes of the partition detect those sync words and others, inside the same burst window, do not.
On the capture processor in this case, the flag surfaces as one bit of an interrupt status word in the receiver trace:
rtcpu_nvcsi_intr: tstamp:3013750150 class:GLOBAL type:PHY_INTR0 phy:1 cil:1 st:0 vc:0 status:0x10000000
0x10000000 sets bit 28 of a 32-bit status register, and bit 28 is defined as NVCSI_INTR_FLAG_CIL_INTR0_DPHY_LANE_ALIGN_ERR. The phy:1 and cil:1 fields in the same line name the PHY partition and lane interface unit that raised the error, which is where you look next.
The intermittency is the diagnostic. Lane skew and deskew state sit at the boundary of what the receiver can absorb, so whether a burst aligns depends on the clock rates at stream-on and on the deserializer's calibration timing — the link passes one run and fails the next. A physical fault does not behave that way: a dead lane or a cracked trace fails at the same partition on every run. When captures succeed at full rate and full resolution a fraction of the time, treat the fault as a configuration number, not as hardware.
Likely causes in order of probability
Work the list top down; each item carries a test that convicts or clears it in minutes.
- serdes_pix_clk_hz is wrong or missing. With a SerDes between sensor and receiver, the receiver never sees the sensor's pixel clock directly; the device-tree property serdes_pix_clk_hz tells it what pixel rate to expect on the CSI bus. When this property is defined, the receiver driver uses it alone to configure the SoC-camera interface, and it must be larger than the sensor-side pix_clk_hz. Test: print both values from your overlay and check serdes_pix_clk_hz against the calculation in the next section. A value copied from another overlay — the usual origin — is wrong for any new lane count or bit depth.
- The capture clocks run at their floor. The frame-ingest (vi), image-processing (isp), CSI-controller (nvcsi) and memory (emc) clocks scale down when idle. A stream that starts while one of them sits at its minimum mis-times bursts, and the failure lands wherever the slow block happened to idle that run — intermittency again. Test: read rate and max_rate for each block in the debugfs clock tree while capturing; any block below its maximum is a suspect. Fix: the pinning sequence below.
- Deskew calibration never completes at stream-on. A SerDes pair corrects clock-to-data skew with deskew calibration, and the receiver waits for the initial calibration pass. Deserializers that send periodic deskew bursts hand the receiver fresh chances to complete it; the link in the case below generated a burst every frame with an initial deskew width of 8 × 32k UI. Test: with receiver tracing on, check whether the alignment interrupt coincides with the first frames after stream-on rather than with mid-stream frames.
- Lane routing on the board. Mismatched trace lengths between the deserializer and the receiver land here last, because a link that occasionally runs flawlessly at full rate proves the physical lanes can align. Convict the routing only after items 1–3 clear, and when a lane-mapping change precedes the failures, re-run the lane checks a multi-lane camera needs on a carrier board.
A mis-sized receive path also has downstream signatures: short frames and green or padded frames look like sensor-mode problems but trace back to the same interface numbers — the short-frame check and the green-frame walkthrough cover both.
Worked example: sizing serdes_pix_clk_hz for a 1.6 GHz two-lane link
The case this example works: a CSI link whose deserializer outputs 1.6 GHz per data lane, with two data lanes enabled and 16 bits per pixel on the bus; the sensor mode is 3840 × 1024 delivered as GRAY8. Inputs and sources: the data rate and lane count come from the deserializer's register configuration and the overlay's lane mapping; the bits-per-pixel value comes from the packed pixel width the link carries.
Rule, in words: serdes_pix_clk_hz tells the receiver what pixel rate arrives on the CSI bus, so compute it from the per-lane data rate, the lane count and the bits per pixel — then confirm the reverse calculation reproduces the data rate.
Forward: 1,600,000,000 Hz × 2 ÷ 16 = 200,000,000 Hz = 200 MHz.
Reverse check: 200,000,000 Hz × 16 ÷ 2 = 1,600,000,000 Hz = 1.6 GHz — the loop closes.
Result: write serdes_pix_clk_hz = 200000000, in hertz as the property expects.
Decision and threshold: the property must be larger than pix_clk_hz, and the receiver sizes its buffers from the value, so anything below the true pixel rate overruns the receive path — which is how one wrong number produces alignment errors at stream start. Set 200 MHz where it exceeds pix_clk_hz; if 200 MHz only matches pix_clk_hz, test one step higher while debugging, because an over-value only adds buffer margin while an under-value causes overrun. If the failures clear at the higher value, the computed value was your problem.
The same lane-and-data-rate arithmetic that sets this property also sets the frame-rate budget; the frame-rate estimation from lanes and data rate works from the identical numbers.
Pin the receive clocks before you debug
Even with serdes_pix_clk_hz correct, a capture that starts while the receive path idles at its floor rate fails the same way. The fix in the case is two steps per clock across the four blocks of the capture path — vi (frame ingest), isp, nvcsi (the CSI controller) and emc (memory bandwidth). First lock each clock's rate request, then read each block's maximum and write it back as the current rate:
echo 1 > /sys/kernel/debug/bpmp/debug/clk/vi/mrq_rate_locked
echo 1 > /sys/kernel/debug/bpmp/debug/clk/isp/mrq_rate_locked
echo 1 > /sys/kernel/debug/bpmp/debug/clk/nvcsi/mrq_rate_locked
echo 1 > /sys/kernel/debug/bpmp/debug/clk/emc/mrq_rate_locked
cat /sys/kernel/debug/bpmp/debug/clk/vi/max_rate | tee /sys/kernel/debug/bpmp/debug/clk/vi/rate
cat /sys/kernel/debug/bpmp/debug/clk/isp/max_rate | tee /sys/kernel/debug/bpmp/debug/clk/isp/rate
cat /sys/kernel/debug/bpmp/debug/clk/nvcsi/max_rate | tee /sys/kernel/debug/bpmp/debug/clk/nvcsi/rate
cat /sys/kernel/debug/bpmp/debug/clk/emc/max_rate | tee /sys/kernel/debug/bpmp/debug/clk/emc/rate
The first four lines set mrq_rate_locked, which stops the clock governor from re-scaling underneath a capture. The next four copy max_rate into rate for each block, and the tee on each line prints the value as it lands. Insufficient memory bandwidth fails captures the same way; the frame-rate bottleneck hunt uses the same reads.
The case also enabled receiver tracing with modprobe rtcpu_debug and tracing_on, but that belongs to the log capture, not the fix. Pin the clocks first, and add tracing only when you need the interrupt lines as evidence. Raise the trace buffer size in the same tracing directory before a ten-run loop, or the early runs will push out the late ones.
One cost to accept: clocks pinned at maximum raise the processor's idle power. Keep the pinning for bring-up and for systems that must start streaming at unpredictable times, and measure the power difference before shipping it into a tight power budget.
Prove it with a repeated capture loop
Before changing any value, capture one success log and one failure log and diff them: the alignment interrupt appears only in the failures. That confirms the signature before you touch the overlay.
Then loop a fixed pipeline ten times. The case used a raw grab of the full frame to a file:
gst-launch-1.0 v4l2src device=/dev/video2 ! 'video/x-raw,format=GRAY8,width=3840,height=1024' ! filesink location=./test.yuv
Run it ten times back to back and count the output files. In the case, this loop passed once in ten before the clock work and passed every run after the rate fix and the pinning sequence. Watch the trace during each run: type:PHY_INTR0 carrying status:0x10000000 must be absent from a clean run.
If a residual error remains once alignment holds, the failure class moves downstream. Short frames point at the sensor mode the receiver expects, and errors that arrive as capture-session failures after clean frames point at recovery logic rather than the PHY — the capture-session error recovery guide covers that path.
The decision, restated: one passing capture proves the lanes can align; ten consecutive passes prove the link stays aligned. Gate every overlay and sensor-mode change on the ten-run loop.
Prevention checklist
Carry these into the next overlay and the next board:
- Compute serdes_pix_clk_hz from the measured data rate, lane count and bits per pixel — never copy it between designs; the reverse calculation is a thirty-second check against transcription errors.
- Keep serdes_pix_clk_hz larger than pix_clk_hz in every overlay you ship, and record both values in a comment so the next engineer sees the margin.
- Apply the clock pinning at boot rather than by hand after login; a stream that starts at boot needs the clocks already locked.
- Gate stream-on on the deserializer's initial deskew calibration; periodic bursts can retry a missed first pass, but the first pass still sets the link state.
- Route the deserializer-to-receiver data lanes as matched pairs and keep stubs off the lines; the intermittent mode otherwise hides routing faults that a hard failure would expose.
- Make the ten-run capture loop a release gate for every overlay and sensor-mode change.
CSI bring-up on an embedded processor collects platform-specific quirks one at a time; a CSI capture workaround reference for an image sensor on an embedded board shows how deep a single capture-path fix can run.
When to sidestep the CSI link
If the capture processor has a spare USB3 host port and the cameras sit within cable reach, a USB3 board-level camera removes the serializer, the deserializer, the deskew calibration and the overlay from the design entirely. USB3 trains its own link at enumeration, so there is no lane alignment state to lose and no calibration to wait for. The trade is reach: SerDes exists to carry multiple cameras over long, thin cable runs, while USB3 stays practical over roughly 3 m; past that, the GigE board cameras hand the link to standard Ethernet.
The board-level cameras category holds both interface families, and the camera finder filters by interface, resolution and shutter if you would rather start from the full range. Three USB3 and GigE parts cover the common compact builds:
- Sensor format
- 1/1.8"
- Lens mount
- C-mount
- Sensor format
- 1/1.8"
- Interface
- USB3
- Sensor format
- 1/1.8"
- Lens mount
- CS-mount
The LS-BCM-0003 pairs a 3.1 MP sensor, global shutter, 120 fps and a C-mount on a 1/1.8" format over USB3. The MV-CB060-10UM-B carries 6 MP mono on a bare board over USB3 for designs that have the lens and carrier planned already. The LS-BCM-0020 covers the longer-run case on the same compact footprint: a 6.3 MP rolling-shutter sensor at 18 fps over GigE, behind a CS-mount. And if the camera leaves the custom board altogether, area scan cameras with GigE or USB3 interfaces negotiate their own links the same way, leaving this failure class behind on the embedded path.
Compact cameras to build in
120 models · from $179.00Questions
Why do captures fail intermittently instead of every time?
Because the failure is a margin problem, not a broken wire. Lane skew and deskew results shift with the clock rates at stream-on, the power state of the capture blocks and the deserializer's calibration timing, so the same link passes one run and fails the next. A physical fault is different: a dead lane, a cracked trace or a misrouted pair fails every capture at the same partition. The tell is the rate: a one-in-ten pass points at configuration, a zero-for-ten record points at hardware.
What does interrupt status 0x10000000 mean in the receiver trace?
The status word is a 32-bit interrupt flag register: 0x10000000 is bit 28 set, which the receiver firmware defines as NVCSI_INTR_FLAG_CIL_INTR0_DPHY_LANE_ALIGN_ERR. Read any status value the same way: match the hex weight against the flag table, and the set bit names the condition. The phy and cil fields beside the status select which partition and lane interface unit raised it, so the same decode tells you which camera link to examine first.
Can the deserializer's periodic deskew bursts cover an incorrect serdes_pix_clk_hz?
No. Periodic deskew bursts give the receiver fresh attempts at the initial calibration, which helps when the first pass misses at stream-on. They do not change the value the receiver parsed once at initialization: serdes_pix_clk_hz tells the capture path what pixel rate the CSI bus will carry, and the path sizes its buffers from that number. A burst can retry alignment, but if the declared pixel clock sits under the real rate, the buffers overrun again on the next frame.
I disabled two of the three cameras and the failures continued — why?
Because each camera channel owns its own PHY partition on the receiver, and a mis-configured link fails alone exactly as it fails in the group. In the case behind this guide, the single enabled channel still passed only two captures in six. The partition fields in the interrupt line identify which link raised the error, so enable one channel at a time to find the failing link, then apply the pixel-clock calculation and the clock pinning to that link's overlay entry.


