Documentation/userspace-api/media/v4l/mmap.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _mmap:
   5
   6 ******************************
   7 Streaming I/O (Memory Mapping)
   8 ******************************
   9
  10 Input and output devices support this I/O method when the
  11 ``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
  12 :c:type:`v4l2_capability` returned by the
  13 :ref:`VIDIOC_QUERYCAP` ioctl is set. There are two
  14 streaming methods, to determine if the memory mapping flavor is
  15 supported applications must call the :ref:`VIDIOC_REQBUFS` ioctl
  16 with the memory type set to ``V4L2_MEMORY_MMAP``.
  17
  18 Streaming is an I/O method where only pointers to buffers are exchanged
  19 between application and driver, the data itself is not copied. Memory
  20 mapping is primarily intended to map buffers in device memory into the
  21 application's address space. Device memory can be for example the video
  22 memory on a graphics card with a video capture add-on. However, being
  23 the most efficient I/O method available for a long time, many other
  24 drivers support streaming as well, allocating buffers in DMA-able main
  25 memory.
  26
  27 A driver can support many sets of buffers. Each set is identified by a
  28 unique buffer type value. The sets are independent and each set can hold
  29 a different type of data. To access different sets at the same time
  30 different file descriptors must be used. [#f1]_
  31
  32 To allocate device buffers applications call the
  33 :ref:`VIDIOC_REQBUFS` ioctl with the desired number
  34 of buffers and buffer type, for example ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
  35 This ioctl can also be used to change the number of buffers or to free
  36 the allocated memory, provided none of the buffers are still mapped.
  37
  38 Before applications can access the buffers they must map them into their
  39 address space with the :c:func:`mmap()` function. The
  40 location of the buffers in device memory can be determined with the
  41 :ref:`VIDIOC_QUERYBUF` ioctl. In the single-planar
  42 API case, the ``m.offset`` and ``length`` returned in a struct
  43 :c:type:`v4l2_buffer` are passed as sixth and second
  44 parameter to the :c:func:`mmap()` function. When using the
  45 multi-planar API, struct :c:type:`v4l2_buffer` contains an
  46 array of struct :c:type:`v4l2_plane` structures, each
  47 containing its own ``m.offset`` and ``length``. When using the
  48 multi-planar API, every plane of every buffer has to be mapped
  49 separately, so the number of calls to :c:func:`mmap()` should
  50 be equal to number of buffers times number of planes in each buffer. The
  51 offset and length values must not be modified. Remember, the buffers are
  52 allocated in physical memory, as opposed to virtual memory, which can be
  53 swapped out to disk. Applications should free the buffers as soon as
  54 possible with the :c:func:`munmap()` function.
  55
  56 Example: Mapping buffers in the single-planar API
  57 =================================================
  58
  59 .. code-block:: c
  60
  61     struct v4l2_requestbuffers reqbuf;
  62     struct {
  63         void *start;
  64         size_t length;
  65     } *buffers;
  66     unsigned int i;
  67
  68     memset(&reqbuf, 0, sizeof(reqbuf));
  69     reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
  70     reqbuf.memory = V4L2_MEMORY_MMAP;
  71     reqbuf.count = 20;
  72
  73     if (-1 == ioctl (fd, VIDIOC_REQBUFS, &reqbuf)) {
  74         if (errno == EINVAL)
  75             printf("Video capturing or mmap-streaming is not supported\\n");
  76         else
  77             perror("VIDIOC_REQBUFS");
  78
  79         exit(EXIT_FAILURE);
  80     }
  81
  82     /* We want at least five buffers. */
  83
  84     if (reqbuf.count < 5) {
  85         /* You may need to free the buffers here. */
  86         printf("Not enough buffer memory\\n");
  87         exit(EXIT_FAILURE);
  88     }
  89
  90     buffers = calloc(reqbuf.count, sizeof(*buffers));
  91     assert(buffers != NULL);
  92
  93     for (i = 0; i < reqbuf.count; i++) {
  94         struct v4l2_buffer buffer;
  95
  96         memset(&buffer, 0, sizeof(buffer));
  97         buffer.type = reqbuf.type;
  98         buffer.memory = V4L2_MEMORY_MMAP;
  99         buffer.index = i;
 100
 101         if (-1 == ioctl (fd, VIDIOC_QUERYBUF, &buffer)) {
 102             perror("VIDIOC_QUERYBUF");
 103             exit(EXIT_FAILURE);
 104         }
 105
 106         buffers[i].length = buffer.length; /* remember for munmap() */
 107
 108         buffers[i].start = mmap(NULL, buffer.length,
 109                     PROT_READ | PROT_WRITE, /* recommended */
 110                     MAP_SHARED,             /* recommended */
 111                     fd, buffer.m.offset);
 112
 113         if (MAP_FAILED == buffers[i].start) {
 114             /* If you do not exit here you should unmap() and free()
 115                the buffers mapped so far. */
 116             perror("mmap");
 117             exit(EXIT_FAILURE);
 118         }
 119     }
 120
 121     /* Cleanup. */
 122
 123     for (i = 0; i < reqbuf.count; i++)
 124         munmap(buffers[i].start, buffers[i].length);
 125
 126 Example: Mapping buffers in the multi-planar API
 127 ================================================
 128
 129 .. code-block:: c
 130
 131     struct v4l2_requestbuffers reqbuf;
 132     /* Our current format uses 3 planes per buffer */
 133     #define FMT_NUM_PLANES = 3
 134
 135     struct {
 136         void *start[FMT_NUM_PLANES];
 137         size_t length[FMT_NUM_PLANES];
 138     } *buffers;
 139     unsigned int i, j;
 140
 141     memset(&reqbuf, 0, sizeof(reqbuf));
 142     reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
 143     reqbuf.memory = V4L2_MEMORY_MMAP;
 144     reqbuf.count = 20;
 145
 146     if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) < 0) {
 147         if (errno == EINVAL)
 148             printf("Video capturing or mmap-streaming is not supported\\n");
 149         else
 150             perror("VIDIOC_REQBUFS");
 151
 152         exit(EXIT_FAILURE);
 153     }
 154
 155     /* We want at least five buffers. */
 156
 157     if (reqbuf.count < 5) {
 158         /* You may need to free the buffers here. */
 159         printf("Not enough buffer memory\\n");
 160         exit(EXIT_FAILURE);
 161     }
 162
 163     buffers = calloc(reqbuf.count, sizeof(*buffers));
 164     assert(buffers != NULL);
 165
 166     for (i = 0; i < reqbuf.count; i++) {
 167         struct v4l2_buffer buffer;
 168         struct v4l2_plane planes[FMT_NUM_PLANES];
 169
 170         memset(&buffer, 0, sizeof(buffer));
 171         buffer.type = reqbuf.type;
 172         buffer.memory = V4L2_MEMORY_MMAP;
 173         buffer.index = i;
 174         /* length in struct v4l2_buffer in multi-planar API stores the size
 175          * of planes array. */
 176         buffer.length = FMT_NUM_PLANES;
 177         buffer.m.planes = planes;
 178
 179         if (ioctl(fd, VIDIOC_QUERYBUF, &buffer) < 0) {
 180             perror("VIDIOC_QUERYBUF");
 181             exit(EXIT_FAILURE);
 182         }
 183
 184         /* Every plane has to be mapped separately */
 185         for (j = 0; j < FMT_NUM_PLANES; j++) {
 186             buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
 187
 188             buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
 189                      PROT_READ | PROT_WRITE, /* recommended */
 190                      MAP_SHARED,             /* recommended */
 191                      fd, buffer.m.planes[j].m.offset);
 192
 193             if (MAP_FAILED == buffers[i].start[j]) {
 194                 /* If you do not exit here you should unmap() and free()
 195                    the buffers and planes mapped so far. */
 196                 perror("mmap");
 197                 exit(EXIT_FAILURE);
 198             }
 199         }
 200     }
 201
 202     /* Cleanup. */
 203
 204     for (i = 0; i < reqbuf.count; i++)
 205         for (j = 0; j < FMT_NUM_PLANES; j++)
 206             munmap(buffers[i].start[j], buffers[i].length[j]);
 207
 208 Conceptually streaming drivers maintain two buffer queues, an incoming
 209 and an outgoing queue. They separate the synchronous capture or output
 210 operation locked to a video clock from the application which is subject
 211 to random disk or network delays and preemption by other processes,
 212 thereby reducing the probability of data loss. The queues are organized
 213 as FIFOs, buffers will be output in the order enqueued in the incoming
 214 FIFO, and were captured in the order dequeued from the outgoing FIFO.
 215
 216 The driver may require a minimum number of buffers enqueued at all times
 217 to function, apart of this no limit exists on the number of buffers
 218 applications can enqueue in advance, or dequeue and process. They can
 219 also enqueue in a different order than buffers have been dequeued, and
 220 the driver can *fill* enqueued *empty* buffers in any order.  [#f2]_ The
 221 index number of a buffer (struct :c:type:`v4l2_buffer`
 222 ``index``) plays no role here, it only identifies the buffer.
 223
 224 Initially all mapped buffers are in dequeued state, inaccessible by the
 225 driver. For capturing applications it is customary to first enqueue all
 226 mapped buffers, then to start capturing and enter the read loop. Here
 227 the application waits until a filled buffer can be dequeued, and
 228 re-enqueues the buffer when the data is no longer needed. Output
 229 applications fill and enqueue buffers, when enough buffers are stacked
 230 up the output is started with :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`.
 231 In the write loop, when the application runs out of free buffers, it
 232 must wait until an empty buffer can be dequeued and reused.
 233
 234 To enqueue and dequeue a buffer applications use the
 235 :ref:`VIVIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
 236 ioctl. The status of a buffer being mapped, enqueued, full or empty can
 237 be determined at any time using the :ref:`VIDIOC_QUERYBUF` ioctl. Two
 238 methods exist to suspend execution of the application until one or more
 239 buffers can be dequeued.  By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
 240 blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK``
 241 flag was given to the :c:func:`open()` function,
 242 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
 243 error code when no buffer is available. The :c:func:`select()`
 244 or :c:func:`poll()` functions are always available.
 245
 246 To start and stop capturing or output applications call the
 247 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF
 248 <VIDIOC_STREAMON>` ioctl.
 249
 250 .. note:::ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
 251    removes all buffers from both queues as a side effect. Since there is
 252    no notion of doing anything "now" on a multitasking system, if an
 253    application needs to synchronize with another event it should examine
 254    the struct ::c:type:`v4l2_buffer` ``timestamp`` of captured
 255    or outputted buffers.
 256
 257 Drivers implementing memory mapping I/O must support the
 258 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QUERYBUF
 259 <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF
 260 <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
 261 and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap()
 262 <func-mmap>`, :c:func:`munmap()`, :ref:`select()
 263 <func-select>` and :c:func:`poll()` function. [#f3]_
 264
 265 [capture example]
 266
 267 .. [#f1]
 268    One could use one file descriptor and set the buffer type field
 269    accordingly when calling :ref:`VIDIOC_QBUF` etc.,
 270    but it makes the :c:func:`select()` function ambiguous. We also
 271    like the clean approach of one file descriptor per logical stream.
 272    Video overlay for example is also a logical stream, although the CPU
 273    is not needed for continuous operation.
 274
 275 .. [#f2]
 276    Random enqueue order permits applications processing images out of
 277    order (such as video codecs) to return buffers earlier, reducing the
 278    probability of data loss. Random fill order allows drivers to reuse
 279    buffers on a LIFO-basis, taking advantage of caches holding
 280    scatter-gather lists and the like.
 281
 282 .. [#f3]
 283    At the driver level :c:func:`select()` and :c:func:`poll()` are
 284    the same, and :c:func:`select()` is too important to be optional.
 285    The rest should be evident.