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-media" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html