| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _userp: |
| 5 |
|
| 6 |
***************************** |
| 7 |
Streaming I/O (User Pointers) |
| 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. If the |
| 14 |
particular user pointer method (not only memory mapping) is supported |
| 15 |
must be determined by calling the :ref:`VIDIOC_REQBUFS` ioctl |
| 16 |
with the memory type set to ``V4L2_MEMORY_USERPTR``. |
| 17 |
|
| 18 |
This I/O method combines advantages of the read/write and memory mapping |
| 19 |
methods. Buffers (planes) are allocated by the application itself, and |
| 20 |
can reside for example in virtual or shared memory. Only pointers to |
| 21 |
data are exchanged, these pointers and meta-information are passed in |
| 22 |
struct :c:type:`v4l2_buffer` (or in struct |
| 23 |
:c:type:`v4l2_plane` in the multi-planar API case). The |
| 24 |
driver must be switched into user pointer I/O mode by calling the |
| 25 |
:ref:`VIDIOC_REQBUFS` with the desired buffer type. |
| 26 |
No buffers (planes) are allocated beforehand, consequently they are not |
| 27 |
indexed and cannot be queried like mapped buffers with the |
| 28 |
:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl. |
| 29 |
|
| 30 |
Example: Initiating streaming I/O with user pointers |
| 31 |
==================================================== |
| 32 |
|
| 33 |
.. code-block:: c |
| 34 |
|
| 35 |
struct v4l2_requestbuffers reqbuf; |
| 36 |
|
| 37 |
memset (&reqbuf, 0, sizeof (reqbuf)); |
| 38 |
reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; |
| 39 |
reqbuf.memory = V4L2_MEMORY_USERPTR; |
| 40 |
|
| 41 |
if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) { |
| 42 |
if (errno == EINVAL) |
| 43 |
printf ("Video capturing or user pointer streaming is not supported\\n"); |
| 44 |
else |
| 45 |
perror ("VIDIOC_REQBUFS"); |
| 46 |
|
| 47 |
exit (EXIT_FAILURE); |
| 48 |
} |
| 49 |
|
| 50 |
Buffer (plane) addresses and sizes are passed on the fly with the |
| 51 |
:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. Although buffers are commonly |
| 52 |
cycled, applications can pass different addresses and sizes at each |
| 53 |
:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the |
| 54 |
driver swaps memory pages within physical memory to create a continuous |
| 55 |
area of memory. This happens transparently to the application in the |
| 56 |
virtual memory subsystem of the kernel. When buffer pages have been |
| 57 |
swapped out to disk they are brought back and finally locked in physical |
| 58 |
memory for DMA. [#f1]_ |
| 59 |
|
| 60 |
Filled or displayed buffers are dequeued with the |
| 61 |
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the |
| 62 |
memory pages at any time between the completion of the DMA and this |
| 63 |
ioctl. The memory is also unlocked when |
| 64 |
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called, |
| 65 |
:ref:`VIDIOC_REQBUFS`, or when the device is closed. |
| 66 |
Applications must take care not to free buffers without dequeuing. |
| 67 |
Firstly, the buffers remain locked for longer, wasting physical memory. |
| 68 |
Secondly the driver will not be notified when the memory is returned to |
| 69 |
the application's free list and subsequently reused for other purposes, |
| 70 |
possibly completing the requested DMA and overwriting valuable data. |
| 71 |
|
| 72 |
For capturing applications it is customary to enqueue a number of empty |
| 73 |
buffers, to start capturing and enter the read loop. Here the |
| 74 |
application waits until a filled buffer can be dequeued, and re-enqueues |
| 75 |
the buffer when the data is no longer needed. Output applications fill |
| 76 |
and enqueue buffers, when enough buffers are stacked up output is |
| 77 |
started. In the write loop, when the application runs out of free |
| 78 |
buffers it must wait until an empty buffer can be dequeued and reused. |
| 79 |
Two methods exist to suspend execution of the application until one or |
| 80 |
more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF |
| 81 |
<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the |
| 82 |
``O_NONBLOCK`` flag was given to the :c:func:`open()` function, |
| 83 |
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` |
| 84 |
error code when no buffer is available. The :ref:`select() |
| 85 |
<func-select>` or :c:func:`poll()` function are always |
| 86 |
available. |
| 87 |
|
| 88 |
To start and stop capturing or output applications call the |
| 89 |
:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and |
| 90 |
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl. |
| 91 |
|
| 92 |
.. note:: |
| 93 |
|
| 94 |
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from |
| 95 |
both queues and unlocks all buffers as a side effect. Since there is no |
| 96 |
notion of doing anything "now" on a multitasking system, if an |
| 97 |
application needs to synchronize with another event it should examine |
| 98 |
the struct :c:type:`v4l2_buffer` ``timestamp`` of captured or |
| 99 |
outputted buffers. |
| 100 |
|
| 101 |
Drivers implementing user pointer I/O must support the |
| 102 |
:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, |
| 103 |
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` |
| 104 |
and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the |
| 105 |
:c:func:`select()` and :c:func:`poll()` function. [#f2]_ |
| 106 |
|
| 107 |
.. [#f1] |
| 108 |
We expect that frequently used buffers are typically not swapped out. |
| 109 |
Anyway, the process of swapping, locking or generating scatter-gather |
| 110 |
lists may be time consuming. The delay can be masked by the depth of |
| 111 |
the incoming buffer queue, and perhaps by maintaining caches assuming |
| 112 |
a buffer will be soon enqueued again. On the other hand, to optimize |
| 113 |
memory usage drivers can limit the number of buffers locked in |
| 114 |
advance and recycle the most recently used buffers first. Of course, |
| 115 |
the pages of empty buffers in the incoming queue need not be saved to |
| 116 |
disk. Output buffers must be saved on the incoming and outgoing queue |
| 117 |
because an application may share them with other processes. |
| 118 |
|
| 119 |
.. [#f2] |
| 120 |
At the driver level :c:func:`select()` and :c:func:`poll()` are |
| 121 |
the same, and :c:func:`select()` is too important to be optional. |
| 122 |
The rest should be evident. |