Back to home page

LXR

 
 

    


0001                 The Common Clk Framework
0002                 Mike Turquette <mturquette@ti.com>
0003 
0004 This document endeavours to explain the common clk framework details,
0005 and how to port a platform over to this framework.  It is not yet a
0006 detailed explanation of the clock api in include/linux/clk.h, but
0007 perhaps someday it will include that information.
0008 
0009         Part 1 - introduction and interface split
0010 
0011 The common clk framework is an interface to control the clock nodes
0012 available on various devices today.  This may come in the form of clock
0013 gating, rate adjustment, muxing or other operations.  This framework is
0014 enabled with the CONFIG_COMMON_CLK option.
0015 
0016 The interface itself is divided into two halves, each shielded from the
0017 details of its counterpart.  First is the common definition of struct
0018 clk which unifies the framework-level accounting and infrastructure that
0019 has traditionally been duplicated across a variety of platforms.  Second
0020 is a common implementation of the clk.h api, defined in
0021 drivers/clk/clk.c.  Finally there is struct clk_ops, whose operations
0022 are invoked by the clk api implementation.
0023 
0024 The second half of the interface is comprised of the hardware-specific
0025 callbacks registered with struct clk_ops and the corresponding
0026 hardware-specific structures needed to model a particular clock.  For
0027 the remainder of this document any reference to a callback in struct
0028 clk_ops, such as .enable or .set_rate, implies the hardware-specific
0029 implementation of that code.  Likewise, references to struct clk_foo
0030 serve as a convenient shorthand for the implementation of the
0031 hardware-specific bits for the hypothetical "foo" hardware.
0032 
0033 Tying the two halves of this interface together is struct clk_hw, which
0034 is defined in struct clk_foo and pointed to within struct clk_core.  This
0035 allows for easy navigation between the two discrete halves of the common
0036 clock interface.
0037 
0038         Part 2 - common data structures and api
0039 
0040 Below is the common struct clk_core definition from
0041 drivers/clk/clk.c, modified for brevity:
0042 
0043         struct clk_core {
0044                 const char              *name;
0045                 const struct clk_ops    *ops;
0046                 struct clk_hw           *hw;
0047                 struct module           *owner;
0048                 struct clk_core         *parent;
0049                 const char              **parent_names;
0050                 struct clk_core         **parents;
0051                 u8                      num_parents;
0052                 u8                      new_parent_index;
0053                 ...
0054         };
0055 
0056 The members above make up the core of the clk tree topology.  The clk
0057 api itself defines several driver-facing functions which operate on
0058 struct clk.  That api is documented in include/linux/clk.h.
0059 
0060 Platforms and devices utilizing the common struct clk_core use the struct
0061 clk_ops pointer in struct clk_core to perform the hardware-specific parts of
0062 the operations defined in clk-provider.h:
0063 
0064         struct clk_ops {
0065                 int             (*prepare)(struct clk_hw *hw);
0066                 void            (*unprepare)(struct clk_hw *hw);
0067                 int             (*is_prepared)(struct clk_hw *hw);
0068                 void            (*unprepare_unused)(struct clk_hw *hw);
0069                 int             (*enable)(struct clk_hw *hw);
0070                 void            (*disable)(struct clk_hw *hw);
0071                 int             (*is_enabled)(struct clk_hw *hw);
0072                 void            (*disable_unused)(struct clk_hw *hw);
0073                 unsigned long   (*recalc_rate)(struct clk_hw *hw,
0074                                                 unsigned long parent_rate);
0075                 long            (*round_rate)(struct clk_hw *hw,
0076                                                 unsigned long rate,
0077                                                 unsigned long *parent_rate);
0078                 int             (*determine_rate)(struct clk_hw *hw,
0079                                                   struct clk_rate_request *req);
0080                 int             (*set_parent)(struct clk_hw *hw, u8 index);
0081                 u8              (*get_parent)(struct clk_hw *hw);
0082                 int             (*set_rate)(struct clk_hw *hw,
0083                                             unsigned long rate,
0084                                             unsigned long parent_rate);
0085                 int             (*set_rate_and_parent)(struct clk_hw *hw,
0086                                             unsigned long rate,
0087                                             unsigned long parent_rate,
0088                                             u8 index);
0089                 unsigned long   (*recalc_accuracy)(struct clk_hw *hw,
0090                                                 unsigned long parent_accuracy);
0091                 int             (*get_phase)(struct clk_hw *hw);
0092                 int             (*set_phase)(struct clk_hw *hw, int degrees);
0093                 void            (*init)(struct clk_hw *hw);
0094                 int             (*debug_init)(struct clk_hw *hw,
0095                                               struct dentry *dentry);
0096         };
0097 
0098         Part 3 - hardware clk implementations
0099 
0100 The strength of the common struct clk_core comes from its .ops and .hw pointers
0101 which abstract the details of struct clk from the hardware-specific bits, and
0102 vice versa.  To illustrate consider the simple gateable clk implementation in
0103 drivers/clk/clk-gate.c:
0104 
0105 struct clk_gate {
0106         struct clk_hw   hw;
0107         void __iomem    *reg;
0108         u8              bit_idx;
0109         ...
0110 };
0111 
0112 struct clk_gate contains struct clk_hw hw as well as hardware-specific
0113 knowledge about which register and bit controls this clk's gating.
0114 Nothing about clock topology or accounting, such as enable_count or
0115 notifier_count, is needed here.  That is all handled by the common
0116 framework code and struct clk_core.
0117 
0118 Let's walk through enabling this clk from driver code:
0119 
0120         struct clk *clk;
0121         clk = clk_get(NULL, "my_gateable_clk");
0122 
0123         clk_prepare(clk);
0124         clk_enable(clk);
0125 
0126 The call graph for clk_enable is very simple:
0127 
0128 clk_enable(clk);
0129         clk->ops->enable(clk->hw);
0130         [resolves to...]
0131                 clk_gate_enable(hw);
0132                 [resolves struct clk gate with to_clk_gate(hw)]
0133                         clk_gate_set_bit(gate);
0134 
0135 And the definition of clk_gate_set_bit:
0136 
0137 static void clk_gate_set_bit(struct clk_gate *gate)
0138 {
0139         u32 reg;
0140 
0141         reg = __raw_readl(gate->reg);
0142         reg |= BIT(gate->bit_idx);
0143         writel(reg, gate->reg);
0144 }
0145 
0146 Note that to_clk_gate is defined as:
0147 
0148 #define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw)
0149 
0150 This pattern of abstraction is used for every clock hardware
0151 representation.
0152 
0153         Part 4 - supporting your own clk hardware
0154 
0155 When implementing support for a new type of clock it is only necessary to
0156 include the following header:
0157 
0158 #include <linux/clk-provider.h>
0159 
0160 To construct a clk hardware structure for your platform you must define
0161 the following:
0162 
0163 struct clk_foo {
0164         struct clk_hw hw;
0165         ... hardware specific data goes here ...
0166 };
0167 
0168 To take advantage of your data you'll need to support valid operations
0169 for your clk:
0170 
0171 struct clk_ops clk_foo_ops {
0172         .enable         = &clk_foo_enable;
0173         .disable        = &clk_foo_disable;
0174 };
0175 
0176 Implement the above functions using container_of:
0177 
0178 #define to_clk_foo(_hw) container_of(_hw, struct clk_foo, hw)
0179 
0180 int clk_foo_enable(struct clk_hw *hw)
0181 {
0182         struct clk_foo *foo;
0183 
0184         foo = to_clk_foo(hw);
0185 
0186         ... perform magic on foo ...
0187 
0188         return 0;
0189 };
0190 
0191 Below is a matrix detailing which clk_ops are mandatory based upon the
0192 hardware capabilities of that clock.  A cell marked as "y" means
0193 mandatory, a cell marked as "n" implies that either including that
0194 callback is invalid or otherwise unnecessary.  Empty cells are either
0195 optional or must be evaluated on a case-by-case basis.
0196 
0197                               clock hardware characteristics
0198                 -----------------------------------------------------------
0199                 | gate | change rate | single parent | multiplexer | root |
0200                 |------|-------------|---------------|-------------|------|
0201 .prepare        |      |             |               |             |      |
0202 .unprepare      |      |             |               |             |      |
0203                 |      |             |               |             |      |
0204 .enable         | y    |             |               |             |      |
0205 .disable        | y    |             |               |             |      |
0206 .is_enabled     | y    |             |               |             |      |
0207                 |      |             |               |             |      |
0208 .recalc_rate    |      | y           |               |             |      |
0209 .round_rate     |      | y [1]       |               |             |      |
0210 .determine_rate |      | y [1]       |               |             |      |
0211 .set_rate       |      | y           |               |             |      |
0212                 |      |             |               |             |      |
0213 .set_parent     |      |             | n             | y           | n    |
0214 .get_parent     |      |             | n             | y           | n    |
0215                 |      |             |               |             |      |
0216 .recalc_accuracy|      |             |               |             |      |
0217                 |      |             |               |             |      |
0218 .init           |      |             |               |             |      |
0219                 -----------------------------------------------------------
0220 [1] either one of round_rate or determine_rate is required.
0221 
0222 Finally, register your clock at run-time with a hardware-specific
0223 registration function.  This function simply populates struct clk_foo's
0224 data and then passes the common struct clk parameters to the framework
0225 with a call to:
0226 
0227 clk_register(...)
0228 
0229 See the basic clock types in drivers/clk/clk-*.c for examples.
0230 
0231         Part 5 - Disabling clock gating of unused clocks
0232 
0233 Sometimes during development it can be useful to be able to bypass the
0234 default disabling of unused clocks. For example, if drivers aren't enabling
0235 clocks properly but rely on them being on from the bootloader, bypassing
0236 the disabling means that the driver will remain functional while the issues
0237 are sorted out.
0238 
0239 To bypass this disabling, include "clk_ignore_unused" in the bootargs to the
0240 kernel.
0241 
0242         Part 6 - Locking
0243 
0244 The common clock framework uses two global locks, the prepare lock and the
0245 enable lock.
0246 
0247 The enable lock is a spinlock and is held across calls to the .enable,
0248 .disable and .is_enabled operations. Those operations are thus not allowed to
0249 sleep, and calls to the clk_enable(), clk_disable() and clk_is_enabled() API
0250 functions are allowed in atomic context.
0251 
0252 The prepare lock is a mutex and is held across calls to all other operations.
0253 All those operations are allowed to sleep, and calls to the corresponding API
0254 functions are not allowed in atomic context.
0255 
0256 This effectively divides operations in two groups from a locking perspective.
0257 
0258 Drivers don't need to manually protect resources shared between the operations
0259 of one group, regardless of whether those resources are shared by multiple
0260 clocks or not. However, access to resources that are shared between operations
0261 of the two groups needs to be protected by the drivers. An example of such a
0262 resource would be a register that controls both the clock rate and the clock
0263 enable/disable state.
0264 
0265 The clock framework is reentrant, in that a driver is allowed to call clock
0266 framework functions from within its implementation of clock operations. This
0267 can for instance cause a .set_rate operation of one clock being called from
0268 within the .set_rate operation of another clock. This case must be considered
0269 in the driver implementations, but the code flow is usually controlled by the
0270 driver in that case.
0271 
0272 Note that locking must also be considered when code outside of the common
0273 clock framework needs to access resources used by the clock operations. This
0274 is considered out of scope of this document.