[RFC v2 3/5] media: v4l2-ctrls: Add v4l2 helper functions for single-capture controls

[Mirela Rabulea <mirela.rabulea@nxp.com>]

Add v4l2 helper functions to support backward compatibility
with older user-space applications that are still using the
single-capture exposure and gain controls.

After the addition of multi-capture exposure and gain controls,
the following scenarios are possible:
1. Old applications & old sensor drivers
   Both the application and the driver are using single-capture controls,
   no problem here.
2. Old applications & new sensor drivers
   The application is using single-capture controls and we want the drivers
   to implement only the new multi-capture controls. In this case the
   driver should use the v4l2_ctrl_new_single_cap_ctrls helper to create
   the old single-capture controls, for backward compatibility.
3. New application & old sensor drivers
   The new application can query if the driver supports multi-capture
   controls, if it doesn't, the application may fallback to single-capture
   controls.
4. New application & new sensor drivers
   Both the application and the driver are using multi-capture controls,
   again, no problem here.

Signed-off-by: Mirela Rabulea <mirela.rabulea@nxp.com>
---

Changes in v2:
	New patch

 drivers/media/v4l2-core/v4l2-ctrls-core.c | 85 +++++++++++++++++++++++
 include/media/v4l2-ctrls.h                | 76 ++++++++++++++++++++
 2 files changed, 161 insertions(+)

diff --git a/drivers/media/v4l2-core/v4l2-ctrls-core.c b/drivers/media/v4l2-core/v4l2-ctrls-core.c
index 98b960775e87..41f307e3afa6 100644
--- a/drivers/media/v4l2-core/v4l2-ctrls-core.c
+++ b/drivers/media/v4l2-core/v4l2-ctrls-core.c
@@ -2719,3 +2719,88 @@ int v4l2_ctrl_new_fwnode_properties(struct v4l2_ctrl_handler *hdl,
 	return hdl->error;
 }
 EXPORT_SYMBOL(v4l2_ctrl_new_fwnode_properties);
+
+int v4l2_ctrl_new_single_cap_ctrls(struct v4l2_ctrl_handler *hdl,
+				   const struct v4l2_ctrl_ops *ctrl_ops)
+{
+	if (hdl->error)
+		return hdl->error;
+
+	v4l2_ctrl_new_std(hdl, ctrl_ops, V4L2_CID_EXPOSURE,
+			  0, 0, 1, 0);
+
+	v4l2_ctrl_new_std(hdl, ctrl_ops, V4L2_CID_ANALOGUE_GAIN,
+			  0, 0, 1, 0);
+
+	v4l2_ctrl_new_std(hdl, ctrl_ops, V4L2_CID_DIGITAL_GAIN,
+			  0, 0, 1, 0);
+
+	return hdl->error;
+}
+EXPORT_SYMBOL(v4l2_ctrl_new_single_cap_ctrls);
+
+struct v4l2_ctrl *__v4l2_get_multi_ctrl(struct v4l2_ctrl *ctrl_single)
+{
+	struct v4l2_ctrl_handler *hdl = ctrl_single->handler;
+	struct v4l2_ctrl_ref *ref;
+
+	switch (ctrl_single->id) {
+	case V4L2_CID_EXPOSURE:
+		ref = find_ref(hdl, V4L2_CID_EXPOSURE_MULTI);
+		break;
+	case V4L2_CID_ANALOGUE_GAIN:
+		ref = find_ref(hdl, V4L2_CID_AGAIN_MULTI);
+		break;
+	case V4L2_CID_DIGITAL_GAIN:
+		ref = find_ref(hdl, V4L2_CID_DGAIN_MULTI);
+		break;
+	default:
+		return NULL;
+	}
+
+	return ref->ctrl;
+}
+EXPORT_SYMBOL(__v4l2_get_multi_ctrl);
+
+struct v4l2_ctrl *__v4l2_get_single_ctrl(struct v4l2_ctrl *ctrl_multi)
+{
+	struct v4l2_ctrl_handler *hdl = ctrl_multi->handler;
+	struct v4l2_ctrl_ref *ref;
+
+	switch (ctrl_multi->id) {
+	case V4L2_CID_EXPOSURE_MULTI:
+		ref = find_ref(hdl, V4L2_CID_EXPOSURE);
+		break;
+	case V4L2_CID_AGAIN_MULTI:
+		ref = find_ref(hdl, V4L2_CID_ANALOGUE_GAIN);
+		break;
+	case V4L2_CID_DGAIN_MULTI:
+		ref = find_ref(hdl, V4L2_CID_DIGITAL_GAIN);
+		break;
+	default:
+		return NULL;
+	}
+
+	return ref->ctrl;
+}
+EXPORT_SYMBOL(__v4l2_get_single_ctrl);
+
+int __v4l2_s_ctrl_multi_to_single(struct v4l2_ctrl *ctrl_multi)
+{
+	struct v4l2_ctrl *ctrl_single = NULL;
+
+	if (!ctrl_multi)
+		return -EINVAL;
+
+	ctrl_single = __v4l2_get_single_ctrl(ctrl_multi);
+	/* don't fail if no corresponding single control is found */
+	if (!ctrl_single)
+		return 0;
+
+	/* update the value of the single control, without calling s_ctrl */
+	ctrl_single->cur.val = ctrl_multi->p_cur.p_u32[0];
+
+	return 0;
+}
+EXPORT_SYMBOL(__v4l2_s_ctrl_multi_to_single);
+
diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
index 4a294a5c7bdd..d3a9dde47349 100644
--- a/include/media/v4l2-ctrls.h
+++ b/include/media/v4l2-ctrls.h
@@ -1587,6 +1587,82 @@ int v4l2_ctrl_new_fwnode_properties(struct v4l2_ctrl_handler *hdl,
 				    const struct v4l2_ctrl_ops *ctrl_ops,
 				    const struct v4l2_fwnode_device_properties *p);
 
+/**
+ * v4l2_ctrl_new_single_cap_ctrls() - Register single capture controls for
+ *				      backward compatibility
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler to register controls on
+ * @ctrl_ops: pointer to &struct v4l2_ctrl_ops to register controls with
+ *
+ * This function registers the single capture controls for exposure
+ * and gains, for backward compatibility with userspace applications that
+ * do not use yet the new, multi-capture controls.
+ *
+ * Currently, the following v4l2 controls are parsed and registered:
+ * - V4L2_CID_EXPOSURE
+ * - V4L2_CID_ANALOGUE_GAIN
+ * - V4L2_CID_DIGITAL_GAIN;
+ *
+ * Controls already registered by the caller with the @hdl control handler are
+ * not overwritten. Callers should register the controls they want to handle
+ * themselves before calling this function.
+ *
+ * Return: 0 on success, a negative error code on failure.
+ */
+int v4l2_ctrl_new_single_cap_ctrls(struct v4l2_ctrl_handler *hdl,
+				   const struct v4l2_ctrl_ops *ctrl_ops);
+
+/**
+ * __v4l2_get_multi_ctrl() - Return the multi-capture controls for a given
+ *			     single-capture control
+ *
+ * @ctrl_single: pointer to &struct v4l2_ctrl for the single-capture control
+ *
+ * This function finds the corresponding multi-capture control for a given
+ * single-capture control.
+ *
+ * This function assumes the control's handler is already locked,
+ * allowing it to be used from within the &v4l2_ctrl_ops functions.
+ *
+ * Return: a pointer to the multi-capture control if found, NULL otherwise.
+ */
+struct v4l2_ctrl *__v4l2_get_multi_ctrl(struct v4l2_ctrl *ctrl_single);
+
+/**
+ * __v4l2_get_single_ctrl() - Return the single-capture controls for a given
+ *			      multi-capture control
+ *
+ * @ctrl_multi: pointer to &struct v4l2_ctrl for the multi-capture control
+ *
+ * This function finds the corresponding single-capture control for a given
+ * multi-capture control.
+ *
+ * This function assumes the control's handler is already locked,
+ * allowing it to be used from within the &v4l2_ctrl_ops functions.
+ *
+ * Return: a pointer to the single-capture control if found, NULL otherwise.
+ */
+struct v4l2_ctrl *__v4l2_get_single_ctrl(struct v4l2_ctrl *ctrl_multi);
+
+/**
+ * __v4l2_s_ctrl_multi_to_single() - Set the single-capture control for a
+ *				     given multi-capture control
+ *
+ * @ctrl_multi: pointer to &struct v4l2_ctrl for the multi-capture control
+ *
+ * This function finds the corresponding single-capture control for a given
+ * multi-capture control, and updates single-capture control with the value
+ * from the first element of the multie-capture control, to ensure
+ * backward compatibility with older user-space applications that still use
+ * the single-capture exposure and gain controls.
+ *
+ * This function assumes the control's handler is already locked,
+ * allowing it to be used from within the &v4l2_ctrl_ops functions.
+ *
+ * Return: 0 on success, a negative error code on failure.
+ */
+int __v4l2_s_ctrl_multi_to_single(struct v4l2_ctrl *ctrl_multi);
+
 /**
  * v4l2_ctrl_type_op_equal - Default v4l2_ctrl_type_ops equal callback.
  *
-- 
2.43.0