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