System designTroubleshooting

V4L2 raw Bayer capture hangs at select: diagnose the timeout

A V4L2 raw capture hits a select() timeout when the node never agreed to your format. Read back VIDIOC_S_FMT, find the sensor's node, set the mode.

LumaSpec Vision10 min read Share on LinkedIn

On this page 11 sections
  1. 01What a first-frame select() timeout tells you
  2. 02Cause 1: VIDIOC_S_FMT accepted a different format
  3. 03Cause 2: the raw stream is on another /dev/video node
  4. 04Cause 3: the sensor mode control
  5. 05Cause 4: the link itself
  6. 06The dmesg test that separates the causes
  7. 07Worked example: IMX219 raw at 3280×2464, 20 fps
  8. 08The fix, in order
  9. 09When the usual answer is wrong
  10. 10Checks before you blame the camera
  11. 11Questions

You asked a raw sensor for SRGGB10 at 3280×2464. Every ioctl from VIDIOC_REQBUFS through VIDIOC_STREAMON returned success, and then select() sat for two seconds and returned 0, frame after frame, until the program gave up with its 'select timeout' message. v4l2-ctl does the same thing more quietly: no message, and a zero-byte output file. Your capture loop is fine. A timeout on the very first frame means no complete frame ever reached the queue, and in most cases the node you opened never agreed to produce the format you set. This guide walks the causes in order of probability, gives a test for each, and ends with the file-size check that proves the fix. Once frames flow, the capture commands are in Capture raw Bayer RG10 frames from six V4L2 cameras with v4l2-ctl.

What a first-frame select() timeout tells you

select() returning 0 is the documented timeout: the descriptor stayed unreadable for the full tv_sec = 2 your code set. At a 20 fps mode that is about 40 frame periods in which not one buffer completed. Everything below the queue worked, because open, REQBUFS, the four QBUF calls and STREAMON would each have returned an errno otherwise.

The failure sits between the sensor and the queue: frames are never generated, or they are dropped before completion. DQBUF can also fail with an internal error or a signal loss once streaming is under way, but a sensor that never starts raises no ioctl error at all. That is why your symptom is a timeout and not a return code. When frames flow for a while and then starve, the fault is different and has its own arithmetic: V4L2 DQBUF stalls after a few frames: buffer starvation math. Here the stall is at frame zero.

Cause 1: VIDIOC_S_FMT accepted a different format

VIDIOC_S_FMT is a negotiation, not an order. When the width, height and pixel format combination is not one the node's current mode outputs, most drivers rewrite the struct to a supported value and still return success. The classic capture example never reads the struct back, so you arm buffers and wait for SRGGB10 frames the node never promised. On boards whose video0 node belongs to a hardware ISP, the supported list can be YUV only, and a raw Bayer fourcc gets silently swapped. The same happens with a size the mode table lacks: 3280×2464 exists on the sensor's full mode, but a node fixed to a binned mode hands back its own geometry. Test it by printing what came back:

struct v4l2_format fmt;   /* your request, zeroed first */
int fd = open(dev_name, O_RDWR | O_NONBLOCK);

memset(&fmt, 0, sizeof(fmt));
fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
fmt.fmt.pix.width = 3280;
fmt.fmt.pix.height = 2464;
fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_SRGGB10;
fmt.fmt.pix.field = V4L2_FIELD_NONE;
if (ioctl(fd, VIDIOC_S_FMT, &fmt) < 0)
    perror("VIDIOC_S_FMT");
/* the driver may have rewritten everything: check before STREAMON */
printf("%ux%u fourcc %08x\n",
       fmt.fmt.pix.width, fmt.fmt.pix.height, fmt.fmt.pix.pixelformat);

If that line does not print 3280x2464 with the SRGGB10 fourcc, the negotiation changed your request and the timeout is explained. List what the node supports with v4l2-ctl -d /dev/video0 --list-formats, choose one advertised entry exactly — pixel format, width, height and interval together — and set that. A geometry the driver half-accepts stalls just as silently; V4L2 raw capture failing on an undersized frame height walks through one such case.

Cause 2: the raw stream is on another /dev/video node

Embedded SoCs build a pipeline: sensor, receiver, ISP, then capture nodes. /dev/video0 is frequently the ISP's output, and the sensor's unprocessed frames surface on a different device node, often video1 or higher. Your program then opens a node that streams something else entirely, which is cause 1 again, or a node whose pipeline was never routed, which streams nothing. What raw output actually is, with no ISP in the path, is covered in CSI camera with no ISP: what raw sensor output means.

The test is to print the media graph with media-ctl, follow the links from the sensor's pads, and then list formats on every /dev/videoN. The node whose list contains the raw Bayer fourcc is the raw node. The routing step is shown in media-ctl pipeline setup: fix capture node failures on embedded SoCs, and the same split seen from the other side — raw captures fine while the ISP element finds no camera — is in Sensor captures raw with v4l2-ctl but nvarguscamerasrc finds no camera.

The fix: open the raw node, and stop any ISP capture tool first. The ISP daemon holds the sensor link, and these drivers let only one of the two nodes stream at a time. For this class of sensor, a full walkthrough is in capturing raw IMX219 frames with the camera ISP driver configured.

Cause 3: the sensor mode control

Some sensor drivers expose several register modes at the same resolution, chosen by a control rather than by the format. The active mode sets the timing the CSI link carries, so requesting one mode's format while the control points elsewhere means no frame ever starts. The working recipe sets the control before streaming:

v4l2-ctl -d /dev/video0 -c sensor_mode=0 --stream-mmap --stream-count=1 --stream-skip=3 --stream-to=frame.raw

If the control is missing on video0, it lives on the subdevice node; v4l2-ctl list-ctrls returns nothing: controls live on the right node shows where to look. Frame-rate requests go the same way, because an interval the current mode cannot deliver gets re-clamped rather than refused, as V4L2 timeperframe changed but fps stuck at 30 explains.

The same signature — STREAMON succeeds, then silence — comes from a physical link that delivers nothing. Reseat a CSI ribbon and check its orientation before anything else. On USB3 and GigE industrial cameras, a damaged or unseated cable drops frames with no ioctl error, and a port renegotiated to a slower link starves the largest frames first. Swapping to a known-good spare from the camera cables range removes this whole class in minutes:

Cables3 m USB3.0 camera cable, high-flex (drag chain) (LS-CBL-0219)LS-CBL-0219$62.00View partBuild a system with it

The dmesg test that separates the causes

Clear the log, run the capture, let it time out, then read dmesg. Three patterns tell you where you are:

  • A videobuf2 warning at __vb2_queue_cancel means the queue was torn down with buffers still armed. That is the consequence of killing a stuck capture, not the cause of the stall, and it confirms the driver never produced a frame.
  • Sensor, receiver or short-frame messages point at a mode or routing mismatch; CSI camera short frame errors: match the mode to the sensor output covers that family.
  • A silent log plus the timeout points back to causes 1 and 2: a format negotiation or node mismatch fails so cleanly that the kernel has nothing to report.

Worked example: IMX219 raw at 3280×2464, 20 fps

Inputs, all from the failing set-up this page is about: sensor full mode 3280×2464 at 20/1 fps, V4L2_PIX_FMT_SRGGB10, four mmap buffers, and a select timeout of 2 s. The rule: V4L2's deep-depth Bayer formats store each sample in two bytes, so a frame is width × height × 2 bytes; the packed variant that fits four pixels into five bytes uses a different fourcc.

frame_bytes = width × height × bytes_per_sample data_rate = frame_bytes × fps timeout_window = fps × select_timeout_s

The arithmetic, carried in units:

  • Pixels per frame: 3280 × 2464 = 8,081,920 pixels
  • Bytes per frame: 8,081,920 × 2 = 16,163,840 B, about 15.4 MiB
  • Four buffers: 16,163,840 B × 4 = 64,655,360 B, about 61.7 MiB mapped
  • Data rate: 16,163,840 B × 20 = 323,276,800 B/s, about 323 MB/s
  • Timeout window: 20 fps × 2 s = 40 frame periods with zero frames delivered

The decision: memory is not the problem, since four buffers map in under 100 MiB, and a CSI or USB3 link that cannot carry 323 MB/s reports errors instead of delivering nothing for 40 frame periods. With dmesg quiet and STREAMON clean, commit to the diagnosis — the node never agreed to SRGGB10 at 3280×2464, or the raw stream lives on another node — and run the cause 1 and cause 2 tests. The proof is the file size after the fix: one frame captured with --stream-count=1 is exactly 16,163,840 bytes. A board-level walkthrough of the same sensor is in troubleshooting IMX219 capture through V4L2.

The fix, in order

  1. Note the dmesg baseline, then clear the log.
  2. List formats on every /dev/videoN with v4l2-ctl -d /dev/videoN --list-formats, and pick the node that advertises the raw Bayer fourcc.
  3. Print the media graph and confirm the sensor's pads route to that node.
  4. Set the format exactly, then check the returned struct as in cause 1.
  5. Set sensor_mode to the index that matches your format before STREAMON.
  6. Capture one frame with --stream-count=1 --stream-skip=3 and check that the file size equals width × height × 2 bytes.
What you observe Most likely cause Test that settles it
Returned format differs from the request Format negotiation, cause 1 Print the struct after VIDIOC_S_FMT
No raw fourcc on video0 at all Wrong node, cause 2 Media graph routes the sensor elsewhere
Format matches, capture still silent Mode control, cause 3 -c sensor_mode=0 before streaming
Timeout on one port or cable only Link, cause 4 Swap to a known-good cable

When the usual answer is wrong

Format, node and mode all check out and it still hangs. Four less common causes, in the order worth checking:

Checks before you blame the camera

  • The struct VIDIOC_S_FMT returned matches your request in width, height and fourcc.
  • The node was chosen from the media graph, not from the habit of typing /dev/video0.
  • sensor_mode points at a mode that lists your format and interval.
  • dmesg stays clean while the capture attempt runs.
  • One frame's file size equals width × height × 2 bytes for unpacked 10-bit raw.
  • At least three frames are skipped after STREAMON before you judge image content.
  • Every ISP capture tool is closed before you open the raw node.

None of this is specific to development boards. Industrial cameras that bind a standard driver on a Linux host appear as /dev/videoN nodes with the same ioctls, so the swap test and the file-size check work unchanged. Board-level cameras and area scan cameras both cover that path:

Board-level cameras3.1 MP USB3 board-level camera, IMX252, 1/1.8" global shutter, 120 fps (LS-BCM-0003)LS-BCM-0003
Sensor format
1/1.8"
Lens mount
C-mount
$690.00View part
Area scan cameras12 MP USB3 area scan camera, IMX226, 1/1.7" rolling shutter, 30 fps, 4000 × 3000 resolution (LS-CMR-0166)LS-CMR-0166
Sensor format
1/1.7"
Interface
USB3
$560.00View part

If the hang survives all four causes, send the dmesg output and the node's format listing through the contact page. A replacement camera starts in the camera finder or the system configurator.

Questions

Why does select() return 0 instead of an error?

Zero is the documented timeout return: the descriptor stayed unreadable for the whole wait because no buffer completed and no error was flagged. Your open used O_NONBLOCK, so an impatient DQBUF would return EAGAIN rather than block, and select is the only thing that waits. A sensor that never starts streaming raises no ioctl error on this path, which is why the timeout, not an errno, is the diagnostic you get.

How do I see the formats a node really supports?

Run v4l2-ctl -d /dev/video0 --list-formats before writing code: it enumerates every pixel format the driver accepts on that node, and the entry currently in use is marked differently from the rest. Pick one entry exactly — pixel format, width, height and frame interval together — then set it and read the struct VIDIOC_S_FMT returns. The gap between this list and your request is the whole of cause 1.

Can I run the ISP pipeline and capture raw frames at the same time?

On this class of embedded board, no. The ISP daemon claims the sensor link, and the raw node and the ISP output are separate device nodes that the driver lets only one side stream. Stop the ISP capture tool, then open the raw node. The mirror case — raw works while the ISP element reports no camera — is the same serialization seen from the other end.

How many frames should --stream-skip discard?

Three is a sound number for a first capture. The first frames after STREAMON can be dark or half-exposed while the sensor's timing settles, and any auto-exposure in the path needs a few frames to converge. At 20 fps, skipping three costs 150 ms and protects the one frame you keep. Skipping none is why a first raw file sometimes looks black rather than wrong-format.

What does the videobuf2 __vb2_queue_cancel warning mean?

It means the queue was torn down with buffers still armed — the consequence of interrupting a capture that was stuck at frame zero, not the cause of the stall. It appears in dmesg when v4l2-ctl or your own program exits through the timeout path. Treat it as confirmation that the driver never delivered a frame, and look upstream at the format, the node and the sensor mode.