From patchwork Fri Jan 22 00:57:08 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 8086331 X-Patchwork-Delegate: geert@linux-m68k.org Return-Path: X-Original-To: patchwork-linux-renesas-soc@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id CD03B9FC36 for ; Fri, 22 Jan 2016 00:57:53 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id CC1D12034C for ; Fri, 22 Jan 2016 00:57:52 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id C9CC12042A for ; Fri, 22 Jan 2016 00:57:51 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751269AbcAVA5v (ORCPT ); Thu, 21 Jan 2016 19:57:51 -0500 Received: from galahad.ideasonboard.com ([185.26.127.97]:58727 "EHLO galahad.ideasonboard.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751084AbcAVA5u (ORCPT ); Thu, 21 Jan 2016 19:57:50 -0500 Received: from avalon.access.network (nblzone-211-213.nblnetworks.fi [83.145.211.213]) by galahad.ideasonboard.com (Postfix) with ESMTPSA id A7AC820B64 for ; Fri, 22 Jan 2016 01:56:45 +0100 (CET) From: Laurent Pinchart To: linux-renesas-soc@vger.kernel.org Subject: [PATCH/RFC v2 39/56] DocBook: media: Document the V4L2 request API Date: Fri, 22 Jan 2016 02:57:08 +0200 Message-Id: <1453424245-18782-40-git-send-email-laurent.pinchart+renesas@ideasonboard.com> X-Mailer: git-send-email 2.4.10 In-Reply-To: <1453424245-18782-1-git-send-email-laurent.pinchart+renesas@ideasonboard.com> References: <1453424245-18782-1-git-send-email-laurent.pinchart+renesas@ideasonboard.com> Sender: linux-renesas-soc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-renesas-soc@vger.kernel.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=ham 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 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 | 12 ++- 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, 118 insertions(+), 1 deletion(-) 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 8b5e014224d6..30cb0f244f06 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 144158b3a5ac..15ef027809dd 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -838,7 +838,17 @@ is the file descriptor associated with a DMABUF buffer. - __u32 + __u16 + request + + 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. + + + + __u16 reserved2 A place holder for future extensions. Drivers and applications diff --git a/Documentation/DocBook/media/v4l/request-api.xml b/Documentation/DocBook/media/v4l/request-api.xml new file mode 100644 index 000000000000..992f25ae59a9 --- /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 fa7ad7e33228..c4726825ed7b 100644 --- a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml @@ -65,6 +65,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 8b98a0e421fc..742f1dd3f670 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