1 /* 2 * linux/include/linux/clk-provider.h 3 * 4 * Copyright (c) 2010-2011 Jeremy Kerr <[email protected]> 5 * Copyright (C) 2011-2012 Linaro Ltd <[email protected]> 6 * 7 * This program is free software; you can redistribute it and/or modify 8 * it under the terms of the GNU General Public License version 2 as 9 * published by the Free Software Foundation. 10 */ 11 #ifndef __LINUX_CLK_PROVIDER_H 12 #define __LINUX_CLK_PROVIDER_H 13 14 #include <linux/clk.h> 15 16 #ifdef CONFIG_COMMON_CLK 17 18 /* 19 * flags used across common struct clk. these flags should only affect the 20 * top-level framework. custom flags for dealing with hardware specifics 21 * belong in struct clk_foo 22 */ 23 #define CLK_SET_RATE_GATE BIT(0) /* must be gated across rate change */ 24 #define CLK_SET_PARENT_GATE BIT(1) /* must be gated across re-parent */ 25 #define CLK_SET_RATE_PARENT BIT(2) /* propagate rate change up one level */ 26 #define CLK_IGNORE_UNUSED BIT(3) /* do not gate even if unused */ 27 #define CLK_IS_ROOT BIT(4) /* root clk, has no parent */ 28 29 struct clk_hw; 30 31 /** 32 * struct clk_ops - Callback operations for hardware clocks; these are to 33 * be provided by the clock implementation, and will be called by drivers 34 * through the clk_* api. 35 * 36 * @prepare: Prepare the clock for enabling. This must not return until 37 * the clock is fully prepared, and it's safe to call clk_enable. 38 * This callback is intended to allow clock implementations to 39 * do any initialisation that may sleep. Called with 40 * prepare_lock held. 41 * 42 * @unprepare: Release the clock from its prepared state. This will typically 43 * undo any work done in the @prepare callback. Called with 44 * prepare_lock held. 45 * 46 * @enable: Enable the clock atomically. This must not return until the 47 * clock is generating a valid clock signal, usable by consumer 48 * devices. Called with enable_lock held. This function must not 49 * sleep. 50 * 51 * @disable: Disable the clock atomically. Called with enable_lock held. 52 * This function must not sleep. 53 * 54 * @recalc_rate Recalculate the rate of this clock, by quering hardware. The 55 * parent rate is an input parameter. It is up to the caller to 56 * insure that the prepare_mutex is held across this call. 57 * Returns the calculated rate. Optional, but recommended - if 58 * this op is not set then clock rate will be initialized to 0. 59 * 60 * @round_rate: Given a target rate as input, returns the closest rate actually 61 * supported by the clock. 62 * 63 * @get_parent: Queries the hardware to determine the parent of a clock. The 64 * return value is a u8 which specifies the index corresponding to 65 * the parent clock. This index can be applied to either the 66 * .parent_names or .parents arrays. In short, this function 67 * translates the parent value read from hardware into an array 68 * index. Currently only called when the clock is initialized by 69 * __clk_init. This callback is mandatory for clocks with 70 * multiple parents. It is optional (and unnecessary) for clocks 71 * with 0 or 1 parents. 72 * 73 * @set_parent: Change the input source of this clock; for clocks with multiple 74 * possible parents specify a new parent by passing in the index 75 * as a u8 corresponding to the parent in either the .parent_names 76 * or .parents arrays. This function in affect translates an 77 * array index into the value programmed into the hardware. 78 * Returns 0 on success, -EERROR otherwise. 79 * 80 * @set_rate: Change the rate of this clock. The requested rate is specified 81 * by the second argument, which should typically be the return 82 * of .round_rate call. The third argument gives the parent rate 83 * which is likely helpful for most .set_rate implementation. 84 * Returns 0 on success, -EERROR otherwise. 85 * 86 * The clk_enable/clk_disable and clk_prepare/clk_unprepare pairs allow 87 * implementations to split any work between atomic (enable) and sleepable 88 * (prepare) contexts. If enabling a clock requires code that might sleep, 89 * this must be done in clk_prepare. Clock enable code that will never be 90 * called in a sleepable context may be implement in clk_enable. 91 * 92 * Typically, drivers will call clk_prepare when a clock may be needed later 93 * (eg. when a device is opened), and clk_enable when the clock is actually 94 * required (eg. from an interrupt). Note that clk_prepare MUST have been 95 * called before clk_enable. 96 */ 97 struct clk_ops { 98 int (*prepare)(struct clk_hw *hw); 99 void (*unprepare)(struct clk_hw *hw); 100 int (*enable)(struct clk_hw *hw); 101 void (*disable)(struct clk_hw *hw); 102 int (*is_enabled)(struct clk_hw *hw); 103 unsigned long (*recalc_rate)(struct clk_hw *hw, 104 unsigned long parent_rate); 105 long (*round_rate)(struct clk_hw *hw, unsigned long, 106 unsigned long *); 107 int (*set_parent)(struct clk_hw *hw, u8 index); 108 u8 (*get_parent)(struct clk_hw *hw); 109 int (*set_rate)(struct clk_hw *hw, unsigned long, 110 unsigned long); 111 void (*init)(struct clk_hw *hw); 112 }; 113 114 /** 115 * struct clk_init_data - holds init data that's common to all clocks and is 116 * shared between the clock provider and the common clock framework. 117 * 118 * @name: clock name 119 * @ops: operations this clock supports 120 * @parent_names: array of string names for all possible parents 121 * @num_parents: number of possible parents 122 * @flags: framework-level hints and quirks 123 */ 124 struct clk_init_data { 125 const char *name; 126 const struct clk_ops *ops; 127 const char **parent_names; 128 u8 num_parents; 129 unsigned long flags; 130 }; 131 132 /** 133 * struct clk_hw - handle for traversing from a struct clk to its corresponding 134 * hardware-specific structure. struct clk_hw should be declared within struct 135 * clk_foo and then referenced by the struct clk instance that uses struct 136 * clk_foo's clk_ops 137 * 138 * @clk: pointer to the struct clk instance that points back to this struct 139 * clk_hw instance 140 * 141 * @init: pointer to struct clk_init_data that contains the init data shared 142 * with the common clock framework. 143 */ 144 struct clk_hw { 145 struct clk *clk; 146 struct clk_init_data *init; 147 }; 148 149 /* 150 * DOC: Basic clock implementations common to many platforms 151 * 152 * Each basic clock hardware type is comprised of a structure describing the 153 * clock hardware, implementations of the relevant callbacks in struct clk_ops, 154 * unique flags for that hardware type, a registration function and an 155 * alternative macro for static initialization 156 */ 157 158 /** 159 * struct clk_fixed_rate - fixed-rate clock 160 * @hw: handle between common and hardware-specific interfaces 161 * @fixed_rate: constant frequency of clock 162 */ 163 struct clk_fixed_rate { 164 struct clk_hw hw; 165 unsigned long fixed_rate; 166 u8 flags; 167 }; 168 169 extern const struct clk_ops clk_fixed_rate_ops; 170 struct clk *clk_register_fixed_rate(struct device *dev, const char *name, 171 const char *parent_name, unsigned long flags, 172 unsigned long fixed_rate); 173 174 /** 175 * struct clk_gate - gating clock 176 * 177 * @hw: handle between common and hardware-specific interfaces 178 * @reg: register controlling gate 179 * @bit_idx: single bit controlling gate 180 * @flags: hardware-specific flags 181 * @lock: register lock 182 * 183 * Clock which can gate its output. Implements .enable & .disable 184 * 185 * Flags: 186 * CLK_GATE_SET_TO_DISABLE - by default this clock sets the bit at bit_idx to 187 * enable the clock. Setting this flag does the opposite: setting the bit 188 * disable the clock and clearing it enables the clock 189 */ 190 struct clk_gate { 191 struct clk_hw hw; 192 void __iomem *reg; 193 u8 bit_idx; 194 u8 flags; 195 spinlock_t *lock; 196 }; 197 198 #define CLK_GATE_SET_TO_DISABLE BIT(0) 199 200 extern const struct clk_ops clk_gate_ops; 201 struct clk *clk_register_gate(struct device *dev, const char *name, 202 const char *parent_name, unsigned long flags, 203 void __iomem *reg, u8 bit_idx, 204 u8 clk_gate_flags, spinlock_t *lock); 205 206 /** 207 * struct clk_divider - adjustable divider clock 208 * 209 * @hw: handle between common and hardware-specific interfaces 210 * @reg: register containing the divider 211 * @shift: shift to the divider bit field 212 * @width: width of the divider bit field 213 * @lock: register lock 214 * 215 * Clock with an adjustable divider affecting its output frequency. Implements 216 * .recalc_rate, .set_rate and .round_rate 217 * 218 * Flags: 219 * CLK_DIVIDER_ONE_BASED - by default the divisor is the value read from the 220 * register plus one. If CLK_DIVIDER_ONE_BASED is set then the divider is 221 * the raw value read from the register, with the value of zero considered 222 * invalid 223 * CLK_DIVIDER_POWER_OF_TWO - clock divisor is 2 raised to the value read from 224 * the hardware register 225 */ 226 struct clk_divider { 227 struct clk_hw hw; 228 void __iomem *reg; 229 u8 shift; 230 u8 width; 231 u8 flags; 232 spinlock_t *lock; 233 }; 234 235 #define CLK_DIVIDER_ONE_BASED BIT(0) 236 #define CLK_DIVIDER_POWER_OF_TWO BIT(1) 237 238 extern const struct clk_ops clk_divider_ops; 239 struct clk *clk_register_divider(struct device *dev, const char *name, 240 const char *parent_name, unsigned long flags, 241 void __iomem *reg, u8 shift, u8 width, 242 u8 clk_divider_flags, spinlock_t *lock); 243 244 /** 245 * struct clk_mux - multiplexer clock 246 * 247 * @hw: handle between common and hardware-specific interfaces 248 * @reg: register controlling multiplexer 249 * @shift: shift to multiplexer bit field 250 * @width: width of mutliplexer bit field 251 * @num_clks: number of parent clocks 252 * @lock: register lock 253 * 254 * Clock with multiple selectable parents. Implements .get_parent, .set_parent 255 * and .recalc_rate 256 * 257 * Flags: 258 * CLK_MUX_INDEX_ONE - register index starts at 1, not 0 259 * CLK_MUX_INDEX_BIT - register index is a single bit (power of two) 260 */ 261 struct clk_mux { 262 struct clk_hw hw; 263 void __iomem *reg; 264 u8 shift; 265 u8 width; 266 u8 flags; 267 spinlock_t *lock; 268 }; 269 270 #define CLK_MUX_INDEX_ONE BIT(0) 271 #define CLK_MUX_INDEX_BIT BIT(1) 272 273 extern const struct clk_ops clk_mux_ops; 274 struct clk *clk_register_mux(struct device *dev, const char *name, 275 const char **parent_names, u8 num_parents, unsigned long flags, 276 void __iomem *reg, u8 shift, u8 width, 277 u8 clk_mux_flags, spinlock_t *lock); 278 279 /** 280 * struct clk_fixed_factor - fixed multiplier and divider clock 281 * 282 * @hw: handle between common and hardware-specific interfaces 283 * @mult: multiplier 284 * @div: divider 285 * 286 * Clock with a fixed multiplier and divider. The output frequency is the 287 * parent clock rate divided by div and multiplied by mult. 288 * Implements .recalc_rate, .set_rate and .round_rate 289 */ 290 291 struct clk_fixed_factor { 292 struct clk_hw hw; 293 unsigned int mult; 294 unsigned int div; 295 }; 296 297 extern struct clk_ops clk_fixed_factor_ops; 298 struct clk *clk_register_fixed_factor(struct device *dev, const char *name, 299 const char *parent_name, unsigned long flags, 300 unsigned int mult, unsigned int div); 301 302 /** 303 * clk_register - allocate a new clock, register it and return an opaque cookie 304 * @dev: device that is registering this clock 305 * @hw: link to hardware-specific clock data 306 * 307 * clk_register is the primary interface for populating the clock tree with new 308 * clock nodes. It returns a pointer to the newly allocated struct clk which 309 * cannot be dereferenced by driver code but may be used in conjuction with the 310 * rest of the clock API. In the event of an error clk_register will return an 311 * error code; drivers must test for an error code after calling clk_register. 312 */ 313 struct clk *clk_register(struct device *dev, struct clk_hw *hw); 314 315 void clk_unregister(struct clk *clk); 316 317 /* helper functions */ 318 const char *__clk_get_name(struct clk *clk); 319 struct clk_hw *__clk_get_hw(struct clk *clk); 320 u8 __clk_get_num_parents(struct clk *clk); 321 struct clk *__clk_get_parent(struct clk *clk); 322 inline int __clk_get_enable_count(struct clk *clk); 323 inline int __clk_get_prepare_count(struct clk *clk); 324 unsigned long __clk_get_rate(struct clk *clk); 325 unsigned long __clk_get_flags(struct clk *clk); 326 int __clk_is_enabled(struct clk *clk); 327 struct clk *__clk_lookup(const char *name); 328 329 /* 330 * FIXME clock api without lock protection 331 */ 332 int __clk_prepare(struct clk *clk); 333 void __clk_unprepare(struct clk *clk); 334 void __clk_reparent(struct clk *clk, struct clk *new_parent); 335 unsigned long __clk_round_rate(struct clk *clk, unsigned long rate); 336 337 #endif /* CONFIG_COMMON_CLK */ 338 #endif /* CLK_PROVIDER_H */ 339