Hi Thomas,
Thanks for the patch.
On Thursday 14 June 2012 15:37:36 Tomasz Stanislawski wrote:
> This patch adds description and usage examples for importing
> DMABUF file descriptor in V4L2.
>
> Signed-off-by: Tomasz Stanislawski <t.stanislaws@xxxxxxxxxxx>
> Signed-off-by: Kyungmin Park <kyungmin.park@xxxxxxxxxxx>
> CC: linux-doc@xxxxxxxxxxxxxxx
I just have a couple of minor comments, after taking them into account you can
add
Acked-by: Laurent Pinchart <laurent.pinchart@xxxxxxxxxxxxxxxx>
> ---
> Documentation/DocBook/media/v4l/compat.xml | 4 +
> Documentation/DocBook/media/v4l/io.xml | 179 +++++++++++++++++
> .../DocBook/media/v4l/vidioc-create-bufs.xml | 3 +-
> Documentation/DocBook/media/v4l/vidioc-qbuf.xml | 15 ++
> Documentation/DocBook/media/v4l/vidioc-reqbufs.xml | 47 ++---
> 5 files changed, 225 insertions(+), 23 deletions(-)
>
[snip]
> diff --git a/Documentation/DocBook/media/v4l/io.xml
> b/Documentation/DocBook/media/v4l/io.xml index fd6aca2..f55b0ab 100644
> --- a/Documentation/DocBook/media/v4l/io.xml
> +++ b/Documentation/DocBook/media/v4l/io.xml
[snip]
> + <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;
You need to set reqbuf.count to a non-zero value.
> +
> +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>Buffer (plane) file is passed on the fly with the &VIDIOC-QBUF;
s/file/file descriptor/
> +ioctl. In case of multiplanar buffers, every plane can be associated with a
> +different DMABUF descriptor.Although buffers are commonly cycled,
s/descriptor./descriptor. /
> applications +can pass different DMABUF descriptor at each
s/pass/pass a/
> <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>Filled 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; or &func-poll; function are always available.</para>
> +
> + <para>To start and stop capturing or output 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> ioctl, the
s/ioctl/ioctls/
s/, the/, and the/
> <function>select()</function> +and <function>poll()</function>
> function.</para>
s/function/functions/
> +
> + </section>
> +
> <section id="async">
> <title>Asynchronous I/O</title>
>
> @@ -673,6 +829,14 @@ memory, set by the application. See <xref
> linkend="userp" /> for details. <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>
> <entry></entry>
> @@ -748,6 +912,15 @@ should set this to 0.</entry>
> </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>
> <entry></entry>
> @@ -982,6 +1155,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>
> diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
> b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index
> 765549f..4444c66 100644
> --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
> +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
> @@ -103,7 +103,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>
> diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
> b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 9caa49a..cb5f5ff
> 100644
> --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
> +++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
> @@ -112,6 +112,21 @@ 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>
s/$/ field/
> +to a file descriptor associated with a
> DMABUF buffer. When the multi-planar API is +used and
s/and//
> <structfield>m.fd</structfield> 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. 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
--
Regards,
Laurent Pinchart
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
