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