userp.rst

  1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
  2.. c:namespace:: V4L
  3
  4.. _userp:
  5
  6*****************************
  7Streaming I/O (User Pointers)
  8*****************************
  9
 10Input 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
 14particular user pointer method (not only memory mapping) is supported
 15must be determined by calling the :ref:`VIDIOC_REQBUFS` ioctl
 16with the memory type set to ``V4L2_MEMORY_USERPTR``.
 17
 18This I/O method combines advantages of the read/write and memory mapping
 19methods. Buffers (planes) are allocated by the application itself, and
 20can reside for example in virtual or shared memory. Only pointers to
 21data are exchanged, these pointers and meta-information are passed in
 22struct :c:type:`v4l2_buffer` (or in struct
 23:c:type:`v4l2_plane` in the multi-planar API case). The
 24driver must be switched into user pointer I/O mode by calling the
 25:ref:`VIDIOC_REQBUFS` with the desired buffer type.
 26No buffers (planes) are allocated beforehand, consequently they are not
 27indexed and cannot be queried like mapped buffers with the
 28:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl.
 29
 30Example: 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
 50Buffer (plane) addresses and sizes are passed on the fly with the
 51:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. Although buffers are commonly
 52cycled, applications can pass different addresses and sizes at each
 53:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the
 54driver swaps memory pages within physical memory to create a continuous
 55area of memory. This happens transparently to the application in the
 56virtual memory subsystem of the kernel. When buffer pages have been
 57swapped out to disk they are brought back and finally locked in physical
 58memory for DMA. [#f1]_
 59
 60Filled or displayed buffers are dequeued with the
 61:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
 62memory pages at any time between the completion of the DMA and this
 63ioctl. The memory is also unlocked when
 64:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
 65:ref:`VIDIOC_REQBUFS`, or when the device is closed.
 66Applications must take care not to free buffers without dequeuing.
 67Firstly, the buffers remain locked for longer, wasting physical memory.
 68Secondly the driver will not be notified when the memory is returned to
 69the application's free list and subsequently reused for other purposes,
 70possibly completing the requested DMA and overwriting valuable data.
 71
 72For capturing applications it is customary to enqueue a number of empty
 73buffers, to start capturing and enter the read loop. Here the
 74application waits until a filled buffer can be dequeued, and re-enqueues
 75the buffer when the data is no longer needed. Output applications fill
 76and enqueue buffers, when enough buffers are stacked up output is
 77started. In the write loop, when the application runs out of free
 78buffers it must wait until an empty buffer can be dequeued and reused.
 79Two methods exist to suspend execution of the application until one or
 80more 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``
 84error code when no buffer is available. The :ref:`select()
 85<func-select>` or :c:func:`poll()` function are always
 86available.
 87
 88To 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
101Drivers 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>`
104and :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.