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