1 /* 2 * linux/include/linux/clk.h 3 * 4 * Copyright (C) 2004 ARM Limited. 5 * Written by Deep Blue Solutions Limited. 6 * Copyright (C) 2011-2012 Linaro Ltd <[email protected]> 7 * 8 * This program is free software; you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License version 2 as 10 * published by the Free Software Foundation. 11 */ 12 #ifndef __LINUX_CLK_H 13 #define __LINUX_CLK_H 14 15 #include <linux/err.h> 16 #include <linux/kernel.h> 17 #include <linux/notifier.h> 18 19 struct device; 20 21 struct clk; 22 23 #ifdef CONFIG_COMMON_CLK 24 25 /** 26 * DOC: clk notifier callback types 27 * 28 * PRE_RATE_CHANGE - called immediately before the clk rate is changed, 29 * to indicate that the rate change will proceed. Drivers must 30 * immediately terminate any operations that will be affected by the 31 * rate change. Callbacks may either return NOTIFY_DONE, NOTIFY_OK, 32 * NOTIFY_STOP or NOTIFY_BAD. 33 * 34 * ABORT_RATE_CHANGE: called if the rate change failed for some reason 35 * after PRE_RATE_CHANGE. In this case, all registered notifiers on 36 * the clk will be called with ABORT_RATE_CHANGE. Callbacks must 37 * always return NOTIFY_DONE or NOTIFY_OK. 38 * 39 * POST_RATE_CHANGE - called after the clk rate change has successfully 40 * completed. Callbacks must always return NOTIFY_DONE or NOTIFY_OK. 41 * 42 */ 43 #define PRE_RATE_CHANGE BIT(0) 44 #define POST_RATE_CHANGE BIT(1) 45 #define ABORT_RATE_CHANGE BIT(2) 46 47 /** 48 * struct clk_notifier - associate a clk with a notifier 49 * @clk: struct clk * to associate the notifier with 50 * @notifier_head: a blocking_notifier_head for this clk 51 * @node: linked list pointers 52 * 53 * A list of struct clk_notifier is maintained by the notifier code. 54 * An entry is created whenever code registers the first notifier on a 55 * particular @clk. Future notifiers on that @clk are added to the 56 * @notifier_head. 57 */ 58 struct clk_notifier { 59 struct clk *clk; 60 struct srcu_notifier_head notifier_head; 61 struct list_head node; 62 }; 63 64 /** 65 * struct clk_notifier_data - rate data to pass to the notifier callback 66 * @clk: struct clk * being changed 67 * @old_rate: previous rate of this clk 68 * @new_rate: new rate of this clk 69 * 70 * For a pre-notifier, old_rate is the clk's rate before this rate 71 * change, and new_rate is what the rate will be in the future. For a 72 * post-notifier, old_rate and new_rate are both set to the clk's 73 * current rate (this was done to optimize the implementation). 74 */ 75 struct clk_notifier_data { 76 struct clk *clk; 77 unsigned long old_rate; 78 unsigned long new_rate; 79 }; 80 81 int clk_notifier_register(struct clk *clk, struct notifier_block *nb); 82 83 int clk_notifier_unregister(struct clk *clk, struct notifier_block *nb); 84 85 /** 86 * clk_get_accuracy - obtain the clock accuracy in ppb (parts per billion) 87 * for a clock source. 88 * @clk: clock source 89 * 90 * This gets the clock source accuracy expressed in ppb. 91 * A perfect clock returns 0. 92 */ 93 long clk_get_accuracy(struct clk *clk); 94 95 #else 96 97 static inline long clk_get_accuracy(struct clk *clk) 98 { 99 return -ENOTSUPP; 100 } 101 102 #endif 103 104 /** 105 * clk_prepare - prepare a clock source 106 * @clk: clock source 107 * 108 * This prepares the clock source for use. 109 * 110 * Must not be called from within atomic context. 111 */ 112 #ifdef CONFIG_HAVE_CLK_PREPARE 113 int clk_prepare(struct clk *clk); 114 #else 115 static inline int clk_prepare(struct clk *clk) 116 { 117 might_sleep(); 118 return 0; 119 } 120 #endif 121 122 /** 123 * clk_unprepare - undo preparation of a clock source 124 * @clk: clock source 125 * 126 * This undoes a previously prepared clock. The caller must balance 127 * the number of prepare and unprepare calls. 128 * 129 * Must not be called from within atomic context. 130 */ 131 #ifdef CONFIG_HAVE_CLK_PREPARE 132 void clk_unprepare(struct clk *clk); 133 #else 134 static inline void clk_unprepare(struct clk *clk) 135 { 136 might_sleep(); 137 } 138 #endif 139 140 #ifdef CONFIG_HAVE_CLK 141 /** 142 * clk_get - lookup and obtain a reference to a clock producer. 143 * @dev: device for clock "consumer" 144 * @id: clock consumer ID 145 * 146 * Returns a struct clk corresponding to the clock producer, or 147 * valid IS_ERR() condition containing errno. The implementation 148 * uses @dev and @id to determine the clock consumer, and thereby 149 * the clock producer. (IOW, @id may be identical strings, but 150 * clk_get may return different clock producers depending on @dev.) 151 * 152 * Drivers must assume that the clock source is not enabled. 153 * 154 * clk_get should not be called from within interrupt context. 155 */ 156 struct clk *clk_get(struct device *dev, const char *id); 157 158 /** 159 * devm_clk_get - lookup and obtain a managed reference to a clock producer. 160 * @dev: device for clock "consumer" 161 * @id: clock consumer ID 162 * 163 * Returns a struct clk corresponding to the clock producer, or 164 * valid IS_ERR() condition containing errno. The implementation 165 * uses @dev and @id to determine the clock consumer, and thereby 166 * the clock producer. (IOW, @id may be identical strings, but 167 * clk_get may return different clock producers depending on @dev.) 168 * 169 * Drivers must assume that the clock source is not enabled. 170 * 171 * devm_clk_get should not be called from within interrupt context. 172 * 173 * The clock will automatically be freed when the device is unbound 174 * from the bus. 175 */ 176 struct clk *devm_clk_get(struct device *dev, const char *id); 177 178 /** 179 * clk_enable - inform the system when the clock source should be running. 180 * @clk: clock source 181 * 182 * If the clock can not be enabled/disabled, this should return success. 183 * 184 * May be called from atomic contexts. 185 * 186 * Returns success (0) or negative errno. 187 */ 188 int clk_enable(struct clk *clk); 189 190 /** 191 * clk_disable - inform the system when the clock source is no longer required. 192 * @clk: clock source 193 * 194 * Inform the system that a clock source is no longer required by 195 * a driver and may be shut down. 196 * 197 * May be called from atomic contexts. 198 * 199 * Implementation detail: if the clock source is shared between 200 * multiple drivers, clk_enable() calls must be balanced by the 201 * same number of clk_disable() calls for the clock source to be 202 * disabled. 203 */ 204 void clk_disable(struct clk *clk); 205 206 /** 207 * clk_get_rate - obtain the current clock rate (in Hz) for a clock source. 208 * This is only valid once the clock source has been enabled. 209 * @clk: clock source 210 */ 211 unsigned long clk_get_rate(struct clk *clk); 212 213 /** 214 * clk_put - "free" the clock source 215 * @clk: clock source 216 * 217 * Note: drivers must ensure that all clk_enable calls made on this 218 * clock source are balanced by clk_disable calls prior to calling 219 * this function. 220 * 221 * clk_put should not be called from within interrupt context. 222 */ 223 void clk_put(struct clk *clk); 224 225 /** 226 * devm_clk_put - "free" a managed clock source 227 * @dev: device used to acuqire the clock 228 * @clk: clock source acquired with devm_clk_get() 229 * 230 * Note: drivers must ensure that all clk_enable calls made on this 231 * clock source are balanced by clk_disable calls prior to calling 232 * this function. 233 * 234 * clk_put should not be called from within interrupt context. 235 */ 236 void devm_clk_put(struct device *dev, struct clk *clk); 237 238 /* 239 * The remaining APIs are optional for machine class support. 240 */ 241 242 243 /** 244 * clk_round_rate - adjust a rate to the exact rate a clock can provide 245 * @clk: clock source 246 * @rate: desired clock rate in Hz 247 * 248 * Returns rounded clock rate in Hz, or negative errno. 249 */ 250 long clk_round_rate(struct clk *clk, unsigned long rate); 251 252 /** 253 * clk_set_rate - set the clock rate for a clock source 254 * @clk: clock source 255 * @rate: desired clock rate in Hz 256 * 257 * Returns success (0) or negative errno. 258 */ 259 int clk_set_rate(struct clk *clk, unsigned long rate); 260 261 /** 262 * clk_set_parent - set the parent clock source for this clock 263 * @clk: clock source 264 * @parent: parent clock source 265 * 266 * Returns success (0) or negative errno. 267 */ 268 int clk_set_parent(struct clk *clk, struct clk *parent); 269 270 /** 271 * clk_get_parent - get the parent clock source for this clock 272 * @clk: clock source 273 * 274 * Returns struct clk corresponding to parent clock source, or 275 * valid IS_ERR() condition containing errno. 276 */ 277 struct clk *clk_get_parent(struct clk *clk); 278 279 /** 280 * clk_get_sys - get a clock based upon the device name 281 * @dev_id: device name 282 * @con_id: connection ID 283 * 284 * Returns a struct clk corresponding to the clock producer, or 285 * valid IS_ERR() condition containing errno. The implementation 286 * uses @dev_id and @con_id to determine the clock consumer, and 287 * thereby the clock producer. In contrast to clk_get() this function 288 * takes the device name instead of the device itself for identification. 289 * 290 * Drivers must assume that the clock source is not enabled. 291 * 292 * clk_get_sys should not be called from within interrupt context. 293 */ 294 struct clk *clk_get_sys(const char *dev_id, const char *con_id); 295 296 #else /* !CONFIG_HAVE_CLK */ 297 298 static inline struct clk *clk_get(struct device *dev, const char *id) 299 { 300 return NULL; 301 } 302 303 static inline struct clk *devm_clk_get(struct device *dev, const char *id) 304 { 305 return NULL; 306 } 307 308 static inline void clk_put(struct clk *clk) {} 309 310 static inline void devm_clk_put(struct device *dev, struct clk *clk) {} 311 312 static inline int clk_enable(struct clk *clk) 313 { 314 return 0; 315 } 316 317 static inline void clk_disable(struct clk *clk) {} 318 319 static inline unsigned long clk_get_rate(struct clk *clk) 320 { 321 return 0; 322 } 323 324 static inline int clk_set_rate(struct clk *clk, unsigned long rate) 325 { 326 return 0; 327 } 328 329 static inline long clk_round_rate(struct clk *clk, unsigned long rate) 330 { 331 return 0; 332 } 333 334 static inline int clk_set_parent(struct clk *clk, struct clk *parent) 335 { 336 return 0; 337 } 338 339 static inline struct clk *clk_get_parent(struct clk *clk) 340 { 341 return NULL; 342 } 343 344 #endif 345 346 /* clk_prepare_enable helps cases using clk_enable in non-atomic context. */ 347 static inline int clk_prepare_enable(struct clk *clk) 348 { 349 int ret; 350 351 ret = clk_prepare(clk); 352 if (ret) 353 return ret; 354 ret = clk_enable(clk); 355 if (ret) 356 clk_unprepare(clk); 357 358 return ret; 359 } 360 361 /* clk_disable_unprepare helps cases using clk_disable in non-atomic context. */ 362 static inline void clk_disable_unprepare(struct clk *clk) 363 { 364 clk_disable(clk); 365 clk_unprepare(clk); 366 } 367 368 /** 369 * clk_add_alias - add a new clock alias 370 * @alias: name for clock alias 371 * @alias_dev_name: device name 372 * @id: platform specific clock name 373 * @dev: device 374 * 375 * Allows using generic clock names for drivers by adding a new alias. 376 * Assumes clkdev, see clkdev.h for more info. 377 */ 378 int clk_add_alias(const char *alias, const char *alias_dev_name, char *id, 379 struct device *dev); 380 381 struct device_node; 382 struct of_phandle_args; 383 384 #if defined(CONFIG_OF) && defined(CONFIG_COMMON_CLK) 385 struct clk *of_clk_get(struct device_node *np, int index); 386 struct clk *of_clk_get_by_name(struct device_node *np, const char *name); 387 struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec); 388 #else 389 static inline struct clk *of_clk_get(struct device_node *np, int index) 390 { 391 return ERR_PTR(-ENOENT); 392 } 393 static inline struct clk *of_clk_get_by_name(struct device_node *np, 394 const char *name) 395 { 396 return ERR_PTR(-ENOENT); 397 } 398 #endif 399 400 #endif 401