From patchwork Wed Oct 10 14:46:21 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tomasz Stanislawski X-Patchwork-Id: 12111 Return-Path: X-Original-To: patchwork@peony.canonical.com Delivered-To: patchwork@peony.canonical.com Received: from fiordland.canonical.com (fiordland.canonical.com [91.189.94.145]) by peony.canonical.com (Postfix) with ESMTP id 87F0F24189 for ; Wed, 10 Oct 2012 14:48:50 +0000 (UTC) Received: from mail-ie0-f180.google.com (mail-ie0-f180.google.com [209.85.223.180]) by fiordland.canonical.com (Postfix) with ESMTP id E3C71A18EFC for ; Wed, 10 Oct 2012 14:48:49 +0000 (UTC) Received: by mail-ie0-f180.google.com with SMTP id e10so991843iej.11 for ; Wed, 10 Oct 2012 07:48:49 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=x-forwarded-to:x-forwarded-for:delivered-to:received-spf:x-auditid :from:to:date:message-id:x-mailer:in-reply-to:references :x-brightmail-tracker:cc:subject:x-beenthere:x-mailman-version :precedence:list-id:list-unsubscribe:list-archive:list-post :list-help:list-subscribe:mime-version:content-type :content-transfer-encoding:sender:errors-to:x-gm-message-state; bh=sSsVEAMzfY2IgXcI4dKNocBbKNNB2pituuttrxqDsFg=; b=hdhdVrBVYa0jLFvXK02jxrRmpfOeOGsXKvqo1EAuQHUGaIMlSxApDgtT/LGc0PdmEa SR3UN6TDdVatt/jcNIs1XtJeQehyMRKLVQ/WkDQ6NjzriiH/YLToq6f21aGVM9mT0Va7 S1+gxzOGIvFOmL/EstFK8i6wuYwKEJurdiEkWYXr70xdv2H4+RlUL41e8VPSYHme12nw QJUECqbDMF/Wu0sScunw8elkg2s7SJr7Y0P9yS7FH+ZOWjkZkCzN1lubM31LImX31Nqu EWeh6DubId6ux0CQhXj0SP9f2sjD6IyCuhTpuTEgicVXEukYr3vsfEY74jhQhM+Q8JZw WJyA== Received: by 10.50.157.201 with SMTP id wo9mr5434691igb.57.1349880529273; Wed, 10 Oct 2012 07:48:49 -0700 (PDT) X-Forwarded-To: linaro-patchwork@canonical.com X-Forwarded-For: patch@linaro.org linaro-patchwork@canonical.com Delivered-To: patches@linaro.org Received: by 10.50.67.148 with SMTP id n20csp235514igt; Wed, 10 Oct 2012 07:48:47 -0700 (PDT) Received: by 10.180.94.226 with SMTP id df2mr13512181wib.11.1349880526066; Wed, 10 Oct 2012 07:48:46 -0700 (PDT) Received: from mombin.canonical.com (mombin.canonical.com. [91.189.95.16]) by mx.google.com with ESMTP id c28si1774570wep.30.2012.10.10.07.48.44; Wed, 10 Oct 2012 07:48:46 -0700 (PDT) Received-SPF: neutral (google.com: 91.189.95.16 is neither permitted nor denied by best guess record for domain of linaro-mm-sig-bounces@lists.linaro.org) client-ip=91.189.95.16; Authentication-Results: mx.google.com; spf=neutral (google.com: 91.189.95.16 is neither permitted nor denied by best guess record for domain of linaro-mm-sig-bounces@lists.linaro.org) smtp.mail=linaro-mm-sig-bounces@lists.linaro.org Received: from localhost ([127.0.0.1] helo=mombin.canonical.com) by mombin.canonical.com with esmtp (Exim 4.71) (envelope-from ) id 1TLxaU-0000nG-Pw; Wed, 10 Oct 2012 14:48:42 +0000 Received: from mailout4.samsung.com ([203.254.224.34]) by mombin.canonical.com with esmtp (Exim 4.71) (envelope-from ) id 1TLxaS-0000jJ-Lo for linaro-mm-sig@lists.linaro.org; Wed, 10 Oct 2012 14:48:41 +0000 Received: from epcpsbgm2.samsung.com (epcpsbgm2 [203.254.230.27]) by mailout4.samsung.com (Oracle Communications Messaging Server 7u4-24.01(7.0.4.24.0) 64bit (built Nov 17 2011)) with ESMTP id <0MBO00B6GMH2K980@mailout4.samsung.com> for linaro-mm-sig@lists.linaro.org; Wed, 10 Oct 2012 23:48:38 +0900 (KST) X-AuditID: cbfee61b-b7f2b6d000000f14-dd-50758ac6c3fb Received: from epmmp1.local.host ( [203.254.227.16]) by epcpsbgm2.samsung.com (EPCPMTA) with SMTP id C0.CA.03860.6CA85705; Wed, 10 Oct 2012 23:48:38 +0900 (KST) Received: from mcdsrvbld02.digital.local ([106.116.37.23]) by mmp1.samsung.com (Oracle Communications Messaging Server 7u4-24.01 (7.0.4.24.0) 64bit (built Nov 17 2011)) with ESMTPA id <0MBO002YDME0EC70@mmp1.samsung.com> for linaro-mm-sig@lists.linaro.org; Wed, 10 Oct 2012 23:48:38 +0900 (KST) From: Tomasz Stanislawski To: linux-media@vger.kernel.org, dri-devel@lists.freedesktop.org Date: Wed, 10 Oct 2012 16:46:21 +0200 Message-id: <1349880405-26049-3-git-send-email-t.stanislaws@samsung.com> X-Mailer: git-send-email 1.7.10 In-reply-to: <1349880405-26049-1-git-send-email-t.stanislaws@samsung.com> References: <1349880405-26049-1-git-send-email-t.stanislaws@samsung.com> X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFnrEJMWRmVeSWpSXmKPExsVy+t9jAd1jXaUBBn/vC1p8ufKQyYHR4/a/ x8wBjFFcNimpOZllqUX6dglcGa+uHWYrmNzNWHHqfW4D4//iLkYODgkBE4kZZ727GDmBTDGJ C/fWs3UxcnEICSxilFjSOB3KWcsksXLqTHaQKjaghmNLPjOC2CICDhKn785iBiliFjjJLPHk +iuwhLBApMT8+ZeZQWwWAVWJbRfXMYFs4xXwkJi2JB1im7zE0/t9bCA2p4CnxIV508HKhYBK /q/fzDSBkXcBI8MqRtHUguSC4qT0XCO94sTc4tK8dL3k/NxNjGCfP5PewbiqweIQowAHoxIP b0VGSYAQa2JZcWXuIUYJDmYlEV5Tn9IAId6UxMqq1KL8+KLSnNTiQ4zSHCxK4rzNHikBQgLp iSWp2ampBalFMFkmDk6pBsbVDEuUiu3ufPKstLmtMtkq3lpuctb/7o5mg7Aj5UoPdp6dHq4T nsqw5dWMR84xW45mX9r7yVdhZ+CzD7FvwveufuY5ub/dTmrx3dv5nwNvSHKu+CHTtTjjTu+a 5l0ixhtUo05UCN8POSX5udzD7VbCsrPN7z4oOjt06r26HWLa67zmY/yLH2VKLMUZiYZazEXF iQD2v3Bh9QEAAA== Cc: k.debski@samsung.com, s.nawrocki@samsung.com, pawel@osciak.com, sumit.semwal@ti.com, linux-doc@vger.kernel.org, mchehab@redhat.com, robdclark@gmail.com, linaro-mm-sig@lists.linaro.org, kyungmin.park@samsung.com, laurent.pinchart@ideasonboard.com, airlied@redhat.com, remi@remlab.net Subject: [Linaro-mm-sig] [PATCHv10 02/26] Documentation: media: description of DMABUF importing in V4L2 X-BeenThere: linaro-mm-sig@lists.linaro.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: "Unified memory management interest group." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: linaro-mm-sig-bounces@lists.linaro.org Errors-To: linaro-mm-sig-bounces@lists.linaro.org X-Gm-Message-State: ALoCoQnq1mlQDntSNewuIc7C+F9hajBx0ziEH7SyVBm/6NTbuOa4z797Adu/bjJcFcbamOLVRGVx This patch adds description and usage examples for importing DMABUF file descriptor in V4L2. Signed-off-by: Tomasz Stanislawski Signed-off-by: Kyungmin Park CC: linux-doc@vger.kernel.org Acked-by: Hans Verkuil --- 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(-) diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 4fdf6b5..50eb630 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 b5d1cbd..0abb5cb 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 @@ -673,6 +829,14 @@ memory, set by the application. See for details. 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 @@ -744,6 +908,15 @@ should set this to 0. + + 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 a8cda1a..cd99436 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 2d37abe..3504a7f 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 2b50ef2..78a06a9 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 .