projects/linux·blob master · refs

271 lines · 10.9 KiB

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