1<refentry id="vidioc-expbuf"> 2 3 <refmeta> 4 <refentrytitle>ioctl VIDIOC_EXPBUF</refentrytitle> 5 &manvol; 6 </refmeta> 7 8 <refnamediv> 9 <refname>VIDIOC_EXPBUF</refname> 10 <refpurpose>Export a buffer as a DMABUF file descriptor.</refpurpose> 11 </refnamediv> 12 13 <refsynopsisdiv> 14 <funcsynopsis> 15 <funcprototype> 16 <funcdef>int <function>ioctl</function></funcdef> 17 <paramdef>int <parameter>fd</parameter></paramdef> 18 <paramdef>int <parameter>request</parameter></paramdef> 19 <paramdef>struct v4l2_exportbuffer *<parameter>argp</parameter></paramdef> 20 </funcprototype> 21 </funcsynopsis> 22 </refsynopsisdiv> 23 24 <refsect1> 25 <title>Arguments</title> 26 27 <variablelist> 28 <varlistentry> 29 <term><parameter>fd</parameter></term> 30 <listitem> 31 <para>&fd;</para> 32 </listitem> 33 </varlistentry> 34 <varlistentry> 35 <term><parameter>request</parameter></term> 36 <listitem> 37 <para>VIDIOC_EXPBUF</para> 38 </listitem> 39 </varlistentry> 40 <varlistentry> 41 <term><parameter>argp</parameter></term> 42 <listitem> 43 <para></para> 44 </listitem> 45 </varlistentry> 46 </variablelist> 47 </refsect1> 48 49 <refsect1> 50 <title>Description</title> 51 52 <note> 53 <title>Experimental</title> 54 <para>This is an <link linkend="experimental"> experimental </link> 55 interface and may change in the future.</para> 56 </note> 57 58<para>This ioctl is an extension to the <link linkend="mmap">memory 59mapping</link> I/O method, therefore it is available only for 60<constant>V4L2_MEMORY_MMAP</constant> buffers. It can be used to export a 61buffer as a DMABUF file at any time after buffers have been allocated with the 62&VIDIOC-REQBUFS; ioctl.</para> 63 64<para> To export a buffer, applications fill &v4l2-exportbuffer;. The 65<structfield> type </structfield> field is set to the same buffer type as was 66previously used with &v4l2-requestbuffers;<structfield> type </structfield>. 67Applications must also set the <structfield> index </structfield> field. Valid 68index numbers range from zero to the number of buffers allocated with 69&VIDIOC-REQBUFS; (&v4l2-requestbuffers;<structfield> count </structfield>) 70minus one. For the multi-planar API, applications set the <structfield> plane 71</structfield> field to the index of the plane to be exported. Valid planes 72range from zero to the maximal number of valid planes for the currently active 73format. For the single-planar API, applications must set <structfield> plane 74</structfield> to zero. Additional flags may be posted in the <structfield> 75flags </structfield> field. Refer to a manual for open() for details. 76Currently only O_CLOEXEC is supported. All other fields must be set to zero. 77In the case of multi-planar API, every plane is exported separately using 78multiple <constant> VIDIOC_EXPBUF </constant> calls. </para> 79 80<para> After calling <constant>VIDIOC_EXPBUF</constant> the <structfield> fd 81</structfield> field will be set by a driver. This is a DMABUF file 82descriptor. The application may pass it to other DMABUF-aware devices. Refer to 83<link linkend="dmabuf">DMABUF importing</link> for details about importing 84DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it 85is no longer used to allow the associated memory to be reclaimed. </para> 86 </refsect1> 87 88 <refsect1> 89 <title>Examples</title> 90 91 <example> 92 <title>Exporting a buffer.</title> 93 <programlisting> 94int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd) 95{ 96 &v4l2-exportbuffer; expbuf; 97 98 memset(&expbuf, 0, sizeof(expbuf)); 99 expbuf.type = bt; 100 expbuf.index = index; 101 if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { 102 perror("VIDIOC_EXPBUF"); 103 return -1; 104 } 105 106 *dmafd = expbuf.fd; 107 108 return 0; 109} 110 </programlisting> 111 </example> 112 113 <example> 114 <title>Exporting a buffer using the multi-planar API.</title> 115 <programlisting> 116int buffer_export_mp(int v4lfd, &v4l2-buf-type; bt, int index, 117 int dmafd[], int n_planes) 118{ 119 int i; 120 121 for (i = 0; i < n_planes; ++i) { 122 &v4l2-exportbuffer; expbuf; 123 124 memset(&expbuf, 0, sizeof(expbuf)); 125 expbuf.type = bt; 126 expbuf.index = index; 127 expbuf.plane = i; 128 if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { 129 perror("VIDIOC_EXPBUF"); 130 while (i) 131 close(dmafd[--i]); 132 return -1; 133 } 134 dmafd[i] = expbuf.fd; 135 } 136 137 return 0; 138} 139 </programlisting> 140 </example> 141 142 <table pgwide="1" frame="none" id="v4l2-exportbuffer"> 143 <title>struct <structname>v4l2_exportbuffer</structname></title> 144 <tgroup cols="3"> 145 &cs-str; 146 <tbody valign="top"> 147 <row> 148 <entry>__u32</entry> 149 <entry><structfield>type</structfield></entry> 150 <entry>Type of the buffer, same as &v4l2-format; 151<structfield>type</structfield> or &v4l2-requestbuffers; 152<structfield>type</structfield>, set by the application. See <xref 153linkend="v4l2-buf-type" /></entry> 154 </row> 155 <row> 156 <entry>__u32</entry> 157 <entry><structfield>index</structfield></entry> 158 <entry>Number of the buffer, set by the application. This field is 159only used for <link linkend="mmap">memory mapping</link> I/O and can range from 160zero to the number of buffers allocated with the &VIDIOC-REQBUFS; and/or 161&VIDIOC-CREATE-BUFS; ioctls. </entry> 162 </row> 163 <row> 164 <entry>__u32</entry> 165 <entry><structfield>plane</structfield></entry> 166 <entry>Index of the plane to be exported when using the 167multi-planar API. Otherwise this value must be set to zero. </entry> 168 </row> 169 <row> 170 <entry>__u32</entry> 171 <entry><structfield>flags</structfield></entry> 172 <entry>Flags for the newly created file, currently only <constant> 173O_CLOEXEC </constant> is supported, refer to the manual of open() for more 174details.</entry> 175 </row> 176 <row> 177 <entry>__s32</entry> 178 <entry><structfield>fd</structfield></entry> 179 <entry>The DMABUF file descriptor associated with a buffer. Set by 180 the driver.</entry> 181 </row> 182 <row> 183 <entry>__u32</entry> 184 <entry><structfield>reserved[11]</structfield></entry> 185 <entry>Reserved field for future use. Must be set to zero.</entry> 186 </row> 187 </tbody> 188 </tgroup> 189 </table> 190 191 </refsect1> 192 193 <refsect1> 194 &return-value; 195 <variablelist> 196 <varlistentry> 197 <term><errorcode>EINVAL</errorcode></term> 198 <listitem> 199 <para>A queue is not in MMAP mode or DMABUF exporting is not 200supported or <structfield> flags </structfield> or <structfield> type 201</structfield> or <structfield> index </structfield> or <structfield> plane 202</structfield> fields are invalid.</para> 203 </listitem> 204 </varlistentry> 205 </variablelist> 206 </refsect1> 207 208</refentry> 209