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:13 +0200
Subject: [PATCH RFC v2 3/6] media: v4l2-ctrls: add lens group status
 controls for zoom and focus
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit
Message-Id: <20230406-feature-controls-lens-v2-3-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?dDVhMjNUYmU1ODlkREtSNlJTZ21jSzkxM1kvdG40Qk9xWDcvWjhEWllvcTF2?=
 =?utf-8?B?b1lsMXNld3dUcit5VEh2bzRWMk9ER3NyTUhJeWpndXZrNDIvZHFEWHgwQ0JC?=
 =?utf-8?B?dmlxV09Qb0VnTlV4NVNscmdTalZnU2IxbmprNDFHMGlQSmdFS09OSjRaK3ZJ?=
 =?utf-8?B?dmU5TDIvT2JoWXlTc29BeUNlT1ptc3pHS2JrWmQ1dmtneG1SYVRrVi9JaTFT?=
 =?utf-8?B?VU4vWStRd1V2SlE3OXZmNGhuKzI2VVBnQXN5QVYzamplRk1sSWtXRUp2SHg1?=
 =?utf-8?B?NDNqSVd3azYwR0xpdFlKc3VvbmhETExIOWFHb3IzWnY5ak5IaHBEMjJLb1M0?=
 =?utf-8?B?MnZWRXpMR0tjQjRmVVlTU0htK1JqUVJMQWZWc3o4NFVFU0cvM00vRDhlQ3pt?=
 =?utf-8?B?c040MklHdUV6eDA0VjVRVWp3V2Y4aTB3bWZ0aHBibXRGYXNsRmttRkVjREM4?=
 =?utf-8?B?R3R0V1VsRzZNSkdmc3BlL2dIMU1RMkFJWjVuS3ZMbDZXQXBKVjE0emc1NkdR?=
 =?utf-8?B?bkxBbnJ2L2RnOEZGSThzb1FkWlc3OWg4WDJuQlN6c1RTNFMvb2grdlY3Mkgw?=
 =?utf-8?B?S2I3VE93c3VYRUhyc2k5bXl4VmJvU09pdEZDL3RQYXhzM0l6WGJmQ0NnbFFW?=
 =?utf-8?B?VHY5WHdYdTByNUMxQ050S29jUmllWFZRUUhLMFRoUnc5RmdadGt0eENVa0dy?=
 =?utf-8?B?YkVWS1FsZHZ0bkZ6WHQrTlhPREhpaDR1MkRPK3JtcVZRWkxid3JWRVUyS1Js?=
 =?utf-8?B?L1lFcXFkQ0ppUmExYmIvc2hBQ1ZYMzhRbnFqQnNyV1hsTGZySHdIcG1lbDJP?=
 =?utf-8?B?T21peng3eXUyeStMNTQra2lZNWxaYTkwK29WdGp3RXY2SVJKRFNSbFNyNVBR?=
 =?utf-8?B?SmJraEZiQVFHS0FXWGM2ZTczUXYzNDAvUzBJZ1I5TzdtdG1TN0FVdjlHaytr?=
 =?utf-8?B?OXhKUXRIQ1VpaWRDWlZMQzFLSThLU0Z1eGd2U09tWDV4K3Y0dk1mYTNrK205?=
 =?utf-8?B?ZWJsOWhYKzFYbXozYnAwK01LeFB3U3RyRXpkd3FobXp0TGtrcWRoK016U21L?=
 =?utf-8?B?TStHSzFrcjhwVGVyN0drVTViWUUzU0gvWnVBdlNxeDdnTnBocHpKUlpSWE1W?=
 =?utf-8?B?Mjh2K3J2TjVRSVZWNXhLcmxBN2VjOGJkMVZpekFKSjRSTE5BR1RDYTNRUHZK?=
 =?utf-8?B?TjlpVUtwWFVKSEpjbjhFK0FlRE8wVW5MN3lLTWNRbVRuSktUaTF1R1lIYkRp?=
 =?utf-8?B?eHdiTDRHbkFJSmczcnprNi93NEg1TThjYzFBWmZRZ055NzZlcTk0dU9HaUJD?=
 =?utf-8?B?OHB6YnIyNnhXU0Z0eis5YVlnZDR4ajlMMWZ1MWZKL1FaTWlyUDZ2bE81Zm05?=
 =?utf-8?B?U3F4M1YxQTRtdm5DMVcxamFFTTR4cldzTk5qc09USnlhV2piTEo5SzJjK1B4?=
 =?utf-8?B?Vks3aXZVQ2ZIYUNycnk5SVFabVZwVjJUcndjWWZSSjlBUW1rMnFYU3ZjUkJj?=
 =?utf-8?B?bG9nU3ZCWld0ai9KcDQzVWFIbkRXRDVwbDdibFlzeDFSaWhpWGd4WDlEQU9y?=
 =?utf-8?B?em9uVDdBekhBWURFWVJTdFVwMTJGQWRaQys2WlpXMkYzU291a2pMcjh0OTNT?=
 =?utf-8?B?eENoU1RWdUVYVjBYZ3JNejVkTm5HWjZMdDFQeURwZks1NmFzdGxUcVdxQjFT?=
 =?utf-8?B?RmN6bG5GR3didnZ0cjN0bm9KeXVPTlgyOU5BM1BpeWtQWHRSMGU0Zjl4U09P?=
 =?utf-8?B?YVJZMW5UcWFRMVJaMWIraWh2QVBFeUlqZlN6dFhIZ08wWWNiNUpScWxvUzgv?=
 =?utf-8?B?cnM3VWJNcFVIUUNtVTkxS1F5bllTYm85R0ZoeGN5cGxnOEc5RDB3a1EwMk9j?=
 =?utf-8?B?Ulg5MDl2TUhyclphdlFQUkRpZk9vVzRsMjZJbmJNbmN5STZvM3RTRUwxZGhQ?=
 =?utf-8?B?OFBHVnhjZjZYRUlWTHNtZUllM3BJTzdiRmJGaThsRFNEQm5OaDlQMFAyYkxm?=
 =?utf-8?B?OHIvNEtPUlpyelVKY3poRG9ndVVJZDN1WmtUcm1MSGx1WWc0OFlFSEgxdVRl?=
 =?utf-8?B?MDJPZzlmVTR3ajBEYzBmcGg3cndRa2pRK2V1NlVQZ3BRT1pvam9LczNiOCtV?=
 =?utf-8?B?UzM5QjRPM3FYUTJkY0NSUFFSalRnbHlOYmZYUVRXaFdmNXdmeDdHeSs4VUxK?=
 =?utf-8?B?Y2c9PQ==?=
X-OriginatorOrg: wolfvision.net
X-MS-Exchange-CrossTenant-Network-Message-Id: c9bbbe5b-b84d-4d9e-12df-08db4571cb9c
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:25.4366
 (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: iBtpHv1xbmlZF57ajBLFX6fQh5kB4SJyuslA6EDvQY0EoCKob87W/Cq83ZqLjBoGFgcsop658jp/A2wJj8qgmXcsxaZHeU+j8+M1kBZd4Mk=
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

Add the controls V4L2_CID_{FOCUS,ZOOM}_{CURRENT,STATUS} that report the
current position and status, respectively, of the zoom lens group and
the focus lens group.

Signed-off-by: Michael Riesch <michael.riesch@wolfvision.net>
---
 .../userspace-api/media/v4l/ext-ctrls-camera.rst   | 46 ++++++++++++++++++++++
 drivers/media/v4l2-core/v4l2-ctrls-defs.c          | 10 +++++
 include/uapi/linux/v4l2-controls.h                 |  9 +++++
 3 files changed, 65 insertions(+)

diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst
index 42cf4c3cda0c..3ea4175f9619 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst
@@ -150,6 +150,29 @@ enum v4l2_exposure_metering -
     write-only control. It should be implemented only if the device cannot
     handle absolute values.
 
+``V4L2_CID_FOCUS_CURRENT (integer)``
+    The current position of the focal point. The unit is undefined. Larger
+    values indicate that the focus is closer to the camera, smaller values
+    indicate that the focus is closer to infinity. This is a read-only control.
+
+``V4L2_CID_FOCUS_STATUS (bitmask)``
+    The status of the focus lens group. The possible flags are described in
+    the table below. This is a read-only control.
+
+.. tabularcolumns:: |p{6.8cm}|p{10.7cm}|
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    * - ``V4L2_LENS_STATUS_IDLE``
+      - Focus lens group is at rest.
+    * - ``V4L2_LENS_STATUS_BUSY``
+      - Focus lens group is moving.
+    * - ``V4L2_LENS_STATUS_FAILED``
+      - Focus lens group has failed to reach its target position. The driver
+	will not transition from this state until another action is performed
+	by an application.
 
 ``V4L2_CID_FOCUS_AUTO (boolean)``
     Enables continuous automatic focus adjustments. The effect of manual
@@ -241,6 +264,29 @@ enum v4l2_auto_focus_range -
     movement. A negative value moves the zoom lens group towards the
     wide-angle direction. The zoom speed unit is driver-specific.
 
+``V4L2_CID_ZOOM_CURRENT (integer)``
+    The current objective lens focal length. The unit is undefined and
+    its value should be a positive integer. This is a read-only control.
+
+``V4L2_CID_ZOOM_STATUS (bitmask)``
+    The status of the zoom lens group. The possible flags are described in
+    the table below. This is a read-only control.
+
+.. tabularcolumns:: |p{6.8cm}|p{10.7cm}|
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    * - ``V4L2_LENS_STATUS_IDLE``
+      - Zoom lens group is at rest.
+    * - ``V4L2_LENS_STATUS_BUSY``
+      - Zoom lens group is moving.
+    * - ``V4L2_LENS_STATUS_FAILED``
+      - Zoom lens group has failed to reach its target position. The driver will
+	not transition from this state until another action is performed by an
+	application.
+
 ``V4L2_CID_IRIS_ABSOLUTE (integer)``
     This control sets the camera's aperture to the specified value. The
     unit is undefined. Larger values open the iris wider, smaller values
diff --git a/drivers/media/v4l2-core/v4l2-ctrls-defs.c b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
index 564fedee2c88..794ef3ab0c02 100644
--- a/drivers/media/v4l2-core/v4l2-ctrls-defs.c
+++ b/drivers/media/v4l2-core/v4l2-ctrls-defs.c
@@ -1044,6 +1044,10 @@ const char *v4l2_ctrl_get_name(u32 id)
 	case V4L2_CID_CAMERA_ORIENTATION:	return "Camera Orientation";
 	case V4L2_CID_CAMERA_SENSOR_ROTATION:	return "Camera Sensor Rotation";
 	case V4L2_CID_HDR_SENSOR_MODE:		return "HDR Sensor Mode";
+	case V4L2_CID_FOCUS_CURRENT:		return "Focus, Current";
+	case V4L2_CID_FOCUS_STATUS:		return "Focus, Status";
+	case V4L2_CID_ZOOM_CURRENT:		return "Zoom, Current";
+	case V4L2_CID_ZOOM_STATUS:		return "Zoom, Status";
 
 	/* FM Radio Modulator controls */
 	/* Keep the order of the 'case's the same as in v4l2-controls.h! */
@@ -1593,6 +1597,12 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
 		*flags |= V4L2_CTRL_FLAG_WRITE_ONLY |
 			  V4L2_CTRL_FLAG_EXECUTE_ON_WRITE;
 		break;
+	case V4L2_CID_FOCUS_CURRENT:
+	case V4L2_CID_FOCUS_STATUS:
+	case V4L2_CID_ZOOM_CURRENT:
+	case V4L2_CID_ZOOM_STATUS:
+		*flags |= V4L2_CTRL_FLAG_READ_ONLY | V4L2_CTRL_FLAG_VOLATILE;
+		break;
 	case V4L2_CID_FLASH_STROBE_STATUS:
 	case V4L2_CID_AUTO_FOCUS_STATUS:
 	case V4L2_CID_FLASH_READY:
diff --git a/include/uapi/linux/v4l2-controls.h b/include/uapi/linux/v4l2-controls.h
index 5e80daa4ffe0..793ee8c65e87 100644
--- a/include/uapi/linux/v4l2-controls.h
+++ b/include/uapi/linux/v4l2-controls.h
@@ -993,6 +993,15 @@ enum v4l2_auto_focus_range {
 
 #define V4L2_CID_HDR_SENSOR_MODE		(V4L2_CID_CAMERA_CLASS_BASE+36)
 
+#define V4L2_LENS_STATUS_IDLE			(0 << 0)
+#define V4L2_LENS_STATUS_BUSY			(1 << 0)
+#define V4L2_LENS_STATUS_FAILED			(1 << 2)
+
+#define V4L2_CID_FOCUS_CURRENT			(V4L2_CID_CAMERA_CLASS_BASE+37)
+#define V4L2_CID_FOCUS_STATUS			(V4L2_CID_CAMERA_CLASS_BASE+38)
+#define V4L2_CID_ZOOM_CURRENT			(V4L2_CID_CAMERA_CLASS_BASE+39)
+#define V4L2_CID_ZOOM_STATUS			(V4L2_CID_CAMERA_CLASS_BASE+40)
+
 /* FM Modulator class control IDs */
 
 #define V4L2_CID_FM_TX_CLASS_BASE		(V4L2_CTRL_CLASS_FM_TX | 0x900)

-- 
2.37.2