From patchwork Mon Jul 10 13:22:39 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 93073 X-Patchwork-Delegate: sakari.ailus@iki.fi Received: from vger.kernel.org ([23.128.96.18]) by www.linuxtv.org with esmtp (Exim 4.92) (envelope-from ) id 1qIqr5-00EP7m-1n; Mon, 10 Jul 2023 13:23:07 +0000 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231358AbjGJNXF (ORCPT + 1 other); Mon, 10 Jul 2023 09:23:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36848 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229969AbjGJNXE (ORCPT ); Mon, 10 Jul 2023 09:23:04 -0400 Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id AFD0A100 for ; Mon, 10 Jul 2023 06:22:56 -0700 (PDT) Received: from uno.LocalDomain (93-61-96-190.ip145.fastwebnet.it [93.61.96.190]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 81B6EBEB; Mon, 10 Jul 2023 15:22:06 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1688995326; bh=a3X+mOsubBqW8aQtyXJqoPH788qdIvxtQegZ82/7KPA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Ok+tuAaGXVmU0lCoz8dlhNtAh0ScTfwCwPUi5sbqze6+wkdLQeGAZeRjVqMKoP/NQ 0FWZ5xA+pHuLBWVIiLEO1c8qfZUViObgxg7X8XXP4yOU2cIA+4BnYUwmK19IozbIvp BEd+YoCt9/M08VNh4tVpzTD14d19g1UXDKqr8fxE= From: Jacopo Mondi To: linux-media@vger.kernel.org Cc: Jacopo Mondi , Hans Verkuil , Sakari Ailus , Laurent Pinchart , Dave Stevenson Subject: [PATCH v3 1/2] Documentation: v4l: Flip handling for RAW sensors Date: Mon, 10 Jul 2023 15:22:39 +0200 Message-Id: <20230710132240.7864-2-jacopo.mondi@ideasonboard.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230710132240.7864-1-jacopo.mondi@ideasonboard.com> References: <20230710132240.7864-1-jacopo.mondi@ideasonboard.com> MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,SPF_HELO_PASS,SPF_PASS, T_SCC_BODY_TEXT_LINE 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: -4.8 (----) X-LSpam-Report: No, score=-4.8 required=5.0 tests=BAYES_00=-1.9,DKIM_SIGNED=0.1,DKIM_VALID=-0.1,DKIM_VALID_AU=-0.1,HEADER_FROM_DIFFERENT_DOMAINS=0.5,MAILING_LIST_MULTI=-1,RCVD_IN_DNSWL_MED=-2.3 autolearn=ham autolearn_force=no Document the requirement of notifying to userspace the possible re-ordering of the color sample components when a vertical or horizontal flip is applied to a RAW camera sensor. Signed-off-by: Jacopo Mondi Reviewed-by: Dave Stevenson --- Documentation/driver-api/media/camera-sensor.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index 93f4f2536c25..cd915ca119ea 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -173,3 +173,19 @@ V4L2_CID_VFLIP controls with the values programmed by the register sequences. The default values of these controls shall be 0 (disabled). Especially these controls shall not be inverted, independently of the sensor's mounting rotation. + +Flip handling for raw camera color sensors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Applying vertical and horizontal flips on raw camera sensors inverts the color +sample reading direction on the sensor's pixel array. This may cause the +re-ordering of the color samples on the sensor's output frame. As an example, a +raw camera sensor with a Bayer pattern color filter array with a native RGGB +Bayer order will produce frames with GRBG component ordering when an horizontal +flip is applied. Camera sensor drivers where inverting the reading order +direction causes a re-ordering of the color components are required to register +the ``V4L2_CID_VFLIP`` and ``V4L2_CID_HFLIP`` controls with the +``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` flag enabled to notify userspace that enabling +a flip can potentially change the output buffer content layout. Flips should +also be taken into account when enumerating and handling media bus formats +on the camera sensor source pads. From patchwork Mon Jul 10 13:22:40 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 93075 X-Patchwork-Delegate: sakari.ailus@iki.fi Received: from vger.kernel.org ([23.128.96.18]) by www.linuxtv.org with esmtp (Exim 4.92) (envelope-from ) id 1qIqrA-00EP7m-Ci; Mon, 10 Jul 2023 13:23:12 +0000 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231637AbjGJNXL (ORCPT + 1 other); Mon, 10 Jul 2023 09:23:11 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36958 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231320AbjGJNXJ (ORCPT ); Mon, 10 Jul 2023 09:23:09 -0400 Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D937BE2 for ; Mon, 10 Jul 2023 06:23:04 -0700 (PDT) Received: from uno.LocalDomain (93-61-96-190.ip145.fastwebnet.it [93.61.96.190]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 179FDDA7; Mon, 10 Jul 2023 15:22:07 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1688995327; bh=QKpNeSKW5e8AbrpNtPSuMYB/au8vcmPe2kyEIMgFs1U=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nLLOmg5Y8lJU0JjR+G9pqAFHvIOuSrvaH/bPECJbbI0bD0GHD/UdYhUDUGJg+h3on DumMjCSY1K+H4hgXVbs96N+fRN0z0jewcYPIjhKt1riYfLuHE5IjBFmyKMAnD7pplW /y8hpi93pO1UHq8o5FUYGk1OwBTSgNODJ2kall20= From: Jacopo Mondi To: linux-media@vger.kernel.org Cc: Jacopo Mondi , Hans Verkuil , Sakari Ailus , Laurent Pinchart , Dave Stevenson Subject: [PATCH v3 2/2] Documentation: v4l: Exposure/gain for camera sensor Date: Mon, 10 Jul 2023 15:22:40 +0200 Message-Id: <20230710132240.7864-3-jacopo.mondi@ideasonboard.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230710132240.7864-1-jacopo.mondi@ideasonboard.com> References: <20230710132240.7864-1-jacopo.mondi@ideasonboard.com> MIME-Version: 1.0 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_BLOCKED, SPF_HELO_PASS,SPF_PASS,T_SCC_BODY_TEXT_LINE 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: -4.8 (----) X-LSpam-Report: No, score=-4.8 required=5.0 tests=BAYES_00=-1.9,DKIM_SIGNED=0.1,DKIM_VALID=-0.1,DKIM_VALID_AU=-0.1,HEADER_FROM_DIFFERENT_DOMAINS=0.5,MAILING_LIST_MULTI=-1,RCVD_IN_DNSWL_MED=-2.3 autolearn=ham autolearn_force=no Document the suggested way to exposure controls for exposure and gain for camera sensor drivers. Signed-off-by: Jacopo Mondi Reviewed-by: Dave Stevenson --- .../driver-api/media/camera-sensor.rst | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index cd915ca119ea..67fe77b1edb9 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -189,3 +189,30 @@ the ``V4L2_CID_VFLIP`` and ``V4L2_CID_HFLIP`` controls with the a flip can potentially change the output buffer content layout. Flips should also be taken into account when enumerating and handling media bus formats on the camera sensor source pads. + +Exposure and Gain Control +------------------------- + +Camera sensor drivers that allow applications to control the image exposure +and gain should do so by exposing dedicated controls to applications. + +Exposure time is controlled by registering the ``V4L2_CID_EXPOSURE`` control. +The control definition does not specify a unit to allow maximum flexibility +for multiple device types, but when used for camera sensor drivers it should be +expressed in unit of lines whenever possible. + +To convert lines into units of time, the total line length (visible and +not visible pixels) has to be divided by the pixel rate:: + + line duration = total line length / pixel rate + = (image width + horizontal blanking) / pixel rate + +Camera sensor driver should try whenever possible to distinguish between the +analogue and digital gain control functions. Analogue gain is a multiplication +factor applied to all color channels on the pixel array before they get +converted into the digital domain. It should be made controllable by +registering the ``V4L2_CID_ANALOGUE_GAIN`` control, expressed as a device +specific gain code. Digital gain control is optional and should be exposed to +applications by registering ``V4L2_CID_DIGITAL_GAIN``. Camera sensor drivers are +discouraged from using ``V4L2_CID_GAIN`` as it doesn't allow differentiation of +analogue vs digital gain.