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