| 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.mem_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:`VIDIOC_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. |