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 is supported.  All other fields must be set to zero.
  77 In the case of multi-planar API, every plane is exported separately using
  78 multiple <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
  82 descriptor. The application may pass it to other DMABUF-aware devices. Refer to
  83 <link linkend="dmabuf">DMABUF importing</link> for details about importing
  84 DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it
  85 is 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>
  94 int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd)
  95 {
  96         &v4l2-exportbuffer; expbuf;
  97
  98         memset(&amp;expbuf, 0, sizeof(expbuf));
  99         expbuf.type = bt;
 100         expbuf.index = index;
 101         if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;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>
 116 int 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 &lt; n_planes; ++i) {
 122                 &v4l2-exportbuffer; expbuf;
 123
 124                 memset(&amp;expbuf, 0, sizeof(expbuf));
 125                 expbuf.type = bt;
 126                 expbuf.index = index;
 127                 expbuf.plane = i;
 128                 if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;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
 153 linkend="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
 159 only used for <link linkend="mmap">memory mapping</link> I/O and can range from
 160 zero 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
 167 multi-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>
 173 O_CLOEXEC </constant> is supported, refer to the manual of open() for more
 174 details.</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
 200 supported 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>