Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) The Common Clk Framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) :Author: Mike Turquette <mturquette@ti.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) This document endeavours to explain the common clk framework details,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) and how to port a platform over to this framework.  It is not yet a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) detailed explanation of the clock api in include/linux/clk.h, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) perhaps someday it will include that information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) Introduction and interface split
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) ================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) The common clk framework is an interface to control the clock nodes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) available on various devices today.  This may come in the form of clock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) gating, rate adjustment, muxing or other operations.  This framework is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) enabled with the CONFIG_COMMON_CLK option.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) The interface itself is divided into two halves, each shielded from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) details of its counterpart.  First is the common definition of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) clk which unifies the framework-level accounting and infrastructure that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) has traditionally been duplicated across a variety of platforms.  Second
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) is a common implementation of the clk.h api, defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) drivers/clk/clk.c.  Finally there is struct clk_ops, whose operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) are invoked by the clk api implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) The second half of the interface is comprised of the hardware-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) callbacks registered with struct clk_ops and the corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) hardware-specific structures needed to model a particular clock.  For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) the remainder of this document any reference to a callback in struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) clk_ops, such as .enable or .set_rate, implies the hardware-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) implementation of that code.  Likewise, references to struct clk_foo
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) serve as a convenient shorthand for the implementation of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) hardware-specific bits for the hypothetical "foo" hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) Tying the two halves of this interface together is struct clk_hw, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) is defined in struct clk_foo and pointed to within struct clk_core.  This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) allows for easy navigation between the two discrete halves of the common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) clock interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) Common data structures and api
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) Below is the common struct clk_core definition from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) drivers/clk/clk.c, modified for brevity::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) 	struct clk_core {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) 		const char		*name;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) 		const struct clk_ops	*ops;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) 		struct clk_hw		*hw;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) 		struct module		*owner;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) 		struct clk_core		*parent;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) 		const char		**parent_names;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) 		struct clk_core		**parents;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) 		u8			num_parents;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) 		u8			new_parent_index;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) 		...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) 	};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) The members above make up the core of the clk tree topology.  The clk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) api itself defines several driver-facing functions which operate on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) struct clk.  That api is documented in include/linux/clk.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) Platforms and devices utilizing the common struct clk_core use the struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) clk_ops pointer in struct clk_core to perform the hardware-specific parts of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) the operations defined in clk-provider.h::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) 	struct clk_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) 		int		(*prepare)(struct clk_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) 		void		(*unprepare)(struct clk_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) 		int		(*is_prepared)(struct clk_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) 		void		(*unprepare_unused)(struct clk_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) 		int		(*enable)(struct clk_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) 		void		(*disable)(struct clk_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) 		int		(*is_enabled)(struct clk_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) 		void		(*disable_unused)(struct clk_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) 		unsigned long	(*recalc_rate)(struct clk_hw *hw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) 						unsigned long parent_rate);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) 		long		(*round_rate)(struct clk_hw *hw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) 						unsigned long rate,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) 						unsigned long *parent_rate);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) 		int		(*determine_rate)(struct clk_hw *hw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) 						  struct clk_rate_request *req);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) 		int		(*set_parent)(struct clk_hw *hw, u8 index);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) 		u8		(*get_parent)(struct clk_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) 		int		(*set_rate)(struct clk_hw *hw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) 					    unsigned long rate,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) 					    unsigned long parent_rate);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) 		int		(*set_rate_and_parent)(struct clk_hw *hw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) 					    unsigned long rate,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) 					    unsigned long parent_rate,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) 					    u8 index);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 		unsigned long	(*recalc_accuracy)(struct clk_hw *hw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) 						unsigned long parent_accuracy);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) 		int		(*get_phase)(struct clk_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) 		int		(*set_phase)(struct clk_hw *hw, int degrees);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) 		void		(*init)(struct clk_hw *hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) 		void		(*debug_init)(struct clk_hw *hw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) 					      struct dentry *dentry);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) 	};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) Hardware clk implementations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) The strength of the common struct clk_core comes from its .ops and .hw pointers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) which abstract the details of struct clk from the hardware-specific bits, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) vice versa.  To illustrate consider the simple gateable clk implementation in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) drivers/clk/clk-gate.c::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) 	struct clk_gate {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) 		struct clk_hw	hw;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 		void __iomem    *reg;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) 		u8              bit_idx;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) 		...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) 	};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) struct clk_gate contains struct clk_hw hw as well as hardware-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) knowledge about which register and bit controls this clk's gating.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Nothing about clock topology or accounting, such as enable_count or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) notifier_count, is needed here.  That is all handled by the common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) framework code and struct clk_core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) Let's walk through enabling this clk from driver code::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) 	struct clk *clk;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) 	clk = clk_get(NULL, "my_gateable_clk");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 	clk_prepare(clk);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) 	clk_enable(clk);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) The call graph for clk_enable is very simple::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) 	clk_enable(clk);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) 		clk->ops->enable(clk->hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) 		[resolves to...]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) 			clk_gate_enable(hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) 			[resolves struct clk gate with to_clk_gate(hw)]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) 				clk_gate_set_bit(gate);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) And the definition of clk_gate_set_bit::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) 	static void clk_gate_set_bit(struct clk_gate *gate)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 	{
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) 		u32 reg;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) 		reg = __raw_readl(gate->reg);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) 		reg |= BIT(gate->bit_idx);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) 		writel(reg, gate->reg);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) 	}
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) Note that to_clk_gate is defined as::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) 	#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) This pattern of abstraction is used for every clock hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) representation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) Supporting your own clk hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) ================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) When implementing support for a new type of clock it is only necessary to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) include the following header::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) 	#include <linux/clk-provider.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) To construct a clk hardware structure for your platform you must define
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) the following::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) 	struct clk_foo {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) 		struct clk_hw hw;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) 		... hardware specific data goes here ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) 	};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) To take advantage of your data you'll need to support valid operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) for your clk::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) 	struct clk_ops clk_foo_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) 		.enable		= &clk_foo_enable,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) 		.disable	= &clk_foo_disable,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) 	};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) Implement the above functions using container_of::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) 	#define to_clk_foo(_hw) container_of(_hw, struct clk_foo, hw)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) 	int clk_foo_enable(struct clk_hw *hw)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) 	{
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) 		struct clk_foo *foo;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) 		foo = to_clk_foo(hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) 		... perform magic on foo ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) 		return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) 	};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) Below is a matrix detailing which clk_ops are mandatory based upon the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) hardware capabilities of that clock.  A cell marked as "y" means
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) mandatory, a cell marked as "n" implies that either including that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) callback is invalid or otherwise unnecessary.  Empty cells are either
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) optional or must be evaluated on a case-by-case basis.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) .. table:: clock hardware characteristics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)    |                | gate | change rate | single parent | multiplexer | root |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)    +================+======+=============+===============+=============+======+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)    |.prepare        |      |             |               |             |      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)    |.unprepare      |      |             |               |             |      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)    |.enable         | y    |             |               |             |      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)    |.disable        | y    |             |               |             |      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)    |.is_enabled     | y    |             |               |             |      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)    |.recalc_rate    |      | y           |               |             |      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223)    |.round_rate     |      | y [1]_      |               |             |      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)    |.determine_rate |      | y [1]_      |               |             |      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)    |.set_rate       |      | y           |               |             |      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)    |.set_parent     |      |             | n             | y           | n    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)    |.get_parent     |      |             | n             | y           | n    |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)    |.recalc_accuracy|      |             |               |             |      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)    |.init           |      |             |               |             |      |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)    +----------------+------+-------------+---------------+-------------+------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) .. [1] either one of round_rate or determine_rate is required.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) Finally, register your clock at run-time with a hardware-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) registration function.  This function simply populates struct clk_foo's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) data and then passes the common struct clk parameters to the framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) with a call to::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) 	clk_register(...)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) See the basic clock types in ``drivers/clk/clk-*.c`` for examples.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) Disabling clock gating of unused clocks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) =======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) Sometimes during development it can be useful to be able to bypass the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) default disabling of unused clocks. For example, if drivers aren't enabling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) clocks properly but rely on them being on from the bootloader, bypassing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) the disabling means that the driver will remain functional while the issues
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) are sorted out.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) To bypass this disabling, include "clk_ignore_unused" in the bootargs to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) Locking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) The common clock framework uses two global locks, the prepare lock and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) enable lock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) The enable lock is a spinlock and is held across calls to the .enable,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) .disable operations. Those operations are thus not allowed to sleep,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) and calls to the clk_enable(), clk_disable() API functions are allowed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) atomic context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) For clk_is_enabled() API, it is also designed to be allowed to be used in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) atomic context. However, it doesn't really make any sense to hold the enable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) lock in core, unless you want to do something else with the information of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) the enable state with that lock held. Otherwise, seeing if a clk is enabled is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) a one-shot read of the enabled state, which could just as easily change after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) the function returns because the lock is released. Thus the user of this API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) needs to handle synchronizing the read of the state with whatever they're
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) using it for to make sure that the enable state doesn't change during that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) The prepare lock is a mutex and is held across calls to all other operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) All those operations are allowed to sleep, and calls to the corresponding API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) functions are not allowed in atomic context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) This effectively divides operations in two groups from a locking perspective.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) Drivers don't need to manually protect resources shared between the operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) of one group, regardless of whether those resources are shared by multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) clocks or not. However, access to resources that are shared between operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) of the two groups needs to be protected by the drivers. An example of such a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) resource would be a register that controls both the clock rate and the clock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) enable/disable state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) The clock framework is reentrant, in that a driver is allowed to call clock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) framework functions from within its implementation of clock operations. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) can for instance cause a .set_rate operation of one clock being called from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) within the .set_rate operation of another clock. This case must be considered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) in the driver implementations, but the code flow is usually controlled by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) driver in that case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) Note that locking must also be considered when code outside of the common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) clock framework needs to access resources used by the clock operations. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) is considered out of scope of this document.