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