Merge branch 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media updates from Mauro Carvalho Chehab: - Missing MAINTAINERS entries were added for several drivers - Adds V4L2 support for DMABUF handling, allowing zero-copy buffer sharing between V4L2 devices and GPU - Got rid of all warnings when compiling with W=1 on x86 - Add a new driver for Exynos hardware (s3c-camif) - Several bug fixes, cleanups and driver improvements * 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (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 ...
This commit is contained in:
Linus Torvalds
@@ -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>
|
||||
|
||||
|
||||
@@ -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(&reqbuf, 0, sizeof (reqbuf));
|
||||
reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
|
||||
reqbuf.memory = V4L2_MEMORY_DMABUF;
|
||||
reqbuf.count = 1;
|
||||
|
||||
if (ioctl(fd, &VIDIOC-REQBUFS;, &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(&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;, &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(&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(&planes, 0, sizeof planes);
|
||||
|
||||
for (i = 0; i < n_planes; ++i)
|
||||
buf.m.planes[i].m.fd = dmafd[i];
|
||||
|
||||
if (ioctl(v4lfd, &VIDIOC-QBUF;, &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>
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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>
|
||||
|
||||
212
Documentation/DocBook/media/v4l/vidioc-expbuf.xml
Normal file
212
Documentation/DocBook/media/v4l/vidioc-expbuf.xml
Normal file
@@ -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>
|
||||
@@ -109,6 +109,23 @@ they cannot be swapped out to disk. Buffers remain locked until
|
||||
dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is
|
||||
called, or until the device is closed.</para>
|
||||
|
||||
<para>To enqueue a <link linkend="dmabuf">DMABUF</link> buffer applications
|
||||
set the <structfield>memory</structfield> field to
|
||||
<constant>V4L2_MEMORY_DMABUF</constant> and the <structfield>m.fd</structfield>
|
||||
field to a file descriptor associated with a DMABUF buffer. When the
|
||||
multi-planar API is used the <structfield>m.fd</structfield> fields of the
|
||||
passed array of &v4l2-plane; have to be used instead. When
|
||||
<constant>VIDIOC_QBUF</constant> is called with a pointer to this structure the
|
||||
driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the
|
||||
<constant>V4L2_BUF_FLAG_MAPPED</constant> and
|
||||
<constant>V4L2_BUF_FLAG_DONE</constant> flags in the
|
||||
<structfield>flags</structfield> field, or it returns an error code. This
|
||||
ioctl locks the buffer. Locking a buffer means passing it to a driver for a
|
||||
hardware access (usually DMA). If an application accesses (reads/writes) a
|
||||
locked buffer then the result is undefined. Buffers remain locked until
|
||||
dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is called, or
|
||||
until the device is closed.</para>
|
||||
|
||||
<para>Applications call the <constant>VIDIOC_DQBUF</constant>
|
||||
ioctl to dequeue a filled (capturing) or displayed (output) buffer
|
||||
from the driver's outgoing queue. They just set the
|
||||
|
||||
@@ -48,28 +48,30 @@
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>This ioctl is used to initiate <link linkend="mmap">memory
|
||||
mapped</link> or <link linkend="userp">user pointer</link>
|
||||
I/O. Memory mapped buffers are located in device memory and must be
|
||||
allocated with this ioctl before they can be mapped into the
|
||||
application's address space. User buffers are allocated by
|
||||
applications themselves, and this ioctl is merely used to switch the
|
||||
driver into user pointer I/O mode and to setup some internal structures.</para>
|
||||
<para>This ioctl is used to initiate <link linkend="mmap">memory mapped</link>,
|
||||
<link linkend="userp">user pointer</link> or <link
|
||||
linkend="dmabuf">DMABUF</link> based I/O. Memory mapped buffers are located in
|
||||
device memory and must be allocated with this ioctl before they can be mapped
|
||||
into the application's address space. User buffers are allocated by
|
||||
applications themselves, and this ioctl is merely used to switch the driver
|
||||
into user pointer I/O mode and to setup some internal structures.
|
||||
Similarly, DMABUF buffers are allocated by applications through a device
|
||||
driver, and this ioctl only configures the driver into DMABUF I/O mode without
|
||||
performing any direct allocation.</para>
|
||||
|
||||
<para>To allocate device buffers applications initialize all
|
||||
fields of the <structname>v4l2_requestbuffers</structname> structure.
|
||||
They set the <structfield>type</structfield> field to the respective
|
||||
stream or buffer type, the <structfield>count</structfield> field to
|
||||
the desired number of buffers, <structfield>memory</structfield>
|
||||
must be set to the requested I/O method and the <structfield>reserved</structfield> array
|
||||
must be zeroed. When the ioctl
|
||||
is called with a pointer to this structure the driver will attempt to allocate
|
||||
the requested number of buffers and it stores the actual number
|
||||
allocated in the <structfield>count</structfield> field. It can be
|
||||
smaller than the number requested, even zero, when the driver runs out
|
||||
of free memory. A larger number is also possible when the driver requires
|
||||
more buffers to function correctly. For example video output requires at least two buffers,
|
||||
one displayed and one filled by the application.</para>
|
||||
<para>To allocate device buffers applications initialize all fields of the
|
||||
<structname>v4l2_requestbuffers</structname> structure. They set the
|
||||
<structfield>type</structfield> field to the respective stream or buffer type,
|
||||
the <structfield>count</structfield> field to the desired number of buffers,
|
||||
<structfield>memory</structfield> must be set to the requested I/O method and
|
||||
the <structfield>reserved</structfield> array must be zeroed. When the ioctl is
|
||||
called with a pointer to this structure the driver will attempt to allocate the
|
||||
requested number of buffers and it stores the actual number allocated in the
|
||||
<structfield>count</structfield> field. It can be smaller than the number
|
||||
requested, even zero, when the driver runs out of free memory. A larger number
|
||||
is also possible when the driver requires more buffers to function correctly.
|
||||
For example video output requires at least two buffers, one displayed and one
|
||||
filled by the application.</para>
|
||||
<para>When the I/O method is not supported the ioctl
|
||||
returns an &EINVAL;.</para>
|
||||
|
||||
@@ -102,7 +104,8 @@ as the &v4l2-format; <structfield>type</structfield> field. See <xref
|
||||
<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>
|
||||
|
||||
Reference in New Issue
Block a user