Documentation/linux_tv/media/v4l/userp.rst

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