Capturing Frames With v4l2-ctl

v4l2-ctl exposes its streaming options grouped by topic — run --help-streaming or --help-vidcap to see everything available. To capture a single compressed MJPEG frame at QVGA resolution:

$ v4l2-ctl --set-fmt-video=width=320,height=240,pixelformat=MJPG \
           --stream-mmap --stream-count=1 --stream-to=ep_grab.mjpg

And to capture the same resolution as raw YUYV instead:

$ v4l2-ctl --set-fmt-video=width=320,height=240,pixelformat=YUYV \
           --stream-mmap --stream-count=1 --stream-to=ep_grab_yuyv.raw

Comparing the two file sizes makes the compression ratio obvious immediately:

$ ls -lh ep_grab.mjpg ep_grab_yuyv.raw
-rw-r--r-- 1 user user  9.4K ep_grab.mjpg
-rw-r--r-- 1 user user  150K ep_grab_yuyv.raw

It is good practice to always encode the pixel format in a raw capture’s filename (as above, _yuyv) — a raw buffer has no header describing its own contents, so without a naming convention you will not remember how to interpret it later.

Converting And Identifying Captured Frames

Compressed formats like MJPEG carry their own header, so a generic media-type prober can identify them instantly. GStreamer’s gst-typefind-1.0 is a convenient way to confirm what you actually captured:

$ gst-typefind-1.0 ep_grab.mjpg
ep_grab.mjpg - image/jpeg, width=(int)320, height=(int)240, sof-marker=(int)0

$ gst-typefind-1.0 ep_grab_yuyv.raw
ep_grab_yuyv.raw - FAILED: Could not determine type of stream.

The raw YUYV capture fails type detection because it is headerless — you must tell the decoder the format explicitly. ffmpeg handles this with the -f rawvideo input demuxer:

$ ffmpeg -f rawvideo -pix_fmt yuyv422 -s 320x240 \
         -i ep_grab_yuyv.raw ep_grab.png

This produces a standard viewable PNG from a buffer that, on its own, is nothing more than an undifferentiated block of bytes to any general-purpose image tool.

Debugging V4L2 From User Space

When a capture pipeline misbehaves — frames never arrive, streaming hangs, or formats silently mismatch — V4L2 provides two independent kernel-side trace switches you can flip from user space without recompiling anything.

Core videobuf2 tracing is controlled per module through sysfs:

$ echo 0x3 | sudo tee /sys/module/videobuf2_v4l2/parameters/debug
$ echo 0x3 | sudo tee /sys/module/videobuf2_common/parameters/debug

With this enabled, every buffer allocation and queue/dequeue transition inside the vb2 core is logged:

$ dmesg | tail
[  912.104221] videobuf2_common: __setup_offsets: buffer 0, plane 0 offset 0x00000000
[  912.104309] videobuf2_common: __vb2_queue_alloc: allocated 4 buffers, 1 plane(s) each
[  912.104382] videobuf2_common: vb2_mmap: buffer 0, plane 0 successfully mapped
[  912.104417] videobuf2_common: vb2_core_qbuf: qbuf of buffer 0 succeeded

Per-device ioctl tracing is controlled through a debug node under each video device’s own sysfs entry:

$ echo 0x3 | sudo tee /sys/class/video4linux/video0/dev_debug

This logs every V4L2 ioctl the device receives, including the actual arguments — extremely useful for confirming exactly what format or control value a user-space application requested:

$ dmesg | tail
[  944.552140] video0: VIDIOC_QUERYCAP: driver=uvcvideo, card=USB HD Camera, version=0x06080000
[  944.552198] video0: VIDIOC_S_FMT: type=vid-cap, width=1280, height=720, pixelformat=MJPG
[  944.553310] video0: VIDIOC_STREAMON: type=vid-cap

Comparison Table: Capture And Debug Options

Tool / Switch	Purpose	Where It Applies
–stream-mmap –stream-to	Capture N frames to disk	v4l2-ctl, user space
gst-typefind-1.0	Identify a compressed file’s container format	Any captured file
ffmpeg -f rawvideo	Decode a headerless raw capture into a viewable image	Raw YUYV/other captures
videobuf2_*/parameters/debug	Trace buffer queue state machine	Kernel vb2 core, all devices
video4linux/videoX/dev_debug	Trace ioctl calls and arguments	Kernel V4L2 core, one device

Demo: Capture With Live Kernel Tracing

This original walkthrough, ep_v4l2_capture_debug.sh, ties everything together: it enables both debug switches, captures one MJPEG frame, and prints the matching kernel trace lines.

#!/bin/sh
# ep_v4l2_capture_debug.sh — EmbeddedPathashala streaming + debug demo
set -e

DEV=${1:-/dev/video0}

echo "[ep] enabling videobuf2 core tracing..."
echo 0x3 | sudo tee /sys/module/videobuf2_v4l2/parameters/debug   > /dev/null
echo 0x3 | sudo tee /sys/module/videobuf2_common/parameters/debug > /dev/null

echo "[ep] enabling per-device ioctl tracing on ${DEV}..."
NODE=$(basename "$DEV")
echo 0x3 | sudo tee /sys/class/video4linux/"$NODE"/dev_debug > /dev/null

echo "[ep] capturing one MJPEG frame..."
v4l2-ctl -d "$DEV" \
  --set-fmt-video=width=1280,height=720,pixelformat=MJPG \
  --stream-mmap --stream-count=1 --stream-to=ep_grab.mjpg

echo "[ep] captured file:"
ls -lh ep_grab.mjpg

echo "[ep] matching kernel trace:"
dmesg | tail -n 8

Run it:

$ chmod +x ep_v4l2_capture_debug.sh
$ ./ep_v4l2_capture_debug.sh /dev/video0

Expected output:

[ep] enabling videobuf2 core tracing...
[ep] enabling per-device ioctl tracing on /dev/video0...
[ep] capturing one MJPEG frame...
< 1 frames captured >
[ep] captured file:
-rw-r--r-- 1 user user 41K ep_grab.mjpg
[ep] matching kernel trace:
[  978.201004] video0: VIDIOC_S_FMT: type=vid-cap, width=1280, height=720, pixelformat=MJPG
[  978.201980] video0: VIDIOC_REQBUFS: count=4, memory=mmap
[  978.202144] videobuf2_common: __vb2_queue_alloc: allocated 4 buffers, 1 plane(s) each
[  978.202390] video0: VIDIOC_STREAMON: type=vid-cap
[  978.235710] videobuf2_common: vb2_core_qbuf: qbuf of buffer 0 succeeded
[  978.269812] video0: VIDIOC_DQBUF: index=0, bytesused=41932
[  978.269920] video0: VIDIOC_STREAMOFF: type=vid-cap

Real-World Use Cases

Kernel and BSP engineers reach for V4L2 streaming capture debugging whenever a newly ported sensor driver captures corrupted frames, times out on VIDIOC_DQBUF, or silently drops resolution changes — the dev_debug ioctl trace usually reveals within seconds whether user space sent the wrong format or the driver rejected a valid one. Camera manufacturers use scripted v4l2-ctl --stream-to captures as an automated regression test in continuous integration, comparing output file sizes and gst-typefind results run over run to catch driver regressions before they reach production firmware.

Common Mistakes And Troubleshooting

Best Practices

Capture a small number of frames with --stream-count first when validating a new configuration — there is no reason to stream continuously just to confirm a format works. Always pair a raw capture’s filename with its pixel format and resolution, and prefer scripting the debug-enable / capture / debug-disable sequence together (as in the demo above) so tracing never accidentally stays on.

Performance Considerations

Both videobuf2 debug tracing and per-device dev_debug tracing add a printk() call on the kernel’s hot path for every buffer and ioctl — acceptable for a handful of test frames, but a measurable throughput hit at 60+ fps. Never ship debug tracing enabled in a production image.

Security Considerations

dmesg output containing full ioctl arguments can, in principle, expose format and control details about a camera pipeline to any local user who can read the kernel ring buffer — restrict dmesg read access (kernel.dmesg_restrict) on multi-user embedded systems if this is a concern.

Summary And Key Takeaways

V4L2 streaming capture with v4l2-ctl lets you pull raw or compressed frames to disk without writing code, gst-typefind-1.0 and ffmpeg help you identify and convert what you captured, and the two independent kernel debug switches — videobuf2 module parameters and per-device dev_debug — give you a full ioctl-level and buffer-level trace in dmesg whenever a capture pipeline needs troubleshooting.

Conclusion

You can now capture, convert, and debug V4L2 video end-to-end from the command line. The final lecture in this mini-series covers how to validate that a driver is fully V4L2-compliant using the v4l2-compliance tool — essential reading before submitting any new camera driver upstream.

Frequently Asked Questions

How do I capture a single frame with v4l2-ctl?

Use v4l2-ctl –stream-mmap –stream-count=1 –stream-to=filename, combined with –set-fmt-video to choose the resolution and pixel format first.

Why can’t I open my raw V4L2 capture in an image viewer?

A raw capture has no header describing its format, so generic image viewers cannot detect its dimensions or pixel layout; use ffmpeg with -f rawvideo and explicit -s and -pix_fmt flags to convert it.

How do I enable V4L2 kernel debug tracing?

Write 0x3 to /sys/module/videobuf2_v4l2/parameters/debug and /sys/module/videobuf2_common/parameters/debug for core tracing, and to /sys/class/video4linux/videoX/dev_debug for per-device ioctl tracing, then read the output with dmesg.

What does dev_debug actually trace?

It logs every V4L2 ioctl call made against that specific device node, including the arguments passed, directly into the kernel log.

Is it safe to leave V4L2 debug tracing enabled permanently?

No, it adds logging overhead on every buffer and ioctl operation and can flood dmesg at high frame rates; disable it by writing 0x0 back to the same sysfs files once debugging is finished.

What is the difference between gst-typefind-1.0 and ffmpeg for this?

gst-typefind-1.0 only identifies what format a self-describing file already is, while ffmpeg can both identify and actively decode or convert a file, including headerless raw captures when you supply the format manually.