From patchwork Mon Nov 21 18:15:14 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 87689 Received: from vger.kernel.org ([23.128.96.18]) by www.linuxtv.org with esmtp (Exim 4.92) (envelope-from ) id 1oxBKX-006jMS-03; Mon, 21 Nov 2022 18:15:42 +0000 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229622AbiKUSPj (ORCPT + 1 other); Mon, 21 Nov 2022 13:15:39 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59486 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229628AbiKUSPh (ORCPT ); Mon, 21 Nov 2022 13:15:37 -0500 Received: from relay6-d.mail.gandi.net (relay6-d.mail.gandi.net [217.70.183.198]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 223ABC051E for ; Mon, 21 Nov 2022 10:15:35 -0800 (PST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id C20CEC0009; Mon, 21 Nov 2022 18:15:32 +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 v2 1/2] documentation: media: camera_sensor: Document blankings handling Date: Mon, 21 Nov 2022 19:15:14 +0100 Message-Id: <20221121181515.34008-2-jacopo@jmondi.org> X-Mailer: git-send-email 2.38.1 In-Reply-To: <20221121181515.34008-1-jacopo@jmondi.org> References: <20221121181515.34008-1-jacopo@jmondi.org> MIME-Version: 1.0 X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_NONE,WEIRD_QUOTING autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-LSpam-Score: -2.4 (--) X-LSpam-Report: No, score=-2.4 required=5.0 tests=BAYES_00=-1.9,HEADER_FROM_DIFFERENT_DOMAINS=0.5,MAILING_LIST_MULTI=-1,WEIRD_QUOTING=0.001 autolearn=ham autolearn_force=no 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 | 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 c7d4891bd24e..382ea4ecebd4 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -108,6 +108,39 @@ 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 required +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 limits for the controls should be re-calculated using the newly +configured size: + +.. code-block:: c + + #define SENSOR_MAX_VTS + + max_vblank = SENSOR_MAX_VTS - (analogue crop height); + ret = __v4l2_ctrl_modify_range(sensor->ctrls.vblank, + sensor->ctrls.vblank->minimum, + max_vblank, sensor->ctrls.vblank->step, + sensor->ctrls.vblank->minimum); + +The minimum value could potentially change as well. + +The control default value is reset to the control's minimum and the V4L2 +control framework automatically clamps the control's value in the new limits. + USB cameras etc. devices ~~~~~~~~~~~~~~~~~~~~~~~~ From patchwork Mon Nov 21 18:15:15 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 87690 Received: from vger.kernel.org ([23.128.96.18]) by www.linuxtv.org with esmtp (Exim 4.92) (envelope-from ) id 1oxBKZ-006jMS-BS; Mon, 21 Nov 2022 18:15:43 +0000 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229628AbiKUSPk (ORCPT + 1 other); Mon, 21 Nov 2022 13:15:40 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59502 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229702AbiKUSPj (ORCPT ); Mon, 21 Nov 2022 13:15:39 -0500 Received: from relay6-d.mail.gandi.net (relay6-d.mail.gandi.net [217.70.183.198]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 6399AC0528 for ; Mon, 21 Nov 2022 10:15:38 -0800 (PST) Received: (Authenticated sender: jacopo@jmondi.org) by mail.gandi.net (Postfix) with ESMTPSA id B1F6BC0005; Mon, 21 Nov 2022 18:15:35 +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 v2 2/2] documentation: media: camera_sensor: Update exposure on blanking change Date: Mon, 21 Nov 2022 19:15:15 +0100 Message-Id: <20221121181515.34008-3-jacopo@jmondi.org> X-Mailer: git-send-email 2.38.1 In-Reply-To: <20221121181515.34008-1-jacopo@jmondi.org> References: <20221121181515.34008-1-jacopo@jmondi.org> MIME-Version: 1.0 X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_NONE,WEIRD_QUOTING autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-LSpam-Score: -2.4 (--) X-LSpam-Report: No, score=-2.4 required=5.0 tests=BAYES_00=-1.9,HEADER_FROM_DIFFERENT_DOMAINS=0.5,MAILING_LIST_MULTI=-1,WEIRD_QUOTING=0.001 autolearn=ham autolearn_force=no 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 | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) -- 2.38.1 diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index 382ea4ecebd4..675f55ad54b5 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -184,3 +184,39 @@ 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 limits on vertical blanking update +""""""""""""""""""""""""""""""""""""""""""""""""""""" + +The sensor exposure time, specified by the ``V4L2_CID_EXPOSURE`` control, is +usually limited to a maximum value related to the frame interval. Frequently it +is a number of lines less than the frame length that will be specified in the +sensor documentation. + +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 + + #define SENSOR_EXPOSURE_OFFSET + + static int s_ctrl(struct v4l2_ctrl *ctrl) + { + int exp_max; + + switch (ctrl->id) { + case V4L2_CID_VBLANK: + exp_max = (analogue crop height) + ctrl->val - SENSOR_EXPOSURE_OFFSET; + __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;