From ce3b5952bac17835363543ddf97e89d98b1d771f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 17 Oct 2012 10:05:09 -0300 Subject: DocBook/media/Makefile: Fix build due to uapi breakage The uapi changeset forgot to fix the header locations, needed for the DocBook specs. Fix it. Cc: David Howells Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/Makefile | 76 ++++++++++++++++++------------------ 1 file changed, 38 insertions(+), 38 deletions(-) (limited to 'Documentation/DocBook/media') diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 9b7e4c557928..f9fd615427fb 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -56,15 +56,15 @@ FUNCS = \ write \ IOCTLS = \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/videodev2.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/audio.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/ca.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/dmx.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/frontend.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([A-Z][^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/net.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/video.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/media.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/v4l2-subdev.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/videodev2.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/audio.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/ca.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/dmx.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/frontend.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([A-Z][^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/net.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/video.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/media.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ VIDIOC_SUBDEV_G_FRAME_INTERVAL \ VIDIOC_SUBDEV_S_FRAME_INTERVAL \ VIDIOC_SUBDEV_ENUM_MBUS_CODE \ @@ -74,32 +74,32 @@ IOCTLS = \ VIDIOC_SUBDEV_S_SELECTION \ TYPES = \ - $(shell perl -ne 'print "$$1 " if /^typedef\s+[^\s]+\s+([^\s]+)\;/' $(srctree)/include/linux/videodev2.h) \ - $(shell perl -ne 'print "$$1 " if /^}\s+([a-z0-9_]+_t)/' $(srctree)/include/linux/dvb/frontend.h) + $(shell perl -ne 'print "$$1 " if /^typedef\s+[^\s]+\s+([^\s]+)\;/' $(srctree)/include/uapi/linux/videodev2.h) \ + $(shell perl -ne 'print "$$1 " if /^}\s+([a-z0-9_]+_t)/' $(srctree)/include/uapi/linux/dvb/frontend.h) ENUMS = \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/videodev2.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/audio.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/ca.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/dmx.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/frontend.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/net.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/video.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/media.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-mediabus.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-subdev.h) + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/videodev2.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/audio.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/ca.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/dmx.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/frontend.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/net.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/video.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-mediabus.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) STRUCTS = \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/videodev2.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s\{]+)\s*/)' $(srctree)/include/linux/dvb/audio.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/linux/dvb/ca.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/linux/dvb/dmx.h) \ - $(shell perl -ne 'print "$$1 " if (!/dtv\_cmds\_h/ && /^struct\s+([^\s]+)\s+/)' $(srctree)/include/linux/dvb/frontend.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([A-Z][^\s]+)\s+/)' $(srctree)/include/linux/dvb/net.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/linux/dvb/video.h) \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/media.h) \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-subdev.h) \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-mediabus.h) + $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/videodev2.h) \ + $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s\{]+)\s*/)' $(srctree)/include/uapi/linux/dvb/audio.h) \ + $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/ca.h) \ + $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/dmx.h) \ + $(shell perl -ne 'print "$$1 " if (!/dtv\_cmds\_h/ && /^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/frontend.h) \ + $(shell perl -ne 'print "$$1 " if (/^struct\s+([A-Z][^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/net.h) \ + $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/video.h) \ + $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \ + $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ + $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-mediabus.h) ERRORS = \ E2BIG \ @@ -205,7 +205,7 @@ $(MEDIA_OBJ_DIR)/v4l2.xml: $(OBJIMGFILES) @(ln -sf $(MEDIA_SRC_DIR)/v4l/*xml $(MEDIA_OBJ_DIR)/) @(ln -sf $(MEDIA_SRC_DIR)/dvb/*xml $(MEDIA_OBJ_DIR)/) -$(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/linux/videodev2.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/uapi/linux/videodev2.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "") > $@ @@ -216,7 +216,7 @@ $(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/linux/videodev2.h $(MEDIA_O @( \ echo "") >> $@ -$(MEDIA_OBJ_DIR)/audio.h.xml: $(srctree)/include/linux/dvb/audio.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/audio.h.xml: $(srctree)/include/uapi/linux/dvb/audio.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "") > $@ @@ -227,7 +227,7 @@ $(MEDIA_OBJ_DIR)/audio.h.xml: $(srctree)/include/linux/dvb/audio.h $(MEDIA_OBJ_D @( \ echo "") >> $@ -$(MEDIA_OBJ_DIR)/ca.h.xml: $(srctree)/include/linux/dvb/ca.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/ca.h.xml: $(srctree)/include/uapi/linux/dvb/ca.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "") > $@ @@ -238,7 +238,7 @@ $(MEDIA_OBJ_DIR)/ca.h.xml: $(srctree)/include/linux/dvb/ca.h $(MEDIA_OBJ_DIR)/v4 @( \ echo "") >> $@ -$(MEDIA_OBJ_DIR)/dmx.h.xml: $(srctree)/include/linux/dvb/dmx.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/dmx.h.xml: $(srctree)/include/uapi/linux/dvb/dmx.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "") > $@ @@ -249,7 +249,7 @@ $(MEDIA_OBJ_DIR)/dmx.h.xml: $(srctree)/include/linux/dvb/dmx.h $(MEDIA_OBJ_DIR)/ @( \ echo "") >> $@ -$(MEDIA_OBJ_DIR)/frontend.h.xml: $(srctree)/include/linux/dvb/frontend.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/frontend.h.xml: $(srctree)/include/uapi/linux/dvb/frontend.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "") > $@ @@ -260,7 +260,7 @@ $(MEDIA_OBJ_DIR)/frontend.h.xml: $(srctree)/include/linux/dvb/frontend.h $(MEDIA @( \ echo "") >> $@ -$(MEDIA_OBJ_DIR)/net.h.xml: $(srctree)/include/linux/dvb/net.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/net.h.xml: $(srctree)/include/uapi/linux/dvb/net.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "") > $@ @@ -271,7 +271,7 @@ $(MEDIA_OBJ_DIR)/net.h.xml: $(srctree)/include/linux/dvb/net.h $(MEDIA_OBJ_DIR)/ @( \ echo "") >> $@ -$(MEDIA_OBJ_DIR)/video.h.xml: $(srctree)/include/linux/dvb/video.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/video.h.xml: $(srctree)/include/uapi/linux/dvb/video.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "") > $@ -- cgit v1.2.3-59-g8ed1b From e7d993550167ef810b6658fc7b0a73517c2ed957 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Sun, 21 Oct 2012 15:30:02 -0300 Subject: [media] v4l: Correct definition of v4l2_buffer.flags related to cache management V4L2_BUF_FLAG_NO_CACHE_INVALIDATE and V4L2_BUF_FLAG_NO_CACHE_CLEAN were define incorrectly in the documentation. Fix this by changing the documentation to match reality. Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/io.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/DocBook/media') diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index b5d1cbdc558b..7e2f3d7d78ad 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -923,7 +923,7 @@ application. Drivers set or clear this flag when the V4L2_BUF_FLAG_NO_CACHE_INVALIDATE - 0x0400 + 0x0800 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 +932,7 @@ passed on to a DMA-capable hardware unit for further processing or output. V4L2_BUF_FLAG_NO_CACHE_CLEAN - 0x0800 + 0x1000 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, -- cgit v1.2.3-59-g8ed1b From 4b9c1cb641c466cd3b366132017da3c8ab9d540c Mon Sep 17 00:00:00 2001 From: Tomasz Stanislawski Date: Thu, 14 Jun 2012 10:37:36 -0300 Subject: [media] Documentation: media: description of DMABUF importing in V4L2 This patch adds description and usage examples for importing DMABUF file descriptor in V4L2. Signed-off-by: Tomasz Stanislawski Signed-off-by: Kyungmin Park Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/compat.xml | 4 + Documentation/DocBook/media/v4l/io.xml | 181 ++++++++++++++++++++- .../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, 235 insertions(+), 30 deletions(-) (limited to 'Documentation/DocBook/media') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 4fdf6b562d1c..50eb63024eb7 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2586,6 +2586,10 @@ ioctls. Vendor and device specific media bus pixel formats. . + + Importing DMABUF file descriptors as a new IO method described + in . + diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 7e2f3d7d78ad..be0fad7e1209 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 O_NONBLOCK flag was given to the &func-open; function, VIDIOC_DQBUF returns immediately with an &EAGAIN; when no buffer is available. The -&func-select; or &func-poll; function are always available. +&func-select; or &func-poll; functions are always available. To start and stop capturing or output applications call the &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note @@ -472,6 +472,162 @@ rest should be evident. +
+ Streaming I/O (DMA buffer importing) + + + Experimental + This is an experimental + interface and may change in the future. + + +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. + +Input and output devices support the streaming I/O method when the +V4L2_CAP_STREAMING flag in the +capabilities 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 +V4L2_MEMORY_DMABUF. + + 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. + + + Initiating streaming I/O with DMABUF file descriptors + + +&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); +} + + + + 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 +VIDIOC_QBUF call. + + + Queueing DMABUF using single plane API + + +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; +} + + + + + Queueing DMABUF using multi plane API + + +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; +} + + + + 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. + + 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 +VIDIOC_DQBUF blocks when no buffer is in the +outgoing queue. When the O_NONBLOCK flag was +given to the &func-open; function, VIDIOC_DQBUF +returns immediately with an &EAGAIN; when no buffer is available. The +&func-select; and &func-poll; functions are always available. + + To start and stop capturing or displaying applications call the +&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that +VIDIOC_STREAMOFF 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; +timestamp of captured buffers, or set the field +before enqueuing buffers for output. + + Drivers implementing DMABUF importing I/O must support the +VIDIOC_REQBUFS, VIDIOC_QBUF, +VIDIOC_DQBUF, VIDIOC_STREAMON and +VIDIOC_STREAMOFF ioctls, and the +select() and poll() functions. + +
+
Asynchronous I/O @@ -672,6 +828,14 @@ memory, set by the application. See for details. in the length field of this v4l2_buffer structure. + + + int + fd + For the single-plane API and when +memory is V4L2_MEMORY_DMABUF this +is the file descriptor associated with a DMABUF buffer. + __u32 length @@ -743,6 +907,15 @@ should set this to 0. pointer to the memory allocated for this plane by an application. + + + int + fd + When the memory type in the containing &v4l2-buffer; is + V4L2_MEMORY_DMABUF, this is a file + descriptor associated with a DMABUF buffer, similar to the + fd field in &v4l2-buffer;. + __u32 data_offset @@ -964,6 +1137,12 @@ pointer I/O. 3 [to do] + + V4L2_MEMORY_DMABUF + 4 + The buffer is used for DMA shared +buffer I/O. + diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index a8cda1acacd9..cd9943672434 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -6,7 +6,8 @@ VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer I/O + Create buffers for Memory Mapped or User Pointer or DMA Buffer + I/O @@ -55,11 +56,11 @@ This ioctl is used to create buffers for memory -mapped or user pointer -I/O. It can be used as an alternative or in addition to the -VIDIOC_REQBUFS ioctl, when a tighter control over buffers -is required. This ioctl can be called multiple times to create buffers of -different sizes. +mapped or user pointer or DMA buffer I/O. It can be used as an alternative or in +addition to the VIDIOC_REQBUFS ioctl, when a tighter +control over buffers is required. This ioctl can be called multiple times to +create buffers of different sizes. To allocate device buffers applications initialize relevant fields of the v4l2_create_buffers structure. They set the @@ -109,7 +110,8 @@ information. __u32 memory Applications set this field to -V4L2_MEMORY_MMAP or +V4L2_MEMORY_MMAP, +V4L2_MEMORY_DMABUF or V4L2_MEMORY_USERPTR. See diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 2d37abefce13..3504a7f2f382 100644 --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml @@ -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. + To enqueue a DMABUF buffer applications +set the memory field to +V4L2_MEMORY_DMABUF and the m.fd +field to a file descriptor associated with a DMABUF buffer. When the +multi-planar API is used the m.fd fields of the +passed array of &v4l2-plane; have to be used instead. When +VIDIOC_QBUF is called with a pointer to this structure the +driver sets the V4L2_BUF_FLAG_QUEUED flag and clears the +V4L2_BUF_FLAG_MAPPED and +V4L2_BUF_FLAG_DONE flags in the +flags 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. + Applications call the VIDIOC_DQBUF ioctl to dequeue a filled (capturing) or displayed (output) buffer from the driver's outgoing queue. They just set the diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml index 2b50ef2007f3..78a06a9a5ece 100644 --- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml @@ -48,28 +48,30 @@ Description - This ioctl is used to initiate memory -mapped or user pointer -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. +This ioctl is used to initiate memory mapped, +user pointer or DMABUF 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. - To allocate device buffers applications initialize all -fields of the v4l2_requestbuffers structure. -They set the type field to the respective -stream or buffer type, the count field to -the desired number of buffers, memory -must be set to the requested I/O method and the reserved 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 count 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. + To allocate device buffers applications initialize all fields of the +v4l2_requestbuffers structure. They set the +type field to the respective stream or buffer type, +the count field to the desired number of buffers, +memory must be set to the requested I/O method and +the reserved 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 +count 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. When the I/O method is not supported the ioctl returns an &EINVAL;. @@ -102,7 +104,8 @@ as the &v4l2-format; type field. See __u32 memory Applications set this field to -V4L2_MEMORY_MMAP or +V4L2_MEMORY_MMAP, +V4L2_MEMORY_DMABUF or V4L2_MEMORY_USERPTR. See . -- cgit v1.2.3-59-g8ed1b From 19b6ef51640fb35666884c7b577b1a24a4be8e34 Mon Sep 17 00:00:00 2001 From: Tomasz Stanislawski Date: Thu, 14 Jun 2012 11:32:22 -0300 Subject: [media] 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 Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- 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 | 212 ++++++++++++++++++++++ 4 files changed, 219 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/vidioc-expbuf.xml (limited to 'Documentation/DocBook/media') diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 50eb63024eb7..3dd9e78815d1 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2590,6 +2590,9 @@ ioctls. Importing DMABUF file descriptors as a new IO method described in . + + Exporting DMABUF files using &VIDIOC-EXPBUF; ioctl. +
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index be0fad7e1209..388a34032653 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -488,6 +488,9 @@ 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. + Refer to DMABUF exporting for +details about exporting 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 &v4l2-capability; returned by diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 10ccde9d16d0..4d110b1ad3e9 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -543,6 +543,7 @@ and discussions on the V4L mailing list. &sub-enuminput; &sub-enumoutput; &sub-enumstd; + &sub-expbuf; &sub-g-audio; &sub-g-audioout; &sub-g-crop; diff --git a/Documentation/DocBook/media/v4l/vidioc-expbuf.xml b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml new file mode 100644 index 000000000000..72dfbd20a802 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-expbuf.xml @@ -0,0 +1,212 @@ + + + + ioctl VIDIOC_EXPBUF + &manvol; + + + + VIDIOC_EXPBUF + Export a buffer as a DMABUF file descriptor. + + + + + + int ioctl + int fd + int request + struct v4l2_exportbuffer *argp + + + + + + Arguments + + + + fd + + &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 a DMABUF file at any time after buffers have been allocated with the +&VIDIOC-REQBUFS; ioctl. + + To export a buffer, applications fill &v4l2-exportbuffer;. The + type field is set to the same buffer type as was +previously used with &v4l2-requestbuffers; type . +Applications must also set the index field. Valid +index numbers range from zero to the number of buffers allocated with +&VIDIOC-REQBUFS; (&v4l2-requestbuffers; count ) +minus one. For the multi-planar API, applications set the plane + 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 plane + to zero. Additional flags may be posted in the +flags 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 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 DMABUF-aware devices. Refer to +DMABUF importing 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. + + + +
+ Examples + + + Exporting a buffer. + +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; +} + + + + + Exporting a buffer using the multi-planar API. + +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; +} + + +
+ + + + + struct <structname>v4l2_exportbuffer</structname> + + &cs-str; + + + __u32 + type + Type of the buffer, same as &v4l2-format; +type or &v4l2-requestbuffers; +type, set by the application. See + + + __u32 + index + Number of the buffer, set by the application. This field is +only used for memory mapping I/O and can range from +zero to the number of buffers allocated with the &VIDIOC-REQBUFS; and/or +&VIDIOC-CREATE-BUFS; ioctls. + + + __u32 + plane + Index of the plane to be exported when using the +multi-planar API. Otherwise this value must be set to zero. + + + __u32 + flags + Flags for the newly created file, currently only +O_CLOEXEC is supported, refer to the manual of open() for more +details. + + + __s32 + fd + The DMABUF file descriptor associated with a buffer. Set by + the driver. + + + __u32 + reserved[11] + Reserved field for future use. Must be set to zero. + + + +
+ + + + + &return-value; + + + EINVAL + + A queue is not in MMAP mode or DMABUF exporting is not +supported or flags or type + or index or plane + fields are invalid. + + + + + + -- cgit v1.2.3-59-g8ed1b