From patchwork Thu Apr 5 13:59:59 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tomasz Stanislawski X-Patchwork-Id: 7675 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 A111D23ECD for ; Thu, 5 Apr 2012 14:00:54 +0000 (UTC) Received: from mail-iy0-f180.google.com (mail-iy0-f180.google.com [209.85.210.180]) by fiordland.canonical.com (Postfix) with ESMTP id 37281A18AFC for ; Thu, 5 Apr 2012 14:00:54 +0000 (UTC) Received: by mail-iy0-f180.google.com with SMTP id e36so2485048iag.11 for ; Thu, 05 Apr 2012 07:00:54 -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 :mime-version:date:from:in-reply-to:to:message-id:x-mailer :references:cc:subject:x-beenthere:x-mailman-version:precedence :list-id:list-unsubscribe:list-archive:list-post:list-help :list-subscribe:content-type:content-transfer-encoding:sender :errors-to:x-gm-message-state; bh=n4miwaIjswsyp3Q6Xor4G4kJtZXKzcdc0u9JX3HCk+c=; b=YWTitwCKbWYqi3vcUrbrYke0RFjt8LL0xfGg5Mh4e/0cDbIEQz8xEck3N/LAkWb0Dd erWIBUZ5TtWos2s9sitGlnU/XSo9jLoyXLgo5UTvuiy202kcoMlCaQrUXWnrk/2lSfij fk8hD9s8Wk4kOXUGsTajaZ0h137N2R69SXkwOtMG97FwS6iHyMpe9F9whOV71U5Bwv9L Vb0QrqEknsuD0SohSJJBhG0Vq2X9CZK7Oe4tT8esVd+15gWGbHlUGSPG8T3QuBhcSMMK sVL1U7zxkunlgkR0Dt7HfAGQmgPSYI0O8YXwcUGOzz/JiptDS8TDPQioixz0wApb63qd sFhA== Received: by 10.50.168.67 with SMTP id zu3mr2036867igb.28.1333634453926; Thu, 05 Apr 2012 07:00:53 -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.231.164.217 with SMTP id f25csp61169iby; Thu, 5 Apr 2012 07:00:47 -0700 (PDT) Received: by 10.216.85.81 with SMTP id t59mr1830263wee.28.1333634440467; Thu, 05 Apr 2012 07:00:40 -0700 (PDT) Received: from mombin.canonical.com (mombin.canonical.com. [91.189.95.16]) by mx.google.com with ESMTP id de10si6238659wib.0.2012.04.05.07.00.39; Thu, 05 Apr 2012 07:00:40 -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 1SFnEq-0004SO-A1; Thu, 05 Apr 2012 14:00:36 +0000 Received: from mailout3.w1.samsung.com ([210.118.77.13]) by mombin.canonical.com with esmtp (Exim 4.71) (envelope-from ) id 1SFnEo-0003qs-Kq for linaro-mm-sig@lists.linaro.org; Thu, 05 Apr 2012 14:00:34 +0000 MIME-version: 1.0 Received: from euspt1 ([210.118.77.13]) by mailout3.w1.samsung.com (Sun Java(tm) System Messaging Server 6.3-8.04 (built Jul 29 2009; 32bit)) with ESMTP id <0M2000068EWFSN70@mailout3.w1.samsung.com> for linaro-mm-sig@lists.linaro.org; Thu, 05 Apr 2012 15:00:15 +0100 (BST) Received: from linux.samsung.com ([106.116.38.10]) by spt1.w1.samsung.com (iPlanet Messaging Server 5.2 Patch 2 (built Jul 14 2004)) with ESMTPA id <0M20009QTEWUP5@spt1.w1.samsung.com> for linaro-mm-sig@lists.linaro.org; Thu, 05 Apr 2012 15:00:31 +0100 (BST) Received: from mcdsrvbld02.digital.local (unknown [106.116.37.23]) by linux.samsung.com (Postfix) with ESMTP id DF26C270090; Thu, 05 Apr 2012 16:07:22 +0200 (CEST) Date: Thu, 05 Apr 2012 15:59:59 +0200 From: Tomasz Stanislawski In-reply-to: <1333634408-4960-1-git-send-email-t.stanislaws@samsung.com> To: linux-media@vger.kernel.org, dri-devel@lists.freedesktop.org Message-id: <1333634408-4960-3-git-send-email-t.stanislaws@samsung.com> X-Mailer: git-send-email 1.7.9.1 References: <1333634408-4960-1-git-send-email-t.stanislaws@samsung.com> Cc: pawel@osciak.com, sumit.semwal@ti.com, robdclark@gmail.com, linaro-mm-sig@lists.linaro.org, kyungmin.park@samsung.com, airlied@redhat.com Subject: [Linaro-mm-sig] [PATCH 02/11] 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: , Sender: linaro-mm-sig-bounces@lists.linaro.org Errors-To: linaro-mm-sig-bounces@lists.linaro.org X-Gm-Message-State: ALoCoQmyfiFOm5NVzDgF8uUXj1keFMTjUTsbjMAqeEBtRvr7IW4UYbTD+mQTcnB0rXV1om83klzR This patch adds description and usage examples for importing DMABUF file descriptor in V4L2. Signed-off-by: Tomasz Stanislawski Signed-off-by: Kyungmin Park --- Documentation/DocBook/media/v4l/compat.xml | 4 + Documentation/DocBook/media/v4l/io.xml | 177 ++++++++++++++++++++ .../DocBook/media/v4l/vidioc-create-bufs.xml | 1 + Documentation/DocBook/media/v4l/vidioc-qbuf.xml | 15 ++ Documentation/DocBook/media/v4l/vidioc-reqbufs.xml | 8 +- 5 files changed, 203 insertions(+), 2 deletions(-) diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index bce97c5..2a2083d 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2523,6 +2523,10 @@ ioctls. Selection API. + + 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 b815929..2a32363 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -472,6 +472,160 @@ 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 was introduced to provide a generic mean for sharing +buffers between multiple HW devices. Some device drivers provide an API that +may be capable to export a DMA buffer as a DMABUF file descriptor. The other +device drivers may be configured to use such a buffer. They implements an API +for importing of DMABUF. This section describes the support of DMABUF importing +in V4L2. + + Input and output devices support this I/O method when the +V4L2_CAP_STREAMING flag in the +capabilities field of &v4l2-capability; returned by +the &VIDIOC-QUERYCAP; ioctl is set. If the particular importing buffer via +DMABUF file descriptors method is supported must be determined by calling the +&VIDIOC-REQBUFS; ioctl. + + This I/O method is dedicated for sharing DMA buffers between V4L and +other APIs. Buffers (planes) are allocated by the application itself using +a client API. The buffers must be exported as DMABUF file descriptor. Only those +file descriptor are exchanged, these files 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. No buffers (planes) are allocated beforehand, consequently +they are not indexed and cannot be queried like mapped buffers with the +VIDIOC_QUERYBUF ioctl. + + + 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; + +if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { + if (errno == EINVAL) + printf ("Video capturing or user pointer streaming is not supported\n"); + else + perror ("VIDIOC_REQBUFS"); + + exit (EXIT_FAILURE); +} + + + + Buffer (plane) file 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 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; +} + + + + Filled or displayed buffers are dequeued with the +&VIDIOC-DQBUF; ioctl. The driver can unpin the buffer at any +time between the completion of the DMA and this ioctl. The memory is +also unpinned 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; or &func-poll; function are always available. + + To start and stop capturing or output applications call the +&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note +VIDIOC_STREAMOFF removes all buffers from both queues and +unlocks/unpins 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 user pointer I/O must support the +VIDIOC_REQBUFS, VIDIOC_QBUF, +VIDIOC_DQBUF, VIDIOC_STREAMON and +VIDIOC_STREAMOFF ioctl, the select() +and poll() function. + +
+
Asynchronous I/O @@ -671,6 +825,14 @@ memory, set by the application. See for details. v4l2_buffer structure. + + int + fd + For the single-planar API and when +memory is V4L2_MEMORY_DMABUF this +is the file descriptor associated with a DMABUF buffer. + + __u32 length @@ -746,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 @@ -980,6 +1151,12 @@ pointer I/O. 3 [to do] + + V4L2_MEMORY_DMABUF + 2 + 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 73ae8a6..adc92be 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -98,6 +98,7 @@ information. memory Applications set this field to V4L2_MEMORY_MMAP or +V4L2_MEMORY_DMABUF or V4L2_MEMORY_USERPTR. diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 9caa49a..d4f212f 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. + To enqueue a DMABUF buffer applications +set the memory field to +V4L2_MEMORY_DMABUF, the m.fd +field to the file descriptor to a DMABUF buffer. When the multi-planar API is +used, m.fd 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 may pin and lock the buffer. Buffers remain locked/pinned 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 7be4b1d..d758622 100644 --- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml @@ -50,11 +50,14 @@ This ioctl is used to initiate memory mapped or user pointer -I/O. Memory mapped buffers are located in device memory and must be +I/O or DMABUF file descriptors. +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. +driver into user pointer I/O mode and to setup some internal structures. +A DMABUF file descriptor is a generic carrier for HW allocated buffers +dedicated to share them between multimedia APIs. To allocate device buffers applications initialize all fields of the v4l2_requestbuffers structure. @@ -103,6 +106,7 @@ as the &v4l2-format; type field. See memory Applications set this field to V4L2_MEMORY_MMAP or +V4L2_MEMORY_DMABUF or V4L2_MEMORY_USERPTR.