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