[PATCHv8 17/26] Documentation: media: description of DMABUF exporting in V4L2
On Tue August 14 2012 17:34:47 Tomasz Stanislawski wrote:
> This patch adds description and usage examples for exporting
> DMABUF file descriptor in V4L2.
>
> Signed-off-by: Tomasz Stanislawski
> Signed-off-by: Kyungmin Park
> CC: linux-doc at vger.kernel.org
> ---
> Documentation/DocBook/media/v4l/compat.xml|3 +
> Documentation/DocBook/media/v4l/io.xml|3 +
> Documentation/DocBook/media/v4l/v4l2.xml |1 +
> Documentation/DocBook/media/v4l/vidioc-expbuf.xml | 223
> +
> 4 files changed, 230 insertions(+)
> create mode 100644 Documentation/DocBook/media/v4l/vidioc-expbuf.xml
>
> diff --git a/Documentation/DocBook/media/v4l/compat.xml
> b/Documentation/DocBook/media/v4l/compat.xml
> index ff45330..802c1ab 100644
> --- a/Documentation/DocBook/media/v4l/compat.xml
> +++ b/Documentation/DocBook/media/v4l/compat.xml
> @@ -2609,6 +2609,9 @@ ioctls.
> Importing DMABUF file descriptors as a new IO method described
> in .
>
> +
> + Exporting DMABUF files using ioctl.
> +
>
>
>
> diff --git a/Documentation/DocBook/media/v4l/io.xml
> b/Documentation/DocBook/media/v4l/io.xml
> index 98253ee..c27e59b 100644
> --- a/Documentation/DocBook/media/v4l/io.xml
> +++ b/Documentation/DocBook/media/v4l/io.xml
> @@ -488,6 +488,9 @@ 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.
>
> +Refer to DMABUF exporting for
> +details about exporting a V4L2 buffers as DMABUF file descriptors.
> +
> Input and output devices support the streaming I/O method when the
> V4L2_CAP_STREAMING flag in the
> capabilities field of returned
> by
> diff --git a/Documentation/DocBook/media/v4l/v4l2.xml
> b/Documentation/DocBook/media/v4l/v4l2.xml
> index 0292ed1..874c085 100644
> --- a/Documentation/DocBook/media/v4l/v4l2.xml
> +++ b/Documentation/DocBook/media/v4l/v4l2.xml
> @@ -568,6 +568,7 @@ and discussions on the V4L mailing list.
>
>
>
> +
This list is sorted alphabetically, so sub-expbuf should go after sub-enumstd.
>
>
>
> diff --git a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml
> b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml
> new file mode 100644
> index 000..30ebf67
> --- /dev/null
> +++ b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml
> @@ -0,0 +1,223 @@
> +
> +
> +
> +ioctl VIDIOC_EXPBUF
> +
> +
> +
> +
> +VIDIOC_EXPBUF
> +Export a buffer as a DMABUF file descriptor.
> +
> +
> +
> +
> +
> + int ioctl
> + int fd
> + int request
> + struct v4l2_exportbuffer
> *argp
> +
> +
> +
> +
> +
> +Arguments
> +
> +
> +
> + fd
> +
> +
> +
> +
> +
> + request
> +
> + VIDIOC_EXPBUF
> +
> +
> +
> + argp
> +
> +
> +
> +
> +
> +
> +
> +
> +Description
> +
> +
> + Experimental
> + This is an experimental
> + interface and may change in the future.
> +
> +
> +This ioctl is an extension to the memory
> +mapping I/O method therefore it is available only for
> +V4L2_MEMORY_MMAP buffers. It can be used to export a
> +buffer as DMABUF file at any time after buffers have been allocated with the
> + ioctl.
> +
> +Prior to exporting an application calls +linkend="vidioc-querybuf">VIDIOC_QUERYBUF to obtain memory offsets.
> When
> +using the multi-planar API every plane has
> +own offset.
> +
> +To export a buffer, the application fills . The
> + mem_offset field is set to the offset obtained
> +from VIDIOC_QUERYBUF . Additional flags may be posted
> in
> +the flags field. Refer to manual for open
> syscall
Better IMHO: 'Refer to the manual for open()'
> +for details. Currently only O_CLOEXEC is guaranteed to be supported. All
> other
> +fields must be set to zero. In a case of multi-planar API, every plane is
> +exported separately using multiple VIDIOC_EXPBUF
> +calls.
> +
> + After calling VIDIOC_EXPBUF the fd
> + field will be set by a driver. This is a DMABUF file
> +descriptor. The application may pass it to other API. Refer to +linkend="dmabuf">DMABUF importing for details about importing DMABUF
> +files into V4L2 nodes. A developer is encouraged to close a DMABUF file when
> it
> +is no longer used.
Some explanation of why this is recommended would be useful.
> +
> +
> +
> +
> + Examples
> +
> +
> + Exporting a buffer.
> +
> +int buffer_export(int v4lfd, bt, int index, int *dmafd)
> +{
> + buf;
> + expbuf;
> +
> + memset(buf, 0, sizeof buf);
> + buf.type = bt;
> + buf.memory = V4L2_MEMORY_MMAP;
> + buf.index = index;
> +
> + if (ioctl (v4lfd, , buf) == -1) {
> + perror ("VIDIOC_QUERYBUF");
> +
Re: [PATCHv8 17/26] Documentation: media: description of DMABUF exporting in V4L2
On Tue August 14 2012 17:34:47 Tomasz Stanislawski wrote: This patch adds description and usage examples for exporting 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|3 + Documentation/DocBook/media/v4l/io.xml|3 + Documentation/DocBook/media/v4l/v4l2.xml |1 + Documentation/DocBook/media/v4l/vidioc-expbuf.xml | 223 + 4 files changed, 230 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/vidioc-expbuf.xml diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index ff45330..802c1ab 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2609,6 +2609,9 @@ ioctls./para paraImporting DMABUF file descriptors as a new IO method described in xref linkend=dmabuf /./para /listitem +listitem + paraExporting DMABUF files using VIDIOC-EXPBUF; ioctl./para +/listitem /itemizedlist /section diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 98253ee..c27e59b 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -488,6 +488,9 @@ 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 +paraRefer to link linked=vidioc-expbuf DMABUF exporting /link for +details about exporting a V4L2 buffers as DMABUF file descriptors./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 diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 0292ed1..874c085 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -568,6 +568,7 @@ and discussions on the V4L mailing list./revremark sub-overlay; sub-prepare-buf; sub-qbuf; +sub-expbuf; This list is sorted alphabetically, so sub-expbuf should go after sub-enumstd. sub-querybuf; sub-querycap; sub-queryctrl; diff --git a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml new file mode 100644 index 000..30ebf67 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml @@ -0,0 +1,223 @@ +refentry id=vidioc-expbuf + + refmeta +refentrytitleioctl VIDIOC_EXPBUF/refentrytitle +manvol; + /refmeta + + refnamediv +refnameVIDIOC_EXPBUF/refname +refpurposeExport a buffer as a DMABUF file descriptor./refpurpose + /refnamediv + + refsynopsisdiv +funcsynopsis + funcprototype + funcdefint functionioctl/function/funcdef + paramdefint parameterfd/parameter/paramdef + paramdefint parameterrequest/parameter/paramdef + paramdefstruct v4l2_exportbuffer *parameterargp/parameter/paramdef + /funcprototype +/funcsynopsis + /refsynopsisdiv + + refsect1 +titleArguments/title + +variablelist + varlistentry + termparameterfd/parameter/term + listitem + parafd;/para + /listitem + /varlistentry + varlistentry + termparameterrequest/parameter/term + listitem + paraVIDIOC_EXPBUF/para + /listitem + /varlistentry + varlistentry + termparameterargp/parameter/term + listitem + para/para + /listitem + /varlistentry +/variablelist + /refsect1 + + refsect1 +titleDescription/title + +note + titleExperimental/title + paraThis is an link linkend=experimental experimental /link + interface and may change in the future./para +/note + +paraThis ioctl is an extension to the link linkend=mmapmemory +mapping/link I/O method therefore it is available only for +constantV4L2_MEMORY_MMAP/constant buffers. It can be used to export a +buffer as DMABUF file at any time after buffers have been allocated with the +VIDIOC-REQBUFS; ioctl./para + +paraPrior to exporting an application calls link +linkend=vidioc-querybufVIDIOC_QUERYBUF/link to obtain memory offsets. When +using the link linkend=planar-apismulti-planar API/link every plane has +own offset./para + +paraTo export a buffer, the application fills v4l2-exportbuffer;. The +structfield mem_offset /structfield field is set to the offset obtained +from constant VIDIOC_QUERYBUF /constant. Additional flags may be posted in +the structfield flags /structfield field. Refer
[PATCHv8 17/26] Documentation: media: description of DMABUF exporting in V4L2
This patch adds description and usage examples for exporting
DMABUF file descriptor in V4L2.
Signed-off-by: Tomasz Stanislawski
Signed-off-by: Kyungmin Park
CC: linux-doc at vger.kernel.org
---
Documentation/DocBook/media/v4l/compat.xml|3 +
Documentation/DocBook/media/v4l/io.xml|3 +
Documentation/DocBook/media/v4l/v4l2.xml |1 +
Documentation/DocBook/media/v4l/vidioc-expbuf.xml | 223 +
4 files changed, 230 insertions(+)
create mode 100644 Documentation/DocBook/media/v4l/vidioc-expbuf.xml
diff --git a/Documentation/DocBook/media/v4l/compat.xml
b/Documentation/DocBook/media/v4l/compat.xml
index ff45330..802c1ab 100644
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2609,6 +2609,9 @@ ioctls.
Importing DMABUF file descriptors as a new IO method described
in .
+
+ Exporting DMABUF files using ioctl.
+
diff --git a/Documentation/DocBook/media/v4l/io.xml
b/Documentation/DocBook/media/v4l/io.xml
index 98253ee..c27e59b 100644
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -488,6 +488,9 @@ 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.
+Refer to DMABUF exporting for
+details about exporting a V4L2 buffers as DMABUF file descriptors.
+
Input and output devices support the streaming I/O method when the
V4L2_CAP_STREAMING flag in the
capabilities field of returned by
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml
b/Documentation/DocBook/media/v4l/v4l2.xml
index 0292ed1..874c085 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -568,6 +568,7 @@ and discussions on the V4L mailing list.
+
diff --git a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml
b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml
new file mode 100644
index 000..30ebf67
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml
@@ -0,0 +1,223 @@
+
+
+
+ioctl VIDIOC_EXPBUF
+
+
+
+
+VIDIOC_EXPBUF
+Export a buffer as a DMABUF file descriptor.
+
+
+
+
+
+ int ioctl
+ int fd
+ int request
+ struct v4l2_exportbuffer
*argp
+
+
+
+
+
+Arguments
+
+
+
+ fd
+
+
+
+
+
+ request
+
+ VIDIOC_EXPBUF
+
+
+
+ argp
+
+
+
+
+
+
+
+
+Description
+
+
+ Experimental
+ This is an experimental
+ interface and may change in the future.
+
+
+This ioctl is an extension to the memory
+mapping I/O method therefore it is available only for
+V4L2_MEMORY_MMAP buffers. It can be used to export a
+buffer as DMABUF file at any time after buffers have been allocated with the
+ ioctl.
+
+Prior to exporting an application calls VIDIOC_QUERYBUF to obtain memory offsets. When
+using the multi-planar API every plane has
+own offset.
+
+To export a buffer, the application fills . The
+ mem_offset field is set to the offset obtained
+from VIDIOC_QUERYBUF . Additional flags may be posted in
+the flags field. Refer to manual for open syscall
+for details. Currently only O_CLOEXEC is guaranteed to be supported. All other
+fields must be set to zero. In a case of multi-planar API, every plane is
+exported separately using multiple VIDIOC_EXPBUF
+calls.
+
+ After calling VIDIOC_EXPBUF the fd
+ field will be set by a driver. This is a DMABUF file
+descriptor. The application may pass it to other API. Refer to DMABUF importing for details about importing DMABUF
+files into V4L2 nodes. A developer is encouraged to close a DMABUF file when it
+is no longer used.
+
+
+
+
+ Examples
+
+
+ Exporting a buffer.
+
+int buffer_export(int v4lfd, bt, int index, int *dmafd)
+{
+buf;
+expbuf;
+
+ memset(buf, 0, sizeof buf);
+ buf.type = bt;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = index;
+
+ if (ioctl (v4lfd, , buf) == -1) {
+ perror ("VIDIOC_QUERYBUF");
+ return -1;
+ }
+
+ memset(expbuf, 0, sizeof expbuf);
+ expbuf.mem_offset = buf.m.offset;
+ if (ioctl (v4lfd, , expbuf) == -1) {
+ perror ("VIDIOC_EXPBUF");
+ return -1;
+ }
+
+ *dmafd = expbuf.fd;
+
+ return 0;
+}
+
+
+
+
+ Exporting a buffer using multi plane API.
+
+int buffer_export_mp(int v4lfd, bt, int index,
+ int dmafd[], int n_planes)
+{
+buf;
+planes[VIDEO_MAX_PLANES];
+ int i;
+
+ memset(buf, 0, sizeof buf);
+ buf.type = bt;
+
[PATCHv8 17/26] Documentation: media: description of DMABUF exporting in V4L2
This patch adds description and usage examples for exporting 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|3 + Documentation/DocBook/media/v4l/io.xml|3 + Documentation/DocBook/media/v4l/v4l2.xml |1 + Documentation/DocBook/media/v4l/vidioc-expbuf.xml | 223 + 4 files changed, 230 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/vidioc-expbuf.xml diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index ff45330..802c1ab 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2609,6 +2609,9 @@ ioctls./para paraImporting DMABUF file descriptors as a new IO method described in xref linkend=dmabuf /./para /listitem +listitem + paraExporting DMABUF files using VIDIOC-EXPBUF; ioctl./para +/listitem /itemizedlist /section diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 98253ee..c27e59b 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -488,6 +488,9 @@ 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 +paraRefer to link linked=vidioc-expbuf DMABUF exporting /link for +details about exporting a V4L2 buffers as DMABUF file descriptors./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 diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 0292ed1..874c085 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -568,6 +568,7 @@ and discussions on the V4L mailing list./revremark sub-overlay; sub-prepare-buf; sub-qbuf; +sub-expbuf; sub-querybuf; sub-querycap; sub-queryctrl; diff --git a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml new file mode 100644 index 000..30ebf67 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml @@ -0,0 +1,223 @@ +refentry id=vidioc-expbuf + + refmeta +refentrytitleioctl VIDIOC_EXPBUF/refentrytitle +manvol; + /refmeta + + refnamediv +refnameVIDIOC_EXPBUF/refname +refpurposeExport a buffer as a DMABUF file descriptor./refpurpose + /refnamediv + + refsynopsisdiv +funcsynopsis + funcprototype + funcdefint functionioctl/function/funcdef + paramdefint parameterfd/parameter/paramdef + paramdefint parameterrequest/parameter/paramdef + paramdefstruct v4l2_exportbuffer *parameterargp/parameter/paramdef + /funcprototype +/funcsynopsis + /refsynopsisdiv + + refsect1 +titleArguments/title + +variablelist + varlistentry + termparameterfd/parameter/term + listitem + parafd;/para + /listitem + /varlistentry + varlistentry + termparameterrequest/parameter/term + listitem + paraVIDIOC_EXPBUF/para + /listitem + /varlistentry + varlistentry + termparameterargp/parameter/term + listitem + para/para + /listitem + /varlistentry +/variablelist + /refsect1 + + refsect1 +titleDescription/title + +note + titleExperimental/title + paraThis is an link linkend=experimental experimental /link + interface and may change in the future./para +/note + +paraThis ioctl is an extension to the link linkend=mmapmemory +mapping/link I/O method therefore it is available only for +constantV4L2_MEMORY_MMAP/constant buffers. It can be used to export a +buffer as DMABUF file at any time after buffers have been allocated with the +VIDIOC-REQBUFS; ioctl./para + +paraPrior to exporting an application calls link +linkend=vidioc-querybufVIDIOC_QUERYBUF/link to obtain memory offsets. When +using the link linkend=planar-apismulti-planar API/link every plane has +own offset./para + +paraTo export a buffer, the application fills v4l2-exportbuffer;. The +structfield mem_offset /structfield field is set to the offset obtained +from constant VIDIOC_QUERYBUF /constant. Additional flags may be posted in +the structfield flags /structfield field. Refer to manual for open syscall +for details. Currently only O_CLOEXEC is guaranteed to be supported. All other +fields must be set to zero. In a case of multi-planar API, every plane is +exported separately using multiple constant VIDIOC_EXPBUF
