clk: update kernel docs
Subsystems (2)
v2 cover clk: update kernel docs
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/[email protected]
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.
---
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,
Signature · 1 line
Brian Masney <[email protected]>
PATCH v2 1/4 clk: move core flags into a new enum for kernel docs
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.
--- include/linux/clk-provider.h | 55 +++++++++++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 21 deletions(-)
include/linux/clk-provider.h +34 -21
@@ -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 ;
Signature · 1 line
2.53.0
Re: [PATCH v2 1/4] clk: move core flags into a new enum for kernel docs
Quoted 5 lines · 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_flagsfor the enum since the nameclk_flagsis already in use inclk.cfor the debugfs interface.
Quoted 7 lines
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 <[email protected]>--- include/linux/clk-provider.h | 55 +++++++++++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 21 deletions(-)
LGTM. Thanks.
Signature · 1 line
~Randy
Re: [PATCH v2 1/4] clk: move core flags into a new enum for kernel docs
In reply to Brian MasneyHi Stephen,
Quoted 68 lines · 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_flagsfor the enum since the nameclk_flagsis already in use inclk.cfor 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 <[email protected]>--- include/linux/clk-provider.h | 55 +++++++++++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 21 deletions(-)include/linux/clk-provider.h +24
-21@@ -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 */
include/linux/clk-provider.h line 47
Quoted 10 lines
include/linux/clk-provider.h +10
-0+/* 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
Stephen Boyd
maintainerRe: [PATCH v2 1/4] clk: move core flags into a new enum for kernel docs
Quoting Brian Masney (2026-03-27 06:30:37)
Quoted 32 lines
Quoted 6 lines
include/linux/clk-provider.h +6
-0+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 */ include/linux/clk-provider.h line 47
Quoted 10 lines
include/linux/clk-provider.h +10
-0+/* 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.
Quoted 8 lines
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?
Don't break type safety. I hope we don't get to the point that we have more than 32 flags, but you never know. Why do we need an enum? Just to make it easier to grab in docs? Presumably a doc block would work just as well and not put down a land mine to be discovered later.
PATCH v2 2/4 clk: add kernel docs for struct clk_core
In reply to Brian MasneyDocument all of the members of struct clk_core.
--- drivers/clk/clk.c | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+)
drivers/clk/clk.c +51 -0
@@ -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;
Signature · 1 line
2.53.0
Re: [PATCH v2 2/4] clk: add kernel docs for struct clk_core
Quoted 6 lines · Brian Masney
Document all of the members of struct
clk_core.Signed-off-by Brian Masney <[email protected]>--- drivers/clk/clk.c | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+)
Thanks.
Signature · 1 line
~Randy
PATCH v2 3/4 docs: clk: include some identifiers to keep documentation up to date
In reply to Brian MasneyThe 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.
--- Documentation/driver-api/clk.rst | 58 +++++++--------------------------------- 1 file changed, 9 insertions(+), 49 deletions(-)
Documentation/driver-api/clk.rst +9 -49
@@ -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 ============================
Signature · 1 line
2.53.0
Re: [PATCH v2 3/4] docs: clk: include some identifiers to keep documentation up to date
Quoted 5 lines · Brian Masney
The clk documentation currently has a separate list of some members of struct
clk_coreand structclk_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.
Quoted 7 lines
While changes are being made here, let's also include the newly-added enum
clk_core_flags.Signed-off-by Brian Masney <[email protected]>--- Documentation/driver-api/clk.rst | 58 +++++++--------------------------------- 1 file changed, 9 insertions(+), 49 deletions(-)
Thanks.
Signature · 1 line
~Randy
PATCH v2 4/4 clk: test: convert constants to use HZ_PER_MHZ
In reply to Brian MasneyConvert 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
@@ -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
Re: [PATCH v2 4/4] clk: test: convert constants to use HZ_PER_MHZ
Quoted 3 lines · Brian Masney
Convert the DUMMY_CLOCK_* constants over to use
HZ_PER_MHZ.Signed-off-by Brian Masney <[email protected]>
Thanks!
Maxime