Documentation/DocBook/media/v4l/vidioc-expbuf.xml

   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(&amp;expbuf, 0, sizeof(expbuf));
  94         expbuf.type = bt;
  95         expbuf.index = index;
  96         if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;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 &lt; n_planes; ++i) {
 117                 &v4l2-exportbuffer; expbuf;
 118
 119                 memset(&amp;expbuf, 0, sizeof(expbuf));
 120                 expbuf.type = bt;
 121                 expbuf.index = index;
 122                 expbuf.plane = i;
 123                 if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;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>