PREV_LEC  |  NEXT_LEC

What You Will Learn

Prerequisites

The Five V4L2 System Calls

Unlike many kernel subsystems that expose dozens of specialised system calls, V4L2 deliberately keeps the user-facing surface tiny. Every single V4L2 operation you will ever perform — capability discovery, format negotiation, buffer allocation, streaming, control tuning — is built out of exactly five familiar POSIX calls, all defined by including <linux/videodev2.h>.

Call	Purpose	Typical Use
open()	Obtain a file descriptor for a video node	First call, once per application session
close()	Release the device and free driver-side state	Program shutdown or device switch
ioctl()	Everything else — capability, format, buffers, streaming control	Called dozens of times per session
mmap()	Zero-copy map a kernel-allocated frame buffer into the process	Used with V4L2_MEMORY_MMAP buffers
read() / write()	Blocking streaming I/O without explicit buffer management	Simple capture/output devices, rarely used for high-throughput cameras

The V4L2 ioctl() Catalog

The real complexity of the V4L2 user space API lives inside ioctl(). Every request number is defined in the same videodev2.h header, and each one is paired with a specific structure that carries data in, out, or both ways. The current mainline kernel exposes well over sixty V4L2 ioctls; the table below covers the core set you need to capture a single frame end to end — this is also exactly the group referenced by the Linux kernel documentation on V4L2 ioctls.

ioctl	Structure	What it does
VIDIOC_QUERYCAP	struct v4l2_capability	Reports driver name, card name, bus info, and supported capability bitmask
VIDIOC_ENUM_FMT	struct v4l2_fmtdesc	Lists the pixel formats the driver supports for a given buffer type
VIDIOC_G_FMT	struct v4l2_format	Reads back the currently active format
VIDIOC_TRY_FMT	struct v4l2_format	Asks “would this format be accepted?” without actually changing anything
VIDIOC_S_FMT	struct v4l2_format	Commits a new capture format; driver may adjust and return the granted values
VIDIOC_CROPCAP / VIDIOC_G_CROP / VIDIOC_S_CROP	struct v4l2_cropcap / v4l2_crop	Query and set the active cropping rectangle relative to sensor/display bounds
VIDIOC_REQBUFS	struct v4l2_requestbuffers	Requests N driver-managed buffers of a given memory type (MMAP/USERPTR/DMABUF)
VIDIOC_QUERYBUF	struct v4l2_buffer	Fetches offset/length info for a buffer so it can be mmap()‘d
VIDIOC_QBUF	struct v4l2_buffer	Hands a buffer to the driver so it can be filled (capture) or displayed (output)
VIDIOC_DQBUF	struct v4l2_buffer	Retrieves a filled/displayed buffer back from the driver; blocks unless O_NONBLOCK
VIDIOC_STREAMON / VIDIOC_STREAMOFF	enum v4l2_buf_type	Starts or stops the actual DMA/streaming engine

Capture Pipeline Workflow

Every V4L2 capture application, no matter how sophisticated, follows the same skeleton sequence. Memorising this order is more valuable than memorising any single ioctl, because the kernel will reject calls made out of sequence (for example, VIDIOC_DQBUF before VIDIOC_STREAMON returns -EINVAL).

Writing an ep_v4l2query Demo Program

To keep this lecture focused, we will write a small original program — ep_v4l2query — that exercises only the first step every real capture app needs: opening a device and querying its capability and supported formats. Later lectures in this chapter build the full buffer/streaming loop on top of this same skeleton.

/* ep_v4l2query.c
 * Original demo for EmbeddedPathashala's free Linux kernel development course.
 * Opens a V4L2 node, prints capability info, and enumerates supported formats.
 */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <fcntl.h>
#include <unistd.h>
#include <errno.h>
#include <sys/ioctl.h>
#include <linux/videodev2.h>

static int ep_xioctl(int fd, unsigned long request, void *arg)
{
    int r;
    do {
        r = ioctl(fd, request, arg);
    } while (r == -1 && errno == EINTR);
    return r;
}

int main(int argc, char **argv)
{
    const char *dev = (argc > 1) ? argv[1] : "/dev/video0";
    struct v4l2_capability cap;
    struct v4l2_fmtdesc fmt;
    int fd;

    fd = open(dev, O_RDWR);
    if (fd < 0) {
        perror("ep_v4l2query: open");
        return 1;
    }

    if (ep_xioctl(fd, VIDIOC_QUERYCAP, &cap) == -1) {
        perror("ep_v4l2query: VIDIOC_QUERYCAP");
        close(fd);
        return 1;
    }

    printf("Driver     : %s\n", cap.driver);
    printf("Card       : %s\n", cap.card);
    printf("Bus info   : %s\n", cap.bus_info);

    if (!(cap.device_caps & V4L2_CAP_VIDEO_CAPTURE)) {
        fprintf(stderr, "%s is not a video capture device\n", dev);
        close(fd);
        return 1;
    }

    printf("\nSupported pixel formats:\n");
    memset(&fmt, 0, sizeof(fmt));
    fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    while (ep_xioctl(fd, VIDIOC_ENUM_FMT, &fmt) == 0) {
        printf("  [%d] %-8s  %s\n", fmt.index,
               (char *)&fmt.pixelformat, fmt.description);
        fmt.index++;
    }

    close(fd);
    return 0;
}

Build and Run

gcc -Wall -o ep_v4l2query ep_v4l2query.c
./ep_v4l2query /dev/video0

Expected Output

Driver     : uvcvideo
Card       : HD USB Camera
Bus info   : usb-0000:00:14.0-3

Supported pixel formats:
  [0] YUYV      YUYV 4:2:2
  [1] MJPG      Motion-JPEG
  [2] H264      H.264

Common Mistakes & Troubleshooting

Symptom	Likely Cause	Fix
VIDIOC_QUERYCAP fails with ENOTTY	Node opened is not a V4L2 device (wrong /dev entry)	Verify with v4l2-ctl --list-devices before opening
VIDIOC_S_FMT silently changes your resolution	Driver does not support the exact size/format requested	Always re-read the struct after S_FMT and use the granted values, or call TRY_FMT first
VIDIOC_DQBUF blocks forever	VIDIOC_STREAMON was never called, or no buffer was queued	Confirm every requested buffer was QBUF‘d before STREAMON
mmap() returns MAP_FAILED	Called before VIDIOC_QUERYBUF, or wrong length/offset used	Always use the length/m.offset filled by QUERYBUF, never guess values
Interrupted system call errors	A signal handler interrupted a blocking ioctl()/read()	Wrap calls in an EINTR retry loop, as shown in ep_xioctl() above

Best Practices

Interview Questions

Why does V4L2 need only five system calls when it supports so many device types?

Because almost all device-specific behaviour is pushed into the ioctl() argument structures rather than into new system calls. This keeps the kernel-user ABI stable and small while still allowing drivers to expose radically different capabilities (capture, output, sensors, touch) through the same five entry points.

What is the difference between VIDIOC_TRY_FMT and VIDIOC_S_FMT?

TRY_FMT only validates a format against the driver without changing device state — safe to call anytime, including while streaming. S_FMT actually commits the format and can fail or be rejected if buffers are already allocated or streaming is active.

Why must VIDIOC_QBUF be called for every buffer before VIDIOC_STREAMON?

STREAMON only starts the driver’s DMA engine; it does not implicitly queue anything. If no buffers are queued, the driver has nowhere to write incoming frames, so the first DQBUF would either block indefinitely or fail.

Summary and Key Takeaways

This lecture is the foundation for the rest of this chapter in EmbeddedPathashala’s free Linux kernel development course. In the next lecture we extend ep_v4l2query into a full buffer-management and streaming program, wiring together REQBUFS, mmap(), and the QBUF/DQBUF loop to actually pull live frames off a camera.

Frequently Asked Questions

What is the V4L2 user space API used for?

It is the standard Linux interface applications use to discover, configure, and capture from video devices — webcams, capture cards, and embedded camera sensors — without needing driver-specific code.

Do I need root permission to use V4L2 ioctls?

No, as long as your user account has read/write permission on the /dev/videoX node, typically granted via the video group.

Can I use the V4L2 API without mmap, just with read()?

Yes, if the driver advertises V4L2_CAP_READWRITE, but most modern USB and embedded camera drivers only support the mmap/streaming path for performance reasons.

How many buffers should I request with VIDIOC_REQBUFS?

Three or four is a common starting point; enough to keep the pipeline from stalling while still bounding memory use. The driver may return fewer or more than requested.

What does VIDIOC_QUERYCAP actually tell me?

It reports the driver name, the card/device name, bus information, and a capability bitmask describing whether the device supports capture, output, streaming, and read/write I/O.

Is this V4L2 API the same one GStreamer and FFmpeg use internally?

Yes. Frameworks like GStreamer’s v4l2src and FFmpeg’s v4l2 input device are thin wrappers around exactly this ioctl sequence.

Where can I practise this without a physical camera?

Load the v4l2loopback kernel module to create a virtual /dev/videoX node you can feed test frames into and query exactly like real hardware.

Is this part of a free Linux device drivers course?

Yes, this lecture is part of EmbeddedPathashala’s free Linux kernel development course, which also covers writing the V4L2 driver side of this same API in earlier chapters.

PREV_LEC  |  NEXT_LEC