From patchwork Mon Nov 7 20:49:57 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 13035208 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0AD93C4332F for ; Mon, 7 Nov 2022 20:50:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233054AbiKGUuZ (ORCPT ); Mon, 7 Nov 2022 15:50:25 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40718 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233050AbiKGUuW (ORCPT ); Mon, 7 Nov 2022 15:50:22 -0500 Received: from relay9-d.mail.gandi.net (relay9-d.mail.gandi.net [IPv6:2001:4b98:dc4:8::229]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EB57F1E3D5 for ; Mon, 7 Nov 2022 12:50:20 -0800 (PST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id 0ABC9FF811; Mon, 7 Nov 2022 20:50:17 +0000 (UTC) From: Jacopo Mondi To: Sakari Ailus , Laurent Pinchart , Dave Stevenson , Hans Verkuil , Mauro Carvalho Chehab Cc: Jacopo Mondi , Linux Media Mailing List Subject: [PATCH 1/3] Documentation: media: camera-sensor: Correct frame interval Date: Mon, 7 Nov 2022 21:49:57 +0100 Message-Id: <20221107204959.37691-2-jacopo@jmondi.org> X-Mailer: git-send-email 2.38.1 In-Reply-To: <20221107204959.37691-1-jacopo@jmondi.org> References: <20221107204959.37691-1-jacopo@jmondi.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org The formula to compute the frame interval uses the analogue crop rectangle dimensions to compute the total frame size in conjunction with blankings. Horizontal and vertical blankings are realized by extending the time interval during which no valid pixels are sent on the bus between visible lines and between consecutive frames, whose size is smaller than the analogue crop rectangle if any additional cropping or pixel subsampling is applied on the sensor processing pipeline. Correct the documentation to use the visible line length and frame height instead of the analogue crop dimensions. Signed-off-by: Jacopo Mondi --- Documentation/driver-api/media/camera-sensor.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index c7d4891bd24e..bb7d62db4cd1 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -87,12 +87,11 @@ less all modern raw camera sensors. The frame interval is calculated using the following equation:: - frame interval = (analogue crop width + horizontal blanking) * - (analogue crop height + vertical blanking) / pixel rate + frame interval = (visible width + horizontal blanking) * + (visibile height + vertical blanking) / pixel rate The formula is bus independent and is applicable for raw timing parameters on -large variety of devices beyond camera sensors. Devices that have no analogue -crop, use the full source image size, i.e. pixel array size. +large variety of devices beyond camera sensors. Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and ``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control From patchwork Mon Nov 7 20:49:58 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 13035209 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 97A53C43219 for ; Mon, 7 Nov 2022 20:50:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233055AbiKGUuZ (ORCPT ); Mon, 7 Nov 2022 15:50:25 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40726 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233040AbiKGUuX (ORCPT ); Mon, 7 Nov 2022 15:50:23 -0500 Received: from relay9-d.mail.gandi.net (relay9-d.mail.gandi.net [IPv6:2001:4b98:dc4:8::229]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8352227176 for ; Mon, 7 Nov 2022 12:50:22 -0800 (PST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id AAE53FF80B; Mon, 7 Nov 2022 20:50:19 +0000 (UTC) From: Jacopo Mondi To: Sakari Ailus , Laurent Pinchart , Dave Stevenson , Hans Verkuil , Mauro Carvalho Chehab Cc: Jacopo Mondi , Linux Media Mailing List Subject: [PATCH 2/3] documentation: media: camera_sensor: Document blankings handling Date: Mon, 7 Nov 2022 21:49:58 +0100 Message-Id: <20221107204959.37691-3-jacopo@jmondi.org> X-Mailer: git-send-email 2.38.1 In-Reply-To: <20221107204959.37691-1-jacopo@jmondi.org> References: <20221107204959.37691-1-jacopo@jmondi.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org When a new image format is applied on the sensor it is necessary to update the vertical and horizontal blanking limits, to comply with the new visibile sizes. Add that part to the documentation of camera sensor subdevices. Signed-off-by: Jacopo Mondi --- .../driver-api/media/camera-sensor.rst | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index bb7d62db4cd1..31f74f85ebc5 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -107,6 +107,35 @@ The first entity in the linear pipeline is the pixel array. The pixel array may be followed by other entities that are there to allow configuring binning, skipping, scaling or digital crop :ref:`v4l2-subdev-selections`. +Blankings initialization and reconfiguration +"""""""""""""""""""""""""""""""""""""""""""" + +The value used to initialize the vertical and horizontal blanking controls +should be selected in order to realize, in association with the driver default +format and default pixel rate, a reasonable frame rate output, usually one of +the standard 15, 30 or 60 frame per second. + +When a new frame size is applied on the subdevice sensor drivers are requested +to update the limits of their blankings controls. + +The V4L2 control framework provides the ``v4l2_ctrl_modify_range()`` function +(and the unlocked ``__v4l2_ctrl_modify_range()`` counterpart) to assist drivers +in re-computing the controls limits. + +The new maximum limit for the controls should be re-calculated using the +newly applied visibile width and height + +.. code-block:: c + + max_vblank = MAX_VTS - sensor->fmt.height; + ret = __v4l2_ctrl_modify_range(sensor->ctrls.vblank, + sensor->ctrls.vblank->minimum, + max_vblank, sensor->ctrls.vblank->step, + sensor->ctrls.vblank->minimum); + +The blankings default value is reset to the control minimum and the V4L2 +control framework automatically clamps the control's value in the new limits. + USB cameras etc. devices ~~~~~~~~~~~~~~~~~~~~~~~~ From patchwork Mon Nov 7 20:49:59 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 13035210 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 62C41C43217 for ; Mon, 7 Nov 2022 20:50:28 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233062AbiKGUu1 (ORCPT ); Mon, 7 Nov 2022 15:50:27 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:40750 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233056AbiKGUu0 (ORCPT ); Mon, 7 Nov 2022 15:50:26 -0500 Received: from relay9-d.mail.gandi.net (relay9-d.mail.gandi.net [217.70.183.199]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id DB6BA1E3D5 for ; Mon, 7 Nov 2022 12:50:23 -0800 (PST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id 5E2CBFF80C; Mon, 7 Nov 2022 20:50:21 +0000 (UTC) From: Jacopo Mondi To: Sakari Ailus , Laurent Pinchart , Dave Stevenson , Hans Verkuil , Mauro Carvalho Chehab Cc: Jacopo Mondi , Linux Media Mailing List Subject: [PATCH 3/3] documentation: media: camera_sensor: Update exposure on blanking change Date: Mon, 7 Nov 2022 21:49:59 +0100 Message-Id: <20221107204959.37691-4-jacopo@jmondi.org> X-Mailer: git-send-email 2.38.1 In-Reply-To: <20221107204959.37691-1-jacopo@jmondi.org> References: <20221107204959.37691-1-jacopo@jmondi.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org The maximum achieable exposure time in a camera sensor is usually bound by the total frame height (visible + blankings) minus a fixed sensor-speific offset. When the vertical blanking control value is changed, the exposure control limits should be updated as well. Add this to the camera sensor documentation. Signed-off-by: Jacopo Mondi --- .../driver-api/media/camera-sensor.rst | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index 31f74f85ebc5..76206c7647d6 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -179,3 +179,36 @@ used to obtain device's power state after the power state transition: The function returns a non-zero value if it succeeded getting the power count or runtime PM was disabled, in either of which cases the driver may proceed to access the device. + +Resetting exposure on vertical blanking update +"""""""""""""""""""""""""""""""""""""""""""""" + +The sensor exposure time, specified by the ``V4L2_CID_EXPOSURE`` control, is +usually limited by a maximum value which is equal to maximum vertical blankings +minus a known offset usually specified in the chip programming manual. + +When a new ``V4L2_CID_VBLANK`` value is applied, regardless of it being actually +programmed to the hardware or not, the limits of the ``V4L2_CID_EXPOSURE`` +control should be updated as well. + +The typical coding pattern that realizes that in the ``.s_ctrl`` callback +handler is: + +.. code-block:: c + + static int s_ctrl(struct v4l2_ctrl *ctrl) + { + int exp_max; + + switch (ctrl->id) { + case V4L2_CID_VBLANK: + exp_max = sensor->fmt.height + ctrl->val - 4; + __v4l2_ctrl_modify_range(sensor->ctrls.exposure, + sensor->ctrls.exposure->minimum, + exp_max, sensor->ctrls.exposure->step, + sensor->ctrls.exposure->default_value); + break; + } + + if (!pm_runtime_get_if_in_use(&sensor->i2c_client->dev)) + return 0;