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