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; 20struct clk; 21struct device_node; 22struct of_phandle_args; 23 24/** 25 * DOC: clk notifier callback types 26 * 27 * PRE_RATE_CHANGE - called immediately before the clk rate is changed, 28 * to indicate that the rate change will proceed. Drivers must 29 * immediately terminate any operations that will be affected by the 30 * rate change. Callbacks may either return NOTIFY_DONE, NOTIFY_OK, 31 * NOTIFY_STOP or NOTIFY_BAD. 32 * 33 * ABORT_RATE_CHANGE: called if the rate change failed for some reason 34 * after PRE_RATE_CHANGE. In this case, all registered notifiers on 35 * the clk will be called with ABORT_RATE_CHANGE. Callbacks must 36 * always return NOTIFY_DONE or NOTIFY_OK. 37 * 38 * POST_RATE_CHANGE - called after the clk rate change has successfully 39 * completed. Callbacks must always return NOTIFY_DONE or NOTIFY_OK. 40 * 41 */ 42#define PRE_RATE_CHANGE BIT(0) 43#define POST_RATE_CHANGE BIT(1) 44#define ABORT_RATE_CHANGE BIT(2) 45 46/** 47 * struct clk_notifier - associate a clk with a notifier 48 * @clk: struct clk * to associate the notifier with 49 * @notifier_head: a blocking_notifier_head for this clk 50 * @node: linked list pointers 51 * 52 * A list of struct clk_notifier is maintained by the notifier code. 53 * An entry is created whenever code registers the first notifier on a 54 * particular @clk. Future notifiers on that @clk are added to the 55 * @notifier_head. 56 */ 57struct clk_notifier { 58 struct clk *clk; 59 struct srcu_notifier_head notifier_head; 60 struct list_head node; 61}; 62 63/** 64 * struct clk_notifier_data - rate data to pass to the notifier callback 65 * @clk: struct clk * being changed 66 * @old_rate: previous rate of this clk 67 * @new_rate: new rate of this clk 68 * 69 * For a pre-notifier, old_rate is the clk's rate before this rate 70 * change, and new_rate is what the rate will be in the future. For a 71 * post-notifier, old_rate and new_rate are both set to the clk's 72 * current rate (this was done to optimize the implementation). 73 */ 74struct clk_notifier_data { 75 struct clk *clk; 76 unsigned long old_rate; 77 unsigned long new_rate; 78}; 79 80#ifdef CONFIG_COMMON_CLK 81 82/** 83 * clk_notifier_register: register a clock rate-change notifier callback 84 * @clk: clock whose rate we are interested in 85 * @nb: notifier block with callback function pointer 86 * 87 * ProTip: debugging across notifier chains can be frustrating. Make sure that 88 * your notifier callback function prints a nice big warning in case of 89 * failure. 90 */ 91int clk_notifier_register(struct clk *clk, struct notifier_block *nb); 92 93/** 94 * clk_notifier_unregister: unregister a clock rate-change notifier callback 95 * @clk: clock whose rate we are no longer interested in 96 * @nb: notifier block which will be unregistered 97 */ 98int clk_notifier_unregister(struct clk *clk, struct notifier_block *nb); 99 100/** 101 * clk_get_accuracy - obtain the clock accuracy in ppb (parts per billion) 102 * for a clock source. 103 * @clk: clock source 104 * 105 * This gets the clock source accuracy expressed in ppb. 106 * A perfect clock returns 0. 107 */ 108long clk_get_accuracy(struct clk *clk); 109 110/** 111 * clk_set_phase - adjust the phase shift of a clock signal 112 * @clk: clock signal source 113 * @degrees: number of degrees the signal is shifted 114 * 115 * Shifts the phase of a clock signal by the specified degrees. Returns 0 on 116 * success, -EERROR otherwise. 117 */ 118int clk_set_phase(struct clk *clk, int degrees); 119 120/** 121 * clk_get_phase - return the phase shift of a clock signal 122 * @clk: clock signal source 123 * 124 * Returns the phase shift of a clock node in degrees, otherwise returns 125 * -EERROR. 126 */ 127int clk_get_phase(struct clk *clk); 128 129/** 130 * clk_is_match - check if two clk's point to the same hardware clock 131 * @p: clk compared against q 132 * @q: clk compared against p 133 * 134 * Returns true if the two struct clk pointers both point to the same hardware 135 * clock node. Put differently, returns true if struct clk *p and struct clk *q 136 * share the same struct clk_core object. 137 * 138 * Returns false otherwise. Note that two NULL clks are treated as matching. 139 */ 140bool clk_is_match(const struct clk *p, const struct clk *q); 141 142#else 143 144static inline int clk_notifier_register(struct clk *clk, 145 struct notifier_block *nb) 146{ 147 return -ENOTSUPP; 148} 149 150static inline int clk_notifier_unregister(struct clk *clk, 151 struct notifier_block *nb) 152{ 153 return -ENOTSUPP; 154} 155 156static inline long clk_get_accuracy(struct clk *clk) 157{ 158 return -ENOTSUPP; 159} 160 161static inline long clk_set_phase(struct clk *clk, int phase) 162{ 163 return -ENOTSUPP; 164} 165 166static inline long clk_get_phase(struct clk *clk) 167{ 168 return -ENOTSUPP; 169} 170 171static inline bool clk_is_match(const struct clk *p, const struct clk *q) 172{ 173 return p == q; 174} 175 176#endif 177 178/** 179 * clk_prepare - prepare a clock source 180 * @clk: clock source 181 * 182 * This prepares the clock source for use. 183 * 184 * Must not be called from within atomic context. 185 */ 186#ifdef CONFIG_HAVE_CLK_PREPARE 187int clk_prepare(struct clk *clk); 188#else 189static inline int clk_prepare(struct clk *clk) 190{ 191 might_sleep(); 192 return 0; 193} 194#endif 195 196/** 197 * clk_unprepare - undo preparation of a clock source 198 * @clk: clock source 199 * 200 * This undoes a previously prepared clock. The caller must balance 201 * the number of prepare and unprepare calls. 202 * 203 * Must not be called from within atomic context. 204 */ 205#ifdef CONFIG_HAVE_CLK_PREPARE 206void clk_unprepare(struct clk *clk); 207#else 208static inline void clk_unprepare(struct clk *clk) 209{ 210 might_sleep(); 211} 212#endif 213 214#ifdef CONFIG_HAVE_CLK 215/** 216 * clk_get - lookup and obtain a reference to a clock producer. 217 * @dev: device for clock "consumer" 218 * @id: clock consumer ID 219 * 220 * Returns a struct clk corresponding to the clock producer, or 221 * valid IS_ERR() condition containing errno. The implementation 222 * uses @dev and @id to determine the clock consumer, and thereby 223 * the clock producer. (IOW, @id may be identical strings, but 224 * clk_get may return different clock producers depending on @dev.) 225 * 226 * Drivers must assume that the clock source is not enabled. 227 * 228 * clk_get should not be called from within interrupt context. 229 */ 230struct clk *clk_get(struct device *dev, const char *id); 231 232/** 233 * devm_clk_get - lookup and obtain a managed reference to a clock producer. 234 * @dev: device for clock "consumer" 235 * @id: clock consumer ID 236 * 237 * Returns a struct clk corresponding to the clock producer, or 238 * valid IS_ERR() condition containing errno. The implementation 239 * uses @dev and @id to determine the clock consumer, and thereby 240 * the clock producer. (IOW, @id may be identical strings, but 241 * clk_get may return different clock producers depending on @dev.) 242 * 243 * Drivers must assume that the clock source is not enabled. 244 * 245 * devm_clk_get should not be called from within interrupt context. 246 * 247 * The clock will automatically be freed when the device is unbound 248 * from the bus. 249 */ 250struct clk *devm_clk_get(struct device *dev, const char *id); 251 252/** 253 * devm_get_clk_from_child - lookup and obtain a managed reference to a 254 * clock producer from child node. 255 * @dev: device for clock "consumer" 256 * @np: pointer to clock consumer node 257 * @con_id: clock consumer ID 258 * 259 * This function parses the clocks, and uses them to look up the 260 * struct clk from the registered list of clock providers by using 261 * @np and @con_id 262 * 263 * The clock will automatically be freed when the device is unbound 264 * from the bus. 265 */ 266struct clk *devm_get_clk_from_child(struct device *dev, 267 struct device_node *np, const char *con_id); 268 269/** 270 * clk_enable - inform the system when the clock source should be running. 271 * @clk: clock source 272 * 273 * If the clock can not be enabled/disabled, this should return success. 274 * 275 * May be called from atomic contexts. 276 * 277 * Returns success (0) or negative errno. 278 */ 279int clk_enable(struct clk *clk); 280 281/** 282 * clk_disable - inform the system when the clock source is no longer required. 283 * @clk: clock source 284 * 285 * Inform the system that a clock source is no longer required by 286 * a driver and may be shut down. 287 * 288 * May be called from atomic contexts. 289 * 290 * Implementation detail: if the clock source is shared between 291 * multiple drivers, clk_enable() calls must be balanced by the 292 * same number of clk_disable() calls for the clock source to be 293 * disabled. 294 */ 295void clk_disable(struct clk *clk); 296 297/** 298 * clk_get_rate - obtain the current clock rate (in Hz) for a clock source. 299 * This is only valid once the clock source has been enabled. 300 * @clk: clock source 301 */ 302unsigned long clk_get_rate(struct clk *clk); 303 304/** 305 * clk_put - "free" the clock source 306 * @clk: clock source 307 * 308 * Note: drivers must ensure that all clk_enable calls made on this 309 * clock source are balanced by clk_disable calls prior to calling 310 * this function. 311 * 312 * clk_put should not be called from within interrupt context. 313 */ 314void clk_put(struct clk *clk); 315 316/** 317 * devm_clk_put - "free" a managed clock source 318 * @dev: device used to acquire the clock 319 * @clk: clock source acquired with devm_clk_get() 320 * 321 * Note: drivers must ensure that all clk_enable calls made on this 322 * clock source are balanced by clk_disable calls prior to calling 323 * this function. 324 * 325 * clk_put should not be called from within interrupt context. 326 */ 327void devm_clk_put(struct device *dev, struct clk *clk); 328 329/* 330 * The remaining APIs are optional for machine class support. 331 */ 332 333 334/** 335 * clk_round_rate - adjust a rate to the exact rate a clock can provide 336 * @clk: clock source 337 * @rate: desired clock rate in Hz 338 * 339 * This answers the question "if I were to pass @rate to clk_set_rate(), 340 * what clock rate would I end up with?" without changing the hardware 341 * in any way. In other words: 342 * 343 * rate = clk_round_rate(clk, r); 344 * 345 * and: 346 * 347 * clk_set_rate(clk, r); 348 * rate = clk_get_rate(clk); 349 * 350 * are equivalent except the former does not modify the clock hardware 351 * in any way. 352 * 353 * Returns rounded clock rate in Hz, or negative errno. 354 */ 355long clk_round_rate(struct clk *clk, unsigned long rate); 356 357/** 358 * clk_set_rate - set the clock rate for a clock source 359 * @clk: clock source 360 * @rate: desired clock rate in Hz 361 * 362 * Returns success (0) or negative errno. 363 */ 364int clk_set_rate(struct clk *clk, unsigned long rate); 365 366/** 367 * clk_has_parent - check if a clock is a possible parent for another 368 * @clk: clock source 369 * @parent: parent clock source 370 * 371 * This function can be used in drivers that need to check that a clock can be 372 * the parent of another without actually changing the parent. 373 * 374 * Returns true if @parent is a possible parent for @clk, false otherwise. 375 */ 376bool clk_has_parent(struct clk *clk, struct clk *parent); 377 378/** 379 * clk_set_rate_range - set a rate range for a clock source 380 * @clk: clock source 381 * @min: desired minimum clock rate in Hz, inclusive 382 * @max: desired maximum clock rate in Hz, inclusive 383 * 384 * Returns success (0) or negative errno. 385 */ 386int clk_set_rate_range(struct clk *clk, unsigned long min, unsigned long max); 387 388/** 389 * clk_set_min_rate - set a minimum clock rate for a clock source 390 * @clk: clock source 391 * @rate: desired minimum clock rate in Hz, inclusive 392 * 393 * Returns success (0) or negative errno. 394 */ 395int clk_set_min_rate(struct clk *clk, unsigned long rate); 396 397/** 398 * clk_set_max_rate - set a maximum clock rate for a clock source 399 * @clk: clock source 400 * @rate: desired maximum clock rate in Hz, inclusive 401 * 402 * Returns success (0) or negative errno. 403 */ 404int clk_set_max_rate(struct clk *clk, unsigned long rate); 405 406/** 407 * clk_set_parent - set the parent clock source for this clock 408 * @clk: clock source 409 * @parent: parent clock source 410 * 411 * Returns success (0) or negative errno. 412 */ 413int clk_set_parent(struct clk *clk, struct clk *parent); 414 415/** 416 * clk_get_parent - get the parent clock source for this clock 417 * @clk: clock source 418 * 419 * Returns struct clk corresponding to parent clock source, or 420 * valid IS_ERR() condition containing errno. 421 */ 422struct clk *clk_get_parent(struct clk *clk); 423 424/** 425 * clk_get_sys - get a clock based upon the device name 426 * @dev_id: device name 427 * @con_id: connection ID 428 * 429 * Returns a struct clk corresponding to the clock producer, or 430 * valid IS_ERR() condition containing errno. The implementation 431 * uses @dev_id and @con_id to determine the clock consumer, and 432 * thereby the clock producer. In contrast to clk_get() this function 433 * takes the device name instead of the device itself for identification. 434 * 435 * Drivers must assume that the clock source is not enabled. 436 * 437 * clk_get_sys should not be called from within interrupt context. 438 */ 439struct clk *clk_get_sys(const char *dev_id, const char *con_id); 440 441#else /* !CONFIG_HAVE_CLK */ 442 443static inline struct clk *clk_get(struct device *dev, const char *id) 444{ 445 return NULL; 446} 447 448static inline struct clk *devm_clk_get(struct device *dev, const char *id) 449{ 450 return NULL; 451} 452 453static inline struct clk *devm_get_clk_from_child(struct device *dev, 454 struct device_node *np, const char *con_id) 455{ 456 return NULL; 457} 458 459static inline void clk_put(struct clk *clk) {} 460 461static inline void devm_clk_put(struct device *dev, struct clk *clk) {} 462 463static inline int clk_enable(struct clk *clk) 464{ 465 return 0; 466} 467 468static inline void clk_disable(struct clk *clk) {} 469 470static inline unsigned long clk_get_rate(struct clk *clk) 471{ 472 return 0; 473} 474 475static inline int clk_set_rate(struct clk *clk, unsigned long rate) 476{ 477 return 0; 478} 479 480static inline long clk_round_rate(struct clk *clk, unsigned long rate) 481{ 482 return 0; 483} 484 485static inline bool clk_has_parent(struct clk *clk, struct clk *parent) 486{ 487 return true; 488} 489 490static inline int clk_set_parent(struct clk *clk, struct clk *parent) 491{ 492 return 0; 493} 494 495static inline struct clk *clk_get_parent(struct clk *clk) 496{ 497 return NULL; 498} 499 500static inline struct clk *clk_get_sys(const char *dev_id, const char *con_id) 501{ 502 return NULL; 503} 504#endif 505 506/* clk_prepare_enable helps cases using clk_enable in non-atomic context. */ 507static inline int clk_prepare_enable(struct clk *clk) 508{ 509 int ret; 510 511 ret = clk_prepare(clk); 512 if (ret) 513 return ret; 514 ret = clk_enable(clk); 515 if (ret) 516 clk_unprepare(clk); 517 518 return ret; 519} 520 521/* clk_disable_unprepare helps cases using clk_disable in non-atomic context. */ 522static inline void clk_disable_unprepare(struct clk *clk) 523{ 524 clk_disable(clk); 525 clk_unprepare(clk); 526} 527 528#if defined(CONFIG_OF) && defined(CONFIG_COMMON_CLK) 529struct clk *of_clk_get(struct device_node *np, int index); 530struct clk *of_clk_get_by_name(struct device_node *np, const char *name); 531struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec); 532#else 533static inline struct clk *of_clk_get(struct device_node *np, int index) 534{ 535 return ERR_PTR(-ENOENT); 536} 537static inline struct clk *of_clk_get_by_name(struct device_node *np, 538 const char *name) 539{ 540 return ERR_PTR(-ENOENT); 541} 542#endif 543 544#endif 545