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.0Quoting 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.
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
© 2016 - 2026 Red Hat, Inc.