Tomasz Stanislawski | 19b6ef5 | 2012-06-14 11:32:22 -0300 | [diff] [blame] | 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. |
Philipp Zabel | c1b96a2 | 2013-05-21 05:11:35 -0300 | [diff] [blame] | 76 | Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, and O_RDWR are supported. All |
| 77 | other fields must be set to zero. |
Tomasz Stanislawski | 19b6ef5 | 2012-06-14 11:32:22 -0300 | [diff] [blame] | 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> |
Tomasz Stanislawski | 19b6ef5 | 2012-06-14 11:32:22 -0300 | [diff] [blame] | 87 | </refsect1> |
Tomasz Stanislawski | 19b6ef5 | 2012-06-14 11:32:22 -0300 | [diff] [blame] | 88 | |
Hans Verkuil | 07b64b8 | 2013-01-11 08:18:55 -0300 | [diff] [blame] | 89 | <refsect1> |
| 90 | <title>Examples</title> |
| 91 | |
| 92 | <example> |
| 93 | <title>Exporting a buffer.</title> |
| 94 | <programlisting> |
Tomasz Stanislawski | 19b6ef5 | 2012-06-14 11:32:22 -0300 | [diff] [blame] | 95 | int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd) |
| 96 | { |
| 97 | &v4l2-exportbuffer; expbuf; |
| 98 | |
| 99 | memset(&expbuf, 0, sizeof(expbuf)); |
| 100 | expbuf.type = bt; |
| 101 | expbuf.index = index; |
| 102 | if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { |
| 103 | perror("VIDIOC_EXPBUF"); |
| 104 | return -1; |
| 105 | } |
| 106 | |
| 107 | *dmafd = expbuf.fd; |
| 108 | |
| 109 | return 0; |
| 110 | } |
Hans Verkuil | 07b64b8 | 2013-01-11 08:18:55 -0300 | [diff] [blame] | 111 | </programlisting> |
| 112 | </example> |
Tomasz Stanislawski | 19b6ef5 | 2012-06-14 11:32:22 -0300 | [diff] [blame] | 113 | |
Hans Verkuil | 07b64b8 | 2013-01-11 08:18:55 -0300 | [diff] [blame] | 114 | <example> |
| 115 | <title>Exporting a buffer using the multi-planar API.</title> |
| 116 | <programlisting> |
Tomasz Stanislawski | 19b6ef5 | 2012-06-14 11:32:22 -0300 | [diff] [blame] | 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 < n_planes; ++i) { |
| 123 | &v4l2-exportbuffer; expbuf; |
| 124 | |
| 125 | memset(&expbuf, 0, sizeof(expbuf)); |
| 126 | expbuf.type = bt; |
| 127 | expbuf.index = index; |
| 128 | expbuf.plane = i; |
| 129 | if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &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 | } |
Hans Verkuil | 07b64b8 | 2013-01-11 08:18:55 -0300 | [diff] [blame] | 140 | </programlisting> |
| 141 | </example> |
Tomasz Stanislawski | 19b6ef5 | 2012-06-14 11:32:22 -0300 | [diff] [blame] | 142 | |
Tomasz Stanislawski | 19b6ef5 | 2012-06-14 11:32:22 -0300 | [diff] [blame] | 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> |
Philipp Zabel | c1b96a2 | 2013-05-21 05:11:35 -0300 | [diff] [blame] | 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> |
Tomasz Stanislawski | 19b6ef5 | 2012-06-14 11:32:22 -0300 | [diff] [blame] | 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. Must be set to zero.</entry> |
| 188 | </row> |
| 189 | </tbody> |
| 190 | </tgroup> |
| 191 | </table> |
| 192 | |
| 193 | </refsect1> |
| 194 | |
| 195 | <refsect1> |
| 196 | &return-value; |
| 197 | <variablelist> |
| 198 | <varlistentry> |
| 199 | <term><errorcode>EINVAL</errorcode></term> |
| 200 | <listitem> |
| 201 | <para>A queue is not in MMAP mode or DMABUF exporting is not |
| 202 | supported or <structfield> flags </structfield> or <structfield> type |
| 203 | </structfield> or <structfield> index </structfield> or <structfield> plane |
| 204 | </structfield> fields are invalid.</para> |
| 205 | </listitem> |
| 206 | </varlistentry> |
| 207 | </variablelist> |
| 208 | </refsect1> |
| 209 | |
| 210 | </refentry> |