[RFC PATCH v5] media: v4l2-common: Add a helper for obtaining the clock producer

[RFC PATCH v5] media: v4l2-common: Add a helper for obtaining the clock producer

[Mehdi Djait]

Introduce a helper for v4l2 sensor drivers on both DT- and ACPI-based
platforms to retrieve a reference to the clock producer from firmware.

This helper behaves the same as clk_get_optional() except where there is
no clock producer like in ACPI-based platforms.

For ACPI-based platforms the function will read the "clock-frequency"
ACPI _DSD property and register a fixed frequency clock with the frequency
indicated in the property.

This function also handles the special ACPI-based system case where:
The clock-frequency _DSD property is present.
A reference to the clock producer is present, where the clock is provided
by a camera sensor PMIC driver (e.g. int3472/tps68470.c).
In this case try to set the clock-frequency value to the provided clock.

Signed-off-by: Mehdi Djait <mehdi.djait@linux.intel.com>
---
v4 -> v5:
Suggested by Arnd Bergmann:
	- removed IS_REACHABLE(CONFIG_COMMON_CLK). IS_REACHABLE() is actually
	discouraged [1]. COFIG_COMMON_CLK is a bool, so IS_ENABLED() will be the
	right solution here
Suggested by Hans de Goede:
	- added handling for the special ACPI-based system case, where
	  both a reference to the clock-provider and the _DSD
	  clock-frequency are present.
	- updated the function's kernel-doc and the commit msg
	  to mention this special case.
Link v4: https://lore.kernel.org/linux-media/20250321130329.342236-1-mehdi.djait@linux.intel.com/
[1] https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/Documentation/kbuild/kconfig-language.rst?h=next-20250513&id=700bd25bd4f47a0f4e02e0a25dde05f1a6b16eea

v3 -> v4:
Suggested by Laurent:
	- removed the #ifdef to use IS_REACHABLE(CONFIG_COMMON_CLK)
	- changed to kasprintf() to allocate the clk name when id is NULL and
	  used the __free(kfree) scope-based cleanup helper when
	  defining the variable to hold the allocated name
Link v3: https://lore.kernel.org/linux-media/20250321093814.18159-1-mehdi.djait@linux.intel.com/

v2 -> v3:
- Added #ifdef CONFIG_COMMON_CLK for the ACPI case
Link v2: https://lore.kernel.org/linux-media/20250310122305.209534-1-mehdi.djait@linux.intel.com/

v1 -> v2:
Suggested by Sakari:
    - removed clk_name
    - removed the IS_ERR() check
    - improved the kernel-doc comment and commit msg
Link v1: https://lore.kernel.org/linux-media/20250227092643.113939-1-mehdi.djait@linux.intel.com



 drivers/media/v4l2-core/v4l2-common.c | 46 +++++++++++++++++++++++++++
 include/media/v4l2-common.h           | 25 +++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/drivers/media/v4l2-core/v4l2-common.c b/drivers/media/v4l2-core/v4l2-common.c
index 4ee4aa19efe6..6099acd339ad 100644
--- a/drivers/media/v4l2-core/v4l2-common.c
+++ b/drivers/media/v4l2-core/v4l2-common.c
@@ -34,6 +34,9 @@
  * Added Gerd Knorrs v4l1 enhancements (Justin Schoeman)
  */
 
+#include <linux/clk.h>
+#include <linux/clkdev.h>
+#include <linux/clk-provider.h>
 #include <linux/module.h>
 #include <linux/types.h>
 #include <linux/kernel.h>
@@ -665,3 +668,46 @@ int v4l2_link_freq_to_bitmap(struct device *dev, const u64 *fw_link_freqs,
 	return 0;
 }
 EXPORT_SYMBOL_GPL(v4l2_link_freq_to_bitmap);
+
+struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
+{
+	const char *clk_id __free(kfree) = NULL;
+	struct clk_hw *clk_hw;
+	struct clk *clk;
+	u32 rate;
+	int ret;
+
+	clk = devm_clk_get_optional(dev, id);
+	ret = device_property_read_u32(dev, "clock-frequency", &rate);
+
+	if (clk) {
+		if (!ret) {
+			ret = clk_set_rate(clk, rate);
+			if (ret)
+				dev_warn(dev, "Failed to set clock rate: %u\n",
+					 rate);
+		}
+
+		return clk;
+	}
+
+	if (ret)
+		return ERR_PTR(ret);
+
+	if (!IS_ENABLED(CONFIG_COMMON_CLK) || !is_acpi_node(dev_fwnode(dev)))
+		return ERR_PTR(-ENOENT);
+
+	if (!id) {
+		clk_id = kasprintf(GFP_KERNEL, "clk-%s", dev_name(dev));
+		if (!clk_id)
+			return ERR_PTR(-ENOMEM);
+		id = clk_id;
+	}
+
+	clk_hw = devm_clk_hw_register_fixed_rate(dev, id, NULL, 0, rate);
+	if (IS_ERR(clk_hw))
+		return ERR_CAST(clk_hw);
+
+	return clk_hw->clk;
+}
+EXPORT_SYMBOL_GPL(devm_v4l2_sensor_clk_get);
diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
index fda903bb3674..5ddbf7b3d9c3 100644
--- a/include/media/v4l2-common.h
+++ b/include/media/v4l2-common.h
@@ -586,6 +586,31 @@ int v4l2_link_freq_to_bitmap(struct device *dev, const u64 *fw_link_freqs,
 			     unsigned int num_of_driver_link_freqs,
 			     unsigned long *bitmap);
 
+/**
+ * devm_v4l2_sensor_clk_get - lookup and obtain a reference to an optional clock
+ *			      producer for a camera sensor.
+ *
+ * @dev: device for v4l2 sensor clock "consumer"
+ * @id: clock consumer ID
+ *
+ * This function behaves the same way as clk_get_optional() except where there
+ * is no clock producer like in ACPI-based platforms.
+ *
+ * For ACPI-based platforms, the function will read the "clock-frequency"
+ * ACPI _DSD property and register a fixed-clock with the frequency indicated
+ * in the property.
+ *
+ * This function also handles the special ACPI-based system case where:
+ * The clock-frequency _DSD property is present.
+ * A reference to the clock producer is present, where the clock is provided by
+ * a camera sensor PMIC driver (e.g. int3472/tps68470.c)
+ * In this case try to set the clock-frequency value to the provided clock.
+ *
+ * Return:
+ * * pointer to a struct clk on success or an error code on failure.
+ */
+struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id);
+
 static inline u64 v4l2_buffer_get_timestamp(const struct v4l2_buffer *buf)
 {
 	/*
-- 
2.49.0

Re: [RFC PATCH v5] media: v4l2-common: Add a helper for obtaining the clock producer

[Mehdi Djait]

Hi everyone,

On Wed, May 21, 2025 at 12:41:15PM +0200, Mehdi Djait wrote:
>  drivers/media/v4l2-core/v4l2-common.c | 46 +++++++++++++++++++++++++++
>  include/media/v4l2-common.h           | 25 +++++++++++++++
>  2 files changed, 71 insertions(+)
> 
> diff --git a/drivers/media/v4l2-core/v4l2-common.c b/drivers/media/v4l2-core/v4l2-common.c
> index 4ee4aa19efe6..6099acd339ad 100644
> --- a/drivers/media/v4l2-core/v4l2-common.c
> +++ b/drivers/media/v4l2-core/v4l2-common.c
> @@ -34,6 +34,9 @@
>   * Added Gerd Knorrs v4l1 enhancements (Justin Schoeman)
>   */
>  
> +#include <linux/clk.h>
> +#include <linux/clkdev.h>
> +#include <linux/clk-provider.h>
>  #include <linux/module.h>
>  #include <linux/types.h>
>  #include <linux/kernel.h>
> @@ -665,3 +668,46 @@ int v4l2_link_freq_to_bitmap(struct device *dev, const u64 *fw_link_freqs,
>  	return 0;
>  }
>  EXPORT_SYMBOL_GPL(v4l2_link_freq_to_bitmap);
> +
> +struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
> +{
> +	const char *clk_id __free(kfree) = NULL;
> +	struct clk_hw *clk_hw;
> +	struct clk *clk;
> +	u32 rate;
> +	int ret;
> +
> +	clk = devm_clk_get_optional(dev, id);
> +	ret = device_property_read_u32(dev, "clock-frequency", &rate);
> +
> +	if (clk) {
> +		if (!ret) {
> +			ret = clk_set_rate(clk, rate);
> +			if (ret)
> +				dev_warn(dev, "Failed to set clock rate: %u\n",
> +					 rate);
> +		}
> +
> +		return clk;
> +	}
> +
> +	if (ret)
> +		return ERR_PTR(ret);
> +
> +	if (!IS_ENABLED(CONFIG_COMMON_CLK) || !is_acpi_node(dev_fwnode(dev)))
> +		return ERR_PTR(-ENOENT);
> +
> +	if (!id) {
> +		clk_id = kasprintf(GFP_KERNEL, "clk-%s", dev_name(dev));
> +		if (!clk_id)
> +			return ERR_PTR(-ENOMEM);
> +		id = clk_id;
> +	}
> +
> +	clk_hw = devm_clk_hw_register_fixed_rate(dev, id, NULL, 0, rate);
> +	if (IS_ERR(clk_hw))
> +		return ERR_CAST(clk_hw);
> +
> +	return clk_hw->clk;
> +}
> +EXPORT_SYMBOL_GPL(devm_v4l2_sensor_clk_get);

I sent this as an RFC because I am still unsure and need comments on two
things. After they are addressed, I plan to send a patch, documentation
patch (what Sakari proposed in the RFC V4 discussion) and convert the
camera sensors using devm_clk_get()

1. Should the case where both the clock and the clock-frequency are
present be reserved just for ACPI systems ? In other words if a DT
system provides both, should we also attempt to set the provided clock
rate ?

If the former makes more sense, maybe add this:

diff --git a/drivers/media/v4l2-core/v4l2-common.c b/drivers/media/v4l2-core/v4l2-common.c
index 6099acd339ad..3dfbbd699c67 100644
--- a/drivers/media/v4l2-core/v4l2-common.c
+++ b/drivers/media/v4l2-core/v4l2-common.c
@@ -674,14 +674,16 @@ struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
        const char *clk_id __free(kfree) = NULL;
        struct clk_hw *clk_hw;
        struct clk *clk;
+       bool acpi_node;
        u32 rate;
        int ret;
 
        clk = devm_clk_get_optional(dev, id);
        ret = device_property_read_u32(dev, "clock-frequency", &rate);
+       acpi_node = is_acpi_node(dev_fwnode(dev));
 
        if (clk) {
-               if (!ret) {
+               if (!ret && acpi_node) {
                        ret = clk_set_rate(clk, rate);
                        if (ret)
                                dev_warn(dev, "Failed to set clock rate: %u\n",
@@ -694,7 +696,7 @@ struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
        if (ret)
                return ERR_PTR(ret);
 
-       if (!IS_ENABLED(CONFIG_COMMON_CLK) || !is_acpi_node(dev_fwnode(dev)))
+       if (!IS_ENABLED(CONFIG_COMMON_CLK) || !acpi_node)
                return ERR_PTR(-ENOENT);

2. Should we just warn when the clk_set_rate() fails or return err code
and exit ?

Re: [RFC PATCH v5] media: v4l2-common: Add a helper for obtaining the clock producer

[Laurent Pinchart]

On Wed, May 21, 2025 at 12:52:08PM +0200, Mehdi Djait wrote:
> Hi everyone,
> 
> On Wed, May 21, 2025 at 12:41:15PM +0200, Mehdi Djait wrote:
> >  drivers/media/v4l2-core/v4l2-common.c | 46 +++++++++++++++++++++++++++
> >  include/media/v4l2-common.h           | 25 +++++++++++++++
> >  2 files changed, 71 insertions(+)
> > 
> > diff --git a/drivers/media/v4l2-core/v4l2-common.c b/drivers/media/v4l2-core/v4l2-common.c
> > index 4ee4aa19efe6..6099acd339ad 100644
> > --- a/drivers/media/v4l2-core/v4l2-common.c
> > +++ b/drivers/media/v4l2-core/v4l2-common.c
> > @@ -34,6 +34,9 @@
> >   * Added Gerd Knorrs v4l1 enhancements (Justin Schoeman)
> >   */
> >  
> > +#include <linux/clk.h>
> > +#include <linux/clkdev.h>
> > +#include <linux/clk-provider.h>
> >  #include <linux/module.h>
> >  #include <linux/types.h>
> >  #include <linux/kernel.h>
> > @@ -665,3 +668,46 @@ int v4l2_link_freq_to_bitmap(struct device *dev, const u64 *fw_link_freqs,
> >  	return 0;
> >  }
> >  EXPORT_SYMBOL_GPL(v4l2_link_freq_to_bitmap);
> > +
> > +struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
> > +{
> > +	const char *clk_id __free(kfree) = NULL;
> > +	struct clk_hw *clk_hw;
> > +	struct clk *clk;
> > +	u32 rate;
> > +	int ret;
> > +
> > +	clk = devm_clk_get_optional(dev, id);
> > +	ret = device_property_read_u32(dev, "clock-frequency", &rate);
> > +
> > +	if (clk) {
> > +		if (!ret) {
> > +			ret = clk_set_rate(clk, rate);
> > +			if (ret)
> > +				dev_warn(dev, "Failed to set clock rate: %u\n",
> > +					 rate);

I would return ERR_PTR(ret) here.

> > +		}
> > +
> > +		return clk;
> > +	}
> > +
> > +	if (ret)
> > +		return ERR_PTR(ret);

And here, return a fixed error code, maybe -ENOENT, as propagating the
device_property_read_u32() error could result in strange error code for
the user.

> > +
> > +	if (!IS_ENABLED(CONFIG_COMMON_CLK) || !is_acpi_node(dev_fwnode(dev)))
> > +		return ERR_PTR(-ENOENT);
> > +
> > +	if (!id) {
> > +		clk_id = kasprintf(GFP_KERNEL, "clk-%s", dev_name(dev));
> > +		if (!clk_id)
> > +			return ERR_PTR(-ENOMEM);
> > +		id = clk_id;
> > +	}
> > +
> > +	clk_hw = devm_clk_hw_register_fixed_rate(dev, id, NULL, 0, rate);
> > +	if (IS_ERR(clk_hw))
> > +		return ERR_CAST(clk_hw);
> > +
> > +	return clk_hw->clk;
> > +}
> > +EXPORT_SYMBOL_GPL(devm_v4l2_sensor_clk_get);
> 
> I sent this as an RFC because I am still unsure and need comments on two
> things. After they are addressed, I plan to send a patch, documentation
> patch (what Sakari proposed in the RFC V4 discussion) and convert the
> camera sensors using devm_clk_get()
> 
> 1. Should the case where both the clock and the clock-frequency are
> present be reserved just for ACPI systems ? In other words if a DT
> system provides both, should we also attempt to set the provided clock
> rate ?

I would very much like to reserve this case for ACPI, yes.

> If the former makes more sense, maybe add this:
> 
> diff --git a/drivers/media/v4l2-core/v4l2-common.c b/drivers/media/v4l2-core/v4l2-common.c
> index 6099acd339ad..3dfbbd699c67 100644
> --- a/drivers/media/v4l2-core/v4l2-common.c
> +++ b/drivers/media/v4l2-core/v4l2-common.c
> @@ -674,14 +674,16 @@ struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
>         const char *clk_id __free(kfree) = NULL;
>         struct clk_hw *clk_hw;
>         struct clk *clk;
> +       bool acpi_node;
>         u32 rate;
>         int ret;
>  
>         clk = devm_clk_get_optional(dev, id);
>         ret = device_property_read_u32(dev, "clock-frequency", &rate);
> +       acpi_node = is_acpi_node(dev_fwnode(dev));
>  
>         if (clk) {
> -               if (!ret) {
> +               if (!ret && acpi_node) {
>                         ret = clk_set_rate(clk, rate);
>                         if (ret)
>                                 dev_warn(dev, "Failed to set clock rate: %u\n",
> @@ -694,7 +696,7 @@ struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
>         if (ret)
>                 return ERR_PTR(ret);
>  
> -       if (!IS_ENABLED(CONFIG_COMMON_CLK) || !is_acpi_node(dev_fwnode(dev)))
> +       if (!IS_ENABLED(CONFIG_COMMON_CLK) || !acpi_node)
>                 return ERR_PTR(-ENOENT);

Looks good to me.

> 2. Should we just warn when the clk_set_rate() fails or return err code
> and exit ?

I'd make it a dev_err() and return an error. We can then relax this
check later if there's a need to.

-- 
Regards,

Laurent Pinchart

Re: [RFC PATCH v5] media: v4l2-common: Add a helper for obtaining the clock producer

[Mehdi Djait]

Hi Laurent,

Thank you for the review!

A very small question below.

On Wed, May 21, 2025 at 01:09:44PM +0200, Laurent Pinchart wrote:
> On Wed, May 21, 2025 at 12:52:08PM +0200, Mehdi Djait wrote:

> > > +struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
> > > +{
> > > +	const char *clk_id __free(kfree) = NULL;
> > > +	struct clk_hw *clk_hw;
> > > +	struct clk *clk;
> > > +	u32 rate;
> > > +	int ret;
> > > +
> > > +	clk = devm_clk_get_optional(dev, id);
> > > +	ret = device_property_read_u32(dev, "clock-frequency", &rate);
> > > +
> > > +	if (clk) {
> > > +		if (!ret) {
> > > +			ret = clk_set_rate(clk, rate);
> > > +			if (ret)
> > > +				dev_warn(dev, "Failed to set clock rate: %u\n",
> > > +					 rate);
> 
> I would return ERR_PTR(ret) here.
> 
> > > +		}
> > > +
> > > +		return clk;
> > > +	}
> > > +
> > > +	if (ret)
> > > +		return ERR_PTR(ret);
> 
> And here, return a fixed error code, maybe -ENOENT, as propagating the
> device_property_read_u32() error could result in strange error code for
> the user.

device_property_read_u32() returns the following:

Return: number of values if @val was %NULL,
        %0 if the property was found (success),
          %-EINVAL if given arguments are not valid,
          %-ENODATA if the property does not have a value,
          %-EPROTO if the property is not an array of numbers,
          %-EOVERFLOW if the size of the property is not as expected.
          %-ENXIO if no suitable firmware interface is present.

Don't you think it is better to keep the return value and not overshadow
it ? The function is well documented and this may help understand where
the problem comes from if getting the clk fails.

--
Kind Regards
Mehdi Djait

Re: [RFC PATCH v5] media: v4l2-common: Add a helper for obtaining the clock producer

[Laurent Pinchart]

On Thu, Jun 12, 2025 at 02:15:10PM +0200, Mehdi Djait wrote:
> Hi Laurent,
> 
> Thank you for the review!
> 
> A very small question below.
> 
> On Wed, May 21, 2025 at 01:09:44PM +0200, Laurent Pinchart wrote:
> > On Wed, May 21, 2025 at 12:52:08PM +0200, Mehdi Djait wrote:
> 
> > > > +struct clk *devm_v4l2_sensor_clk_get(struct device *dev, const char *id)
> > > > +{
> > > > +	const char *clk_id __free(kfree) = NULL;
> > > > +	struct clk_hw *clk_hw;
> > > > +	struct clk *clk;
> > > > +	u32 rate;
> > > > +	int ret;
> > > > +
> > > > +	clk = devm_clk_get_optional(dev, id);
> > > > +	ret = device_property_read_u32(dev, "clock-frequency", &rate);
> > > > +
> > > > +	if (clk) {
> > > > +		if (!ret) {
> > > > +			ret = clk_set_rate(clk, rate);
> > > > +			if (ret)
> > > > +				dev_warn(dev, "Failed to set clock rate: %u\n",
> > > > +					 rate);
> > 
> > I would return ERR_PTR(ret) here.
> > 
> > > > +		}
> > > > +
> > > > +		return clk;
> > > > +	}
> > > > +
> > > > +	if (ret)
> > > > +		return ERR_PTR(ret);
> > 
> > And here, return a fixed error code, maybe -ENOENT, as propagating the
> > device_property_read_u32() error could result in strange error code for
> > the user.
> 
> device_property_read_u32() returns the following:
> 
> Return: number of values if @val was %NULL,
>         %0 if the property was found (success),
>           %-EINVAL if given arguments are not valid,
>           %-ENODATA if the property does not have a value,
>           %-EPROTO if the property is not an array of numbers,
>           %-EOVERFLOW if the size of the property is not as expected.
>           %-ENXIO if no suitable firmware interface is present.
> 
> Don't you think it is better to keep the return value and not overshadow
> it ? The function is well documented and this may help understand where
> the problem comes from if getting the clk fails.

I don't mind too much either way. If we want to make debugging easier,
may an error message would be appropriate.

-- 
Regards,

Laurent Pinchart