[PATCH v2 0/4] clk: update kernel docs

[PATCH v2 0/4] clk: update kernel docs

[Brian Masney]

Here's a small series that updates the kernel documentation for struct
clk_core, moves the clk flags into a new enum so that they can be shown
in the documentation, and updates the clk kunit test to use HZ_PER_MHZ.

Since I've been doing a lot of work in the clk subsystem lately, I would
like to add some more documentation about this subsystem in the future
as I have time. There's a lot of other things that I know can be done
now, and I'd like to just start with these small changes merged.

Changes in v2:
- Add clk_core_flags enum, and kernel doc for this.
- Update descriptions in clk_core based on feedback from Stephen.
- Update clk kernel docs to show some of the new API documentation.
- Link to v1: https://lore.kernel.org/r/20260304-clk-docs-v1-0-fee468db99f1@redhat.com

Merge Strategy
--------------
Since there is a new enum that's added, and it's referenced in the
docoumentation, all of these patches will need to go through Stephen's
tree.

Signed-off-by: Brian Masney <bmasney@redhat.com>
---
Brian Masney (4):
      clk: move core flags into a new enum for kernel docs
      clk: add kernel docs for struct clk_core
      docs: clk: include some identifiers to keep documentation up to date
      clk: test: convert constants to use HZ_PER_MHZ

 Documentation/driver-api/clk.rst | 58 +++++++---------------------------------
 drivers/clk/clk.c                | 51 +++++++++++++++++++++++++++++++++++
 drivers/clk/clk_test.c           |  7 ++---
 include/linux/clk-provider.h     | 55 ++++++++++++++++++++++---------------
 4 files changed, 98 insertions(+), 73 deletions(-)
---
base-commit: 85964cdcad0fac9a0eb7b87a0f9d88cc074b854c
change-id: 20260304-clk-docs-0b578f421600

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

[PATCH v2 1/4] clk: move core flags into a new enum for kernel docs

[Brian Masney]

Let's move all of the existing clk flags into a new enum so that all of
the flags can be easily referenced in the kernel documentation. Note
that I went with name clk_core_flags for the enum since the name
clk_flags is already in use in clk.c for the debugfs interface.

Note: The comment about "Please update clk_flags..." is included as a
separate comment so it doesn't show up in the generated documents.

Signed-off-by: Brian Masney <bmasney@redhat.com>
---
 include/linux/clk-provider.h | 55 +++++++++++++++++++++++++++-----------------
 1 file changed, 34 insertions(+), 21 deletions(-)

diff --git a/include/linux/clk-provider.h b/include/linux/clk-provider.h
index 630705a47129453c241f1b1755f2c2f2a7ed8f77..cb167c17c4f79cf438a26bb113b4968d0f223468 100644
--- a/include/linux/clk-provider.h
+++ b/include/linux/clk-provider.h
@@ -9,29 +9,42 @@
 #include <linux/of.h>
 #include <linux/of_clk.h>
 
-/*
- * flags used across common struct clk.  these flags should only affect the
- * top-level framework.  custom flags for dealing with hardware specifics
- * belong in struct clk_foo
+/* Please update clk_flags[] in drivers/clk/clk.c when making changes here! */
+/**
+ * enum clk_core_flags - framework-level clock flags
  *
- * Please update clk_flags[] in drivers/clk/clk.c when making changes here!
+ * These flags should only affect the top-level framework. Custom flags for
+ * dealing with hardware specifics belong in struct clk_foo.
+ *
+ * @CLK_SET_RATE_GATE: must be gated across rate change
+ * @CLK_SET_PARENT_GATE: must be gated across re-parent
+ * @CLK_SET_RATE_PARENT: propagate rate change up one level
+ * @CLK_IGNORE_UNUSED: do not gate even if unused
+ * @CLK_GET_RATE_NOCACHE: do not use the cached clk rate
+ * @CLK_SET_RATE_NO_REPARENT: don't re-parent on rate change
+ * @CLK_GET_ACCURACY_NOCACHE: do not use the cached clk accuracy
+ * @CLK_RECALC_NEW_RATES: recalc rates after notifications
+ * @CLK_SET_RATE_UNGATE: clock needs to run to set rate
+ * @CLK_IS_CRITICAL: do not gate, ever
+ * @CLK_OPS_PARENT_ENABLE: parents need enable during gate/ungate, set rate and re-parent
+ * @CLK_DUTY_CYCLE_PARENT: duty cycle call may be forwarded to the parent clock
  */
-#define CLK_SET_RATE_GATE	BIT(0) /* must be gated across rate change */
-#define CLK_SET_PARENT_GATE	BIT(1) /* must be gated across re-parent */
-#define CLK_SET_RATE_PARENT	BIT(2) /* propagate rate change up one level */
-#define CLK_IGNORE_UNUSED	BIT(3) /* do not gate even if unused */
-				/* unused */
-				/* unused */
-#define CLK_GET_RATE_NOCACHE	BIT(6) /* do not use the cached clk rate */
-#define CLK_SET_RATE_NO_REPARENT BIT(7) /* don't re-parent on rate change */
-#define CLK_GET_ACCURACY_NOCACHE BIT(8) /* do not use the cached clk accuracy */
-#define CLK_RECALC_NEW_RATES	BIT(9) /* recalc rates after notifications */
-#define CLK_SET_RATE_UNGATE	BIT(10) /* clock needs to run to set rate */
-#define CLK_IS_CRITICAL		BIT(11) /* do not gate, ever */
-/* parents need enable during gate/ungate, set rate and re-parent */
-#define CLK_OPS_PARENT_ENABLE	BIT(12)
-/* duty cycle call may be forwarded to the parent clock */
-#define CLK_DUTY_CYCLE_PARENT	BIT(13)
+enum clk_core_flags {
+	CLK_SET_RATE_GATE		= BIT(0),
+	CLK_SET_PARENT_GATE		= BIT(1),
+	CLK_SET_RATE_PARENT		= BIT(2),
+	CLK_IGNORE_UNUSED		= BIT(3),
+	/* unused */
+	/* unused */
+	CLK_GET_RATE_NOCACHE		= BIT(6),
+	CLK_SET_RATE_NO_REPARENT	= BIT(7),
+	CLK_GET_ACCURACY_NOCACHE	= BIT(8),
+	CLK_RECALC_NEW_RATES		= BIT(9),
+	CLK_SET_RATE_UNGATE		= BIT(10),
+	CLK_IS_CRITICAL			= BIT(11),
+	CLK_OPS_PARENT_ENABLE		= BIT(12),
+	CLK_DUTY_CYCLE_PARENT		= BIT(13),
+};
 
 struct clk;
 struct clk_hw;

-- 
2.53.0

Re: [PATCH v2 1/4] clk: move core flags into a new enum for kernel docs

[Randy Dunlap]

On 3/25/26 4:52 PM, Brian Masney wrote:
> Let's move all of the existing clk flags into a new enum so that all of
> the flags can be easily referenced in the kernel documentation. Note
> that I went with name clk_core_flags for the enum since the name
> clk_flags is already in use in clk.c for the debugfs interface.
> 
> Note: The comment about "Please update clk_flags..." is included as a
> separate comment so it doesn't show up in the generated documents.
> 
> Signed-off-by: Brian Masney <bmasney@redhat.com>
> ---
>  include/linux/clk-provider.h | 55 +++++++++++++++++++++++++++-----------------
>  1 file changed, 34 insertions(+), 21 deletions(-)

LGTM. Thanks.

Acked-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy

Re: [PATCH v2 1/4] clk: move core flags into a new enum for kernel docs

[Brian Masney]

Hi Stephen,

On Wed, Mar 25, 2026 at 07:52:10PM -0400, Brian Masney wrote:
> Let's move all of the existing clk flags into a new enum so that all of
> the flags can be easily referenced in the kernel documentation. Note
> that I went with name clk_core_flags for the enum since the name
> clk_flags is already in use in clk.c for the debugfs interface.
> 
> Note: The comment about "Please update clk_flags..." is included as a
> separate comment so it doesn't show up in the generated documents.
> 
> Signed-off-by: Brian Masney <bmasney@redhat.com>
> ---
>  include/linux/clk-provider.h | 55 +++++++++++++++++++++++++++-----------------
>  1 file changed, 34 insertions(+), 21 deletions(-)
> 
> diff --git a/include/linux/clk-provider.h b/include/linux/clk-provider.h
> index 630705a47129453c241f1b1755f2c2f2a7ed8f77..cb167c17c4f79cf438a26bb113b4968d0f223468 100644
> --- a/include/linux/clk-provider.h
> +++ b/include/linux/clk-provider.h
> @@ -9,29 +9,42 @@
>  #include <linux/of.h>
>  #include <linux/of_clk.h>
>  
> -/*
> - * flags used across common struct clk.  these flags should only affect the
> - * top-level framework.  custom flags for dealing with hardware specifics
> - * belong in struct clk_foo
> +/* Please update clk_flags[] in drivers/clk/clk.c when making changes here! */
> +/**
> + * enum clk_core_flags - framework-level clock flags
>   *
> - * Please update clk_flags[] in drivers/clk/clk.c when making changes here!
> + * These flags should only affect the top-level framework. Custom flags for
> + * dealing with hardware specifics belong in struct clk_foo.
> + *
> + * @CLK_SET_RATE_GATE: must be gated across rate change
> + * @CLK_SET_PARENT_GATE: must be gated across re-parent
> + * @CLK_SET_RATE_PARENT: propagate rate change up one level
> + * @CLK_IGNORE_UNUSED: do not gate even if unused
> + * @CLK_GET_RATE_NOCACHE: do not use the cached clk rate
> + * @CLK_SET_RATE_NO_REPARENT: don't re-parent on rate change
> + * @CLK_GET_ACCURACY_NOCACHE: do not use the cached clk accuracy
> + * @CLK_RECALC_NEW_RATES: recalc rates after notifications
> + * @CLK_SET_RATE_UNGATE: clock needs to run to set rate
> + * @CLK_IS_CRITICAL: do not gate, ever
> + * @CLK_OPS_PARENT_ENABLE: parents need enable during gate/ungate, set rate and re-parent
> + * @CLK_DUTY_CYCLE_PARENT: duty cycle call may be forwarded to the parent clock
>   */
> -#define CLK_SET_RATE_GATE	BIT(0) /* must be gated across rate change */
> -#define CLK_SET_PARENT_GATE	BIT(1) /* must be gated across re-parent */
> -#define CLK_SET_RATE_PARENT	BIT(2) /* propagate rate change up one level */
> -#define CLK_IGNORE_UNUSED	BIT(3) /* do not gate even if unused */
> -				/* unused */
> -				/* unused */
> -#define CLK_GET_RATE_NOCACHE	BIT(6) /* do not use the cached clk rate */
> -#define CLK_SET_RATE_NO_REPARENT BIT(7) /* don't re-parent on rate change */
> -#define CLK_GET_ACCURACY_NOCACHE BIT(8) /* do not use the cached clk accuracy */
> -#define CLK_RECALC_NEW_RATES	BIT(9) /* recalc rates after notifications */
> -#define CLK_SET_RATE_UNGATE	BIT(10) /* clock needs to run to set rate */
> -#define CLK_IS_CRITICAL		BIT(11) /* do not gate, ever */
> -/* parents need enable during gate/ungate, set rate and re-parent */
> -#define CLK_OPS_PARENT_ENABLE	BIT(12)
> -/* duty cycle call may be forwarded to the parent clock */
> -#define CLK_DUTY_CYCLE_PARENT	BIT(13)
> +enum clk_core_flags {
> +	CLK_SET_RATE_GATE		= BIT(0),
> +	CLK_SET_PARENT_GATE		= BIT(1),
> +	CLK_SET_RATE_PARENT		= BIT(2),
> +	CLK_IGNORE_UNUSED		= BIT(3),
> +	/* unused */
> +	/* unused */
> +	CLK_GET_RATE_NOCACHE		= BIT(6),
> +	CLK_SET_RATE_NO_REPARENT	= BIT(7),
> +	CLK_GET_ACCURACY_NOCACHE	= BIT(8),
> +	CLK_RECALC_NEW_RATES		= BIT(9),
> +	CLK_SET_RATE_UNGATE		= BIT(10),
> +	CLK_IS_CRITICAL			= BIT(11),
> +	CLK_OPS_PARENT_ENABLE		= BIT(12),
> +	CLK_DUTY_CYCLE_PARENT		= BIT(13),
> +};

I just checked Sashiko [1] for this series and it has this comment:

    Could converting these unsigned long bitmasks to an enum create a silent
    type-safety trap if flags ever reach BIT(31)?
    
    The flags fields in the clock framework are explicitly designed to be 64-bit
    on 64-bit architectures (unsigned long). The BIT() macro evaluates to an
    unsigned long. When defined as macros, operations like clearing flags
    produce a 64-bit inverted mask, perfectly preserving the upper 32 bits.
    
    By moving these flags into an enum, their types are implicitly downgraded to
    int, since the current maximum flag BIT(13) fits in a 32-bit signed integer.
    If the flags ever grow to include BIT(31), the enumerator value will overflow
    a signed 32-bit int, causing the compiler to type it as an unsigned int.
    
    Applying a bitwise NOT to this unsigned int will produce an unsigned int.
    When this is bitwise ANDed with the 64-bit unsigned long flags variable,
    the unsigned mask will zero-extend to 64 bits, silently clearing all upper
    32 bits (bits 32-63) of the flags field.
    
    Would it be safer to keep them as #define macros and use a DOC: block
    to properly document the flags using kernel-doc without breaking type safety?

It's up to you how we should proceed with this.

[1] https://sashiko.dev/#/patchset/20260325-clk-docs-v2-0-bcf660e1ceb5%40redhat.com

Brian

[PATCH v2 2/4] 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 | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
index 47093cda9df32223c1120c3710261296027c4cd3..08b38ec044db7e50c7313b8f44cc0f6fa2cd4755 100644
--- a/drivers/clk/clk.c
+++ b/drivers/clk/clk.c
@@ -63,6 +63,57 @@ struct clk_parent_map {
 	int			index;
 };
 
+/**
+ * struct clk_core - The internal state of a clk in the clk tree.
+ * @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 operations.
+ * @rate:              Current cached clock rate (Hz).
+ * @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 in the
+ *                     enum clk_core_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 clk 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.
+ *
+ * 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.
+ *
+ */
 struct clk_core {
 	const char		*name;
 	const struct clk_ops	*ops;

-- 
2.53.0

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

[Randy Dunlap]

On 3/25/26 4:52 PM, Brian Masney wrote:
> Document all of the members of struct clk_core.
> 
> Signed-off-by: Brian Masney <bmasney@redhat.com>
> ---
>  drivers/clk/clk.c | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 51 insertions(+)

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Thanks.

-- 
~Randy

[PATCH v2 3/4] docs: clk: include some identifiers to keep documentation up to date

[Brian Masney]

The clk documentation currently has a separate list of some members of
struct clk_core and struct clk_ops. Now that all of these structures
have proper kernel docs, let's go ahead and just include them here via
the identifiers statement in kerneldoc.

While changes are being made here, let's also include the newly-added
enum clk_core_flags.

Signed-off-by: Brian Masney <bmasney@redhat.com>
---
 Documentation/driver-api/clk.rst | 58 +++++++---------------------------------
 1 file changed, 9 insertions(+), 49 deletions(-)

diff --git a/Documentation/driver-api/clk.rst b/Documentation/driver-api/clk.rst
index 93bab5336dfda06069eea700d2830089bf3bce03..d3e93519114637b3a70067128192dd302bedad4b 100644
--- a/Documentation/driver-api/clk.rst
+++ b/Documentation/driver-api/clk.rst
@@ -42,21 +42,8 @@ clock interface.
 Common data structures and api
 ==============================
 
-Below is the common struct clk_core definition from
-drivers/clk/clk.c, modified for brevity::
-
-	struct clk_core {
-		const char		*name;
-		const struct clk_ops	*ops;
-		struct clk_hw		*hw;
-		struct module		*owner;
-		struct clk_core		*parent;
-		const char		**parent_names;
-		struct clk_core		**parents;
-		u8			num_parents;
-		u8			new_parent_index;
-		...
-	};
+.. kernel-doc:: drivers/clk/clk.c
+   :identifiers: struct clk_core
 
 The members above make up the core of the clk tree topology.  The clk
 api itself defines several driver-facing functions which operate on
@@ -64,41 +51,14 @@ struct clk.  That api is documented in include/linux/clk.h.
 
 Platforms and devices utilizing the common struct clk_core use the struct
 clk_ops pointer in struct clk_core to perform the hardware-specific parts of
-the operations defined in clk-provider.h::
+the operations defined in clk-provider.h, and can set one or more
+framework-level flags in the enum clk_core_flags.
 
-	struct clk_ops {
-		int		(*prepare)(struct clk_hw *hw);
-		void		(*unprepare)(struct clk_hw *hw);
-		int		(*is_prepared)(struct clk_hw *hw);
-		void		(*unprepare_unused)(struct clk_hw *hw);
-		int		(*enable)(struct clk_hw *hw);
-		void		(*disable)(struct clk_hw *hw);
-		int		(*is_enabled)(struct clk_hw *hw);
-		void		(*disable_unused)(struct clk_hw *hw);
-		unsigned long	(*recalc_rate)(struct clk_hw *hw,
-						unsigned long parent_rate);
-		long		(*round_rate)(struct clk_hw *hw,
-						unsigned long rate,
-						unsigned long *parent_rate);
-		int		(*determine_rate)(struct clk_hw *hw,
-						  struct clk_rate_request *req);
-		int		(*set_parent)(struct clk_hw *hw, u8 index);
-		u8		(*get_parent)(struct clk_hw *hw);
-		int		(*set_rate)(struct clk_hw *hw,
-					    unsigned long rate,
-					    unsigned long parent_rate);
-		int		(*set_rate_and_parent)(struct clk_hw *hw,
-					    unsigned long rate,
-					    unsigned long parent_rate,
-					    u8 index);
-		unsigned long	(*recalc_accuracy)(struct clk_hw *hw,
-						unsigned long parent_accuracy);
-		int		(*get_phase)(struct clk_hw *hw);
-		int		(*set_phase)(struct clk_hw *hw, int degrees);
-		void		(*init)(struct clk_hw *hw);
-		void		(*debug_init)(struct clk_hw *hw,
-					      struct dentry *dentry);
-	};
+.. kernel-doc:: include/linux/clk-provider.h
+   :identifiers: struct clk_ops
+
+.. kernel-doc:: include/linux/clk-provider.h
+   :identifiers: enum clk_core_flags
 
 Hardware clk implementations
 ============================

-- 
2.53.0

Re: [PATCH v2 3/4] docs: clk: include some identifiers to keep documentation up to date

[Randy Dunlap]

On 3/25/26 4:52 PM, Brian Masney wrote:
> The clk documentation currently has a separate list of some members of
> struct clk_core and struct clk_ops. Now that all of these structures
> have proper kernel docs, let's go ahead and just include them here via
> the identifiers statement in kerneldoc.
> 
> While changes are being made here, let's also include the newly-added
> enum clk_core_flags.
> 
> Signed-off-by: Brian Masney <bmasney@redhat.com>
> ---
>  Documentation/driver-api/clk.rst | 58 +++++++---------------------------------
>  1 file changed, 9 insertions(+), 49 deletions(-)

Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.
-- 
~Randy

[PATCH v2 4/4] 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 v2 4/4] clk: test: convert constants to use HZ_PER_MHZ

[Maxime Ripard]

On Wed, 25 Mar 2026 19:52:13 -0400, Brian Masney wrote:
> Convert the DUMMY_CLOCK_* constants over to use HZ_PER_MHZ.
> 
> Signed-off-by: Brian Masney <bmasney@redhat.com>

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

Thanks!
Maxime