What You Will Learn

Prerequisites

Why Frame Rate Negotiation Is a Separate Step

A camera sensor is not a single fixed-speed device. The same sensor mode that produces a 1920×1080 frame at 30 frames per second can often also run at 15 fps with lower bandwidth, or the driver may refuse to change the rate at all and simply report back whatever it is capable of. Because of this, V4L2 treats frame timing as a negotiation, not a command: the application proposes a rate, and the driver is free to grant it, coerce it to the nearest supported value, or ignore the request entirely on hardware that cannot vary its frame interval. This negotiation happens through the VIDIOC_G_PARM and VIDIOC_S_PARM ioctls, both of which operate on the same struct v4l2_streamparm used for both capture and output devices.

struct v4l2_streamparm and struct v4l2_captureparm

v4l2_streamparm is a union-style structure, exactly like v4l2_format from the previous lecture — its active member depends on the buffer type you set. For a capture device you fill in parm.capture, of type struct v4l2_captureparm. The two fields that matter for frame rate work are:

• capability — a bitmask the driver fills in on VIDIOC_G_PARM. If the V4L2_CAP_TIMEPERFRAME bit is set, the driver supports changing the frame interval through VIDIOC_S_PARM. If it is clear, don’t bother calling VIDIOC_S_PARM — the driver will just reject or ignore it
• timeperframe — a struct v4l2_fract with numerator/denominator fields expressing the interval between frames. A 30 fps stream is expressed as numerator = 1, denominator = 30, not as a plain integer — this lets V4L2 represent non-integer rates like 29.97 fps cleanly

On the latest stable kernel, this API surface has not changed structurally, but most modern sensor drivers built on the V4L2 subdev framework now also expose frame interval selection through VIDIOC_SUBDEV_S_FRAME_INTERVAL at the subdevice level and VIDIOC_ENUM_FRAMEINTERVALS at the video-node level, letting an application discover exactly which discrete or stepwise rates a given resolution supports before ever calling VIDIOC_S_PARM. We will cover frame interval enumeration in a later lecture of this free linux device drivers course; for now, VIDIOC_S_PARM remains the correct call to actually apply the rate.

Requesting a Frame Rate — Modern Example

Below is an original demo, ep_v4l2_parmbuf, rewritten against the current V4L2 headers. It first queries the current parameters, checks the capability bit, then requests 30 fps and reports whether the driver honoured it.

#include <stdio.h>
#include <errno.h>
#include <sys/ioctl.h>
#include <linux/videodev2.h>

#define EP_TARGET_FPS 30

int ep_set_frame_rate(int fd)
{
    struct v4l2_streamparm parm = {0};
    parm.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

    /* Step 1: find out if the driver supports variable frame rate */
    if (ioctl(fd, VIDIOC_G_PARM, &parm) == -1) {
        perror("VIDIOC_G_PARM");
        return -1;
    }

    if (!(parm.parm.capture.capability & V4L2_CAP_TIMEPERFRAME)) {
        fprintf(stderr, "ep_v4l2_parmbuf: driver has a fixed frame rate\n");
        return 0; /* not fatal, just nothing to negotiate */
    }

    /* Step 2: request the target frame rate */
    memset(&parm, 0, sizeof(parm));
    parm.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    parm.parm.capture.timeperframe.numerator   = 1;
    parm.parm.capture.timeperframe.denominator = EP_TARGET_FPS;

    if (ioctl(fd, VIDIOC_S_PARM, &parm) == -1) {
        perror("VIDIOC_S_PARM");
        return -1;
    }

    /* Step 3: the driver may have coerced our request */
    if (parm.parm.capture.timeperframe.denominator != EP_TARGET_FPS) {
        printf("ep_v4l2_parmbuf: fps coerced from %d to %d\n",
               EP_TARGET_FPS, parm.parm.capture.timeperframe.denominator);
    } else {
        printf("ep_v4l2_parmbuf: frame rate set to %d fps\n", EP_TARGET_FPS);
    }

    return 0;
}

Expected output on a UVC webcam that supports the request:

$ ./ep_v4l2_parmbuf /dev/video0
ep_v4l2_parmbuf: frame rate set to 30 fps

On hardware that can only run at 25 fps for the current resolution, you would instead see:

$ ./ep_v4l2_parmbuf /dev/video0
ep_v4l2_parmbuf: fps coerced from 30 to 25

VIDIOC_REQBUFS — Requesting Video Buffers

Once the format and frame rate are settled, the driver still owns no memory for actual video data. Video capture is a high-bandwidth job, so V4L2 never copies frame data through a single ioctl the way VIDIOC_G_FMT passes structure fields. Instead it uses a streaming I/O model: a pool of buffers is allocated once, then repeatedly handed back and forth between the application and the driver as frames are captured. The first step of setting up that pool is VIDIOC_REQBUFS, which takes a fresh struct v4l2_requestbuffers.

struct v4l2_requestbuffers Fields

Discovering Supported I/O Methods — Old Way vs Modern Way

Older driver code had no clean way to ask “which streaming methods does this driver support” — the only option was to call VIDIOC_REQBUFS once per memory type and see which calls succeeded or failed with EINVAL, then undo any buffers that were accidentally allocated in the process. Current kernels avoid this entirely: a single VIDIOC_REQBUFS call with count set to 0 allocates nothing but still returns the capabilities bitmask, letting an application query support cleanly before committing to a real allocation.

Requesting User Pointer Buffers

Below, our original demo ep_v4l2_reqbufs requests four V4L2_MEMORY_USERPTR buffers and checks the granted count:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <sys/ioctl.h>
#include <linux/videodev2.h>

#define EP_BUF_COUNT 4

int ep_request_userptr_buffers(int fd, unsigned int *granted_count)
{
    struct v4l2_requestbuffers req = {0};

    req.count  = EP_BUF_COUNT;
    req.type   = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    req.memory = V4L2_MEMORY_USERPTR;

    if (ioctl(fd, VIDIOC_REQBUFS, &req) == -1) {
        if (errno == EINVAL) {
            fprintf(stderr,
                "ep_v4l2_reqbufs: driver does not support user pointer I/O\n");
        } else {
            perror("VIDIOC_REQBUFS");
        }
        return -1;
    }

    if (req.count < 2) {
        fprintf(stderr,
            "ep_v4l2_reqbufs: insufficient buffer memory (got %u)\n", req.count);
        return -1;
    }

    printf("ep_v4l2_reqbufs: driver granted %u of %u requested buffers\n",
           req.count, EP_BUF_COUNT);

    *granted_count = req.count;
    return 0;
}

With user pointer I/O selected, the kernel does not allocate the buffer memory itself — the application must. Here is the matching allocation step:

struct ep_buffer {
    void   *start;
    size_t  length;
};

struct ep_buffer *ep_allocate_userptr_buffers(unsigned int count, size_t buf_size)
{
    struct ep_buffer *buffers = calloc(count, sizeof(*buffers));
    unsigned int i;

    if (!buffers) {
        fprintf(stderr, "ep_v4l2_reqbufs: out of memory\n");
        return NULL;
    }

    for (i = 0; i < count; ++i) {
        buffers[i].length = buf_size;
        buffers[i].start  = aligned_alloc(4096, buf_size);

        if (!buffers[i].start) {
            fprintf(stderr, "ep_v4l2_reqbufs: allocation failed for buffer %u\n", i);
            free(buffers);
            return NULL;
        }
    }

    return buffers;
}

Expected output:

$ ./ep_v4l2_reqbufs /dev/video0
ep_v4l2_reqbufs: driver granted 4 of 4 requested buffers

Notice the switch from plain malloc() in old reference code to aligned_alloc(4096, buf_size) here. On current kernels, user-pointer buffers handed to a DMA-capable capture driver generally need to be page-aligned so the kernel can pin the correct set of pages for DMA; unaligned buffers are a frequent cause of VIDIOC_QBUF failures we will cover in the next lecture when we enqueue these buffers for capture.

Real-World Use Cases

Frame rate negotiation matters most in bandwidth-constrained pipelines — a USB 2.0 webcam streaming uncompressed YUYV at high resolution simply cannot sustain 60 fps, so applications like video conferencing software query V4L2_CAP_TIMEPERFRAME and fall back gracefully. User-pointer buffer allocation shows up in embedded vision pipelines where frames need to land in a specific pre-registered memory region — for example, a buffer that a downstream image signal processor or a GStreamer element has already reserved — rather than wherever the kernel driver happens to allocate memory internally.

Common Mistakes and Troubleshooting

Best Practices, Performance and Security Considerations

Interview Questions

Summary and Key Takeaways

Frequently Asked Questions