123 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _userp:5 6*****************************7Streaming I/O (User Pointers)8*****************************9 10Input and output devices support this I/O method when the11``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct12:c:type:`v4l2_capability` returned by the13:ref:`VIDIOC_QUERYCAP` ioctl is set. If the14particular user pointer method (not only memory mapping) is supported15must be determined by calling the :ref:`VIDIOC_REQBUFS` ioctl16with the memory type set to ``V4L2_MEMORY_USERPTR``.17 18This I/O method combines advantages of the read/write and memory mapping19methods. Buffers (planes) are allocated by the application itself, and20can reside for example in virtual or shared memory. Only pointers to21data are exchanged, these pointers and meta-information are passed in22struct :c:type:`v4l2_buffer` (or in struct23:c:type:`v4l2_plane` in the multi-planar API case). The24driver must be switched into user pointer I/O mode by calling the25:ref:`VIDIOC_REQBUFS` with the desired buffer type.26No buffers (planes) are allocated beforehand, consequently they are not27indexed and cannot be queried like mapped buffers with the28:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl.29 30Example: Initiating streaming I/O with user pointers31====================================================32 33.. code-block:: c34 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 else45 perror ("VIDIOC_REQBUFS");46 47 exit (EXIT_FAILURE);48 }49 50Buffer (plane) addresses and sizes are passed on the fly with the51:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. Although buffers are commonly52cycled, applications can pass different addresses and sizes at each53:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the54driver swaps memory pages within physical memory to create a continuous55area of memory. This happens transparently to the application in the56virtual memory subsystem of the kernel. When buffer pages have been57swapped out to disk they are brought back and finally locked in physical58memory for DMA. [#f1]_59 60Filled or displayed buffers are dequeued with the61:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the62memory pages at any time between the completion of the DMA and this63ioctl. The memory is also unlocked when64: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 to69the 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 empty73buffers, to start capturing and enter the read loop. Here the74application waits until a filled buffer can be dequeued, and re-enqueues75the buffer when the data is no longer needed. Output applications fill76and enqueue buffers, when enough buffers are stacked up output is77started. In the write loop, when the application runs out of free78buffers it must wait until an empty buffer can be dequeued and reused.79Two methods exist to suspend execution of the application until one or80more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF81<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the82``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 always86available.87 88To start and stop capturing or output applications call the89:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and90:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl.91 92.. note::93 94 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from95 both queues and unlocks all buffers as a side effect. Since there is no96 notion of doing anything "now" on a multitasking system, if an97 application needs to synchronize with another event it should examine98 the struct :c:type:`v4l2_buffer` ``timestamp`` of captured or99 outputted buffers.100 101Drivers implementing user pointer I/O must support the102: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, the105: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-gather110 lists may be time consuming. The delay can be masked by the depth of111 the incoming buffer queue, and perhaps by maintaining caches assuming112 a buffer will be soon enqueued again. On the other hand, to optimize113 memory usage drivers can limit the number of buffers locked in114 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 to116 disk. Output buffers must be saved on the incoming and outgoing queue117 because an application may share them with other processes.118 119.. [#f2]120 At the driver level :c:func:`select()` and :c:func:`poll()` are121 the same, and :c:func:`select()` is too important to be optional.122 The rest should be evident.123