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