]>
Commit | Line | Data |
---|---|---|
f68ac62d MCC |
1 | ======================== |
2 | The Common Clk Framework | |
3 | ======================== | |
4 | ||
5 | :Author: Mike Turquette <mturquette@ti.com> | |
69fe8a8e MT |
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 | ||
f68ac62d MCC |
12 | Introduction and interface split |
13 | ================================ | |
69fe8a8e MT |
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 | |
6203a642 | 38 | is defined in struct clk_foo and pointed to within struct clk_core. This |
13541950 | 39 | allows for easy navigation between the two discrete halves of the common |
69fe8a8e MT |
40 | clock interface. |
41 | ||
f68ac62d MCC |
42 | Common data structures and api |
43 | ============================== | |
69fe8a8e | 44 | |
6203a642 | 45 | Below is the common struct clk_core definition from |
f68ac62d | 46 | drivers/clk/clk.c, modified for brevity:: |
69fe8a8e | 47 | |
6203a642 | 48 | struct clk_core { |
69fe8a8e MT |
49 | const char *name; |
50 | const struct clk_ops *ops; | |
51 | struct clk_hw *hw; | |
6203a642 AS |
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; | |
69fe8a8e MT |
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 | ||
6203a642 AS |
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 | |
f68ac62d | 67 | the operations defined in clk-provider.h:: |
69fe8a8e MT |
68 | |
69 | struct clk_ops { | |
70 | int (*prepare)(struct clk_hw *hw); | |
71 | void (*unprepare)(struct clk_hw *hw); | |
6203a642 AS |
72 | int (*is_prepared)(struct clk_hw *hw); |
73 | void (*unprepare_unused)(struct clk_hw *hw); | |
69fe8a8e MT |
74 | int (*enable)(struct clk_hw *hw); |
75 | void (*disable)(struct clk_hw *hw); | |
76 | int (*is_enabled)(struct clk_hw *hw); | |
6203a642 | 77 | void (*disable_unused)(struct clk_hw *hw); |
69fe8a8e MT |
78 | unsigned long (*recalc_rate)(struct clk_hw *hw, |
79 | unsigned long parent_rate); | |
54e73016 GU |
80 | long (*round_rate)(struct clk_hw *hw, |
81 | unsigned long rate, | |
82 | unsigned long *parent_rate); | |
0817b62c BB |
83 | int (*determine_rate)(struct clk_hw *hw, |
84 | struct clk_rate_request *req); | |
69fe8a8e MT |
85 | int (*set_parent)(struct clk_hw *hw, u8 index); |
86 | u8 (*get_parent)(struct clk_hw *hw); | |
54e73016 GU |
87 | int (*set_rate)(struct clk_hw *hw, |
88 | unsigned long rate, | |
89 | unsigned long parent_rate); | |
3fa2252b SB |
90 | int (*set_rate_and_parent)(struct clk_hw *hw, |
91 | unsigned long rate, | |
54e73016 GU |
92 | unsigned long parent_rate, |
93 | u8 index); | |
5279fc40 | 94 | unsigned long (*recalc_accuracy)(struct clk_hw *hw, |
54e73016 | 95 | unsigned long parent_accuracy); |
6203a642 AS |
96 | int (*get_phase)(struct clk_hw *hw); |
97 | int (*set_phase)(struct clk_hw *hw, int degrees); | |
69fe8a8e | 98 | void (*init)(struct clk_hw *hw); |
54e73016 GU |
99 | int (*debug_init)(struct clk_hw *hw, |
100 | struct dentry *dentry); | |
69fe8a8e MT |
101 | }; |
102 | ||
f68ac62d MCC |
103 | Hardware clk implementations |
104 | ============================ | |
69fe8a8e | 105 | |
6203a642 | 106 | The strength of the common struct clk_core comes from its .ops and .hw pointers |
69fe8a8e MT |
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 | |
f68ac62d | 109 | drivers/clk/clk-gate.c:: |
69fe8a8e | 110 | |
f68ac62d MCC |
111 | struct clk_gate { |
112 | struct clk_hw hw; | |
113 | void __iomem *reg; | |
114 | u8 bit_idx; | |
115 | ... | |
116 | }; | |
69fe8a8e MT |
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 | |
6203a642 | 122 | framework code and struct clk_core. |
69fe8a8e | 123 | |
f68ac62d | 124 | Let's walk through enabling this clk from driver code:: |
69fe8a8e MT |
125 | |
126 | struct clk *clk; | |
127 | clk = clk_get(NULL, "my_gateable_clk"); | |
128 | ||
129 | clk_prepare(clk); | |
130 | clk_enable(clk); | |
131 | ||
f68ac62d | 132 | The call graph for clk_enable is very simple:: |
69fe8a8e | 133 | |
f68ac62d MCC |
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); | |
69fe8a8e | 140 | |
f68ac62d | 141 | And the definition of clk_gate_set_bit:: |
69fe8a8e | 142 | |
f68ac62d MCC |
143 | static void clk_gate_set_bit(struct clk_gate *gate) |
144 | { | |
145 | u32 reg; | |
69fe8a8e | 146 | |
f68ac62d MCC |
147 | reg = __raw_readl(gate->reg); |
148 | reg |= BIT(gate->bit_idx); | |
149 | writel(reg, gate->reg); | |
150 | } | |
69fe8a8e | 151 | |
f68ac62d | 152 | Note that to_clk_gate is defined as:: |
69fe8a8e | 153 | |
f68ac62d | 154 | #define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw) |
69fe8a8e MT |
155 | |
156 | This pattern of abstraction is used for every clock hardware | |
157 | representation. | |
158 | ||
f68ac62d MCC |
159 | Supporting your own clk hardware |
160 | ================================ | |
69fe8a8e | 161 | |
6203a642 | 162 | When implementing support for a new type of clock it is only necessary to |
f68ac62d | 163 | include the following header:: |
69fe8a8e | 164 | |
f68ac62d | 165 | #include <linux/clk-provider.h> |
69fe8a8e | 166 | |
69fe8a8e | 167 | To construct a clk hardware structure for your platform you must define |
f68ac62d | 168 | the following:: |
69fe8a8e | 169 | |
f68ac62d MCC |
170 | struct clk_foo { |
171 | struct clk_hw hw; | |
172 | ... hardware specific data goes here ... | |
173 | }; | |
69fe8a8e MT |
174 | |
175 | To take advantage of your data you'll need to support valid operations | |
f68ac62d | 176 | for your clk:: |
69fe8a8e | 177 | |
f68ac62d MCC |
178 | struct clk_ops clk_foo_ops { |
179 | .enable = &clk_foo_enable; | |
180 | .disable = &clk_foo_disable; | |
181 | }; | |
69fe8a8e | 182 | |
f68ac62d | 183 | Implement the above functions using container_of:: |
69fe8a8e | 184 | |
f68ac62d | 185 | #define to_clk_foo(_hw) container_of(_hw, struct clk_foo, hw) |
69fe8a8e | 186 | |
f68ac62d MCC |
187 | int clk_foo_enable(struct clk_hw *hw) |
188 | { | |
189 | struct clk_foo *foo; | |
69fe8a8e | 190 | |
f68ac62d | 191 | foo = to_clk_foo(hw); |
69fe8a8e | 192 | |
f68ac62d | 193 | ... perform magic on foo ... |
69fe8a8e | 194 | |
f68ac62d MCC |
195 | return 0; |
196 | }; | |
69fe8a8e MT |
197 | |
198 | Below is a matrix detailing which clk_ops are mandatory based upon the | |
a368a6a3 | 199 | hardware capabilities of that clock. A cell marked as "y" means |
69fe8a8e | 200 | mandatory, a cell marked as "n" implies that either including that |
a368a6a3 | 201 | callback is invalid or otherwise unnecessary. Empty cells are either |
69fe8a8e MT |
202 | optional or must be evaluated on a case-by-case basis. |
203 | ||
f68ac62d MCC |
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. | |
69fe8a8e MT |
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 | |
f68ac62d | 246 | with a call to:: |
69fe8a8e | 247 | |
f68ac62d | 248 | clk_register(...) |
69fe8a8e | 249 | |
f68ac62d | 250 | See the basic clock types in ``drivers/clk/clk-*.c`` for examples. |
69fe8a8e | 251 | |
f68ac62d MCC |
252 | Disabling clock gating of unused clocks |
253 | ======================================= | |
1e435256 OJ |
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. | |
843bad83 | 263 | |
f68ac62d MCC |
264 | Locking |
265 | ======= | |
843bad83 LP |
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. |