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 <mturquette@linaro.org> 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 19struct device; 20 21struct 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 */ 58struct 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 */ 75struct clk_notifier_data { 76 struct clk *clk; 77 unsigned long old_rate; 78 unsigned long new_rate; 79}; 80 81/** 82 * clk_notifier_register: register a clock rate-change notifier callback 83 * @clk: clock whose rate we are interested in 84 * @nb: notifier block with callback function pointer 85 * 86 * ProTip: debugging across notifier chains can be frustrating. Make sure that 87 * your notifier callback function prints a nice big warning in case of 88 * failure. 89 */ 90int clk_notifier_register(struct clk *clk, struct notifier_block *nb); 91 92/** 93 * clk_notifier_unregister: unregister a clock rate-change notifier callback 94 * @clk: clock whose rate we are no longer interested in 95 * @nb: notifier block which will be unregistered 96 */ 97int clk_notifier_unregister(struct clk *clk, struct notifier_block *nb); 98 99/** 100 * clk_get_accuracy - obtain the clock accuracy in ppb (parts per billion) 101 * for a clock source. 102 * @clk: clock source 103 * 104 * This gets the clock source accuracy expressed in ppb. 105 * A perfect clock returns 0. 106 */ 107long clk_get_accuracy(struct clk *clk); 108 109/** 110 * clk_set_phase - adjust the phase shift of a clock signal 111 * @clk: clock signal source 112 * @degrees: number of degrees the signal is shifted 113 * 114 * Shifts the phase of a clock signal by the specified degrees. Returns 0 on 115 * success, -EERROR otherwise. 116 */ 117int clk_set_phase(struct clk *clk, int degrees); 118 119/** 120 * clk_get_phase - return the phase shift of a clock signal 121 * @clk: clock signal source 122 * 123 * Returns the phase shift of a clock node in degrees, otherwise returns 124 * -EERROR. 125 */ 126int clk_get_phase(struct clk *clk); 127 128#else 129 130static inline long clk_get_accuracy(struct clk *clk) 131{ 132 return -ENOTSUPP; 133} 134 135static inline long clk_set_phase(struct clk *clk, int phase) 136{ 137 return -ENOTSUPP; 138} 139 140static inline long clk_get_phase(struct clk *clk) 141{ 142 return -ENOTSUPP; 143} 144 145#endif 146 147/** 148 * clk_prepare - prepare a clock source 149 * @clk: clock source 150 * 151 * This prepares the clock source for use. 152 * 153 * Must not be called from within atomic context. 154 */ 155#ifdef CONFIG_HAVE_CLK_PREPARE 156int clk_prepare(struct clk *clk); 157#else 158static inline int clk_prepare(struct clk *clk) 159{ 160 might_sleep(); 161 return 0; 162} 163#endif 164 165/** 166 * clk_unprepare - undo preparation of a clock source 167 * @clk: clock source 168 * 169 * This undoes a previously prepared clock. The caller must balance 170 * the number of prepare and unprepare calls. 171 * 172 * Must not be called from within atomic context. 173 */ 174#ifdef CONFIG_HAVE_CLK_PREPARE 175void clk_unprepare(struct clk *clk); 176#else 177static inline void clk_unprepare(struct clk *clk) 178{ 179 might_sleep(); 180} 181#endif 182 183#ifdef CONFIG_HAVE_CLK 184/** 185 * clk_get - lookup and obtain a reference to a clock producer. 186 * @dev: device for clock "consumer" 187 * @id: clock consumer ID 188 * 189 * Returns a struct clk corresponding to the clock producer, or 190 * valid IS_ERR() condition containing errno. The implementation 191 * uses @dev and @id to determine the clock consumer, and thereby 192 * the clock producer. (IOW, @id may be identical strings, but 193 * clk_get may return different clock producers depending on @dev.) 194 * 195 * Drivers must assume that the clock source is not enabled. 196 * 197 * clk_get should not be called from within interrupt context. 198 */ 199struct clk *clk_get(struct device *dev, const char *id); 200 201/** 202 * devm_clk_get - lookup and obtain a managed reference to a clock producer. 203 * @dev: device for clock "consumer" 204 * @id: clock consumer ID 205 * 206 * Returns a struct clk corresponding to the clock producer, or 207 * valid IS_ERR() condition containing errno. The implementation 208 * uses @dev and @id to determine the clock consumer, and thereby 209 * the clock producer. (IOW, @id may be identical strings, but 210 * clk_get may return different clock producers depending on @dev.) 211 * 212 * Drivers must assume that the clock source is not enabled. 213 * 214 * devm_clk_get should not be called from within interrupt context. 215 * 216 * The clock will automatically be freed when the device is unbound 217 * from the bus. 218 */ 219struct clk *devm_clk_get(struct device *dev, const char *id); 220 221/** 222 * clk_enable - inform the system when the clock source should be running. 223 * @clk: clock source 224 * 225 * If the clock can not be enabled/disabled, this should return success. 226 * 227 * May be called from atomic contexts. 228 * 229 * Returns success (0) or negative errno. 230 */ 231int clk_enable(struct clk *clk); 232 233/** 234 * clk_disable - inform the system when the clock source is no longer required. 235 * @clk: clock source 236 * 237 * Inform the system that a clock source is no longer required by 238 * a driver and may be shut down. 239 * 240 * May be called from atomic contexts. 241 * 242 * Implementation detail: if the clock source is shared between 243 * multiple drivers, clk_enable() calls must be balanced by the 244 * same number of clk_disable() calls for the clock source to be 245 * disabled. 246 */ 247void clk_disable(struct clk *clk); 248 249/** 250 * clk_get_rate - obtain the current clock rate (in Hz) for a clock source. 251 * This is only valid once the clock source has been enabled. 252 * @clk: clock source 253 */ 254unsigned long clk_get_rate(struct clk *clk); 255 256/** 257 * clk_put - "free" the clock source 258 * @clk: clock source 259 * 260 * Note: drivers must ensure that all clk_enable calls made on this 261 * clock source are balanced by clk_disable calls prior to calling 262 * this function. 263 * 264 * clk_put should not be called from within interrupt context. 265 */ 266void clk_put(struct clk *clk); 267 268/** 269 * devm_clk_put - "free" a managed clock source 270 * @dev: device used to acquire the clock 271 * @clk: clock source acquired with devm_clk_get() 272 * 273 * Note: drivers must ensure that all clk_enable calls made on this 274 * clock source are balanced by clk_disable calls prior to calling 275 * this function. 276 * 277 * clk_put should not be called from within interrupt context. 278 */ 279void devm_clk_put(struct device *dev, struct clk *clk); 280 281/* 282 * The remaining APIs are optional for machine class support. 283 */ 284 285 286/** 287 * clk_round_rate - adjust a rate to the exact rate a clock can provide 288 * @clk: clock source 289 * @rate: desired clock rate in Hz 290 * 291 * Returns rounded clock rate in Hz, or negative errno. 292 */ 293long clk_round_rate(struct clk *clk, unsigned long rate); 294 295/** 296 * clk_set_rate - set the clock rate for a clock source 297 * @clk: clock source 298 * @rate: desired clock rate in Hz 299 * 300 * Returns success (0) or negative errno. 301 */ 302int clk_set_rate(struct clk *clk, unsigned long rate); 303 304/** 305 * clk_set_parent - set the parent clock source for this clock 306 * @clk: clock source 307 * @parent: parent clock source 308 * 309 * Returns success (0) or negative errno. 310 */ 311int clk_set_parent(struct clk *clk, struct clk *parent); 312 313/** 314 * clk_get_parent - get the parent clock source for this clock 315 * @clk: clock source 316 * 317 * Returns struct clk corresponding to parent clock source, or 318 * valid IS_ERR() condition containing errno. 319 */ 320struct clk *clk_get_parent(struct clk *clk); 321 322/** 323 * clk_get_sys - get a clock based upon the device name 324 * @dev_id: device name 325 * @con_id: connection ID 326 * 327 * Returns a struct clk corresponding to the clock producer, or 328 * valid IS_ERR() condition containing errno. The implementation 329 * uses @dev_id and @con_id to determine the clock consumer, and 330 * thereby the clock producer. In contrast to clk_get() this function 331 * takes the device name instead of the device itself for identification. 332 * 333 * Drivers must assume that the clock source is not enabled. 334 * 335 * clk_get_sys should not be called from within interrupt context. 336 */ 337struct clk *clk_get_sys(const char *dev_id, const char *con_id); 338 339#else /* !CONFIG_HAVE_CLK */ 340 341static inline struct clk *clk_get(struct device *dev, const char *id) 342{ 343 return NULL; 344} 345 346static inline struct clk *devm_clk_get(struct device *dev, const char *id) 347{ 348 return NULL; 349} 350 351static inline void clk_put(struct clk *clk) {} 352 353static inline void devm_clk_put(struct device *dev, struct clk *clk) {} 354 355static inline int clk_enable(struct clk *clk) 356{ 357 return 0; 358} 359 360static inline void clk_disable(struct clk *clk) {} 361 362static inline unsigned long clk_get_rate(struct clk *clk) 363{ 364 return 0; 365} 366 367static inline int clk_set_rate(struct clk *clk, unsigned long rate) 368{ 369 return 0; 370} 371 372static inline long clk_round_rate(struct clk *clk, unsigned long rate) 373{ 374 return 0; 375} 376 377static inline int clk_set_parent(struct clk *clk, struct clk *parent) 378{ 379 return 0; 380} 381 382static inline struct clk *clk_get_parent(struct clk *clk) 383{ 384 return NULL; 385} 386 387#endif 388 389/* clk_prepare_enable helps cases using clk_enable in non-atomic context. */ 390static inline int clk_prepare_enable(struct clk *clk) 391{ 392 int ret; 393 394 ret = clk_prepare(clk); 395 if (ret) 396 return ret; 397 ret = clk_enable(clk); 398 if (ret) 399 clk_unprepare(clk); 400 401 return ret; 402} 403 404/* clk_disable_unprepare helps cases using clk_disable in non-atomic context. */ 405static inline void clk_disable_unprepare(struct clk *clk) 406{ 407 clk_disable(clk); 408 clk_unprepare(clk); 409} 410 411/** 412 * clk_add_alias - add a new clock alias 413 * @alias: name for clock alias 414 * @alias_dev_name: device name 415 * @id: platform specific clock name 416 * @dev: device 417 * 418 * Allows using generic clock names for drivers by adding a new alias. 419 * Assumes clkdev, see clkdev.h for more info. 420 */ 421int clk_add_alias(const char *alias, const char *alias_dev_name, char *id, 422 struct device *dev); 423 424struct device_node; 425struct of_phandle_args; 426 427#if defined(CONFIG_OF) && defined(CONFIG_COMMON_CLK) 428struct clk *of_clk_get(struct device_node *np, int index); 429struct clk *of_clk_get_by_name(struct device_node *np, const char *name); 430struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec); 431#else 432static inline struct clk *of_clk_get(struct device_node *np, int index) 433{ 434 return ERR_PTR(-ENOENT); 435} 436static inline struct clk *of_clk_get_by_name(struct device_node *np, 437 const char *name) 438{ 439 return ERR_PTR(-ENOENT); 440} 441#endif 442 443#endif 444