Commit 55093284 authored by Guennadi Liakhovetski's avatar Guennadi Liakhovetski Committed by Mauro Carvalho Chehab
Browse files

[media] V4L: document the new VIDIOC_CREATE_BUFS and VIDIOC_PREPARE_BUF ioctl()s 



[mchehab@redhat.com: remove emacs format crap at the end of the new files]
Signed-off-by: default avatarGuennadi Liakhovetski <g.liakhovetski@gmx.de>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 21db3e07

Documentation/DocBook/media/v4l/compat.xml

+3 −0
Original line number Diff line number Diff line
@@ -2486,6 +2486,9 @@ ioctls.</para> 
        <listitem>

	  <para>Flash API. <xref linkend="flash-controls" /></para>

        </listitem>

        <listitem>

	  <para>&VIDIOC-CREATE-BUFS; and &VIDIOC-PREPARE-BUF; ioctls.</para>

        </listitem>

      </itemizedlist>

    </section>

Documentation/DocBook/media/v4l/io.xml

+27 −0
Original line number Diff line number Diff line
@@ -927,6 +927,33 @@ ioctl is called.</entry> 
Applications set or clear this flag before calling the

<constant>VIDIOC_QBUF</constant> ioctl.</entry>

	  </row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry>

	    <entry>0x0400</entry>

	    <entry>The buffer has been prepared for I/O and can be queued by the

application. Drivers set or clear this flag when the

<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link

	  linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link

	  linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link

	  linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry>

	  </row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry>

	    <entry>0x0400</entry>

	    <entry>Caches do not have to be invalidated for this buffer.

Typically applications shall use this flag if the data captured in the buffer

is not going to be touched by the CPU, instead the buffer will, probably, be

passed on to a DMA-capable hardware unit for further processing or output.

</entry>

	  </row>

	  <row>

	    <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry>

	    <entry>0x0800</entry>

	    <entry>Caches do not have to be cleaned for this buffer.

Typically applications shall use this flag for output buffers if the data

in this buffer has not been created by the CPU but by some DMA-capable unit,

in which case caches have not been used.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>

Documentation/DocBook/media/v4l/v4l2.xml

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

    &sub-ioctl;

    <!-- All ioctls go here. -->

    &sub-create-bufs;

    &sub-cropcap;

    &sub-dbg-g-chip-ident;

    &sub-dbg-g-register;
@@ -511,6 +512,7 @@ and discussions on the V4L mailing list.</revremark> 
    &sub-queryctrl;

    &sub-query-dv-preset;

    &sub-querystd;

    &sub-prepare-buf;

    &sub-reqbufs;

    &sub-s-hw-freq-seek;

    &sub-streamon;

Documentation/DocBook/media/v4l/vidioc-create-bufs.xml

0 → 100644
+139 −0
Original line number Diff line number Diff line 
<refentry id="vidioc-create-bufs">

  <refmeta>

    <refentrytitle>ioctl VIDIOC_CREATE_BUFS</refentrytitle>

    &manvol;

  </refmeta>



  <refnamediv>

    <refname>VIDIOC_CREATE_BUFS</refname>

    <refpurpose>Create buffers for Memory Mapped or User Pointer I/O</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_create_buffers *<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_CREATE_BUFS</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><parameter>argp</parameter></term>

	<listitem>

	  <para></para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>



  <refsect1>

    <title>Description</title>



    <para>This ioctl is used to create buffers for <link linkend="mmap">memory

mapped</link> or <link linkend="userp">user pointer</link>

I/O. It can be used as an alternative or in addition to the

<constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter control over buffers

is required. This ioctl can be called multiple times to create buffers of

different sizes.</para>



    <para>To allocate device buffers applications initialize relevant fields of

the <structname>v4l2_create_buffers</structname> structure. They set the

<structfield>type</structfield> field in the

<structname>v4l2_format</structname> structure, embedded in this

structure, to the respective stream or buffer type.

<structfield>count</structfield> must be set to the number of required buffers.

<structfield>memory</structfield> specifies the required I/O method. The

<structfield>format</structfield> field shall typically be filled in using

either the <constant>VIDIOC_TRY_FMT</constant> or

<constant>VIDIOC_G_FMT</constant> ioctl(). Additionally, applications can adjust

<structfield>sizeimage</structfield> fields to fit their specific needs. The

<structfield>reserved</structfield> array must be zeroed.</para>



    <para>When the ioctl is called with a pointer to this structure the driver

will attempt to allocate up to the requested number of buffers and store the

actual number allocated and the starting index in the

<structfield>count</structfield> and the <structfield>index</structfield> fields

respectively. On return <structfield>count</structfield> can be smaller than

the number requested. The driver may also increase buffer sizes if required,

however, it will not update <structfield>sizeimage</structfield> field values.

The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that

information.</para>



    <table pgwide="1" frame="none" id="v4l2-create-buffers">

      <title>struct <structname>v4l2_create_buffers</structname></title>

      <tgroup cols="3">

	&cs-str;

	<tbody valign="top">

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>index</structfield></entry>

	    <entry>The starting buffer index, returned by the driver.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>count</structfield></entry>

	    <entry>The number of buffers requested or granted.</entry>

	  </row>

	  <row>

	    <entry>&v4l2-memory;</entry>

	    <entry><structfield>memory</structfield></entry>

	    <entry>Applications set this field to

<constant>V4L2_MEMORY_MMAP</constant> or

<constant>V4L2_MEMORY_USERPTR</constant>.</entry>

	  </row>

	  <row>

	    <entry>&v4l2-format;</entry>

	    <entry><structfield>format</structfield></entry>

	    <entry>Filled in by the application, preserved by the driver.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>reserved</structfield>[8]</entry>

	    <entry>A place holder for future extensions.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>

  </refsect1>



  <refsect1>

    &return-value;



    <variablelist>

      <varlistentry>

	<term><errorcode>ENOMEM</errorcode></term>

	<listitem>

	  <para>No memory to allocate buffers for <link linkend="mmap">memory

mapped</link> I/O.</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><errorcode>EINVAL</errorcode></term>

	<listitem>

	  <para>The buffer type (<structfield>type</structfield> field) or the

requested I/O method (<structfield>memory</structfield>) is not

supported.</para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

</refentry>

Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml

0 → 100644
+88 −0
Original line number Diff line number Diff line 
<refentry id="vidioc-prepare-buf">

  <refmeta>

    <refentrytitle>ioctl VIDIOC_PREPARE_BUF</refentrytitle>

    &manvol;

  </refmeta>



  <refnamediv>

    <refname>VIDIOC_PREPARE_BUF</refname>

    <refpurpose>Prepare a buffer for I/O</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_buffer *<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_PREPARE_BUF</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><parameter>argp</parameter></term>

	<listitem>

	  <para></para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>



  <refsect1>

    <title>Description</title>



    <para>Applications can optionally call the

<constant>VIDIOC_PREPARE_BUF</constant> ioctl to pass ownership of the buffer

to the driver before actually enqueuing it, using the

<constant>VIDIOC_QBUF</constant> ioctl, and to prepare it for future I/O.

Such preparations may include cache invalidation or cleaning. Performing them

in advance saves time during the actual I/O. In case such cache operations are

not required, the application can use one of

<constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant> and

<constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant> flags to skip the respective

step.</para>



    <para>The <structname>v4l2_buffer</structname> structure is

specified in <xref linkend="buffer" />.</para>

  </refsect1>



  <refsect1>

    &return-value;



    <variablelist>

      <varlistentry>

	<term><errorcode>EBUSY</errorcode></term>

	<listitem>

	  <para>File I/O is in progress.</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><errorcode>EINVAL</errorcode></term>

	<listitem>

	  <para>The buffer <structfield>type</structfield> is not

supported, or the <structfield>index</structfield> is out of bounds,

or no buffers have been allocated yet, or the

<structfield>userptr</structfield> or

<structfield>length</structfield> are invalid.</para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

</refentry>