clk-provider.h revision dc4cd941c900fda27f0146ab615122426229de73
1/* 2 * linux/include/linux/clk-provider.h 3 * 4 * Copyright (c) 2010-2011 Jeremy Kerr <jeremy.kerr@canonical.com> 5 * Copyright (C) 2011-2012 Linaro Ltd <mturquette@linaro.org> 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 30struct 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 */ 98struct 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 */ 125struct 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 */ 145struct 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 */ 164struct clk_fixed_rate { 165 struct clk_hw hw; 166 unsigned long fixed_rate; 167 u8 flags; 168}; 169 170extern const struct clk_ops clk_fixed_rate_ops; 171struct 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/** 176 * struct clk_gate - gating clock 177 * 178 * @hw: handle between common and hardware-specific interfaces 179 * @reg: register controlling gate 180 * @bit_idx: single bit controlling gate 181 * @flags: hardware-specific flags 182 * @lock: register lock 183 * 184 * Clock which can gate its output. Implements .enable & .disable 185 * 186 * Flags: 187 * CLK_GATE_SET_TO_DISABLE - by default this clock sets the bit at bit_idx to 188 * enable the clock. Setting this flag does the opposite: setting the bit 189 * disable the clock and clearing it enables the clock 190 */ 191struct clk_gate { 192 struct clk_hw hw; 193 void __iomem *reg; 194 u8 bit_idx; 195 u8 flags; 196 spinlock_t *lock; 197}; 198 199#define CLK_GATE_SET_TO_DISABLE BIT(0) 200 201extern const struct clk_ops clk_gate_ops; 202struct clk *clk_register_gate(struct device *dev, const char *name, 203 const char *parent_name, unsigned long flags, 204 void __iomem *reg, u8 bit_idx, 205 u8 clk_gate_flags, spinlock_t *lock); 206 207struct clk_div_table { 208 unsigned int val; 209 unsigned int div; 210}; 211 212/** 213 * struct clk_divider - adjustable divider clock 214 * 215 * @hw: handle between common and hardware-specific interfaces 216 * @reg: register containing the divider 217 * @shift: shift to the divider bit field 218 * @width: width of the divider bit field 219 * @table: array of value/divider pairs, last entry should have div = 0 220 * @lock: register lock 221 * 222 * Clock with an adjustable divider affecting its output frequency. Implements 223 * .recalc_rate, .set_rate and .round_rate 224 * 225 * Flags: 226 * CLK_DIVIDER_ONE_BASED - by default the divisor is the value read from the 227 * register plus one. If CLK_DIVIDER_ONE_BASED is set then the divider is 228 * the raw value read from the register, with the value of zero considered 229 * invalid 230 * CLK_DIVIDER_POWER_OF_TWO - clock divisor is 2 raised to the value read from 231 * the hardware register 232 */ 233struct clk_divider { 234 struct clk_hw hw; 235 void __iomem *reg; 236 u8 shift; 237 u8 width; 238 u8 flags; 239 const struct clk_div_table *table; 240 spinlock_t *lock; 241}; 242 243#define CLK_DIVIDER_ONE_BASED BIT(0) 244#define CLK_DIVIDER_POWER_OF_TWO BIT(1) 245 246extern const struct clk_ops clk_divider_ops; 247struct clk *clk_register_divider(struct device *dev, const char *name, 248 const char *parent_name, unsigned long flags, 249 void __iomem *reg, u8 shift, u8 width, 250 u8 clk_divider_flags, spinlock_t *lock); 251struct clk *clk_register_divider_table(struct device *dev, const char *name, 252 const char *parent_name, unsigned long flags, 253 void __iomem *reg, u8 shift, u8 width, 254 u8 clk_divider_flags, const struct clk_div_table *table, 255 spinlock_t *lock); 256 257/** 258 * struct clk_mux - multiplexer clock 259 * 260 * @hw: handle between common and hardware-specific interfaces 261 * @reg: register controlling multiplexer 262 * @shift: shift to multiplexer bit field 263 * @width: width of mutliplexer bit field 264 * @num_clks: number of parent clocks 265 * @lock: register lock 266 * 267 * Clock with multiple selectable parents. Implements .get_parent, .set_parent 268 * and .recalc_rate 269 * 270 * Flags: 271 * CLK_MUX_INDEX_ONE - register index starts at 1, not 0 272 * CLK_MUX_INDEX_BIT - register index is a single bit (power of two) 273 */ 274struct clk_mux { 275 struct clk_hw hw; 276 void __iomem *reg; 277 u8 shift; 278 u8 width; 279 u8 flags; 280 spinlock_t *lock; 281}; 282 283#define CLK_MUX_INDEX_ONE BIT(0) 284#define CLK_MUX_INDEX_BIT BIT(1) 285 286extern const struct clk_ops clk_mux_ops; 287struct clk *clk_register_mux(struct device *dev, const char *name, 288 const char **parent_names, u8 num_parents, unsigned long flags, 289 void __iomem *reg, u8 shift, u8 width, 290 u8 clk_mux_flags, spinlock_t *lock); 291 292/** 293 * struct clk_fixed_factor - fixed multiplier and divider clock 294 * 295 * @hw: handle between common and hardware-specific interfaces 296 * @mult: multiplier 297 * @div: divider 298 * 299 * Clock with a fixed multiplier and divider. The output frequency is the 300 * parent clock rate divided by div and multiplied by mult. 301 * Implements .recalc_rate, .set_rate and .round_rate 302 */ 303 304struct clk_fixed_factor { 305 struct clk_hw hw; 306 unsigned int mult; 307 unsigned int div; 308}; 309 310extern struct clk_ops clk_fixed_factor_ops; 311struct clk *clk_register_fixed_factor(struct device *dev, const char *name, 312 const char *parent_name, unsigned long flags, 313 unsigned int mult, unsigned int div); 314 315/** 316 * clk_register - allocate a new clock, register it and return an opaque cookie 317 * @dev: device that is registering this clock 318 * @hw: link to hardware-specific clock data 319 * 320 * clk_register is the primary interface for populating the clock tree with new 321 * clock nodes. It returns a pointer to the newly allocated struct clk which 322 * cannot be dereferenced by driver code but may be used in conjuction with the 323 * rest of the clock API. In the event of an error clk_register will return an 324 * error code; drivers must test for an error code after calling clk_register. 325 */ 326struct clk *clk_register(struct device *dev, struct clk_hw *hw); 327 328void clk_unregister(struct clk *clk); 329 330/* helper functions */ 331const char *__clk_get_name(struct clk *clk); 332struct clk_hw *__clk_get_hw(struct clk *clk); 333u8 __clk_get_num_parents(struct clk *clk); 334struct clk *__clk_get_parent(struct clk *clk); 335inline int __clk_get_enable_count(struct clk *clk); 336inline int __clk_get_prepare_count(struct clk *clk); 337unsigned long __clk_get_rate(struct clk *clk); 338unsigned long __clk_get_flags(struct clk *clk); 339int __clk_is_enabled(struct clk *clk); 340struct clk *__clk_lookup(const char *name); 341 342/* 343 * FIXME clock api without lock protection 344 */ 345int __clk_prepare(struct clk *clk); 346void __clk_unprepare(struct clk *clk); 347void __clk_reparent(struct clk *clk, struct clk *new_parent); 348unsigned long __clk_round_rate(struct clk *clk, unsigned long rate); 349 350#endif /* CONFIG_COMMON_CLK */ 351#endif /* CLK_PROVIDER_H */ 352