About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / clk.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:52 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog