Root/
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 |
35 | allows easy for 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 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 *); |
73 | int (*set_parent)(struct clk_hw *hw, u8 index); |
74 | u8 (*get_parent)(struct clk_hw *hw); |
75 | int (*set_rate)(struct clk_hw *hw, unsigned long); |
76 | void (*init)(struct clk_hw *hw); |
77 | }; |
78 | |
79 | Part 3 - hardware clk implementations |
80 | |
81 | The strength of the common struct clk comes from its .ops and .hw pointers |
82 | which abstract the details of struct clk from the hardware-specific bits, and |
83 | vice versa. To illustrate consider the simple gateable clk implementation in |
84 | drivers/clk/clk-gate.c: |
85 | |
86 | struct clk_gate { |
87 | struct clk_hw hw; |
88 | void __iomem *reg; |
89 | u8 bit_idx; |
90 | ... |
91 | }; |
92 | |
93 | struct clk_gate contains struct clk_hw hw as well as hardware-specific |
94 | knowledge about which register and bit controls this clk's gating. |
95 | Nothing about clock topology or accounting, such as enable_count or |
96 | notifier_count, is needed here. That is all handled by the common |
97 | framework code and struct clk. |
98 | |
99 | Let's walk through enabling this clk from driver code: |
100 | |
101 | struct clk *clk; |
102 | clk = clk_get(NULL, "my_gateable_clk"); |
103 | |
104 | clk_prepare(clk); |
105 | clk_enable(clk); |
106 | |
107 | The call graph for clk_enable is very simple: |
108 | |
109 | clk_enable(clk); |
110 | clk->ops->enable(clk->hw); |
111 | [resolves to...] |
112 | clk_gate_enable(hw); |
113 | [resolves struct clk gate with to_clk_gate(hw)] |
114 | clk_gate_set_bit(gate); |
115 | |
116 | And the definition of clk_gate_set_bit: |
117 | |
118 | static void clk_gate_set_bit(struct clk_gate *gate) |
119 | { |
120 | u32 reg; |
121 | |
122 | reg = __raw_readl(gate->reg); |
123 | reg |= BIT(gate->bit_idx); |
124 | writel(reg, gate->reg); |
125 | } |
126 | |
127 | Note that to_clk_gate is defined as: |
128 | |
129 | #define to_clk_gate(_hw) container_of(_hw, struct clk_gate, clk) |
130 | |
131 | This pattern of abstraction is used for every clock hardware |
132 | representation. |
133 | |
134 | Part 4 - supporting your own clk hardware |
135 | |
136 | When implementing support for a new type of clock it only necessary to |
137 | include the following header: |
138 | |
139 | #include <linux/clk-provider.h> |
140 | |
141 | include/linux/clk.h is included within that header and clk-private.h |
142 | must never be included from the code which implements the operations for |
143 | a clock. More on that below in Part 5. |
144 | |
145 | To construct a clk hardware structure for your platform you must define |
146 | the following: |
147 | |
148 | struct clk_foo { |
149 | struct clk_hw hw; |
150 | ... hardware specific data goes here ... |
151 | }; |
152 | |
153 | To take advantage of your data you'll need to support valid operations |
154 | for your clk: |
155 | |
156 | struct clk_ops clk_foo_ops { |
157 | .enable = &clk_foo_enable; |
158 | .disable = &clk_foo_disable; |
159 | }; |
160 | |
161 | Implement the above functions using container_of: |
162 | |
163 | #define to_clk_foo(_hw) container_of(_hw, struct clk_foo, hw) |
164 | |
165 | int clk_foo_enable(struct clk_hw *hw) |
166 | { |
167 | struct clk_foo *foo; |
168 | |
169 | foo = to_clk_foo(hw); |
170 | |
171 | ... perform magic on foo ... |
172 | |
173 | return 0; |
174 | }; |
175 | |
176 | Below is a matrix detailing which clk_ops are mandatory based upon the |
177 | hardware capbilities of that clock. A cell marked as "y" means |
178 | mandatory, a cell marked as "n" implies that either including that |
179 | callback is invalid or otherwise uneccesary. Empty cells are either |
180 | optional or must be evaluated on a case-by-case basis. |
181 | |
182 | clock hardware characteristics |
183 | ----------------------------------------------------------- |
184 | | gate | change rate | single parent | multiplexer | root | |
185 | |------|-------------|---------------|-------------|------| |
186 | .prepare | | | | | | |
187 | .unprepare | | | | | | |
188 | | | | | | | |
189 | .enable | y | | | | | |
190 | .disable | y | | | | | |
191 | .is_enabled | y | | | | | |
192 | | | | | | | |
193 | .recalc_rate | | y | | | | |
194 | .round_rate | | y | | | | |
195 | .set_rate | | y | | | | |
196 | | | | | | | |
197 | .set_parent | | | n | y | n | |
198 | .get_parent | | | n | y | n | |
199 | | | | | | | |
200 | .init | | | | | | |
201 | ----------------------------------------------------------- |
202 | |
203 | Finally, register your clock at run-time with a hardware-specific |
204 | registration function. This function simply populates struct clk_foo's |
205 | data and then passes the common struct clk parameters to the framework |
206 | with a call to: |
207 | |
208 | clk_register(...) |
209 | |
210 | See the basic clock types in drivers/clk/clk-*.c for examples. |
211 | |
212 | Part 5 - static initialization of clock data |
213 | |
214 | For platforms with many clocks (often numbering into the hundreds) it |
215 | may be desirable to statically initialize some clock data. This |
216 | presents a problem since the definition of struct clk should be hidden |
217 | from everyone except for the clock core in drivers/clk/clk.c. |
218 | |
219 | To get around this problem struct clk's definition is exposed in |
220 | include/linux/clk-private.h along with some macros for more easily |
221 | initializing instances of the basic clock types. These clocks must |
222 | still be initialized with the common clock framework via a call to |
223 | __clk_init. |
224 | |
225 | clk-private.h must NEVER be included by code which implements struct |
226 | clk_ops callbacks, nor must it be included by any logic which pokes |
227 | around inside of struct clk at run-time. To do so is a layering |
228 | violation. |
229 | |
230 | To better enforce this policy, always follow this simple rule: any |
231 | statically initialized clock data MUST be defined in a separate file |
232 | from the logic that implements its ops. Basically separate the logic |
233 | from the data and all is well. |
234 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9