Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Michael Riesch <michael.riesch@wolfvision.net>
Date:   Tue, 25 Apr 2023 11:45:12 +0200
Subject: [PATCH RFC v2 2/6] media: v4l2-ctrls: clarify documentation of
 V4L2_CID_FOCUS_RELATIVE
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit
Message-Id: <20230406-feature-controls-lens-v2-2-faa8ad2bc404@wolfvision.net>
References: <20230406-feature-controls-lens-v2-0-faa8ad2bc404@wolfvision.net>
In-Reply-To: <20230406-feature-controls-lens-v2-0-faa8ad2bc404@wolfvision.net>
To:     Mauro Carvalho Chehab <mchehab@kernel.org>
Cc:     libcamera-devel@lists.libcamera.org,
        Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
        Sakari Ailus <sakari.ailus@linux.intel.com>,
        Hans Verkuil <hverkuil-cisco@xs4all.nl>,
        Matthias Fend <Matthias.Fend@wolfvision.net>,
        Dave Stevenson <dave.stevenson@raspberrypi.com>,
        linux-media@vger.kernel.org, linux-kernel@vger.kernel.org,
        Michael Riesch <michael.riesch@wolfvision.net>
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?K2MyakpCRUJOWWJSV0xZT1BuVlowV0UyTzkzMS9UZk8wVS9DdG92VFdQWVlP?=
 =?utf-8?B?Vnp0c2VzMm9uakRDOVl4YXdwN1dOTmR6WTRkVUsxNjJiQ2lmMWE0T3BIdTV2?=
 =?utf-8?B?NzcwUXRHb204Q1BaN3pHL3JEWnVHakhHMDJnWWpsOEphdjFKdUNyTFVRZEsr?=
 =?utf-8?B?UXhnK3FOMDIyOFYvMUh0anJrUXVmb3hBWGZtUW1XR1Z5a0xpQ3B1T1JNRGpj?=
 =?utf-8?B?RVF3bzlGWUhyd3JrVkt4aWpta2cyS0RBK21acWRZUm5QK1prUlF3ODlLYXJT?=
 =?utf-8?B?bkQ1YXlPWWUxWWd4eU5CNStiVENuOEQrY0hXL0hRbm95ZWYwSUFrNDhPY2FP?=
 =?utf-8?B?SnV5Z1djQmNRNXE0T2VuZ3NHYmxkZ01LaDNENy83czlZbnVoNW8rWHI5aEIx?=
 =?utf-8?B?MDcrNVN1MWMrZFE1cHVWUXZ3UEZBT0h6SVRlQ20yamt4SVpvY1lUWGpWcmw0?=
 =?utf-8?B?cnRQa3pmU1c2blBIbTd6bmVBNHV6NTZrOUEySlhDUDlRdGhTdEdsRERSZFdn?=
 =?utf-8?B?eDhlc2VONmp6UVFrS00vTEw1bEFqTzcvdC9leUtZQUtGWmRHSzRlUjVpNDFJ?=
 =?utf-8?B?aVhmQW9VTGR2Ymo5QjV1QzdTTTlHYThlUG5zRWM1U2xVUnB4djlpSFo5QnB0?=
 =?utf-8?B?RUhwcjlHWHF3SmljaFdIdHk2djhGNzhyVWtWNU8wTUU1OVhoblQwUHByaXp1?=
 =?utf-8?B?T3ZlT1NUcnFnYXVhQm9HVmtDRTVyTm1NZXNlYzh2SHFnM0JoWHROb1JyZU9q?=
 =?utf-8?B?TmZ5eUdRNW92SmhuZXhld0ZPYjQxdjhTU0hqajJVWk5QZ1RuUzhqWW5Zb0Iw?=
 =?utf-8?B?ZnVIY1pKeEdnZGJKdmE0L0JQdUtHMWkvSXdpTGVVSWppbTBobDd3OG5La3Ba?=
 =?utf-8?B?NFNuT25qVjR2Z2pLakh4eVBadWZ3T3I1UGVEcE1JN3ROcUtWRUxvTGVqazBx?=
 =?utf-8?B?S3I4NmtHYjY4N1JQTUU2TVlUS3RRQXhXVGkzUytZcVdiMGpjTTFFcnZRemlK?=
 =?utf-8?B?MGlXUzhJQk5ub0VYekNFSWdwZ1doZVVLQk95V2M1bWZybG9EcFlGZm42L2JU?=
 =?utf-8?B?RXNzbTVDSTNXd2hZUExyUzMrQ1FobHoxNVNpTDArZlJoSU5JdmwxMmdGOWNz?=
 =?utf-8?B?QmZ0UmJDNXlzZUUrWm1jbkNKTGMzYnBoVTF6Um11RUdCSGw3aTgwV2JoOUpZ?=
 =?utf-8?B?L3NaRDIxWTNrVWt5bXJ2Vlk2WWhaNy9pWWp1Z21ReldyLzVCM2RKU25RVzA1?=
 =?utf-8?B?WXpnbU15ZUZPU1ZFTmpvaEdSN1pJZkYrQks3YlhSMmkwb1AyaG9BT0hONE1O?=
 =?utf-8?B?dlRQL3NhQ1lYRGdnL09VbGJicWI0a2JiL3FtenFVRmM0QlBuOTlCMEZ2K1hT?=
 =?utf-8?B?UzhKS1JORlNXL2JOeFdWQjdvUzJtb1M5cjhjYnljK1owdnJ4TS9ZUUZKWHNj?=
 =?utf-8?B?SEZzQy91RWIycW5WU0xTRjdvNzFudjIrQ1NkUDVWYStzK2xpRjE1N1ZpVFVP?=
 =?utf-8?B?cjdESU9sMkdDWmdYdVFLb2h3WTJkRDRoSFVGaE5VWkpBUUc2T0R6U0pWemFj?=
 =?utf-8?B?K0lZWEc1N0dYTWZrdElEaStiVDNqQnVPMlY2UGlSWlRtU0o3SGd4aFpDb1pa?=
 =?utf-8?B?cHV3QXNRTm5oRVNDMTAyN1huWllmbEZVYkIxTFlEVFk3NnRmT1JIZWxXQi9Z?=
 =?utf-8?B?T1Y3VWhxUnp3cDJmWDljSEhsUGgxWDhGeVBOMXJieG1SMTBqNE5iOXNGVlJY?=
 =?utf-8?B?RkdEMytwWkVPdW5CZEtudUp1bEhtbHBsRXFRWUc3MFovY2xxSWtWcFJyQVg3?=
 =?utf-8?B?MVhRWXVtdlY4b2l0cWdzditvekkzclZJeERoeGtmU04vcUYwS1FCODBrMEN6?=
 =?utf-8?B?cGdpSmM2YXIwR2Vaa2kwZFhlS0x1cHN4blN2RHJ0QkNONi9TYStNbnNMZ1d6?=
 =?utf-8?B?ZFpGWVl0UkpORG8zc01waUxOSWx0R25pcFZ2YktBUHB3ZXRpSHNYd3d3VXFm?=
 =?utf-8?B?d0dEL25NbS8zd3MvdmhDaFRPUnBZRVZyZlJPVyt3bjlpU0R1TTBYYWtJWWNx?=
 =?utf-8?B?ODNza0g2RERzK0lLMVVuQnZjQWtyM1BYOEJkeGVqL0w3WW5MQ3R3MzdpMHpZ?=
 =?utf-8?B?MDRwT0NrR1hueW5VU0RrVlJWUFk5emNDY2pDVmRQSVIxTmxVRnpSejd2aG9a?=
 =?utf-8?B?K1E9PQ==?=
X-OriginatorOrg: wolfvision.net
X-MS-Exchange-CrossTenant-Network-Message-Id: 52afc636-975a-4fe1-09f8-08db4571cb2c
X-MS-Exchange-CrossTenant-AuthSource: GV1SPRMB0046.eurprd08.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 25 Apr 2023 09:45:24.6776
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: e94ec9da-9183-471e-83b3-51baa8eb804f
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: 867sJcN4MPM4n9lfWSdRdGjcNWjYwgSZDN2ejMkliwmeqecv4QLnUULHMxI1QfS11pdZOXJF47xooZ0OfgQshNFXL9ZWKFxLwBcvJle/KTk=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: DU0PR08MB7995
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_NONE,
        RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS,T_SCC_BODY_TEXT_LINE,
        URIBL_BLOCKED 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: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

The control V4L2_CID_FOCUS_RELATIVE only makes sense if the device cannot
handle absolute focal point positioning with V4L2_CID_FOCUS_ABSOLUTE.
Clarify this in the documentation.

Signed-off-by: Michael Riesch <michael.riesch@wolfvision.net>
---
 Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst
index df29150dce7b..42cf4c3cda0c 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst
@@ -147,7 +147,9 @@ enum v4l2_exposure_metering -
     This control moves the focal point of the camera by the specified
     amount. The unit is undefined. Positive values move the focus closer
     to the camera, negative values towards infinity. This is a
-    write-only control.
+    write-only control. It should be implemented only if the device cannot
+    handle absolute values.
+
 
 ``V4L2_CID_FOCUS_AUTO (boolean)``
     Enables continuous automatic focus adjustments. The effect of manual

-- 
2.37.2