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