From patchwork Tue May 26 10:09:29 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hans Verkuil X-Patchwork-Id: 209719 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-9.8 required=3.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 30D2FC433E1 for ; Tue, 26 May 2020 10:09:41 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 09FEE2073B for ; Tue, 26 May 2020 10:09:41 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=xs4all.nl header.i=@xs4all.nl header.b="jE+MFslp" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1731864AbgEZKJk (ORCPT ); Tue, 26 May 2020 06:09:40 -0400 Received: from lb3-smtp-cloud7.xs4all.net ([194.109.24.31]:46263 "EHLO lb3-smtp-cloud7.xs4all.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1731745AbgEZKJj (ORCPT ); Tue, 26 May 2020 06:09:39 -0400 Received: from cust-b5b5937f ([IPv6:fc0c:c16d:66b8:757f:c639:739b:9d66:799d]) by smtp-cloud7.xs4all.net with ESMTPA id dWWajU9GZDazBdWWfjeM9e; Tue, 26 May 2020 12:09:37 +0200 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=xs4all.nl; s=s1; t=1590487777; bh=PLtqEoeLTZJcLkmiOgyYHjH45G+sZjucCtUj5WG57B4=; h=From:To:Subject:Date:Message-Id:MIME-Version:From:Subject; b=jE+MFslpKZXKBOPQR9LuQqSt8iszsoF4vv8geIpCXq6ZjpppRkgOdyWcecoqQmb1u PMGvrBu4TEltW4pxBAXNhYmSCPlpcubdxKI9Bl1yst4hu+NV8WzEKDQ1bA9NbDqOKe r6jyOeagn3lxHPaxfeXQQF/F8HXossiCFBd7DfIgzDEPXbmZANC301zAxweR92dn2T QeyKM1mjdkn3ZtkKpyz2gIlH3HMWj21F5NMsuLrQ3Q4YqnXgu1nLRELRIIjjdgVOST fgzh5IXH5D1X6pK6wU6nav9bQNAC4zf19NXrWl6b4L9al2bnuSfOuom6AKqh3KI0Rg iAUHTOSTtynnw== From: Hans Verkuil To: linux-media@vger.kernel.org Cc: Nicolas Dufresne , Tomasz Figa , Michael Tretter , Hans Verkuil Subject: [PATCHv3 2/5] vidioc-g-parm.rst: update the VIDIOC_G/S_PARM documentation Date: Tue, 26 May 2020 12:09:29 +0200 Message-Id: <20200526100932.2626420-3-hverkuil-cisco@xs4all.nl> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200526100932.2626420-1-hverkuil-cisco@xs4all.nl> References: <20200526100932.2626420-1-hverkuil-cisco@xs4all.nl> MIME-Version: 1.0 X-CMAE-Envelope: MS4wfFFJmlHXpgKGDNrYZdF1OaHQVZiT1uBUnwp0YrrrYa2ptm9gJu2cB5hK+AvULzer4Y+ymp2iiHlIC42NyQscauzzg8YKZUNbfq+oAXXaf73t4cSDl5/r bKNbdzMCKY5jKDJShEoK5Rg9AdM73fJnfD7v8QIkeT2vprTjYKvhGdZvvdy3KeON3x8Mv0d4NZPujVDVhaR5vVlHYmkX2O2iPGpMC5tNnepBITDHVqTyhKW1 HO0dOU6oELXAjKLVj4k21NXU+rGc5O7anEDwEPboBGAyGTK4HCTZIV2oHgWdsvTC0AjxpY1PjtOQN7OdUhWHFSK7+w7FyRqxQcG6DoWhSAU= Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org This documentation is very outdated. In particular, it is not obvious at all that this is used to change the framerate of sensors. Fix it, and include references to the stateful encoder API where this works slightly different. Signed-off-by: Hans Verkuil Acked-by: Tomasz Figa --- .../userspace-api/media/v4l/vidioc-g-parm.rst | 51 ++++++++++++------- 1 file changed, 32 insertions(+), 19 deletions(-) diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst index 42e9f6ee7a59..af3c5863bb87 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-g-parm.rst @@ -42,12 +42,13 @@ Arguments Description =========== -The current video standard determines a nominal number of frames per -second. If less than this number of frames is to be captured or output, -applications can request frame skipping or duplicating on the driver -side. This is especially useful when using the :ref:`read() ` or -:ref:`write() `, which are not augmented by timestamps or sequence -counters, and to avoid unnecessary data copying. +Applications can request a different frame interval. The capture or +output device will be reconfigured to support the requested frame +interval if possible. Optionally drivers may choose to skip or +repeat frames to achieve the requested frame interval. + +For stateful encoders (see :ref:`encoder`) this represents the +frame interval that is typically embedded in the encoded video stream. Changing the frame interval shall never change the format. Changing the format, on the other hand, may change the frame interval. @@ -57,7 +58,8 @@ internally by a driver in read/write mode. For implications see the section discussing the :ref:`read() ` function. To get and set the streaming parameters applications call the -:ref:`VIDIOC_G_PARM ` and :ref:`VIDIOC_S_PARM ` ioctl, respectively. They take a +:ref:`VIDIOC_G_PARM ` and +:ref:`VIDIOC_S_PARM ` ioctl, respectively. They take a pointer to a struct :c:type:`v4l2_streamparm` which contains a union holding separate parameters for input and output devices. @@ -113,14 +115,21 @@ union holding separate parameters for input and output devices. * - struct :c:type:`v4l2_fract` - ``timeperframe`` - This is the desired period between successive frames captured by - the driver, in seconds. The field is intended to skip frames on - the driver side, saving I/O bandwidth. + the driver, in seconds. + * - :cspan:`2` + + This will configure the speed at which the video source (e.g. a sensor) + generates video frames. If the speed is fixed, then the driver may + choose to skip or repeat frames in order to achieve the requested + frame rate. + + For stateful encoders (see :ref:`encoder`) this represents the + frame interval that is typically embedded in the encoded video stream. Applications store here the desired frame period, drivers return - the actual frame period, which must be greater or equal to the - nominal frame period determined by the current video standard - (struct :c:type:`v4l2_standard` ``frameperiod`` - field). Changing the video standard (also implicitly by switching + the actual frame period. + + Changing the video standard (also implicitly by switching the video input) may reset this parameter to the nominal frame period. To reset manually applications can just set this field to zero. @@ -173,11 +182,15 @@ union holding separate parameters for input and output devices. :ref:`write() ` mode (in streaming mode timestamps can be used to throttle the output), saving I/O bandwidth. + For stateful encoders (see :ref:`encoder`) this represents the + frame interval that is typically embedded in the encoded video stream + and it provides a hint to the encoder of the speed at which raw + frames are queued up to the encoder. + Applications store here the desired frame period, drivers return - the actual frame period, which must be greater or equal to the - nominal frame period determined by the current video standard - (struct :c:type:`v4l2_standard` ``frameperiod`` - field). Changing the video standard (also implicitly by switching + the actual frame period. + + Changing the video standard (also implicitly by switching the video output) may reset this parameter to the nominal frame period. To reset manually applications can just set this field to zero. @@ -216,8 +229,8 @@ union holding separate parameters for input and output devices. * - ``V4L2_CAP_TIMEPERFRAME`` - 0x1000 - - The frame skipping/repeating controlled by the ``timeperframe`` - field is supported. + - The frame period can be modified by setting the ``timeperframe`` + field. From patchwork Tue May 26 10:09:32 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hans Verkuil X-Patchwork-Id: 209718 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-9.8 required=3.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id C58B7C433DF for ; Tue, 26 May 2020 10:09:42 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 97DF22073B for ; Tue, 26 May 2020 10:09:42 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=xs4all.nl header.i=@xs4all.nl header.b="nZepC95T" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1731865AbgEZKJl (ORCPT ); Tue, 26 May 2020 06:09:41 -0400 Received: from lb2-smtp-cloud7.xs4all.net ([194.109.24.28]:43133 "EHLO lb2-smtp-cloud7.xs4all.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1731815AbgEZKJk (ORCPT ); Tue, 26 May 2020 06:09:40 -0400 Received: from cust-b5b5937f ([IPv6:fc0c:c16d:66b8:757f:c639:739b:9d66:799d]) by smtp-cloud7.xs4all.net with ESMTPA id dWWajU9GZDazBdWWgjeMAP; Tue, 26 May 2020 12:09:38 +0200 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=xs4all.nl; s=s1; t=1590487778; bh=zbBuzZfTTYRiDTqVVYRYvkiYf1YhHK5RjN+6SH69+3I=; h=From:To:Subject:Date:Message-Id:MIME-Version:From:Subject; b=nZepC95Ti4EsI8WGDZdg/jvjqlxi/tObCubN0RNaRivVFahFsjkf8+h1L71Yyae1B HdOI28bJZrD4Iq3LukWnKUskhd2XGTY+T+yzBnX3Sc+aumuj8LxLAK842e61HEfV0f Vn7NbGB2mMqbwdJhI0Um/BLXAe9HKf1XQBrCdA2SyEgocJdnldQFV5CdS9UFY0oyWU CHutYL7oLhaxO/34MXt28B2BqmEBsH2MF7vRDIN9YYDWNEHucxR4m3l20vVAigk86K qmCodRZsQ0ruHDqy0bL6vxIq+xzvrTdaiQQazYPMoPyrFU3hfDE0ElnuvZFIFlz1NF 7gP1qb9W5uS8Q== From: Hans Verkuil To: linux-media@vger.kernel.org Cc: Nicolas Dufresne , Tomasz Figa , Michael Tretter , Hans Verkuil Subject: [PATCHv3 5/5] dev-encoder.rst: add reference to V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL Date: Tue, 26 May 2020 12:09:32 +0200 Message-Id: <20200526100932.2626420-6-hverkuil-cisco@xs4all.nl> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200526100932.2626420-1-hverkuil-cisco@xs4all.nl> References: <20200526100932.2626420-1-hverkuil-cisco@xs4all.nl> MIME-Version: 1.0 X-CMAE-Envelope: MS4wfLU/x877oZ8J07T/dy4BRHLYUqkq116F8n0FpMovnMHpisdi1zJQ3oUvpdUQXTpaK7ddcNLpFrYtrjAUFsMq0XIZkCqh0qzkcplwvehL428KoeFtskqo R5YvVE3exlhdNlULZT8t44z27KwhjI8KYWuRSfOmW+csQzxJLKuFiQHAF/MweNbOsnwBRdZtqfXMfFmu3Ldc5zoDTq5zYHJENByfUfFwTHrVRKNGAQamEPOk dpC2B+661YmzlSvfGfOewE7u6hjMskLVLyFVbD69VAquu3QGc1Pz6UZ173ljWZxvwf/sFP8NUUEmULEVxVf/3dbPFtUFzdnjh3OgAc0vi1o= Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org Setting the stateful encoder capture frame interval is only supported if this flag is set. Document this. Signed-off-by: Hans Verkuil --- Documentation/userspace-api/media/v4l/dev-encoder.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/userspace-api/media/v4l/dev-encoder.rst b/Documentation/userspace-api/media/v4l/dev-encoder.rst index aace7b812a9c..c3a21bfe0052 100644 --- a/Documentation/userspace-api/media/v4l/dev-encoder.rst +++ b/Documentation/userspace-api/media/v4l/dev-encoder.rst @@ -281,7 +281,8 @@ Initialization 5. **Optional** Set the coded frame interval on the ``CAPTURE`` queue via :c:func:`VIDIOC_S_PARM`. This is only necessary if the coded frame interval is different from the raw frame interval, which is typically - the case for off-line encoding. + the case for off-line encoding. Support for this feature is signalled + by the :ref:`V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL ` format flag. * ** Required fields:**