Version:  2.0.40 2.2.26 2.4.37 3.13 3.14 3.15 3.16 3.17 3.18 3.19 4.0 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10

Linux/Documentation/clk.txt

  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.

This page was automatically generated by LXR 0.3.1 (source).  •  Linux is a registered trademark of Linus Torvalds  •  Contact us