]>
Commit | Line | Data |
---|---|---|
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. |