From patchwork Fri May 6 10:53:27 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sakari Ailus X-Patchwork-Id: 9031861 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 53445BF29F for ; Fri, 6 May 2016 10:57:15 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 380F820389 for ; Fri, 6 May 2016 10:57:14 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id BA60E20390 for ; Fri, 6 May 2016 10:57:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758378AbcEFK5H (ORCPT ); Fri, 6 May 2016 06:57:07 -0400 Received: from mga01.intel.com ([192.55.52.88]:63881 "EHLO mga01.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1758251AbcEFK4n (ORCPT ); Fri, 6 May 2016 06:56:43 -0400 Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by fmsmga101.fm.intel.com with ESMTP; 06 May 2016 03:56:41 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.24,586,1455004800"; d="scan'208";a="960167209" Received: from paasikivi.fi.intel.com ([10.237.72.42]) by fmsmga001.fm.intel.com with ESMTP; 06 May 2016 03:56:42 -0700 Received: from nauris.fi.intel.com (nauris.localdomain [192.168.240.2]) by paasikivi.fi.intel.com (Postfix) with ESMTP id 8E02421126; Fri, 6 May 2016 13:56:36 +0300 (EEST) Received: by nauris.fi.intel.com (Postfix, from userid 1000) id C235F201D1; Fri, 6 May 2016 13:53:37 +0300 (EEST) From: Sakari Ailus To: linux-media@vger.kernel.org Cc: laurent.pinchart@ideasonboard.com, hverkuil@xs4all.nl, mchehab@osg.samsung.com, Laurent Pinchart Subject: [RFC 18/22] DocBook: media: Document the V4L2 request API Date: Fri, 6 May 2016 13:53:27 +0300 Message-Id: <1462532011-15527-19-git-send-email-sakari.ailus@linux.intel.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1462532011-15527-1-git-send-email-sakari.ailus@linux.intel.com> References: <1462532011-15527-1-git-send-email-sakari.ailus@linux.intel.com> Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Spam-Status: No, score=-9.0 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Laurent Pinchart The V4L2 request API consists in extensions to existing V4L2 ioctls. Document it. Signed-off-by: Laurent Pinchart --- Documentation/DocBook/media/v4l/common.xml | 2 + Documentation/DocBook/media/v4l/io.xml | 9 ++- Documentation/DocBook/media/v4l/request-api.xml | 90 ++++++++++++++++++++++ .../DocBook/media/v4l/vidioc-prepare-buf.xml | 9 +++ Documentation/DocBook/media/v4l/vidioc-qbuf.xml | 6 ++ 5 files changed, 113 insertions(+), 3 deletions(-) create mode 100644 Documentation/DocBook/media/v4l/request-api.xml diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index 8b5e014..30cb0f2 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -1073,6 +1073,8 @@ dheight = format.fmt.pix.height; &sub-selection-api; + &sub-request-api; +
Streaming Parameters diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index e09025d..5695bc8 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -833,10 +833,13 @@ is the file descriptor associated with a DMABUF buffer. __u32 - reserved2 + request - A place holder for future extensions. Drivers and applications -must set this to 0. + ID of the request to associate the buffer to. Set by the + application for &VIDIOC-QBUF; and &VIDIOC-PREPARE-BUF;. Set to zero + by the application and the driver in all other cases. See + for more information. + __u32 diff --git a/Documentation/DocBook/media/v4l/request-api.xml b/Documentation/DocBook/media/v4l/request-api.xml new file mode 100644 index 0000000..992f25a --- /dev/null +++ b/Documentation/DocBook/media/v4l/request-api.xml @@ -0,0 +1,90 @@ +
+ + Experimental API for request handling + + + Experimental + This is an experimental + interface and may change in the future. + + +
+ Introduction + +It is often useful to apply certain settings when a buffer is about to be +filled by the DMA capture of a video capture device, ensuring that those +settings are applied in time for them to be used with that buffer. + +One of the prime use-cases of this is Android's CameraHAL v3 which +requires per-frame configuration support. Other use-cases are possible as well: +changing codec settings (bit rate, etc.) starting with a specific buffer, +preparing a configuration to be applied at a certain time, etc. + +The request API is the way V4L2 solves this problem. + +
+ +
+ Request Objects + +At the core of the request API is the request object. Applications store +configuration parameters such as V4L2 controls, formats and selection rectangles +in request objects and then associate those request objects for processing with +specific buffers. + +Request objects are created and managed through the media controller +device node. Details on request object management can be found in the +media controller request API +documentation and are outside the scope of the V4L2 request API. Once a request +object is created it can be referenced by its ID in the V4L2 ioctls that support +requests. + +Applications can store controls, subdev formats and subdev selection +rectangles in requests. To do so they use the usual V4L2 ioctls +&VIDIOC-S-EXT-CTRLS;, &VIDIOC-SUBDEV-S-FMT; and &VIDIOC-SUBDEV-S-SELECTION; with +the request field of the associated structure set to +the request ID (for subdev formats and selection rectangles the +which field need to be additionally set to +V4L2_SUBDEV_FORMAT_REQUEST). Controls, formats and +selection rectangles will be processed as usual but will be stored in the +request instead of applied to the device. + + +Parameters stored in requests can further be retrieved by calling the +&VIDIOC-G-EXT-CTRLS;, &VIDIOC-SUBDEV-G-FMT; or &VIDIOC-SUBDEV-G-SELECTION; +ioctls similarly with the request field of the +associated structure set to the request ID. + + +
+ +
+ Applying Requests + +The simplest way to apply a request is to associated it with a buffer. +This is done by setting the request field of the +&v4l2-buffer; to the request ID when queuing the buffer with the &VIDIOC-QBUF; +ioctl. + + +Once a buffer is queued with a non-zero request ID the driver will apply +all parameters stored in the request atomically. The parameters are guaranteed +to come in effect before the buffer starts being transferred and after all +previous buffers have been complete. + + +For devices with multiple video nodes requests might need to be applied +synchronously with several buffers. This is achieved by first preparing (but not +queuing) all the related buffers using the &VIDIOC-PREPARE-BUF; ioctl with the +request field of the &v4l2-buffer; set to the request +ID. Once this is done the request is queued using the +MEDIA_REQ_CMD_QUEUE command of the &MEDIA-IOC-REQUEST-CMD; +ioctl on the media controller device node. The driver will then queue all +buffers prepared for the request as if the &VIDIOC-QBUF; ioctl was called on all +of them and will apply the request parameters atomically and synchronously with +the transfer of the buffers. + + +
+ +
diff --git a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml index 7bde698..2c5b72c1 100644 --- a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml @@ -59,6 +59,15 @@ not required, the application can use one of V4L2_BUF_FLAG_NO_CACHE_CLEAN flags to skip the respective step. + Applications can prepare a buffer to be processed for a specific +request. To do so they set the request field of the +struct v4l2_buffer to the request ID. The buffer will +then be automatically queued when the request is processed as if the +VIDIOC_QBUF ioctl was called at that time by the +application. For more information about requests see +. + + The v4l2_buffer structure is specified in . diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 8b98a0e..742f1dd 100644 --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml @@ -80,6 +80,12 @@ to a filled-in array of &v4l2-plane; and the length field must be set to the number of elements in that array. + Applications can reference a request to be applied when the buffer is +processed. To do so they set the request field of the +struct v4l2_buffer to the request ID. For more +information about requests see . + + To enqueue a memory mapped buffer applications set the memory field to V4L2_MEMORY_MMAP. When