media: v4l2-common: Add legacy camera sensor clock helper

The recently introduced devm_v4l2_sensor_clk_get() helper aims at
simplifying sensor drivers by centralizing clock handling code, as well
as reducing cargo-cult and deprecated behaviour.

A set of drivers implement external clock handling in a non-standard
way. This can't be changed as there is a high risk of breaking existing
platforms, but keeping the code as-is creates a risk of new drivers
copying deprecated behaviour.

To fix this, introduce a new devm_v4l2_sensor_clk_get_legacy() helper
and use it in those driver. Compared to devm_v4l2_sensor_clk_get(), the
new helper takes the "clock-frequency" property into account and sets
the external clock rate on OF platforms, and adds the ability to specify
a fixed default or fallback clock rate in case the "clock-frequency"
property is not present.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Reviewed-by: Mehdi Djait <mehdi.djait@linux.intel.com>
Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>

drivers/media/v4l2-core/v4l2-common.c

@@ -708,24 +708,40 @@ int v4l2_link_freq_to_bitmap(struct device *dev, const u64 *fw_link_freqs,
 }
 EXPORT_SYMBOL_GPL(v4l2_link_freq_to_bitmap);
 
-struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
+struct clk *__devm_v4l2_sensor_clk_get(struct device *dev, const char *id,
+				       bool legacy, bool fixed_rate,
+				       unsigned long clk_rate)
 {
+	bool of_node = is_of_node(dev_fwnode(dev));
 	const char *clk_id __free(kfree) = NULL;
 	struct clk_hw *clk_hw;
 	struct clk *clk;
-	bool of_node;
-	u32 rate;
-	int ret;
+	u32 rate = clk_rate;
+	int ret = 0;
 
 	clk = devm_clk_get_optional(dev, id);
 	if (IS_ERR(clk))
 		return clk;
 
-	ret = device_property_read_u32(dev, "clock-frequency", &rate);
-	of_node = is_of_node(dev_fwnode(dev));
+	/*
+	 * If the caller didn't request a fixed rate, retrieve it from the
+	 * clock-frequency property. -EINVAL indicates the property is absent,
+	 * and is not a failure. Other errors, or success with a clock-frequency
+	 * value of 0, are hard failures.
+	 */
+	if (!fixed_rate || !clk_rate) {
+		ret = device_property_read_u32(dev, "clock-frequency", &rate);
+		if ((ret && ret != -EINVAL) || (!ret && !rate))
+			return ERR_PTR(-EINVAL);
+	}
 
 	if (clk) {
-		if (!ret && !of_node) {
+		/*
+		 * On non-OF platforms, or when legacy behaviour is requested,
+		 * set the clock rate if a rate has been specified by the caller
+		 * or by the clock-frequency property.
+		 */
+		if (rate && (!of_node || legacy)) {
 			ret = clk_set_rate(clk, rate);
 			if (ret) {
 				dev_err(dev, "Failed to set clock rate: %u\n",
@@ -736,9 +752,14 @@ struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
 		return clk;
 	}
 
-	if (!IS_ENABLED(CONFIG_COMMON_CLK) || of_node)
+	/*
+	 * Register a dummy fixed clock on non-OF platforms or when legacy
+	 * behaviour is requested. This required the common clock framework.
+	 */
+	if (!IS_ENABLED(CONFIG_COMMON_CLK) || (of_node && !legacy))
 		return ERR_PTR(-ENOENT);
 
+	/* We need a rate to create a clock. */
 	if (ret)
 		return ERR_PTR(ret == -EINVAL ? -EPROBE_DEFER : ret);
 
@@ -755,4 +776,4 @@ struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
 
 	return clk_hw->clk;
 }
-EXPORT_SYMBOL_GPL(devm_v4l2_sensor_clk_get);
+EXPORT_SYMBOL_GPL(__devm_v4l2_sensor_clk_get);

include/media/v4l2-common.h

@@ -612,6 +612,10 @@ int v4l2_link_freq_to_bitmap(struct device *dev, const u64 *fw_link_freqs,
 			     unsigned int num_of_driver_link_freqs,
 			     unsigned long *bitmap);
 
+struct clk *__devm_v4l2_sensor_clk_get(struct device *dev, const char *id,
+				       bool legacy, bool fixed_rate,
+				       unsigned long clk_rate);
+
 /**
  * devm_v4l2_sensor_clk_get - lookup and obtain a reference to a clock producer
  *	for a camera sensor
@@ -644,7 +648,42 @@ int v4l2_link_freq_to_bitmap(struct device *dev, const u64 *fw_link_freqs,
  *
  * Returns a pointer to a struct clk on success or an error pointer on failure.
  */
-struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id);
+static inline struct clk *
+devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
+{
+	return __devm_v4l2_sensor_clk_get(dev, id, false, false, 0);
+}
+
+/**
+ * devm_v4l2_sensor_clk_get_legacy - lookup and obtain a reference to a clock
+ *	producer for a camera sensor.
+ *
+ * @dev: device for v4l2 sensor clock "consumer"
+ * @id: clock consumer ID
+ * @fixed_rate: interpret the @clk_rate as a fixed rate or default rate
+ * @clk_rate: the clock rate
+ *
+ * This function behaves the same way as devm_v4l2_sensor_clk_get() except that
+ * it extends the behaviour on ACPI platforms to all platforms.
+ *
+ * The function also provides the ability to set the clock rate to a fixed
+ * frequency by setting @fixed_rate to true and specifying the fixed frequency
+ * in @clk_rate, or to use a default clock rate when the "clock-frequency"
+ * property is absent by setting @fixed_rate to false and specifying the default
+ * frequency in @clk_rate. Setting @fixed_rate to true and @clk_rate to 0 is an
+ * error.
+ *
+ * This function is meant to support legacy behaviour in existing drivers only.
+ * It must not be used in any new driver.
+ *
+ * Returns a pointer to a struct clk on success or an error pointer on failure.
+ */
+static inline struct clk *
+devm_v4l2_sensor_clk_get_legacy(struct device *dev, const char *id,
+				bool fixed_rate, unsigned long clk_rate)
+{
+	return __devm_v4l2_sensor_clk_get(dev, id, true, fixed_rate, clk_rate);
+}
 
 static inline u64 v4l2_buffer_get_timestamp(const struct v4l2_buffer *buf)
 {