]>
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); | |
71 | long (*round_rate)(struct clk_hw *hw, unsigned long, | |
72 | unsigned long *); | |
71472c0c JH |
73 | long (*determine_rate)(struct clk_hw *hw, |
74 | unsigned long rate, | |
75 | unsigned long *best_parent_rate, | |
76 | struct clk **best_parent_clk); | |
69fe8a8e MT |
77 | int (*set_parent)(struct clk_hw *hw, u8 index); |
78 | u8 (*get_parent)(struct clk_hw *hw); | |
79 | int (*set_rate)(struct clk_hw *hw, unsigned long); | |
5279fc40 BB |
80 | unsigned long (*recalc_accuracy)(struct clk_hw *hw, |
81 | unsigned long parent_accuracy); | |
69fe8a8e MT |
82 | void (*init)(struct clk_hw *hw); |
83 | }; | |
84 | ||
85 | Part 3 - hardware clk implementations | |
86 | ||
87 | The strength of the common struct clk comes from its .ops and .hw pointers | |
88 | which abstract the details of struct clk from the hardware-specific bits, and | |
89 | vice versa. To illustrate consider the simple gateable clk implementation in | |
90 | drivers/clk/clk-gate.c: | |
91 | ||
92 | struct clk_gate { | |
93 | struct clk_hw hw; | |
94 | void __iomem *reg; | |
95 | u8 bit_idx; | |
96 | ... | |
97 | }; | |
98 | ||
99 | struct clk_gate contains struct clk_hw hw as well as hardware-specific | |
100 | knowledge about which register and bit controls this clk's gating. | |
101 | Nothing about clock topology or accounting, such as enable_count or | |
102 | notifier_count, is needed here. That is all handled by the common | |
103 | framework code and struct clk. | |
104 | ||
105 | Let's walk through enabling this clk from driver code: | |
106 | ||
107 | struct clk *clk; | |
108 | clk = clk_get(NULL, "my_gateable_clk"); | |
109 | ||
110 | clk_prepare(clk); | |
111 | clk_enable(clk); | |
112 | ||
113 | The call graph for clk_enable is very simple: | |
114 | ||
115 | clk_enable(clk); | |
116 | clk->ops->enable(clk->hw); | |
117 | [resolves to...] | |
118 | clk_gate_enable(hw); | |
119 | [resolves struct clk gate with to_clk_gate(hw)] | |
120 | clk_gate_set_bit(gate); | |
121 | ||
122 | And the definition of clk_gate_set_bit: | |
123 | ||
124 | static void clk_gate_set_bit(struct clk_gate *gate) | |
125 | { | |
126 | u32 reg; | |
127 | ||
128 | reg = __raw_readl(gate->reg); | |
129 | reg |= BIT(gate->bit_idx); | |
130 | writel(reg, gate->reg); | |
131 | } | |
132 | ||
133 | Note that to_clk_gate is defined as: | |
134 | ||
135 | #define to_clk_gate(_hw) container_of(_hw, struct clk_gate, clk) | |
136 | ||
137 | This pattern of abstraction is used for every clock hardware | |
138 | representation. | |
139 | ||
140 | Part 4 - supporting your own clk hardware | |
141 | ||
142 | When implementing support for a new type of clock it only necessary to | |
143 | include the following header: | |
144 | ||
145 | #include <linux/clk-provider.h> | |
146 | ||
147 | include/linux/clk.h is included within that header and clk-private.h | |
148 | must never be included from the code which implements the operations for | |
149 | a clock. More on that below in Part 5. | |
150 | ||
151 | To construct a clk hardware structure for your platform you must define | |
152 | the following: | |
153 | ||
154 | struct clk_foo { | |
155 | struct clk_hw hw; | |
156 | ... hardware specific data goes here ... | |
157 | }; | |
158 | ||
159 | To take advantage of your data you'll need to support valid operations | |
160 | for your clk: | |
161 | ||
162 | struct clk_ops clk_foo_ops { | |
163 | .enable = &clk_foo_enable; | |
164 | .disable = &clk_foo_disable; | |
165 | }; | |
166 | ||
167 | Implement the above functions using container_of: | |
168 | ||
169 | #define to_clk_foo(_hw) container_of(_hw, struct clk_foo, hw) | |
170 | ||
171 | int clk_foo_enable(struct clk_hw *hw) | |
172 | { | |
173 | struct clk_foo *foo; | |
174 | ||
175 | foo = to_clk_foo(hw); | |
176 | ||
177 | ... perform magic on foo ... | |
178 | ||
179 | return 0; | |
180 | }; | |
181 | ||
182 | Below is a matrix detailing which clk_ops are mandatory based upon the | |
a368a6a3 | 183 | hardware capabilities of that clock. A cell marked as "y" means |
69fe8a8e | 184 | mandatory, a cell marked as "n" implies that either including that |
a368a6a3 | 185 | callback is invalid or otherwise unnecessary. Empty cells are either |
69fe8a8e MT |
186 | optional or must be evaluated on a case-by-case basis. |
187 | ||
71472c0c JH |
188 | clock hardware characteristics |
189 | ----------------------------------------------------------- | |
190 | | gate | change rate | single parent | multiplexer | root | | |
191 | |------|-------------|---------------|-------------|------| | |
192 | .prepare | | | | | | | |
193 | .unprepare | | | | | | | |
194 | | | | | | | | |
195 | .enable | y | | | | | | |
196 | .disable | y | | | | | | |
197 | .is_enabled | y | | | | | | |
198 | | | | | | | | |
199 | .recalc_rate | | y | | | | | |
200 | .round_rate | | y [1] | | | | | |
201 | .determine_rate | | y [1] | | | | | |
202 | .set_rate | | y | | | | | |
203 | | | | | | | | |
204 | .set_parent | | | n | y | n | | |
205 | .get_parent | | | n | y | n | | |
206 | | | | | | | | |
5279fc40 BB |
207 | .recalc_accuracy| | | | | | |
208 | | | | | | | | |
71472c0c JH |
209 | .init | | | | | | |
210 | ----------------------------------------------------------- | |
211 | [1] either one of round_rate or determine_rate is required. | |
69fe8a8e MT |
212 | |
213 | Finally, register your clock at run-time with a hardware-specific | |
214 | registration function. This function simply populates struct clk_foo's | |
215 | data and then passes the common struct clk parameters to the framework | |
216 | with a call to: | |
217 | ||
218 | clk_register(...) | |
219 | ||
220 | See the basic clock types in drivers/clk/clk-*.c for examples. | |
221 | ||
222 | Part 5 - static initialization of clock data | |
223 | ||
224 | For platforms with many clocks (often numbering into the hundreds) it | |
225 | may be desirable to statically initialize some clock data. This | |
226 | presents a problem since the definition of struct clk should be hidden | |
227 | from everyone except for the clock core in drivers/clk/clk.c. | |
228 | ||
229 | To get around this problem struct clk's definition is exposed in | |
230 | include/linux/clk-private.h along with some macros for more easily | |
231 | initializing instances of the basic clock types. These clocks must | |
232 | still be initialized with the common clock framework via a call to | |
233 | __clk_init. | |
234 | ||
235 | clk-private.h must NEVER be included by code which implements struct | |
236 | clk_ops callbacks, nor must it be included by any logic which pokes | |
237 | around inside of struct clk at run-time. To do so is a layering | |
238 | violation. | |
239 | ||
240 | To better enforce this policy, always follow this simple rule: any | |
241 | statically initialized clock data MUST be defined in a separate file | |
242 | from the logic that implements its ops. Basically separate the logic | |
243 | from the data and all is well. | |
1e435256 OJ |
244 | |
245 | Part 6 - Disabling clock gating of unused clocks | |
246 | ||
247 | Sometimes during development it can be useful to be able to bypass the | |
248 | default disabling of unused clocks. For example, if drivers aren't enabling | |
249 | clocks properly but rely on them being on from the bootloader, bypassing | |
250 | the disabling means that the driver will remain functional while the issues | |
251 | are sorted out. | |
252 | ||
253 | To bypass this disabling, include "clk_ignore_unused" in the bootargs to the | |
254 | kernel. |