Skip to contentSkip to conversation

clk: add kernel docs for struct clk_core and update tests to use HZ_PER_MHZ

PATCH Superseded Brian Masney 3 participants 6 messages Mar 4 – Mar 25 Common clk

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

cover clk: add kernel docs for struct clk_core and update tests to use HZ_PER_MHZ

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/[email protected]/

---
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,

Signature · 1 line
Brian Masney <[email protected]>
#1 lore raw

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

Document all of the members of struct clk_core.

---
 drivers/clk/clk.c | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
drivers/clk/clk.c +59 -0
index 47093cda9df32223c1120c3710261296027c4cd3..18b7a14e3f2c595d82401be9382a062fbca8a5c6 100644
@@ -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;
Signature · 1 line
2.53.0
maintainer
#2 lore raw

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

Quoting Brian Masney (2026-03-04 14:51:03)

drivers/clk/clk.c struct clk_parent_map { · line 70

Quoted 13 lines
drivers/clk/clk.c +5 -0
index 47093cda9df32223c1120c3710261296027c4cd3..18b7a14e3f2c595d82401be9382a062fbca8a5c6 100644
@@ -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?

drivers/clk/clk.c struct clk_parent_map { · line 82

Quoted 12 lines
drivers/clk/clk.c +12 -0
+ *
+ * @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.

drivers/clk/clk.c struct clk_parent_map { · line 84

Quoted 2 lines
drivers/clk/clk.c +2 -0
+ * @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'

drivers/clk/clk.c struct clk_parent_map { · line 85

Quoted 1 line
drivers/clk/clk.c +1 -0
+ * @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.

drivers/clk/clk.c struct clk_parent_map { · line 92

Quoted 7 lines
drivers/clk/clk.c +7 -0
+ *                     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

drivers/clk/clk.c struct clk_parent_map { · line 93

Quoted 1 line
drivers/clk/clk.c +1 -0
+ *                     and updated when (and if) its parent is later loaded, so

later registered

drivers/clk/clk.c struct clk_parent_map { · line 96

Quoted 3 lines
drivers/clk/clk.c +3 -0
+ *                     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.

drivers/clk/clk.c struct clk_parent_map { · line 105

Quoted 9 lines
drivers/clk/clk.c +9 -0
+ *                     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?

drivers/clk/clk.c struct clk_parent_map { · line 118

Quoted 13 lines
drivers/clk/clk.c +13 -0
+ * @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

Quoted 5 lines
drivers/clk/clk.c +5 -0
+ * @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.
#3 lore raw

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

Quoted 27 lines · Stephen Boyd

Quoting Brian Masney (2026-03-04 14:51:03)

drivers/clk/clk.c struct clk_parent_map { · line 70

Quoted 13 lines
drivers/clk/clk.c +5 -0
index 47093cda9df32223c1120c3710261296027c4cd3..18b7a14e3f2c595d82401be9382a062fbca8a5c6 100644
@@ -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.
*

Quoted 2 lines

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

Quoted 11 lines

drivers/clk/clk.c struct clk_parent_map { · line 105

Quoted 9 lines
drivers/clk/clk.c +9 -0
+ *                     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

#4 lore raw

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

In reply to Brian Masney

Convert the DUMMY_CLOCK_* constants over to use HZ_PER_MHZ.

---
 drivers/clk/clk_test.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
drivers/clk/clk_test.c +4 -3
index a268d7b5d4cb28ec1f029f828c31107f8e130556..372dd289a7ba148a0725ea0643342ccda7196216 100644
@@ -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;
Signature · 1 line
2.53.0
Reviewed-by on the v1 series
#5 lore raw
In reply to Brian Masney
Quoted 7 lines · 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:

[ ... ]

Thanks!
Maxime