Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 19b6ef51 authored by Tomasz Stanislawski's avatar Tomasz Stanislawski Committed by Mauro Carvalho Chehab
Browse files

[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: default avatarTomasz Stanislawski <t.stanislaws@samsung.com>
Signed-off-by: default avatarKyungmin Park <kyungmin.park@samsung.com>
Acked-by: default avatarHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent b799d09a

Documentation/DocBook/media/v4l/compat.xml

+3 −0
Original line number Diff line number Diff line
@@ -2590,6 +2590,9 @@ ioctls.</para> 
	  <para>Importing DMABUF file descriptors as a new IO method described

	  in <xref linkend="dmabuf" />.</para>

        </listitem>

        <listitem>

	  <para>Exporting DMABUF files using &VIDIOC-EXPBUF; ioctl.</para>

        </listitem>

      </itemizedlist>

    </section>

Documentation/DocBook/media/v4l/io.xml

+3 −0
Original line number Diff line number Diff line
@@ -488,6 +488,9 @@ DMA buffer from userspace using a file descriptor previously exported for a 
different or the same device (known as the importer role), or both. This

section describes the DMABUF importer role API in V4L2.</para>



    <para>Refer to <link linked="vidioc-expbuf"> DMABUF exporting </link> for

details about exporting V4L2 buffers as DMABUF file descriptors.</para>



<para>Input and output devices support the streaming I/O method when the

<constant>V4L2_CAP_STREAMING</constant> flag in the

<structfield>capabilities</structfield> field of &v4l2-capability; returned by

Documentation/DocBook/media/v4l/v4l2.xml

+1 −0
Original line number Diff line number Diff line
@@ -543,6 +543,7 @@ and discussions on the V4L mailing list.</revremark> 
    &sub-enuminput;

    &sub-enumoutput;

    &sub-enumstd;

    &sub-expbuf;

    &sub-g-audio;

    &sub-g-audioout;

    &sub-g-crop;

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

0 → 100644
+212 −0
Original line number Diff line number Diff line 
<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(&amp;expbuf, 0, sizeof(expbuf));

	expbuf.type = bt;

	expbuf.index = index;

	if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;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 &lt; n_planes; ++i) {

		&v4l2-exportbuffer; expbuf;



		memset(&amp;expbuf, 0, sizeof(expbuf));

		expbuf.type = bt;

		expbuf.index = index;

		expbuf.plane = i;

		if (ioctl(v4lfd, &VIDIOC-EXPBUF;, &amp;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>