Skip to content

Commit 77c53d0

Browse files
author
Mauro Carvalho Chehab
committed
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 ...
2 parents 9374020 + d8658bc commit 77c53d0

314 files changed

Lines changed: 7754 additions & 1863 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Documentation/DocBook/media/v4l/compat.xml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2586,6 +2586,13 @@ ioctls.</para>
25862586
<para>Vendor and device specific media bus pixel formats.
25872587
<xref linkend="v4l2-mbus-vendor-spec-fmts" />.</para>
25882588
</listitem>
2589+
<listitem>
2590+
<para>Importing DMABUF file descriptors as a new IO method described
2591+
in <xref linkend="dmabuf" />.</para>
2592+
</listitem>
2593+
<listitem>
2594+
<para>Exporting DMABUF files using &VIDIOC-EXPBUF; ioctl.</para>
2595+
</listitem>
25892596
</itemizedlist>
25902597
</section>
25912598

‎Documentation/DocBook/media/v4l/io.xml‎

Lines changed: 185 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -331,7 +331,7 @@ application until one or more buffers can be dequeued. By default
331331
outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
332332
given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
333333
returns immediately with an &EAGAIN; when no buffer is available. The
334-
&func-select; or &func-poll; function are always available.</para>
334+
&func-select; or &func-poll; functions are always available.</para>
335335

336336
<para>To start and stop capturing or output applications call the
337337
&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
@@ -472,6 +472,165 @@ rest should be evident.</para>
472472
</footnote></para>
473473
</section>
474474

475+
<section id="dmabuf">
476+
<title>Streaming I/O (DMA buffer importing)</title>
477+
478+
<note>
479+
<title>Experimental</title>
480+
<para>This is an <link linkend="experimental"> experimental </link>
481+
interface and may change in the future.</para>
482+
</note>
483+
484+
<para>The DMABUF framework provides a generic method for sharing buffers
485+
between multiple devices. Device drivers that support DMABUF can export a DMA
486+
buffer to userspace as a file descriptor (known as the exporter role), import a
487+
DMA buffer from userspace using a file descriptor previously exported for a
488+
different or the same device (known as the importer role), or both. This
489+
section describes the DMABUF importer role API in V4L2.</para>
490+
491+
<para>Refer to <link linked="vidioc-expbuf"> DMABUF exporting </link> for
492+
details about exporting V4L2 buffers as DMABUF file descriptors.</para>
493+
494+
<para>Input and output devices support the streaming I/O method when the
495+
<constant>V4L2_CAP_STREAMING</constant> flag in the
496+
<structfield>capabilities</structfield> field of &v4l2-capability; returned by
497+
the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through
498+
DMABUF file descriptors is supported is determined by calling the
499+
&VIDIOC-REQBUFS; ioctl with the memory type set to
500+
<constant>V4L2_MEMORY_DMABUF</constant>.</para>
501+
502+
<para>This I/O method is dedicated to sharing DMA buffers between different
503+
devices, which may be V4L devices or other video-related devices (e.g. DRM).
504+
Buffers (planes) are allocated by a driver on behalf of an application. Next,
505+
these buffers are exported to the application as file descriptors using an API
506+
which is specific for an allocator driver. Only such file descriptor are
507+
exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or
508+
in &v4l2-plane; in the multi-planar API case). The driver must be switched
509+
into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer
510+
type.</para>
511+
512+
<example>
513+
<title>Initiating streaming I/O with DMABUF file descriptors</title>
514+
515+
<programlisting>
516+
&v4l2-requestbuffers; reqbuf;
517+
518+
memset(&amp;reqbuf, 0, sizeof (reqbuf));
519+
reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
520+
reqbuf.memory = V4L2_MEMORY_DMABUF;
521+
reqbuf.count = 1;
522+
523+
if (ioctl(fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {
524+
if (errno == EINVAL)
525+
printf("Video capturing or DMABUF streaming is not supported\n");
526+
else
527+
perror("VIDIOC_REQBUFS");
528+
529+
exit(EXIT_FAILURE);
530+
}
531+
</programlisting>
532+
</example>
533+
534+
<para>The buffer (plane) file descriptor is passed on the fly with the
535+
&VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be
536+
associated with a different DMABUF descriptor. Although buffers are commonly
537+
cycled, applications can pass a different DMABUF descriptor at each
538+
<constant>VIDIOC_QBUF</constant> call.</para>
539+
540+
<example>
541+
<title>Queueing DMABUF using single plane API</title>
542+
543+
<programlisting>
544+
int buffer_queue(int v4lfd, int index, int dmafd)
545+
{
546+
&v4l2-buffer; buf;
547+
548+
memset(&amp;buf, 0, sizeof buf);
549+
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
550+
buf.memory = V4L2_MEMORY_DMABUF;
551+
buf.index = index;
552+
buf.m.fd = dmafd;
553+
554+
if (ioctl(v4lfd, &VIDIOC-QBUF;, &amp;buf) == -1) {
555+
perror("VIDIOC_QBUF");
556+
return -1;
557+
}
558+
559+
return 0;
560+
}
561+
</programlisting>
562+
</example>
563+
564+
<example>
565+
<title>Queueing DMABUF using multi plane API</title>
566+
567+
<programlisting>
568+
int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
569+
{
570+
&v4l2-buffer; buf;
571+
&v4l2-plane; planes[VIDEO_MAX_PLANES];
572+
int i;
573+
574+
memset(&amp;buf, 0, sizeof buf);
575+
buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
576+
buf.memory = V4L2_MEMORY_DMABUF;
577+
buf.index = index;
578+
buf.m.planes = planes;
579+
buf.length = n_planes;
580+
581+
memset(&amp;planes, 0, sizeof planes);
582+
583+
for (i = 0; i &lt; n_planes; ++i)
584+
buf.m.planes[i].m.fd = dmafd[i];
585+
586+
if (ioctl(v4lfd, &VIDIOC-QBUF;, &amp;buf) == -1) {
587+
perror("VIDIOC_QBUF");
588+
return -1;
589+
}
590+
591+
return 0;
592+
}
593+
</programlisting>
594+
</example>
595+
596+
<para>Captured or displayed buffers are dequeued with the
597+
&VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any
598+
time between the completion of the DMA and this ioctl. The memory is
599+
also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
600+
when the device is closed.</para>
601+
602+
<para>For capturing applications it is customary to enqueue a
603+
number of empty buffers, to start capturing and enter the read loop.
604+
Here the application waits until a filled buffer can be dequeued, and
605+
re-enqueues the buffer when the data is no longer needed. Output
606+
applications fill and enqueue buffers, when enough buffers are stacked
607+
up output is started. In the write loop, when the application
608+
runs out of free buffers it must wait until an empty buffer can be
609+
dequeued and reused. Two methods exist to suspend execution of the
610+
application until one or more buffers can be dequeued. By default
611+
<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
612+
outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
613+
given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
614+
returns immediately with an &EAGAIN; when no buffer is available. The
615+
&func-select; and &func-poll; functions are always available.</para>
616+
617+
<para>To start and stop capturing or displaying applications call the
618+
&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that
619+
<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both queues and
620+
unlocks all buffers as a side effect. Since there is no notion of doing
621+
anything "now" on a multitasking system, if an application needs to synchronize
622+
with another event it should examine the &v4l2-buffer;
623+
<structfield>timestamp</structfield> of captured buffers, or set the field
624+
before enqueuing buffers for output.</para>
625+
626+
<para>Drivers implementing DMABUF importing I/O must support the
627+
<constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>,
628+
<constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and
629+
<constant>VIDIOC_STREAMOFF</constant> ioctls, and the
630+
<function>select()</function> and <function>poll()</function> functions.</para>
631+
632+
</section>
633+
475634
<section id="async">
476635
<title>Asynchronous I/O</title>
477636

@@ -672,6 +831,14 @@ memory, set by the application. See <xref linkend="userp" /> for details.
672831
in the <structfield>length</structfield> field of this
673832
<structname>v4l2_buffer</structname> structure.</entry>
674833
</row>
834+
<row>
835+
<entry></entry>
836+
<entry>int</entry>
837+
<entry><structfield>fd</structfield></entry>
838+
<entry>For the single-plane API and when
839+
<structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this
840+
is the file descriptor associated with a DMABUF buffer.</entry>
841+
</row>
675842
<row>
676843
<entry>__u32</entry>
677844
<entry><structfield>length</structfield></entry>
@@ -743,6 +910,15 @@ should set this to 0.</entry>
743910
pointer to the memory allocated for this plane by an application.
744911
</entry>
745912
</row>
913+
<row>
914+
<entry></entry>
915+
<entry>int</entry>
916+
<entry><structfield>fd</structfield></entry>
917+
<entry>When the memory type in the containing &v4l2-buffer; is
918+
<constant>V4L2_MEMORY_DMABUF</constant>, this is a file
919+
descriptor associated with a DMABUF buffer, similar to the
920+
<structfield>fd</structfield> field in &v4l2-buffer;.</entry>
921+
</row>
746922
<row>
747923
<entry>__u32</entry>
748924
<entry><structfield>data_offset</structfield></entry>
@@ -923,7 +1099,7 @@ application. Drivers set or clear this flag when the
9231099
</row>
9241100
<row>
9251101
<entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry>
926-
<entry>0x0400</entry>
1102+
<entry>0x0800</entry>
9271103
<entry>Caches do not have to be invalidated for this buffer.
9281104
Typically applications shall use this flag if the data captured in the buffer
9291105
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.
9321108
</row>
9331109
<row>
9341110
<entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry>
935-
<entry>0x0800</entry>
1111+
<entry>0x1000</entry>
9361112
<entry>Caches do not have to be cleaned for this buffer.
9371113
Typically applications shall use this flag for output buffers if the data
9381114
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>
9641140
<entry>3</entry>
9651141
<entry>[to do]</entry>
9661142
</row>
1143+
<row>
1144+
<entry><constant>V4L2_MEMORY_DMABUF</constant></entry>
1145+
<entry>4</entry>
1146+
<entry>The buffer is used for <link linkend="dmabuf">DMA shared
1147+
buffer</link> I/O.</entry>
1148+
</row>
9671149
</tbody>
9681150
</tgroup>
9691151
</table>

‎Documentation/DocBook/media/v4l/v4l2.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -543,6 +543,7 @@ and discussions on the V4L mailing list.</revremark>
543543
&sub-enuminput;
544544
&sub-enumoutput;
545545
&sub-enumstd;
546+
&sub-expbuf;
546547
&sub-g-audio;
547548
&sub-g-audioout;
548549
&sub-g-crop;

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

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@
66

77
<refnamediv>
88
<refname>VIDIOC_CREATE_BUFS</refname>
9-
<refpurpose>Create buffers for Memory Mapped or User Pointer I/O</refpurpose>
9+
<refpurpose>Create buffers for Memory Mapped or User Pointer or DMA Buffer
10+
I/O</refpurpose>
1011
</refnamediv>
1112

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

5758
<para>This ioctl is used to create buffers for <link linkend="mmap">memory
58-
mapped</link> or <link linkend="userp">user pointer</link>
59-
I/O. It can be used as an alternative or in addition to the
60-
<constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter control over buffers
61-
is required. This ioctl can be called multiple times to create buffers of
62-
different sizes.</para>
59+
mapped</link> or <link linkend="userp">user pointer</link> or <link
60+
linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in
61+
addition to the <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter
62+
control over buffers is required. This ioctl can be called multiple times to
63+
create buffers of different sizes.</para>
6364

6465
<para>To allocate device buffers applications initialize relevant fields of
6566
the <structname>v4l2_create_buffers</structname> structure. They set the
@@ -109,7 +110,8 @@ information.</para>
109110
<entry>__u32</entry>
110111
<entry><structfield>memory</structfield></entry>
111112
<entry>Applications set this field to
112-
<constant>V4L2_MEMORY_MMAP</constant> or
113+
<constant>V4L2_MEMORY_MMAP</constant>,
114+
<constant>V4L2_MEMORY_DMABUF</constant> or
113115
<constant>V4L2_MEMORY_USERPTR</constant>. See <xref linkend="v4l2-memory"
114116
/></entry>
115117
</row>

0 commit comments

Comments
 (0)