Re: [PATCHv9 02/25] Documentation: media: description of DMABUF importing in V4L2

2012-10-05 Thread Hans Verkuil 
Hi Tomasz,

Just a few more stylistic issues...

On Tue October 2 2012 16:27:13 Tomasz Stanislawski wrote:
 This patch adds description and usage examples for importing
 DMABUF file descriptor in V4L2.
 
 Signed-off-by: Tomasz Stanislawski t.stanisl...@samsung.com
 Signed-off-by: Kyungmin Park kyungmin.p...@samsung.com
 CC: linux-...@vger.kernel.org
 ---
  Documentation/DocBook/media/v4l/compat.xml |4 +
  Documentation/DocBook/media/v4l/io.xml |  180 
 +++-
  .../DocBook/media/v4l/vidioc-create-bufs.xml   |   16 +-
  Documentation/DocBook/media/v4l/vidioc-qbuf.xml|   17 ++
  Documentation/DocBook/media/v4l/vidioc-reqbufs.xml |   47 ++---
  5 files changed, 234 insertions(+), 30 deletions(-)
 
 diff --git a/Documentation/DocBook/media/v4l/compat.xml 
 b/Documentation/DocBook/media/v4l/compat.xml
 index faa0fd1..a46f95b 100644
 --- a/Documentation/DocBook/media/v4l/compat.xml
 +++ b/Documentation/DocBook/media/v4l/compat.xml
 @@ -2621,6 +2621,10 @@ ioctls./para
  listitem
 paraSupport for frequency band enumeration: 
 VIDIOC-ENUM-FREQ-BANDS; ioctl./para
  /listitem
 +listitem
 +   paraImporting DMABUF file descriptors as a new IO method described
 +   in xref linkend=dmabuf /./para
 +/listitem
/itemizedlist
  /section
  
 diff --git a/Documentation/DocBook/media/v4l/io.xml 
 b/Documentation/DocBook/media/v4l/io.xml
 index 1885cc0..5b58657 100644
 --- a/Documentation/DocBook/media/v4l/io.xml
 +++ b/Documentation/DocBook/media/v4l/io.xml
 @@ -331,7 +331,7 @@ application until one or more buffers can be dequeued. By 
 default
  outgoing queue. When the constantO_NONBLOCK/constant flag was
  given to the func-open; function, constantVIDIOC_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
  
  paraTo start and stop capturing or output applications call the
  VIDIOC-STREAMON; and VIDIOC-STREAMOFF; ioctl. Note
 @@ -472,6 +472,161 @@ rest should be evident./para
/footnote/para
/section
  
 +  section id=dmabuf
 +titleStreaming I/O (DMA buffer importing)/title
 +
 +note
 +  titleExperimental/title
 +  paraThis is an link linkend=experimental experimental /link
 +  interface and may change in the future./para
 +/note
 +
 +paraThe 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
 +
 +paraInput and output devices support the streaming I/O method when the
 +constantV4L2_CAP_STREAMING/constant flag in the
 +structfieldcapabilities/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
 +constantV4L2_MEMORY_DMABUF/constant./para
 +
 +paraThis I/O method is dedicated for sharing DMA buffers between V4L 
 and
 +other APIs.

It's more accurate to say something along the lines of: ...is dedicated to 
sharing
DMA buffers between different devices, which may be V4L devices or other
video-related devices (e.g. DRM).

One of the uses of this API is to share buffers between different V4L devices, 
so
that's a bit more generic than the original sentence suggests.

 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
 +  titleInitiating streaming I/O with DMABUF file descriptors/title
 +
 +  programlisting
 +v4l2-requestbuffers; reqbuf;
 +
 +memset (amp;reqbuf, 0, sizeof (reqbuf));

no space after memset

 +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 +reqbuf.memory = V4L2_MEMORY_DMABUF;
 +reqbuf.count = 1;
 +
 +if (ioctl (fd, VIDIOC-REQBUFS;, amp;reqbuf) == -1) {

no space after ioctl

 + if (errno == EINVAL)
 + printf(Video capturing or DMABUF streaming is not 
 supported\n);
 + else
 + perror(VIDIOC_REQBUFS);
 +
 + exit(EXIT_FAILURE);
 +}
 +  /programlisting
 +/example
 +
 +paraThe buffer (plane) file descriptor is passed on the fly with

[PATCHv9 02/25] Documentation: media: description of DMABUF importing in V4L2

2012-10-02 Thread Tomasz Stanislawski 
This patch adds description and usage examples for importing
DMABUF file descriptor in V4L2.

Signed-off-by: Tomasz Stanislawski t.stanisl...@samsung.com
Signed-off-by: Kyungmin Park kyungmin.p...@samsung.com
CC: linux-...@vger.kernel.org
---
 Documentation/DocBook/media/v4l/compat.xml |4 +
 Documentation/DocBook/media/v4l/io.xml |  180 +++-
 .../DocBook/media/v4l/vidioc-create-bufs.xml   |   16 +-
 Documentation/DocBook/media/v4l/vidioc-qbuf.xml|   17 ++
 Documentation/DocBook/media/v4l/vidioc-reqbufs.xml |   47 ++---
 5 files changed, 234 insertions(+), 30 deletions(-)

diff --git a/Documentation/DocBook/media/v4l/compat.xml 
b/Documentation/DocBook/media/v4l/compat.xml
index faa0fd1..a46f95b 100644
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2621,6 +2621,10 @@ ioctls./para
 listitem
  paraSupport for frequency band enumeration: 
VIDIOC-ENUM-FREQ-BANDS; ioctl./para
 /listitem
+listitem
+ paraImporting DMABUF file descriptors as a new IO method described
+ in xref linkend=dmabuf /./para
+/listitem
   /itemizedlist
 /section
 
diff --git a/Documentation/DocBook/media/v4l/io.xml 
b/Documentation/DocBook/media/v4l/io.xml
index 1885cc0..5b58657 100644
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -331,7 +331,7 @@ application until one or more buffers can be dequeued. By 
default
 outgoing queue. When the constantO_NONBLOCK/constant flag was
 given to the func-open; function, constantVIDIOC_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
 
 paraTo start and stop capturing or output applications call the
 VIDIOC-STREAMON; and VIDIOC-STREAMOFF; ioctl. Note
@@ -472,6 +472,161 @@ rest should be evident./para
   /footnote/para
   /section
 
+  section id=dmabuf
+titleStreaming I/O (DMA buffer importing)/title
+
+note
+  titleExperimental/title
+  paraThis is an link linkend=experimental experimental /link
+  interface and may change in the future./para
+/note
+
+paraThe 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
+
+paraInput and output devices support the streaming I/O method when the
+constantV4L2_CAP_STREAMING/constant flag in the
+structfieldcapabilities/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
+constantV4L2_MEMORY_DMABUF/constant./para
+
+paraThis I/O method is dedicated for sharing DMA buffers between V4L and
+other APIs.  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
+  titleInitiating 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
+
+paraThe 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
+constantVIDIOC_QBUF/constant call./para
+
+example
+  titleQueueing 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;
+