From patchwork Wed Aug 24 18:41:28 2011 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Guennadi Liakhovetski X-Patchwork-Id: 1093902 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by demeter1.kernel.org (8.14.4/8.14.4) with ESMTP id p7OIfmg8025634 for ; Wed, 24 Aug 2011 18:41:48 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753803Ab1HXSlq (ORCPT ); Wed, 24 Aug 2011 14:41:46 -0400 Received: from moutng.kundenserver.de ([212.227.17.9]:58998 "EHLO moutng.kundenserver.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753764Ab1HXSlp (ORCPT ); Wed, 24 Aug 2011 14:41:45 -0400 Received: from axis700.grange (dslb-094-221-126-224.pools.arcor-ip.net [94.221.126.224]) by mrelayeu.kundenserver.de (node=mreu4) with ESMTP (Nemesis) id 0MFW2y-1Qzdub250m-00EL5w; Wed, 24 Aug 2011 20:41:34 +0200 Received: from 6a.grange (6a.grange [192.168.1.11]) by axis700.grange (Postfix) with ESMTPS id A6E63189F9A; Wed, 24 Aug 2011 20:41:32 +0200 (CEST) Received: from lyakh by 6a.grange with local (Exim 4.72) (envelope-from ) id 1QwIOK-0002iY-Bu; Wed, 24 Aug 2011 20:41:32 +0200 From: Guennadi Liakhovetski To: Linux Media Mailing List Cc: Hans Verkuil , Laurent Pinchart , Pawel Osciak , Sakari Ailus , Mauro Carvalho Chehab , Marek Szyprowski Subject: [PATCH 3/7 v5] V4L: document the new VIDIOC_CREATE_BUFS and VIDIOC_PREPARE_BUF ioctl()s Date: Wed, 24 Aug 2011 20:41:28 +0200 Message-Id: <1314211292-10414-4-git-send-email-g.liakhovetski@gmx.de> X-Mailer: git-send-email 1.7.2.5 In-Reply-To: <1314211292-10414-1-git-send-email-g.liakhovetski@gmx.de> References: <1314211292-10414-1-git-send-email-g.liakhovetski@gmx.de> X-Provags-ID: V02:K0:QELyUHqMqmp0BfI5uoURPqC1yRXxx8hBmd2K59aoYOk vf31Bwf+k9tq/Vz4ZfiFCjTD2dnVffW+/ql+2z/BSKuRU8vZ2a tHx5YEj4MJeuitVxqfKmMZkgNym5g0O92HleQotWxsLhCTsF29 sPACQXscI+jbpn5ryqVnBqSAbAmUnNLQvHrNnPeo6Yok8/FmPz KX1OCDgloMFolPNTvjM2zrupRTZuOkhRgtDODjnRLU= Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Greylist: IP, sender and recipient auto-whitelisted, not delayed by milter-greylist-4.2.6 (demeter1.kernel.org [140.211.167.41]); Wed, 24 Aug 2011 18:41:49 +0000 (UTC) Signed-off-by: Guennadi Liakhovetski Cc: Hans Verkuil Cc: Laurent Pinchart Cc: Marek Szyprowski Cc: Mauro Carvalho Chehab Cc: Pawel Osciak Cc: Sakari Ailus --- Documentation/DocBook/media/v4l/io.xml | 17 +++ Documentation/DocBook/media/v4l/v4l2.xml | 2 + .../DocBook/media/v4l/vidioc-create-bufs.xml | 147 ++++++++++++++++++++ .../DocBook/media/v4l/vidioc-prepare-buf.xml | 96 +++++++++++++ 4 files changed, 262 insertions(+), 0 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/vidioc-create-bufs.xml create mode 100644 Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 227e7ac..ff03dd2 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -927,6 +927,23 @@ ioctl is called. Applications set or clear this flag before calling the VIDIOC_QBUF ioctl. + + V4L2_BUF_FLAG_NO_CACHE_INVALIDATE + 0x0400 + 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 +passed on to a DMA-capable hardware unit for further processing or output. + + + + V4L2_BUF_FLAG_NO_CACHE_CLEAN + 0x0800 + 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, +in which case caches have not been used. + diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 0d05e87..06bb179 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -462,6 +462,7 @@ and discussions on the V4L mailing list. &sub-close; &sub-ioctl; + &sub-create-bufs; &sub-cropcap; &sub-dbg-g-chip-ident; &sub-dbg-g-register; @@ -504,6 +505,7 @@ and discussions on the V4L mailing list. &sub-queryctrl; &sub-query-dv-preset; &sub-querystd; + &sub-prepare-buf; &sub-reqbufs; &sub-s-hw-freq-seek; &sub-streamon; diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml new file mode 100644 index 0000000..eb99604 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -0,0 +1,147 @@ + + + ioctl VIDIOC_CREATE_BUFS + &manvol; + + + + VIDIOC_CREATE_BUFS + Create buffers for Memory Mapped or User Pointer I/O + + + + + + int ioctl + int fd + int request + struct v4l2_create_buffers *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_CREATE_BUFS + + + + argp + + + + + + + + + Description + + 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. + + To allocate device buffers applications initialize relevant fields of +the v4l2_create_buffers structure. They set the +type field in the +v4l2_format structure, embedded in this +structure, to the respective stream or buffer type. +count must be set to the number of required buffers. +memory specifies the required I/O method. The +format field shall typically be filled in using +either the VIDIOC_TRY_FMT or +VIDIOC_G_FMT ioctl(). Additionally, applications can adjust +sizeimage fields to fit their specific needs. The +reserved array must be zeroed. + + When the ioctl is called with a pointer to this structure the driver +will attempt to allocate up to the requested number of buffers and store the +actual number allocated and the starting index in the +count and the index fields +respectively. On return count can be smaller than +the number requested. The driver may also adjust buffer sizes as it sees fit, +however, it will not update sizeimage fields, the +user has to use VIDIOC_QUERYBUF to retrieve that +information. + + + struct <structname>v4l2_create_buffers</structname> + + &cs-str; + + + __u32 + index + The starting buffer index, returned by the driver. + + + __u32 + count + The number of buffers requested or granted. + + + &v4l2-memory; + memory + Applications set this field to +V4L2_MEMORY_MMAP or +V4L2_MEMORY_USERPTR. + + + &v4l2-format; + format + Filled in by the application, preserved by the driver. + + + __u32 + reserved[8] + A place holder for future extensions. + + + +
+ + + + &return-value; + + + + ENOMEM + + No memory to allocate buffers for memory +mapped I/O. + + + + EINVAL + + The buffer type (type field) or the +requested I/O method (memory) is not +supported. + + + + + + + diff --git a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml new file mode 100644 index 0000000..509e752 --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml @@ -0,0 +1,96 @@ + + + ioctl VIDIOC_PREPARE_BUF + &manvol; + + + + VIDIOC_PREPARE_BUF + Prepare a buffer for I/O + + + + + + int ioctl + int fd + int request + struct v4l2_buffer *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_PREPARE_BUF + + + + argp + + + + + + + + + Description + + Applications can optionally call the +VIDIOC_PREPARE_BUF ioctl to pass ownership of the buffer +to the driver before actually enqueuing it, using the +VIDIOC_QBUF ioctl, and to prepare it for future I/O. +Such preparations may include cache invalidation or cleaning. Performing them +in advance saves time during the actual I/O. In case such cache operations are +not required, the application can use one of +V4L2_BUF_FLAG_NO_CACHE_INVALIDATE and +V4L2_BUF_FLAG_NO_CACHE_CLEAN flags to skip the respective +step. + + The v4l2_buffer structure is +specified in . + + + + &return-value; + + + + EBUSY + + File I/O is in progress. + + + + EINVAL + + The buffer type is not +supported, or the index is out of bounds, +or no buffers have been allocated yet, or the +userptr or +length are invalid. + + + + + + +