CSI camera RGB565 half image flicker: RXFIFO size per pixel

You moved an embedded camera link from packed YUV to RGB565 so the frames could feed an RGB565 panel without a software conversion, and the stream came up broken: only half the image, flickering between the top and bottom halves about once per frame. The sensor is fine. A length in the capture path — the CSI receiver's RXFIFO count, a DMA buffer size, the driver's sizeimage — is still computed for the previous format. This guide gives the byte arithmetic that sets every one of those lengths, the tests that isolate the stale value in minutes, the confirmed fix, and the alternatives when you would rather not maintain a sensor-module driver at all.

The signature: a clean half frame that alternates

The picture toggles between the top half and the bottom half of the scene, each half internally correct, at roughly the frame rate — sometimes twice per frame, set by where the display refresh lands. No error is raised. That combination is diagnostic, not random.

The receive DMA writes pixels sequentially and moves to the next buffer when the programmed byte count is reached. When that count is half the frame, the chain consumes two buffers per frame: the first holds rows 0 to 239, the second rows 240 to 479. Whichever buffer the display grabs next alternates frame to frame, so you see both halves in succession. No bytes were lost; they were cut at the wrong boundary. This is a different fault from a camera that delivers half the expected frame rate — there the rate halves, here the geometry does.

Measure the boundary row: boundary_row = buffer_bytes ÷ bytesperline. At VGA RGB565 a stale length puts the boundary after row 240, exactly half of 480; the arithmetic is below.

Bytes per pixel set every length in the pipeline

One quantity decides the RXFIFO length, the DMA byte counts and sizeimage: the bytes per pixel (bpp) of the format actually streaming. RGB565 packs a pixel into 16 bits — 5 red, 6 green, 5 blue — and the parallel bus carries it as two 8-bit beats per pixel. The media bus code says so: MEDIA_BUS_FMT_RGB565_2X8_LE, two 8-bit transfers, low byte first. Byte order matters when you assemble those beats, the subject of building an RGB565 image converter for microcontroller TFT displays.

YUYV packs two pixels into 4 bytes — also 2 bytes per pixel — so the YUYV-to-RGB565 switch leaves sizeimage unchanged. What broke in the real case was a separately programmed RXFIFO length that had matched the old set-up and did not follow the format change. The format table's bpp entry is only the first of the places a format appears; after any change, re-derive every byte count. The same trap bites host-side code: why your 16-bit image buffer has half the expected pixels and Mono16 buffers with half the elements are the same arithmetic failing at the consumer.

Worked example: VGA RGB565, full arithmetic

With width = 640 px, height = 480 px and bpp = 2 B:

• bytesperline = 640 × 2 = 1,280 B
• sizeimage = 1,280 × 480 = 614,400 B (600 KiB)
• RXFIFO length = 640 × 480 × 2 = 614,400 B; if the receiver counts 8-byte words, that is 614,400 ÷ 8 = 76,800 words
• The stale value, computed at 1 B per pixel: 640 × 480 × 1 = 307,200 B, which is 307,200 ÷ 1,280 = 240 lines — rows 0 to 239 per buffer, the observed top half

Bandwidth check: 614,400 B × 30 fps = 18,432,000 B/s, about 18.4 MB/s. Memory is not the constraint here; the correctness of the boundary is.

Causes in order of probability

Cause 1 carries this exact symptom, and there is a one-minute probe for it: set the capture height to 240. Then 640 × 240 × 2 = 307,200 B — precisely the stale length — and if the full smaller image appears with nothing else touched, the length is your culprit.

Cause 3 deserves a line. The CSI set-up code branches on pixelformat to decide whether the width register takes pixels or bytes, and the new fourcc must sit in the case group with V4L2_PIX_FMT_YUV32 and V4L2_PIX_FMT_SBGGR8 so width is programmed in pixels. A format that falls through counts double bytes per line and shears the image. The short-frame cousins of this fault are covered in CSI camera short frame errors: match the mode to the sensor output and CSI short frames in binning mode.

Cause 4: the sensor side has to move too, writing the output-path registers that switch the module from packed YUV to RGB565 — the exact values and what happens if you skip them are in the fix steps and the notes below.

Cause 5 is the display end. The overlay input format changed from IPU_PIX_FMT_UYVY to IPU_PIX_FMT_RGB565 in the same change; leaving it gives a complete but wrongly decoded picture, the display-side mismatch also seen in fixing grayscale display over composite video.

The fix, step by step

1. Take bpp from the driver's format table: 2 for RGB565.
2. Set bytesperline = width × bpp and sizeimage = bytesperline × height, both reading their bpp from the table entry, so the next format change cannot leave them stale.
3. Set the RXFIFO length — the per-frame byte count the receiver is programmed for — to width × height × bpp. In the integration that motivated this guide, that single edit restored full frames.
4. Add the new fourcc to every switch that branches on pixelformat, above all the width-programming path.
5. Move the sensor to RGB565 output: 0x4300 = 0x6f and 0x501f = 0x01, as the working change has them.
6. Point the display overlay at IPU_PIX_FMT_RGB565.
7. Restart the stream, read the format back, and dump one frame for the checks below.

Format changes that stall or halve elsewhere usually trace to linked attributes rather than the capture length — when changing pixel format halves your frame rate works that list.

Confirm it, then make it stay fixed

• Byte count: one captured frame occupies exactly 614,400 B at VGA.
• Content: checksum the top 240 rows and the bottom 240 rows separately; they must differ. A repeated half fails this test.
• Stability: run a soak capture. If sporadic timeouts appear days later, suspect the ribbon and signal integrity before the driver — the pattern in CSI camera timeout after a working period.
• Load: the software conversion task disappears from CPU load once the panel is fed RGB565 directly.

Three ways out when you would rather not patch drivers

Let the sensor do it — the path fixed above. RGB565 straight from the module, panel fed from the capture buffer, zero conversion work. Choose this when the panel is the only consumer. When another consumer wants YUV, keep capture as YUYV and convert in the blit instead.

Convert in hardware during the blit. SoCs of this class carry a pixel-processing block that turns YUV into RGB while copying to the framebuffer. Capture lengths stay as they were and the CPU stays idle. A third capture route — streaming compressed frames from the sensor — is covered in a JPEG-over-CSI workaround reference for a closely related SoC.

Replace the module with a standard camera. A USB3 or GigE area scan camera negotiates its pixel format over the transport and sizes its own buffers, so a format change becomes a setting, not a patch. You also gain C-mount optics, strobe triggering and cable lengths a ribbon cannot reach — the same output path discussed in displaying a camera image on a VGA output from a vision controller.

Match camera pixels to the panel before ordering: a 640 × 480 panel needs at least 640 × 480 pixels, more if you want headroom for zoom or detail:

Two cameras cover the ends of that range — the MV-CU020-90GC, a 2.5 MP GigE camera with a 1/1.7" sensor, C-mount and global shutter, and the LS-CMR-0166, a 12 MP USB3 camera with a 1/1.7" sensor:

On the host side, terminate USB3 cameras on a quad-port USB3 adaptor and GigE cameras on a dual-port PoE NIC:

All 2 share: Interconnect PCI-E gen2 × 4; Humidity 10% RH to 95% RH (no condensation). Values as printed in each product's data sheet; open a part for its drawing and full specifications.

Cable it with a drag-chain-rated USB3.0 lead such as the 3 m LS-CBL-0219, or browse the camera cables for GigE screw-lock equivalents:

The decision, case by case:

• Staying embedded with one panel within ribbon reach — nothing beats the repaired CSI link for weight and parts count.
• Other consumers need YUV — keep YUYV capture and convert in the blit block.
• More than one camera, real optics, strobe sync, or a run past a few meters — a standard camera from the area scan cameras range, picked through the camera finder or the configurator's camera step, on a host card from frame grabbers.

If the embedded side stays and you want the camera end sized for you, contact us with the panel spec.

Checklist for any capture-format change

Before:

• Compute bytesperline and sizeimage for the new format, arithmetic written down.
• List every place the format appears: the format table entry (fourcc, media bus code, bpp), each pixelformat switch, the RXFIFO length, the sensor output registers, the display overlay format.
• Note the old values so you can diff the readbacks.

During:

• Derive each length from the table's bpp; retire every hardcoded byte count you find.
• Read the format back; sizeimage must equal your number. The readback trap in color image buffers with no size info teaches the same lesson.

After:

• One-frame dump: byte count plus separate checksums of the top and bottom halves.
• Soak run; treat new timeouts as signal integrity first.
• Confirm the software conversion task is gone from CPU load.

Related capture-pipeline fixes are collected on the systems topic page.