-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[media] Documentation: media: description of DMABUF exporting in V4L2
This patch adds description and usage examples for exporting DMABUF file descriptor in V4L2. Signed-off-by: Tomasz Stanislawski <t.stanislaws@samsung.com> Signed-off-by: Kyungmin Park <kyungmin.park@samsung.com> Acked-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
- Loading branch information
Tomasz Stanislawski
authored and
Mauro Carvalho Chehab
committed
Nov 25, 2012
1 parent
b799d09
commit 19b6ef5
Showing
4 changed files
with
219 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,212 @@ | ||
| <refentry id="vidioc-expbuf"> | ||
|
|
||
| <refmeta> | ||
| <refentrytitle>ioctl VIDIOC_EXPBUF</refentrytitle> | ||
| &manvol; | ||
| </refmeta> | ||
|
|
||
| <refnamediv> | ||
| <refname>VIDIOC_EXPBUF</refname> | ||
| <refpurpose>Export a buffer as a DMABUF file descriptor.</refpurpose> | ||
| </refnamediv> | ||
|
|
||
| <refsynopsisdiv> | ||
| <funcsynopsis> | ||
| <funcprototype> | ||
| <funcdef>int <function>ioctl</function></funcdef> | ||
| <paramdef>int <parameter>fd</parameter></paramdef> | ||
| <paramdef>int <parameter>request</parameter></paramdef> | ||
| <paramdef>struct v4l2_exportbuffer *<parameter>argp</parameter></paramdef> | ||
| </funcprototype> | ||
| </funcsynopsis> | ||
| </refsynopsisdiv> | ||
|
|
||
| <refsect1> | ||
| <title>Arguments</title> | ||
|
|
||
| <variablelist> | ||
| <varlistentry> | ||
| <term><parameter>fd</parameter></term> | ||
| <listitem> | ||
| <para>&fd;</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| <varlistentry> | ||
| <term><parameter>request</parameter></term> | ||
| <listitem> | ||
| <para>VIDIOC_EXPBUF</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| <varlistentry> | ||
| <term><parameter>argp</parameter></term> | ||
| <listitem> | ||
| <para></para> | ||
| </listitem> | ||
| </varlistentry> | ||
| </variablelist> | ||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| <title>Description</title> | ||
|
|
||
| <note> | ||
| <title>Experimental</title> | ||
| <para>This is an <link linkend="experimental"> experimental </link> | ||
| interface and may change in the future.</para> | ||
| </note> | ||
|
|
||
| <para>This ioctl is an extension to the <link linkend="mmap">memory | ||
| mapping</link> I/O method, therefore it is available only for | ||
| <constant>V4L2_MEMORY_MMAP</constant> buffers. It can be used to export a | ||
| buffer as a DMABUF file at any time after buffers have been allocated with the | ||
| &VIDIOC-REQBUFS; ioctl.</para> | ||
|
|
||
| <para> To export a buffer, applications fill &v4l2-exportbuffer;. The | ||
| <structfield> type </structfield> field is set to the same buffer type as was | ||
| previously used with &v4l2-requestbuffers;<structfield> type </structfield>. | ||
| Applications must also set the <structfield> index </structfield> field. Valid | ||
| index numbers range from zero to the number of buffers allocated with | ||
| &VIDIOC-REQBUFS; (&v4l2-requestbuffers;<structfield> count </structfield>) | ||
| minus one. For the multi-planar API, applications set the <structfield> plane | ||
| </structfield> field to the index of the plane to be exported. Valid planes | ||
| range from zero to the maximal number of valid planes for the currently active | ||
| format. For the single-planar API, applications must set <structfield> plane | ||
| </structfield> to zero. Additional flags may be posted in the <structfield> | ||
| flags </structfield> field. Refer to a manual for open() for details. | ||
| Currently only O_CLOEXEC is supported. All other fields must be set to zero. | ||
| In the case of multi-planar API, every plane is exported separately using | ||
| multiple <constant> VIDIOC_EXPBUF </constant> calls. </para> | ||
|
|
||
| <para> After calling <constant>VIDIOC_EXPBUF</constant> the <structfield> fd | ||
| </structfield> field will be set by a driver. This is a DMABUF file | ||
| descriptor. The application may pass it to other DMABUF-aware devices. Refer to | ||
| <link linkend="dmabuf">DMABUF importing</link> for details about importing | ||
| DMABUF files into V4L2 nodes. It is recommended to close a DMABUF file when it | ||
| is no longer used to allow the associated memory to be reclaimed. </para> | ||
|
|
||
| </refsect1> | ||
| <refsect1> | ||
| <section> | ||
| <title>Examples</title> | ||
|
|
||
| <example> | ||
| <title>Exporting a buffer.</title> | ||
| <programlisting> | ||
| int buffer_export(int v4lfd, &v4l2-buf-type; bt, int index, int *dmafd) | ||
| { | ||
| &v4l2-exportbuffer; expbuf; | ||
|
|
||
| memset(&expbuf, 0, sizeof(expbuf)); | ||
| expbuf.type = bt; | ||
| expbuf.index = index; | ||
| if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { | ||
| perror("VIDIOC_EXPBUF"); | ||
| return -1; | ||
| } | ||
|
|
||
| *dmafd = expbuf.fd; | ||
|
|
||
| return 0; | ||
| } | ||
| </programlisting> | ||
| </example> | ||
|
|
||
| <example> | ||
| <title>Exporting a buffer using the multi-planar API.</title> | ||
| <programlisting> | ||
| int buffer_export_mp(int v4lfd, &v4l2-buf-type; bt, int index, | ||
| int dmafd[], int n_planes) | ||
| { | ||
| int i; | ||
|
|
||
| for (i = 0; i < n_planes; ++i) { | ||
| &v4l2-exportbuffer; expbuf; | ||
|
|
||
| memset(&expbuf, 0, sizeof(expbuf)); | ||
| expbuf.type = bt; | ||
| expbuf.index = index; | ||
| expbuf.plane = i; | ||
| if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &expbuf) == -1) { | ||
| perror("VIDIOC_EXPBUF"); | ||
| while (i) | ||
| close(dmafd[--i]); | ||
| return -1; | ||
| } | ||
| dmafd[i] = expbuf.fd; | ||
| } | ||
|
|
||
| return 0; | ||
| } | ||
| </programlisting> | ||
| </example> | ||
| </section> | ||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| <table pgwide="1" frame="none" id="v4l2-exportbuffer"> | ||
| <title>struct <structname>v4l2_exportbuffer</structname></title> | ||
| <tgroup cols="3"> | ||
| &cs-str; | ||
| <tbody valign="top"> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>type</structfield></entry> | ||
| <entry>Type of the buffer, same as &v4l2-format; | ||
| <structfield>type</structfield> or &v4l2-requestbuffers; | ||
| <structfield>type</structfield>, set by the application. See <xref | ||
| linkend="v4l2-buf-type" /></entry> | ||
| </row> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>index</structfield></entry> | ||
| <entry>Number of the buffer, set by the application. This field is | ||
| only used for <link linkend="mmap">memory mapping</link> I/O and can range from | ||
| zero to the number of buffers allocated with the &VIDIOC-REQBUFS; and/or | ||
| &VIDIOC-CREATE-BUFS; ioctls. </entry> | ||
| </row> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>plane</structfield></entry> | ||
| <entry>Index of the plane to be exported when using the | ||
| multi-planar API. Otherwise this value must be set to zero. </entry> | ||
| </row> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>flags</structfield></entry> | ||
| <entry>Flags for the newly created file, currently only <constant> | ||
| O_CLOEXEC </constant> is supported, refer to the manual of open() for more | ||
| details.</entry> | ||
| </row> | ||
| <row> | ||
| <entry>__s32</entry> | ||
| <entry><structfield>fd</structfield></entry> | ||
| <entry>The DMABUF file descriptor associated with a buffer. Set by | ||
| the driver.</entry> | ||
| </row> | ||
| <row> | ||
| <entry>__u32</entry> | ||
| <entry><structfield>reserved[11]</structfield></entry> | ||
| <entry>Reserved field for future use. Must be set to zero.</entry> | ||
| </row> | ||
| </tbody> | ||
| </tgroup> | ||
| </table> | ||
|
|
||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| &return-value; | ||
| <variablelist> | ||
| <varlistentry> | ||
| <term><errorcode>EINVAL</errorcode></term> | ||
| <listitem> | ||
| <para>A queue is not in MMAP mode or DMABUF exporting is not | ||
| supported or <structfield> flags </structfield> or <structfield> type | ||
| </structfield> or <structfield> index </structfield> or <structfield> plane | ||
| </structfield> fields are invalid.</para> | ||
| </listitem> | ||
| </varlistentry> | ||
| </variablelist> | ||
| </refsect1> | ||
|
|
||
| </refentry> |