Documentation/media/uapi/v4l/userp.rst

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