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