Commit 77c53d0b authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

Merge branch 'for_3.8-rc1' into v4l_for_linus 

* for_3.8-rc1: (243 commits)
  [media] omap3isp: Replace cpu_is_omap3630() with ISP revision check
  [media] omap3isp: Prepare/unprepare clocks before/after enable/disable
  [media] omap3isp: preview: Add support for 8-bit formats at the sink pad
  [media] omap3isp: Replace printk with dev_*
  [media] omap3isp: Find source pad from external entity
  [media] omap3isp: Configure CSI-2 phy based on platform data
  [media] omap3isp: Add PHY routing configuration
  [media] omap3isp: Add CSI configuration registers from control block to ISP resources
  [media] omap3isp: Remove unneeded module memory address definitions
  [media] omap3isp: Use monotonic timestamps for statistics buffers
  [media] uvcvideo: Fix control value clamping for unsigned integer controls
  [media] uvcvideo: Mark first output terminal as default video node
  [media] uvcvideo: Add VIDIOC_[GS]_PRIORITY support
  [media] uvcvideo: Return -ENOTTY for unsupported ioctls
  [media] uvcvideo: Set device_caps in VIDIOC_QUERYCAP
  [media] uvcvideo: Don't fail when an unsupported format is requested
  [media] uvcvideo: Return -EACCES when trying to access a read/write-only control
  [media] uvcvideo: Set error_idx properly for extended controls API failures
  [media] rtl28xxu: add NOXON DAB/DAB+ USB dongle rev 2
  [media] fc2580: write some registers conditionally
  ...
parents 9374020a d8658bca

Documentation/DocBook/media/v4l/compat.xml

+7 −0
Original line number Diff line number Diff line
@@ -2586,6 +2586,13 @@ ioctls.</para> 
	  <para>Vendor and device specific media bus pixel formats.

	    <xref linkend="v4l2-mbus-vendor-spec-fmts" />.</para>

        </listitem>

        <listitem>

	  <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

+185 −3
Original line number Diff line number Diff line
@@ -331,7 +331,7 @@ application until one or more buffers can be dequeued. By default 
outgoing queue. When the <constant>O_NONBLOCK</constant> flag was

given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>

returns immediately with an &EAGAIN; when no buffer is available. The

&func-select; or &func-poll; function are always available.</para>

&func-select; or &func-poll; functions are always available.</para>



    <para>To start and stop capturing or output applications call the

&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
@@ -472,6 +472,165 @@ rest should be evident.</para> 
      </footnote></para>

  </section>



  <section id="dmabuf">

    <title>Streaming I/O (DMA buffer importing)</title>



    <note>

      <title>Experimental</title>

      <para>This is an <link linkend="experimental"> experimental </link>

      interface and may change in the future.</para>

    </note>



<para>The DMABUF framework provides a generic method for sharing buffers

between multiple devices. Device drivers that support DMABUF can export a DMA

buffer to userspace as a file descriptor (known as the exporter role), import a

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

the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through

DMABUF file descriptors is supported is determined by calling the

&VIDIOC-REQBUFS; ioctl with the memory type set to

<constant>V4L2_MEMORY_DMABUF</constant>.</para>



    <para>This I/O method is dedicated to sharing DMA buffers between different

devices, which may be V4L devices or other video-related devices (e.g. DRM).

Buffers (planes) are allocated by a driver on behalf of an application. Next,

these buffers are exported to the application as file descriptors using an API

which is specific for an allocator driver.  Only such file descriptor are

exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or

in &v4l2-plane; in the multi-planar API case).  The driver must be switched

into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer

type.</para>



    <example>

      <title>Initiating streaming I/O with DMABUF file descriptors</title>



      <programlisting>

&v4l2-requestbuffers; reqbuf;



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

reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

reqbuf.memory = V4L2_MEMORY_DMABUF;

reqbuf.count = 1;



if (ioctl(fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {

	if (errno == EINVAL)

		printf("Video capturing or DMABUF streaming is not supported\n");

	else

		perror("VIDIOC_REQBUFS");



	exit(EXIT_FAILURE);

}

      </programlisting>

    </example>



    <para>The buffer (plane) file descriptor is passed on the fly with the

&VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be

associated with a different DMABUF descriptor. Although buffers are commonly

cycled, applications can pass a different DMABUF descriptor at each

<constant>VIDIOC_QBUF</constant> call.</para>



    <example>

      <title>Queueing DMABUF using single plane API</title>



      <programlisting>

int buffer_queue(int v4lfd, int index, int dmafd)

{

	&v4l2-buffer; buf;



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

	buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;

	buf.memory = V4L2_MEMORY_DMABUF;

	buf.index = index;

	buf.m.fd = dmafd;



	if (ioctl(v4lfd, &VIDIOC-QBUF;, &amp;buf) == -1) {

		perror("VIDIOC_QBUF");

		return -1;

	}



	return 0;

}

      </programlisting>

    </example>



    <example>

      <title>Queueing DMABUF using multi plane API</title>



      <programlisting>

int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)

{

	&v4l2-buffer; buf;

	&v4l2-plane; planes[VIDEO_MAX_PLANES];

	int i;



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

	buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;

	buf.memory = V4L2_MEMORY_DMABUF;

	buf.index = index;

	buf.m.planes = planes;

	buf.length = n_planes;



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



	for (i = 0; i &lt; n_planes; ++i)

		buf.m.planes[i].m.fd = dmafd[i];



	if (ioctl(v4lfd, &VIDIOC-QBUF;, &amp;buf) == -1) {

		perror("VIDIOC_QBUF");

		return -1;

	}



	return 0;

}

      </programlisting>

    </example>



    <para>Captured or displayed buffers are dequeued with the

&VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any

time between the completion of the DMA and this ioctl. The memory is

also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or

when the device is closed.</para>



    <para>For capturing applications it is customary to enqueue a

number of empty buffers, to start capturing and enter the read loop.

Here the application waits until a filled buffer can be dequeued, and

re-enqueues the buffer when the data is no longer needed. Output

applications fill and enqueue buffers, when enough buffers are stacked

up output is started. In the write loop, when the application

runs out of free buffers it must wait until an empty buffer can be

dequeued and reused. Two methods exist to suspend execution of the

application until one or more buffers can be dequeued. By default

<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the

outgoing queue. When the <constant>O_NONBLOCK</constant> flag was

given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>

returns immediately with an &EAGAIN; when no buffer is available. The

&func-select; and &func-poll; functions are always available.</para>



    <para>To start and stop capturing or displaying applications call the

&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that

<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both queues and

unlocks all buffers as a side effect. Since there is no notion of doing

anything "now" on a multitasking system, if an application needs to synchronize

with another event it should examine the &v4l2-buffer;

<structfield>timestamp</structfield> of captured buffers, or set the field

before enqueuing buffers for output.</para>



    <para>Drivers implementing DMABUF importing I/O must support the

<constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>,

<constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and

<constant>VIDIOC_STREAMOFF</constant> ioctls, and the

<function>select()</function> and <function>poll()</function> functions.</para>



  </section>



  <section id="async">

    <title>Asynchronous I/O</title>
@@ -672,6 +831,14 @@ memory, set by the application. See <xref linkend="userp" /> for details. 
	    in the <structfield>length</structfield> field of this

	    <structname>v4l2_buffer</structname> structure.</entry>

	  </row>

	  <row>

	    <entry></entry>

	    <entry>int</entry>

	    <entry><structfield>fd</structfield></entry>

	    <entry>For the single-plane API and when

<structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this

is the file descriptor associated with a DMABUF buffer.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>length</structfield></entry>
@@ -743,6 +910,15 @@ should set this to 0.</entry> 
	      pointer to the memory allocated for this plane by an application.

	      </entry>

	  </row>

	  <row>

	    <entry></entry>

	    <entry>int</entry>

	    <entry><structfield>fd</structfield></entry>

	    <entry>When the memory type in the containing &v4l2-buffer; is

		<constant>V4L2_MEMORY_DMABUF</constant>, this is a file

		descriptor associated with a DMABUF buffer, similar to the

		<structfield>fd</structfield> field in &v4l2-buffer;.</entry>

	  </row>

	  <row>

	    <entry>__u32</entry>

	    <entry><structfield>data_offset</structfield></entry>
@@ -923,7 +1099,7 @@ application. Drivers set or clear this flag when the 
	  </row>

	  <row>

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

	    <entry>0x0400</entry>

	    <entry>0x0800</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
@@ -932,7 +1108,7 @@ passed on to a DMA-capable hardware unit for further processing or output. 
	  </row>

	  <row>

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

	    <entry>0x0800</entry>

	    <entry>0x1000</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,
@@ -964,6 +1140,12 @@ pointer</link> I/O.</entry> 
	    <entry>3</entry>

	    <entry>[to do]</entry>

	  </row>

	  <row>

	    <entry><constant>V4L2_MEMORY_DMABUF</constant></entry>

	    <entry>4</entry>

	    <entry>The buffer is used for <link linkend="dmabuf">DMA shared

buffer</link> I/O.</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>

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-create-bufs.xml

+9 −7
Original line number Diff line number Diff line
@@ -6,7 +6,8 @@ 


  <refnamediv>

    <refname>VIDIOC_CREATE_BUFS</refname>

    <refpurpose>Create buffers for Memory Mapped or User Pointer I/O</refpurpose>

    <refpurpose>Create buffers for Memory Mapped or User Pointer or DMA Buffer

    I/O</refpurpose>

  </refnamediv>



  <refsynopsisdiv>
@@ -55,11 +56,11 @@ 
    </note>



    <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>

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

linkend="dmabuf">DMA buffer</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
@@ -109,7 +110,8 @@ information.</para> 
	    <entry>__u32</entry>

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

	    <entry>Applications set this field to

<constant>V4L2_MEMORY_MMAP</constant> or

<constant>V4L2_MEMORY_MMAP</constant>,

<constant>V4L2_MEMORY_DMABUF</constant> or

<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"

/></entry>

	  </row>

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>

CRA Git | Maintained and supported by SUSTech CRA and CCSE