diff options
Diffstat (limited to 'Documentation/clk.txt')
-rw-r--r-- | Documentation/clk.txt | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/Documentation/clk.txt b/Documentation/clk.txt new file mode 100644 index 000000000000..1943fae014fd --- /dev/null +++ b/Documentation/clk.txt | |||
@@ -0,0 +1,233 @@ | |||
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. | ||