0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _userp:
0005
0006 *****************************
0007 Streaming I/O (User Pointers)
0008 *****************************
0009
0010 Input and output devices support this I/O method when the
0011 ``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
0012 :c:type:`v4l2_capability` returned by the
0013 :ref:`VIDIOC_QUERYCAP` ioctl is set. If the
0014 particular user pointer method (not only memory mapping) is supported
0015 must be determined by calling the :ref:`VIDIOC_REQBUFS` ioctl
0016 with the memory type set to ``V4L2_MEMORY_USERPTR``.
0017
0018 This I/O method combines advantages of the read/write and memory mapping
0019 methods. Buffers (planes) are allocated by the application itself, and
0020 can reside for example in virtual or shared memory. Only pointers to
0021 data are exchanged, these pointers and meta-information are passed in
0022 struct :c:type:`v4l2_buffer` (or in struct
0023 :c:type:`v4l2_plane` in the multi-planar API case). The
0024 driver must be switched into user pointer I/O mode by calling the
0025 :ref:`VIDIOC_REQBUFS` with the desired buffer type.
0026 No buffers (planes) are allocated beforehand, consequently they are not
0027 indexed and cannot be queried like mapped buffers with the
0028 :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl.
0029
0030 Example: Initiating streaming I/O with user pointers
0031 ====================================================
0032
0033 .. code-block:: c
0034
0035 struct v4l2_requestbuffers reqbuf;
0036
0037 memset (&reqbuf, 0, sizeof (reqbuf));
0038 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
0039 reqbuf.memory = V4L2_MEMORY_USERPTR;
0040
0041 if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
0042 if (errno == EINVAL)
0043 printf ("Video capturing or user pointer streaming is not supported\\n");
0044 else
0045 perror ("VIDIOC_REQBUFS");
0046
0047 exit (EXIT_FAILURE);
0048 }
0049
0050 Buffer (plane) addresses and sizes are passed on the fly with the
0051 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. Although buffers are commonly
0052 cycled, applications can pass different addresses and sizes at each
0053 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the
0054 driver swaps memory pages within physical memory to create a continuous
0055 area of memory. This happens transparently to the application in the
0056 virtual memory subsystem of the kernel. When buffer pages have been
0057 swapped out to disk they are brought back and finally locked in physical
0058 memory for DMA. [#f1]_
0059
0060 Filled or displayed buffers are dequeued with the
0061 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
0062 memory pages at any time between the completion of the DMA and this
0063 ioctl. The memory is also unlocked when
0064 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
0065 :ref:`VIDIOC_REQBUFS`, or when the device is closed.
0066 Applications must take care not to free buffers without dequeuing.
0067 Firstly, the buffers remain locked for longer, wasting physical memory.
0068 Secondly the driver will not be notified when the memory is returned to
0069 the application's free list and subsequently reused for other purposes,
0070 possibly completing the requested DMA and overwriting valuable data.
0071
0072 For capturing applications it is customary to enqueue a number of empty
0073 buffers, to start capturing and enter the read loop. Here the
0074 application waits until a filled buffer can be dequeued, and re-enqueues
0075 the buffer when the data is no longer needed. Output applications fill
0076 and enqueue buffers, when enough buffers are stacked up output is
0077 started. In the write loop, when the application runs out of free
0078 buffers it must wait until an empty buffer can be dequeued and reused.
0079 Two methods exist to suspend execution of the application until one or
0080 more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
0081 <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
0082 ``O_NONBLOCK`` flag was given to the :c:func:`open()` function,
0083 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
0084 error code when no buffer is available. The :ref:`select()
0085 <func-select>` or :c:func:`poll()` function are always
0086 available.
0087
0088 To start and stop capturing or output applications call the
0089 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
0090 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl.
0091
0092 .. note::
0093
0094 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
0095 both queues and unlocks all buffers as a side effect. Since there is no
0096 notion of doing anything "now" on a multitasking system, if an
0097 application needs to synchronize with another event it should examine
0098 the struct :c:type:`v4l2_buffer` ``timestamp`` of captured or
0099 outputted buffers.
0100
0101 Drivers implementing user pointer I/O must support the
0102 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
0103 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
0104 and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the
0105 :c:func:`select()` and :c:func:`poll()` function. [#f2]_
0106
0107 .. [#f1]
0108 We expect that frequently used buffers are typically not swapped out.
0109 Anyway, the process of swapping, locking or generating scatter-gather
0110 lists may be time consuming. The delay can be masked by the depth of
0111 the incoming buffer queue, and perhaps by maintaining caches assuming
0112 a buffer will be soon enqueued again. On the other hand, to optimize
0113 memory usage drivers can limit the number of buffers locked in
0114 advance and recycle the most recently used buffers first. Of course,
0115 the pages of empty buffers in the incoming queue need not be saved to
0116 disk. Output buffers must be saved on the incoming and outgoing queue
0117 because an application may share them with other processes.
0118
0119 .. [#f2]
0120 At the driver level :c:func:`select()` and :c:func:`poll()` are
0121 the same, and :c:func:`select()` is too important to be optional.
0122 The rest should be evident.
