• How VIDIOC_QUERYBUF turns a requested buffer into a physical offset
• How mmap() maps that offset into your process address space
• What DMABUF exporter/importer really means between two devices
• How VIDIOC_EXPBUF hands out a DMABUF file descriptor
• Why read/write I/O needs no ioctl at all for buffer setup
• A full working demo you can build and run on a real V4L2 node

This lecture assumes you have already gone through VIDIOC_REQBUFS and the memory model comparison from the previous lecture in this free linux kernel development course. You should be comfortable with basic V4L2 concepts (capture devices, buffer queues, ioctl-based device control) and standard POSIX mmap(). A Linux machine with a V4L2 capture device (a UVC webcam works fine) and kernel headers installed is enough to follow along and build the demo yourself.

When your application calls VIDIOC_REQBUFS with memory = V4L2_MEMORY_MMAP, the driver allocates a set of physically contiguous (or scatter-gather, depending on the DMA engine) buffers inside kernel space. At that point your application knows nothing except how many buffers it got back in req.count. It has no pointer, no address, nothing it can read pixel data from yet. Two more steps are needed before any capture loop can begin: discovering where each buffer lives (VIDIOC_QUERYBUF) and mapping that location into user space (mmap()). This two-step handshake is exactly what the V4L2 core requires for every MMAP buffer, and getting it right is the single most common source of bugs in first-time V4L2 capture applications.

VIDIOC_QUERYBUF is the ioctl that turns a plain buffer index into something you can actually map. You fill in type, memory, and index in a struct v4l2_buffer, and the kernel fills the rest — most importantly length (the buffer size in bytes) and, for the MMAP case, m.offset (a fake file offset that the mmap() call below uses to identify which kernel buffer to map). This offset is not a real memory address; it is a token the V4L2 core uses internally to route the mmap() request to the correct buffer.

struct v4l2_buffer v4l2_buf;
memset(&v4l2_buf, 0, sizeof(v4l2_buf));

v4l2_buf.type   = V4L2_BUF_TYPE_VIDEO_CAPTURE;
v4l2_buf.memory = V4L2_MEMORY_MMAP;
v4l2_buf.index  = buf_index;

if (ioctl(fd, VIDIOC_QUERYBUF, &v4l2_buf) == -1) {
    perror("VIDIOC_QUERYBUF");
    exit(EXIT_FAILURE);
}

/* v4l2_buf.length      -> size of this buffer in bytes   */
/* v4l2_buf.m.offset    -> token to pass into mmap()      */

Once you have length and m.offset, the actual mapping is a single standard POSIX call:

void *start = mmap(NULL,                    /* let kernel pick address   */
                    v4l2_buf.length,          /* map exactly this many bytes */
                    PROT_READ | PROT_WRITE,   /* app reads and writes buffer */
                    MAP_SHARED,               /* changes visible to driver  */
                    fd,                        /* the video device fd       */
                    v4l2_buf.m.offset);        /* offset from QUERYBUF      */

if (start == MAP_FAILED) {
    perror("mmap");
    exit(EXIT_FAILURE);
}

MAP_SHARED is not optional here. With MAP_PRIVATE the kernel would give you a copy-on-write mapping, so writes (and the driver’s own DMA fills) would never be seen consistently on both sides. MAP_SHARED guarantees that when the driver’s DMA engine writes a captured frame into the buffer, your process sees that exact memory without any extra copy — this zero-copy behaviour is the entire reason MMAP I/O exists.

MMAP and USERPTR both describe buffers that live inside one device’s driver. DMABUF exists to solve a different problem: sharing one buffer between two different devices without ever copying the pixel data between them. This matters enormously on modern SoCs where a camera sensor driver, an image signal processor (ISP), a hardware scaler, and a display or encoder may all need to touch the same frame in sequence. Copying a 4K frame at each stage would burn memory bandwidth and add latency; DMABUF lets every stage operate on the same physical memory.

The Linux DMA-BUF framework defines two roles:

• Exporter — the driver that originally allocated the buffer and hands out a file descriptor referencing it
• Importer — any other driver (or subsystem) that receives that file descriptor and attaches to the same underlying memory

In V4L2 terms: you first allocate buffers on the exporting device using VIDIOC_REQBUFS with memory = V4L2_MEMORY_MMAP (MMAP is the only memory type from which buffers can be exported). You then call VIDIOC_EXPBUF once per buffer index to get back a DMABUF file descriptor. That fd can now be handed to a completely different V4L2 node — for example an output/m2m device — by queuing it there with memory = V4L2_MEMORY_DMABUF and placing the fd in v4l2_buffer.m.fd.

struct v4l2_exportbuffer expbuf;
memset(&expbuf, 0, sizeof(expbuf));

expbuf.type  = V4L2_BUF_TYPE_VIDEO_CAPTURE;
expbuf.index = buf_index;
expbuf.flags = O_RDWR;   /* import/export permission on the returned fd */

if (ioctl(fd, VIDIOC_EXPBUF, &expbuf) == -1) {
    perror("VIDIOC_EXPBUF");
    exit(EXIT_FAILURE);
}

int dmabuf_fd = expbuf.fd;   /* pass this fd to the importer device */

One important detail that trips people up: exporting a buffer with VIDIOC_EXPBUF and then immediately mapping that same fd on the very same capture device is pointless — you already have direct mmap() access to those buffers on the exporting device, as shown in the previous section. DMABUF earns its keep specifically when the buffer needs to travel to a second device, which is the normal case on camera and media pipelines with an ISP, scaler, or encoder stage.

Not every V4L2 device supports streaming I/O. Some simple capture devices only implement the classic read()/write() system calls, and even on devices that do support streaming, read/write mode is useful for quick tools and scripts where you don’t want to manage buffer queues at all.

The buffer handling here is trivial by comparison: there is no VIDIOC_REQBUFS, no VIDIOC_QUERYBUF, no ioctl of any kind. The kernel is not involved in buffer allocation — you simply allocate ordinary heap memory in user space with malloc() and pass that buffer straight into read(). The driver copies captured data into it behind the scenes, which means read/write I/O always costs one extra memory copy compared to MMAP or DMABUF — a real cost on high-resolution or high-frame-rate capture, but perfectly fine for low bandwidth devices or occasional captures.

size_t buffer_size = 640 * 480 * 2; /* example: YUYV 4:2:2 frame size */

unsigned char *frame_buf = malloc(buffer_size);
if (!frame_buf) {
    perror("malloc");
    exit(EXIT_FAILURE);
}

ssize_t n = read(fd, frame_buf, buffer_size);
if (n == -1) {
    perror("read");
    exit(EXIT_FAILURE);
}
/* frame_buf now holds n bytes of captured frame data */

This original demo, ep_v4l2_mmapbuf, requests MMAP buffers, queries and maps each one, and prints the mapped address and size — the exact groundwork every streaming capture application needs before it can start queuing and dequeuing frames.

/* ep_v4l2_mmapbuf.c - EmbeddedPathashala V4L2 MMAP buffer mapping demo */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys/mman.h>
#include <sys/ioctl.h>
#include <linux/videodev2.h>

#define EP_BUF_COUNT 4

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

int main(int argc, char **argv)
{
    const char *dev_name = (argc > 1) ? argv[1] : "/dev/video0";
    int fd = open(dev_name, O_RDWR);
    if (fd == -1) {
        perror("open");
        return EXIT_FAILURE;
    }

    struct v4l2_requestbuffers req;
    memset(&req, 0, sizeof(req));
    req.count  = EP_BUF_COUNT;
    req.type   = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    req.memory = V4L2_MEMORY_MMAP;

    if (ioctl(fd, VIDIOC_REQBUFS, &req) == -1) {
        perror("VIDIOC_REQBUFS");
        close(fd);
        return EXIT_FAILURE;
    }

    if (req.count < 2) {
        fprintf(stderr, "Insufficient buffer memory on %s\n", dev_name);
        close(fd);
        return EXIT_FAILURE;
    }

    struct ep_buffer *buffers = calloc(req.count, sizeof(*buffers));
    if (!buffers) {
        perror("calloc");
        close(fd);
        return EXIT_FAILURE;
    }

    for (unsigned int i = 0; i < req.count; i++) {
        struct v4l2_buffer buf;
        memset(&buf, 0, sizeof(buf));
        buf.type   = V4L2_BUF_TYPE_VIDEO_CAPTURE;
        buf.memory = V4L2_MEMORY_MMAP;
        buf.index  = i;

        if (ioctl(fd, VIDIOC_QUERYBUF, &buf) == -1) {
            perror("VIDIOC_QUERYBUF");
            close(fd);
            return EXIT_FAILURE;
        }

        buffers[i].length = buf.length;
        buffers[i].start = mmap(NULL, buf.length,
                                 PROT_READ | PROT_WRITE, MAP_SHARED,
                                 fd, buf.m.offset);

        if (buffers[i].start == MAP_FAILED) {
            perror("mmap");
            close(fd);
            return EXIT_FAILURE;
        }

        printf("Buffer %u mapped at %p, size %zu bytes\n",
               i, buffers[i].start, buffers[i].length);
    }

    for (unsigned int i = 0; i < req.count; i++)
        munmap(buffers[i].start, buffers[i].length);

    free(buffers);
    close(fd);
    return EXIT_SUCCESS;
}

Build and run

$ gcc -Wall -o ep_v4l2_mmapbuf ep_v4l2_mmapbuf.c
$ ./ep_v4l2_mmapbuf /dev/video0

Expected output

Buffer 0 mapped at 0x7f2c1a3b4000, size 614400 bytes
Buffer 1 mapped at 0x7f2c1a24b000, size 614400 bytes
Buffer 2 mapped at 0x7f2c1a1e2000, size 614400 bytes
Buffer 3 mapped at 0x7f2c1a179000, size 614400 bytes

Exact addresses and buffer size will differ on your machine depending on the ASLR layout and the resolution/pixel format currently set on the device with VIDIOC_S_FMT from an earlier lecture.

• Calling mmap() before VIDIOC_QUERYBUF — you need buf.length and buf.m.offset first
• Using MAP_PRIVATE instead of MAP_SHARED — breaks zero-copy DMA visibility
• Forgetting munmap() on every buffer before closing the device fd
• Trying VIDIOC_EXPBUF with memory=USERPTR — export only works from MMAP buffers
• Assuming DMABUF gives you a CPU pointer directly — you still map it separately if you need CPU access
• Not checking req.count after REQBUFS — the driver can silently grant fewer buffers than requested

• Always check the actual req.count returned, never assume you got what you asked for
• Track buffer length alongside the pointer — munmap() needs both
• Prefer DMABUF only when a buffer genuinely needs to cross device boundaries
• Reserve read/write I/O for low-bandwidth or one-off capture tools, not production pipelines
• Close every DMABUF file descriptor once the importer device is done with it

In this lecture of our free linux kernel development course we completed the MMAP buffer mapping flow with VIDIOC_QUERYBUF and mmap(), learned how DMABUF’s exporter/importer model shares buffers across devices with zero copy using VIDIOC_EXPBUF, and saw why read/write I/O is the simplest but least efficient memory model available in V4L2. With all four memory models now covered, we’re ready to move on to actually enqueueing and dequeueing these buffers to run a real capture loop — the subject of the next lecture in this free linux device drivers course.