1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L
3
4 .. _VIDIOC_EXPBUF:
5
6 *******************
7 ioctl VIDIOC_EXPBUF
8 *******************
9
10 Name
11 ====
12
13 VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor.
14
15 Synopsis
16 ========
17
18 .. c:macro:: VIDIOC_EXPBUF
19
20 ``int ioctl(int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp)``
21
22 Arguments
23 =========
24
25 ``fd``
26 File descriptor returned by :c:func:`open()`.
27
28 ``argp``
29 Pointer to struct :c:type:`v4l2_exportbuffer`.
30
31 Description
32 ===========
33
34 This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O
35 method, therefore it is available only for ``V4L2_MEMORY_MMAP`` buffers.
36 It can be used to export a buffer as a DMABUF file at any time after
37 buffers have been allocated with the
38 :ref:`VIDIOC_REQBUFS` ioctl.
39
40 To export a buffer, applications fill struct
41 :c:type:`v4l2_exportbuffer`. The ``type`` field is
42 set to the same buffer type as was previously used with struct
43 :c:type:`v4l2_requestbuffers` ``type``.
44 Applications must also set the ``index`` field. Valid index numbers
45 range from zero to the number of buffers allocated with
46 :ref:`VIDIOC_REQBUFS` (struct
47 :c:type:`v4l2_requestbuffers` ``count``) minus
48 one. For the multi-planar API, applications set the ``plane`` field to
49 the index of the plane to be exported. Valid planes range from zero to
50 the maximal number of valid planes for the currently active format. For
51 the single-planar API, applications must set ``plane`` to zero.
52 Additional flags may be posted in the ``flags`` field. Refer to a manual
53 for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
54 and O_RDWR are supported. All other fields must be set to zero. In the
55 case of multi-planar API, every plane is exported separately using
56 multiple :ref:`VIDIOC_EXPBUF` calls.
57
58 After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a
59 driver. This is a DMABUF file descriptor. The application may pass it to
60 other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>`
61 for details about importing DMABUF files into V4L2 nodes. It is
62 recommended to close a DMABUF file when it is no longer used to allow
63 the associated memory to be reclaimed.
64
65 Examples
66 ========
67
68 .. code-block:: c
69
70 int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd)
71 {
72 struct v4l2_exportbuffer expbuf;
73
74 memset(&expbuf, 0, sizeof(expbuf));
75 expbuf.type = bt;
76 expbuf.index = index;
77 if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
78 perror("VIDIOC_EXPBUF");
79 return -1;
80 }
81
82 *dmafd = expbuf.fd;
83
84 return 0;
85 }
86
87 .. code-block:: c
88
89 int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index,
90 int dmafd[], int n_planes)
91 {
92 int i;
93
94 for (i = 0; i < n_planes; ++i) {
95 struct v4l2_exportbuffer expbuf;
96
97 memset(&expbuf, 0, sizeof(expbuf));
98 expbuf.type = bt;
99 expbuf.index = index;
100 expbuf.plane = i;
101 if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
102 perror("VIDIOC_EXPBUF");
103 while (i)
104 close(dmafd[--i]);
105 return -1;
106 }
107 dmafd[i] = expbuf.fd;
108 }
109
110 return 0;
111 }
112
113 .. c:type:: v4l2_exportbuffer
114
115 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
116
117 .. flat-table:: struct v4l2_exportbuffer
118 :header-rows: 0
119 :stub-columns: 0
120 :widths: 1 1 2
121
122 * - __u32
123 - ``type``
124 - Type of the buffer, same as struct
125 :c:type:`v4l2_format` ``type`` or struct
126 :c:type:`v4l2_requestbuffers` ``type``, set
127 by the application. See :c:type:`v4l2_buf_type`
128 * - __u32
129 - ``index``
130 - Number of the buffer, set by the application. This field is only
131 used for :ref:`memory mapping <mmap>` I/O and can range from
132 zero to the number of buffers allocated with the
133 :ref:`VIDIOC_REQBUFS` and/or
134 :ref:`VIDIOC_CREATE_BUFS` ioctls.
135 * - __u32
136 - ``plane``
137 - Index of the plane to be exported when using the multi-planar API.
138 Otherwise this value must be set to zero.
139 * - __u32
140 - ``flags``
141 - Flags for the newly created file, currently only ``O_CLOEXEC``,
142 ``O_RDONLY``, ``O_WRONLY``, and ``O_RDWR`` are supported, refer to
143 the manual of open() for more details.
144 * - __s32
145 - ``fd``
146 - The DMABUF file descriptor associated with a buffer. Set by the
147 driver.
148 * - __u32
149 - ``reserved[11]``
150 - Reserved field for future use. Drivers and applications must set
151 the array to zero.
152
153 Return Value
154 ============
155
156 On success 0 is returned, on error -1 and the ``errno`` variable is set
157 appropriately. The generic error codes are described at the
158 :ref:`Generic Error Codes <gen-errors>` chapter.
159
160 EINVAL
161 A queue is not in MMAP mode or DMABUF exporting is not supported or
162 ``flags`` or ``type`` or ``index`` or ``plane`` fields are invalid.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.