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