Documentation/userspace-api/media/v4l/dmabuf.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/userspace-api/media/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _dmabuf:
  11
  12 ************************************
  13 Streaming I/O (DMA buffer importing)
  14 ************************************
  15
  16 The DMABUF framework provides a generic method for sharing buffers
  17 between multiple devices. Device drivers that support DMABUF can export
  18 a DMA buffer to userspace as a file descriptor (known as the exporter
  19 role), import a DMA buffer from userspace using a file descriptor
  20 previously exported for a different or the same device (known as the
  21 importer role), or both. This section describes the DMABUF importer role
  22 API in V4L2.
  23
  24 Refer to :ref:`DMABUF exporting <VIDIOC_EXPBUF>` for details about
  25 exporting V4L2 buffers as DMABUF file descriptors.
  26
  27 Input and output devices support the streaming I/O method when the
  28 ``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
  29 :c:type:`v4l2_capability` returned by the
  30 :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl is set. Whether
  31 importing DMA buffers through DMABUF file descriptors is supported is
  32 determined by calling the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
  33 ioctl with the memory type set to ``V4L2_MEMORY_DMABUF``.
  34
  35 This I/O method is dedicated to sharing DMA buffers between different
  36 devices, which may be V4L devices or other video-related devices (e.g.
  37 DRM). Buffers (planes) are allocated by a driver on behalf of an
  38 application. Next, these buffers are exported to the application as file
  39 descriptors using an API which is specific for an allocator driver. Only
  40 such file descriptor are exchanged. The descriptors and meta-information
  41 are passed in struct :c:type:`v4l2_buffer` (or in struct
  42 :c:type:`v4l2_plane` in the multi-planar API case). The
  43 driver must be switched into DMABUF I/O mode by calling the
  44 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type.
  45
  46
  47 Example: Initiating streaming I/O with DMABUF file descriptors
  48 ==============================================================
  49
  50 .. code-block:: c
  51
  52     struct v4l2_requestbuffers reqbuf;
  53
  54     memset(&reqbuf, 0, sizeof (reqbuf));
  55     reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
  56     reqbuf.memory = V4L2_MEMORY_DMABUF;
  57     reqbuf.count = 1;
  58
  59     if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
  60         if (errno == EINVAL)
  61             printf("Video capturing or DMABUF streaming is not supported\\n");
  62         else
  63             perror("VIDIOC_REQBUFS");
  64
  65         exit(EXIT_FAILURE);
  66     }
  67
  68 The buffer (plane) file descriptor is passed on the fly with the
  69 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. In case of multiplanar
  70 buffers, every plane can be associated with a different DMABUF
  71 descriptor. Although buffers are commonly cycled, applications can pass
  72 a different DMABUF descriptor at each :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call.
  73
  74 Example: Queueing DMABUF using single plane API
  75 ===============================================
  76
  77 .. code-block:: c
  78
  79     int buffer_queue(int v4lfd, int index, int dmafd)
  80     {
  81         struct v4l2_buffer buf;
  82
  83         memset(&buf, 0, sizeof buf);
  84         buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
  85         buf.memory = V4L2_MEMORY_DMABUF;
  86         buf.index = index;
  87         buf.m.fd = dmafd;
  88
  89         if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
  90             perror("VIDIOC_QBUF");
  91             return -1;
  92         }
  93
  94         return 0;
  95     }
  96
  97 Example 3.6. Queueing DMABUF using multi plane API
  98 ==================================================
  99
 100 .. code-block:: c
 101
 102     int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
 103     {
 104         struct v4l2_buffer buf;
 105         struct v4l2_plane planes[VIDEO_MAX_PLANES];
 106         int i;
 107
 108         memset(&buf, 0, sizeof buf);
 109         buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
 110         buf.memory = V4L2_MEMORY_DMABUF;
 111         buf.index = index;
 112         buf.m.planes = planes;
 113         buf.length = n_planes;
 114
 115         memset(&planes, 0, sizeof planes);
 116
 117         for (i = 0; i < n_planes; ++i)
 118             buf.m.planes[i].m.fd = dmafd[i];
 119
 120         if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
 121             perror("VIDIOC_QBUF");
 122             return -1;
 123         }
 124
 125         return 0;
 126     }
 127
 128 Captured or displayed buffers are dequeued with the
 129 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
 130 buffer at any time between the completion of the DMA and this ioctl. The
 131 memory is also unlocked when
 132 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
 133 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, or when the device is closed.
 134
 135 For capturing applications it is customary to enqueue a number of empty
 136 buffers, to start capturing and enter the read loop. Here the
 137 application waits until a filled buffer can be dequeued, and re-enqueues
 138 the buffer when the data is no longer needed. Output applications fill
 139 and enqueue buffers, when enough buffers are stacked up output is
 140 started. In the write loop, when the application runs out of free
 141 buffers it must wait until an empty buffer can be dequeued and reused.
 142 Two methods exist to suspend execution of the application until one or
 143 more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
 144 <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
 145 ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
 146 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
 147 error code when no buffer is available. The
 148 :ref:`select() <func-select>` and :ref:`poll() <func-poll>`
 149 functions are always available.
 150
 151 To start and stop capturing or displaying applications call the
 152 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
 153 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls.
 154
 155 .. note::
 156
 157    :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
 158    both queues and unlocks all buffers as a side effect. Since there is no
 159    notion of doing anything "now" on a multitasking system, if an
 160    application needs to synchronize with another event it should examine
 161    the struct :c:type:`v4l2_buffer` ``timestamp`` of captured or
 162    outputted buffers.
 163
 164 Drivers implementing DMABUF importing I/O must support the
 165 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
 166 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON
 167 <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls,
 168 and the :ref:`select() <func-select>` and :ref:`poll() <func-poll>`
 169 functions.