[PATCH 0/2] clk: add kernel docs for struct clk_core and update tests to use HZ_PER_MHZ

[PATCH 0/2] clk: add kernel docs for struct clk_core and update tests to use HZ_PER_MHZ

[Brian Masney]

Here's two patches from my v4 clk rate change series at [1] that should
hopefully be good to go. This series documents all of the members of
struct clk_core, and updates the kunit tests to use HZ_PER_MHZ.

Changes from what was previously posted:
- Add entry for new field hashtable_node that was recently added.
- Update description of duty member.

[1] https://lore.kernel.org/linux-clk/20250923-clk-tests-docs-v4-0-9205cb3d3cba@redhat.com/

Signed-off-by: Brian Masney <bmasney@redhat.com>
---
Brian Masney (2):
      clk: add kernel docs for struct clk_core
      clk: test: convert constants to use HZ_PER_MHZ

 drivers/clk/clk.c      | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++
 drivers/clk/clk_test.c |  7 +++---
 2 files changed, 63 insertions(+), 3 deletions(-)
---
base-commit: fc7b1a72c6cd5cbbd989c6c32a6486e3e4e3594d
change-id: 20260304-clk-docs-0b578f421600

Best regards,
-- 
Brian Masney <bmasney@redhat.com>

[PATCH 1/2] clk: add kernel docs for struct clk_core

[Brian Masney]

Document all of the members of struct clk_core.

Signed-off-by: Brian Masney <bmasney@redhat.com>
---
 drivers/clk/clk.c | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
index 47093cda9df32223c1120c3710261296027c4cd3..18b7a14e3f2c595d82401be9382a062fbca8a5c6 100644
--- a/drivers/clk/clk.c
+++ b/drivers/clk/clk.c
@@ -63,6 +63,65 @@ struct clk_parent_map {
 	int			index;
 };
 
+/**
+ * struct clk_core - This structure represents the internal state of a clk
+ * within the kernel's clock tree. Drivers do not interact with this structure
+ * directly. The clk_core is manipulated by the framework to manage clock
+ * operations, parent/child relationships, rate, and other properties.
+ *
+ * @name:              Unique name of the clk for identification.
+ * @ops:               Pointer to hardware-specific operations for this clk.
+ * @hw:                Pointer for traversing from a struct clk to its
+ *                     corresponding hardware-specific structure.
+ * @owner:             Kernel module owning this clk (for reference counting).
+ * @dev:               Device associated with this clk (optional)
+ * @rpm_node:          Node for runtime power management list management.
+ * @of_node:           Device tree node associated with this clk (if applicable)
+ * @parent:            Pointer to the current parent in the clock tree.
+ * @parents:           Array of possible parents (for muxes/selectable parents).
+ * @num_parents:       Number of possible parents
+ * @new_parent_index:  Index of the new parent during parent change. This is
+ *                     also used when a clk's rate is changed.
+ * @rate:              Current clock rate (Hz). This is effectively a cached
+ *                     value of what the hardware has been programmed with. It's
+ *                     initialized by reading the value at boot time, and will
+ *                     be updated every time an operation affects the rate.
+ *                     Clocks with the CLK_GET_RATE_NOCACHE flag should not use
+ *                     this value, as its rate is expected to change behind the
+ *                     kernel's back (because the firmware might change it, for
+ *                     example). Also, if the clock is orphan, it's set to 0
+ *                     and updated when (and if) its parent is later loaded, so
+ *                     its content is only ever valid if clk_core->orphan is
+ *                     false.
+ * @req_rate:          The last rate requested by a call to clk_set_rate. It's
+ *                     initialized to clk_core->rate. It's also updated to
+ *                     clk_core->rate every time the clock is reparented, and
+ *                     when we're doing the orphan -> !orphan transition.
+ * @new_rate:          New rate to be set during a rate change operation.
+ * @new_parent:        Pointer to new parent during parent change. This is also
+ *                     used when a clk's rate is changed.
+ * @new_child:         Pointer to new child during reparenting. This is also
+ *                     used when a clk's rate is changed.
+ * @flags:             Clock property and capability flags.
+ * @orphan:            True if this clk is currently orphaned.
+ * @rpm_enabled:       True if runtime power management is enabled for this clk.
+ * @enable_count:      Reference count of enables.
+ * @prepare_count:     Reference count of prepares.
+ * @protect_count:     Protection reference count against disable.
+ * @min_rate:          Minimum supported clock rate (Hz).
+ * @max_rate:          Maximum supported clock rate (Hz).
+ * @accuracy:          Accuracy of the clock rate (parts per billion).
+ * @phase:             Current phase (degrees).
+ * @duty:              Current duty cycle configuration (as ratio: num/den).
+ * @children:          All of the children of this clk.
+ * @child_node:        Node for linking as a child in the parent's list.
+ * @hashtable_node:    Node for hash table that allows fast clock lookup by name.
+ * @clks:              All of the clk consumers registered.
+ * @notifier_count:    Number of notifiers registered for this clk.
+ * @dentry:            DebugFS entry for this clk.
+ * @debug_node:        DebugFS node for this clk.
+ * @ref:               Reference count for structure lifetime management.
+ */
 struct clk_core {
 	const char		*name;
 	const struct clk_ops	*ops;

-- 
2.53.0

Re: [PATCH 1/2] clk: add kernel docs for struct clk_core

[Stephen Boyd]

Quoting Brian Masney (2026-03-04 14:51:03)
> diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
> index 47093cda9df32223c1120c3710261296027c4cd3..18b7a14e3f2c595d82401be9382a062fbca8a5c6 100644
> --- a/drivers/clk/clk.c
> +++ b/drivers/clk/clk.c
> @@ -63,6 +63,65 @@ struct clk_parent_map {
>         int                     index;
>  };
>  
> +/**
> + * struct clk_core - This structure represents the internal state of a clk
> + * within the kernel's clock tree. Drivers do not interact with this structure
> + * directly. The clk_core is manipulated by the framework to manage clock
> + * operations, parent/child relationships, rate, and other properties.

Trim this down and use active voice please.

 /**
  * struct clk_core - The internal state of a clk in the clk tree.
  *
  * Managed by the clk framework. Clk providers and consumers do not
  * interact with this structure directly. Instead, clk operations flow
  * through the framework and the framework manipulates this structure
  * to keep track of parent/child relationships, rate, enable state,
  * etc.
  *

Does the longer paragraph description follow directly after the one line
short description? Or does it come after all the members?

> + *
> + * @name:              Unique name of the clk for identification.
> + * @ops:               Pointer to hardware-specific operations for this clk.
> + * @hw:                Pointer for traversing from a struct clk to its
> + *                     corresponding hardware-specific structure.
> + * @owner:             Kernel module owning this clk (for reference counting).
> + * @dev:               Device associated with this clk (optional)
> + * @rpm_node:          Node for runtime power management list management.
> + * @of_node:           Device tree node associated with this clk (if applicable)
> + * @parent:            Pointer to the current parent in the clock tree.
> + * @parents:           Array of possible parents (for muxes/selectable parents).
> + * @num_parents:       Number of possible parents

Add a period.

> + * @new_parent_index:  Index of the new parent during parent change. This is
> + *                     also used when a clk's rate is changed.

Not sure we need to get into the details here. Maybe 'Index of the new
parent during parent change operations'

> + * @rate:              Current clock rate (Hz). This is effectively a cached

Sorta same comment. Not sure we should do anything besides say this is
the cached clk rate in Hz. Maybe we need a better top-level comment
indicating how rates are cached instead and how the framework uses flags
to change the behavior.

> + *                     value of what the hardware has been programmed with. It's
> + *                     initialized by reading the value at boot time, and will
> + *                     be updated every time an operation affects the rate.
> + *                     Clocks with the CLK_GET_RATE_NOCACHE flag should not use
> + *                     this value, as its rate is expected to change behind the
> + *                     kernel's back (because the firmware might change it, for
> + *                     example). Also, if the clock is orphan, it's set to 0

is an orphan

> + *                     and updated when (and if) its parent is later loaded, so

later registered

> + *                     its content is only ever valid if clk_core->orphan is
> + *                     false.
> + * @req_rate:          The last rate requested by a call to clk_set_rate. It's

Use clk_set_rate() to indicate a function.

> + *                     initialized to clk_core->rate. It's also updated to
> + *                     clk_core->rate every time the clock is reparented, and
> + *                     when we're doing the orphan -> !orphan transition.
> + * @new_rate:          New rate to be set during a rate change operation.
> + * @new_parent:        Pointer to new parent during parent change. This is also
> + *                     used when a clk's rate is changed.
> + * @new_child:         Pointer to new child during reparenting. This is also
> + *                     used when a clk's rate is changed.
> + * @flags:             Clock property and capability flags.

Can we somehow link this to the CLK_* defines in clk-provider.h?

> + * @orphan:            True if this clk is currently orphaned.
> + * @rpm_enabled:       True if runtime power management is enabled for this clk.
> + * @enable_count:      Reference count of enables.
> + * @prepare_count:     Reference count of prepares.
> + * @protect_count:     Protection reference count against disable.
> + * @min_rate:          Minimum supported clock rate (Hz).
> + * @max_rate:          Maximum supported clock rate (Hz).
> + * @accuracy:          Accuracy of the clock rate (parts per billion).
> + * @phase:             Current phase (degrees).
> + * @duty:              Current duty cycle configuration (as ratio: num/den).
> + * @children:          All of the children of this clk.
> + * @child_node:        Node for linking as a child in the parent's list.
> + * @hashtable_node:    Node for hash table that allows fast clock lookup by name.

fast clk lookup

> + * @clks:              All of the clk consumers registered.
> + * @notifier_count:    Number of notifiers registered for this clk.
> + * @dentry:            DebugFS entry for this clk.
> + * @debug_node:        DebugFS node for this clk.
> + * @ref:               Reference count for structure lifetime management.

Re: [PATCH 1/2] clk: add kernel docs for struct clk_core

[Brian Masney]

On Tue, Mar 24, 2026 at 07:31:03PM -0700, Stephen Boyd wrote:
> Quoting Brian Masney (2026-03-04 14:51:03)
> > diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
> > index 47093cda9df32223c1120c3710261296027c4cd3..18b7a14e3f2c595d82401be9382a062fbca8a5c6 100644
> > --- a/drivers/clk/clk.c
> > +++ b/drivers/clk/clk.c
> > @@ -63,6 +63,65 @@ struct clk_parent_map {
> >         int                     index;
> >  };
> >  
> > +/**
> > + * struct clk_core - This structure represents the internal state of a clk
> > + * within the kernel's clock tree. Drivers do not interact with this structure
> > + * directly. The clk_core is manipulated by the framework to manage clock
> > + * operations, parent/child relationships, rate, and other properties.
> 
> Trim this down and use active voice please.
> 
>  /**
>   * struct clk_core - The internal state of a clk in the clk tree.
>   *
>   * Managed by the clk framework. Clk providers and consumers do not
>   * interact with this structure directly. Instead, clk operations flow
>   * through the framework and the framework manipulates this structure
>   * to keep track of parent/child relationships, rate, enable state,
>   * etc.
>   *
> 
> Does the longer paragraph description follow directly after the one line
> short description? Or does it come after all the members?

The longer paragraph goes after the description of the members.

https://docs.kernel.org/doc-guide/kernel-doc.html#function-documentation

> > + *                     initialized to clk_core->rate. It's also updated to
> > + *                     clk_core->rate every time the clock is reparented, and
> > + *                     when we're doing the orphan -> !orphan transition.
> > + * @new_rate:          New rate to be set during a rate change operation.
> > + * @new_parent:        Pointer to new parent during parent change. This is also
> > + *                     used when a clk's rate is changed.
> > + * @new_child:         Pointer to new child during reparenting. This is also
> > + *                     used when a clk's rate is changed.
> > + * @flags:             Clock property and capability flags.
> 
> Can we somehow link this to the CLK_* defines in clk-provider.h?

The kerneldoc lists how to link to things at:

https://docs.kernel.org/doc-guide/kernel-doc.html#cross-referencing-from-restructuredtext

I don't see how to link to the #defines the way it is right now, unless
we link to each one individually, which we don't want to do. We should
be able to do something like this:

enum clk_flags {
	CLK_SET_RATE_GATE   = 0,
	CLK_SET_PARENT_GATE = 1 << 0,
	CLK_SET_RATE_PARENT = 1 << 1,
	CLK_IGNORE_UNUSED   = 1 << 2,
	...
};

We could then refernece enum clk_flags in the description, and it'll
automatically link it for us. I'll try this and see how it turns out.

Brian

[PATCH 2/2] clk: test: convert constants to use HZ_PER_MHZ

[Brian Masney]

Convert the DUMMY_CLOCK_* constants over to use HZ_PER_MHZ.

Signed-off-by: Brian Masney <bmasney@redhat.com>
---
 drivers/clk/clk_test.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/drivers/clk/clk_test.c b/drivers/clk/clk_test.c
index a268d7b5d4cb28ec1f029f828c31107f8e130556..372dd289a7ba148a0725ea0643342ccda7196216 100644
--- a/drivers/clk/clk_test.c
+++ b/drivers/clk/clk_test.c
@@ -7,6 +7,7 @@
 #include <linux/clk/clk-conf.h>
 #include <linux/of.h>
 #include <linux/platform_device.h>
+#include <linux/units.h>
 
 /* Needed for clk_hw_get_clk() */
 #include "clk.h"
@@ -21,9 +22,9 @@
 
 static const struct clk_ops empty_clk_ops = { };
 
-#define DUMMY_CLOCK_INIT_RATE	(42 * 1000 * 1000)
-#define DUMMY_CLOCK_RATE_1	(142 * 1000 * 1000)
-#define DUMMY_CLOCK_RATE_2	(242 * 1000 * 1000)
+#define DUMMY_CLOCK_INIT_RATE		(42 * HZ_PER_MHZ)
+#define DUMMY_CLOCK_RATE_1		(142 * HZ_PER_MHZ)
+#define DUMMY_CLOCK_RATE_2		(242 * HZ_PER_MHZ)
 
 struct clk_dummy_context {
 	struct clk_hw hw;

-- 
2.53.0

Re: [PATCH 0/2] clk: add kernel docs for struct clk_core and update tests to use HZ_PER_MHZ

[Maxime Ripard]

On Wed, 4 Mar 2026 17:51:02 -0500, Brian Masney wrote:
> Here's two patches from my v4 clk rate change series at [1] that should
> hopefully be good to go. This series documents all of the members of
> struct clk_core, and updates the kunit tests to use HZ_PER_MHZ.
> 
> Changes from what was previously posted:
> 
> [ ... ]

Reviewed-by: Maxime Ripard <mripard@kernel.org>

Thanks!
Maxime