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/** 81 * struct clk_bulk_data - Data used for bulk clk operations. 82 * 83 * @id: clock consumer ID 84 * @clk: struct clk * to store the associated clock 85 * 86 * The CLK APIs provide a series of clk_bulk_() API calls as 87 * a convenience to consumers which require multiple clks. This 88 * structure is used to manage data for these calls. 89 */ 90struct clk_bulk_data { 91 const char *id; 92 struct clk *clk; 93}; 94 95#ifdef CONFIG_COMMON_CLK 96 97/** 98 * clk_notifier_register: register a clock rate-change notifier callback 99 * @clk: clock whose rate we are interested in 100 * @nb: notifier block with callback function pointer 101 * 102 * ProTip: debugging across notifier chains can be frustrating. Make sure that 103 * your notifier callback function prints a nice big warning in case of 104 * failure. 105 */ 106int clk_notifier_register(struct clk *clk, struct notifier_block *nb); 107 108/** 109 * clk_notifier_unregister: unregister a clock rate-change notifier callback 110 * @clk: clock whose rate we are no longer interested in 111 * @nb: notifier block which will be unregistered 112 */ 113int clk_notifier_unregister(struct clk *clk, struct notifier_block *nb); 114 115/** 116 * clk_get_accuracy - obtain the clock accuracy in ppb (parts per billion) 117 * for a clock source. 118 * @clk: clock source 119 * 120 * This gets the clock source accuracy expressed in ppb. 121 * A perfect clock returns 0. 122 */ 123long clk_get_accuracy(struct clk *clk); 124 125/** 126 * clk_set_phase - adjust the phase shift of a clock signal 127 * @clk: clock signal source 128 * @degrees: number of degrees the signal is shifted 129 * 130 * Shifts the phase of a clock signal by the specified degrees. Returns 0 on 131 * success, -EERROR otherwise. 132 */ 133int clk_set_phase(struct clk *clk, int degrees); 134 135/** 136 * clk_get_phase - return the phase shift of a clock signal 137 * @clk: clock signal source 138 * 139 * Returns the phase shift of a clock node in degrees, otherwise returns 140 * -EERROR. 141 */ 142int clk_get_phase(struct clk *clk); 143 144/** 145 * clk_is_match - check if two clk's point to the same hardware clock 146 * @p: clk compared against q 147 * @q: clk compared against p 148 * 149 * Returns true if the two struct clk pointers both point to the same hardware 150 * clock node. Put differently, returns true if @p and @q 151 * share the same &struct clk_core object. 152 * 153 * Returns false otherwise. Note that two NULL clks are treated as matching. 154 */ 155bool clk_is_match(const struct clk *p, const struct clk *q); 156 157#else 158 159static inline int clk_notifier_register(struct clk *clk, 160 struct notifier_block *nb) 161{ 162 return -ENOTSUPP; 163} 164 165static inline int clk_notifier_unregister(struct clk *clk, 166 struct notifier_block *nb) 167{ 168 return -ENOTSUPP; 169} 170 171static inline long clk_get_accuracy(struct clk *clk) 172{ 173 return -ENOTSUPP; 174} 175 176static inline long clk_set_phase(struct clk *clk, int phase) 177{ 178 return -ENOTSUPP; 179} 180 181static inline long clk_get_phase(struct clk *clk) 182{ 183 return -ENOTSUPP; 184} 185 186static inline bool clk_is_match(const struct clk *p, const struct clk *q) 187{ 188 return p == q; 189} 190 191#endif 192 193/** 194 * clk_prepare - prepare a clock source 195 * @clk: clock source 196 * 197 * This prepares the clock source for use. 198 * 199 * Must not be called from within atomic context. 200 */ 201#ifdef CONFIG_HAVE_CLK_PREPARE 202int clk_prepare(struct clk *clk); 203int __must_check clk_bulk_prepare(int num_clks, 204 const struct clk_bulk_data *clks); 205#else 206static inline int clk_prepare(struct clk *clk) 207{ 208 might_sleep(); 209 return 0; 210} 211 212static inline int clk_bulk_prepare(int num_clks, struct clk_bulk_data *clks) 213{ 214 might_sleep(); 215 return 0; 216} 217#endif 218 219/** 220 * clk_unprepare - undo preparation of a clock source 221 * @clk: clock source 222 * 223 * This undoes a previously prepared clock. The caller must balance 224 * the number of prepare and unprepare calls. 225 * 226 * Must not be called from within atomic context. 227 */ 228#ifdef CONFIG_HAVE_CLK_PREPARE 229void clk_unprepare(struct clk *clk); 230void clk_bulk_unprepare(int num_clks, const struct clk_bulk_data *clks); 231#else 232static inline void clk_unprepare(struct clk *clk) 233{ 234 might_sleep(); 235} 236static inline void clk_bulk_unprepare(int num_clks, struct clk_bulk_data *clks) 237{ 238 might_sleep(); 239} 240#endif 241 242#ifdef CONFIG_HAVE_CLK 243/** 244 * clk_get - lookup and obtain a reference to a clock producer. 245 * @dev: device for clock "consumer" 246 * @id: clock consumer ID 247 * 248 * Returns a struct clk corresponding to the clock producer, or 249 * valid IS_ERR() condition containing errno. The implementation 250 * uses @dev and @id to determine the clock consumer, and thereby 251 * the clock producer. (IOW, @id may be identical strings, but 252 * clk_get may return different clock producers depending on @dev.) 253 * 254 * Drivers must assume that the clock source is not enabled. 255 * 256 * clk_get should not be called from within interrupt context. 257 */ 258struct clk *clk_get(struct device *dev, const char *id); 259 260/** 261 * clk_bulk_get - lookup and obtain a number of references to clock producer. 262 * @dev: device for clock "consumer" 263 * @num_clks: the number of clk_bulk_data 264 * @clks: the clk_bulk_data table of consumer 265 * 266 * This helper function allows drivers to get several clk consumers in one 267 * operation. If any of the clk cannot be acquired then any clks 268 * that were obtained will be freed before returning to the caller. 269 * 270 * Returns 0 if all clocks specified in clk_bulk_data table are obtained 271 * successfully, or valid IS_ERR() condition containing errno. 272 * The implementation uses @dev and @clk_bulk_data.id to determine the 273 * clock consumer, and thereby the clock producer. 274 * The clock returned is stored in each @clk_bulk_data.clk field. 275 * 276 * Drivers must assume that the clock source is not enabled. 277 * 278 * clk_bulk_get should not be called from within interrupt context. 279 */ 280int __must_check clk_bulk_get(struct device *dev, int num_clks, 281 struct clk_bulk_data *clks); 282 283/** 284 * devm_clk_bulk_get - managed get multiple clk consumers 285 * @dev: device for clock "consumer" 286 * @num_clks: the number of clk_bulk_data 287 * @clks: the clk_bulk_data table of consumer 288 * 289 * Return 0 on success, an errno on failure. 290 * 291 * This helper function allows drivers to get several clk 292 * consumers in one operation with management, the clks will 293 * automatically be freed when the device is unbound. 294 */ 295int __must_check devm_clk_bulk_get(struct device *dev, int num_clks, 296 struct clk_bulk_data *clks); 297 298/** 299 * devm_clk_get - lookup and obtain a managed reference to a clock producer. 300 * @dev: device for clock "consumer" 301 * @id: clock consumer ID 302 * 303 * Returns a struct clk corresponding to the clock producer, or 304 * valid IS_ERR() condition containing errno. The implementation 305 * uses @dev and @id to determine the clock consumer, and thereby 306 * the clock producer. (IOW, @id may be identical strings, but 307 * clk_get may return different clock producers depending on @dev.) 308 * 309 * Drivers must assume that the clock source is not enabled. 310 * 311 * devm_clk_get should not be called from within interrupt context. 312 * 313 * The clock will automatically be freed when the device is unbound 314 * from the bus. 315 */ 316struct clk *devm_clk_get(struct device *dev, const char *id); 317 318/** 319 * devm_get_clk_from_child - lookup and obtain a managed reference to a 320 * clock producer from child node. 321 * @dev: device for clock "consumer" 322 * @np: pointer to clock consumer node 323 * @con_id: clock consumer ID 324 * 325 * This function parses the clocks, and uses them to look up the 326 * struct clk from the registered list of clock providers by using 327 * @np and @con_id 328 * 329 * The clock will automatically be freed when the device is unbound 330 * from the bus. 331 */ 332struct clk *devm_get_clk_from_child(struct device *dev, 333 struct device_node *np, const char *con_id); 334 335/** 336 * clk_enable - inform the system when the clock source should be running. 337 * @clk: clock source 338 * 339 * If the clock can not be enabled/disabled, this should return success. 340 * 341 * May be called from atomic contexts. 342 * 343 * Returns success (0) or negative errno. 344 */ 345int clk_enable(struct clk *clk); 346 347/** 348 * clk_bulk_enable - inform the system when the set of clks should be running. 349 * @num_clks: the number of clk_bulk_data 350 * @clks: the clk_bulk_data table of consumer 351 * 352 * May be called from atomic contexts. 353 * 354 * Returns success (0) or negative errno. 355 */ 356int __must_check clk_bulk_enable(int num_clks, 357 const struct clk_bulk_data *clks); 358 359/** 360 * clk_disable - inform the system when the clock source is no longer required. 361 * @clk: clock source 362 * 363 * Inform the system that a clock source is no longer required by 364 * a driver and may be shut down. 365 * 366 * May be called from atomic contexts. 367 * 368 * Implementation detail: if the clock source is shared between 369 * multiple drivers, clk_enable() calls must be balanced by the 370 * same number of clk_disable() calls for the clock source to be 371 * disabled. 372 */ 373void clk_disable(struct clk *clk); 374 375/** 376 * clk_bulk_disable - inform the system when the set of clks is no 377 * longer required. 378 * @num_clks: the number of clk_bulk_data 379 * @clks: the clk_bulk_data table of consumer 380 * 381 * Inform the system that a set of clks is no longer required by 382 * a driver and may be shut down. 383 * 384 * May be called from atomic contexts. 385 * 386 * Implementation detail: if the set of clks is shared between 387 * multiple drivers, clk_bulk_enable() calls must be balanced by the 388 * same number of clk_bulk_disable() calls for the clock source to be 389 * disabled. 390 */ 391void clk_bulk_disable(int num_clks, const struct clk_bulk_data *clks); 392 393/** 394 * clk_get_rate - obtain the current clock rate (in Hz) for a clock source. 395 * This is only valid once the clock source has been enabled. 396 * @clk: clock source 397 */ 398unsigned long clk_get_rate(struct clk *clk); 399 400/** 401 * clk_put - "free" the clock source 402 * @clk: clock source 403 * 404 * Note: drivers must ensure that all clk_enable calls made on this 405 * clock source are balanced by clk_disable calls prior to calling 406 * this function. 407 * 408 * clk_put should not be called from within interrupt context. 409 */ 410void clk_put(struct clk *clk); 411 412/** 413 * clk_bulk_put - "free" the clock source 414 * @num_clks: the number of clk_bulk_data 415 * @clks: the clk_bulk_data table of consumer 416 * 417 * Note: drivers must ensure that all clk_bulk_enable calls made on this 418 * clock source are balanced by clk_bulk_disable calls prior to calling 419 * this function. 420 * 421 * clk_bulk_put should not be called from within interrupt context. 422 */ 423void clk_bulk_put(int num_clks, struct clk_bulk_data *clks); 424 425/** 426 * devm_clk_put - "free" a managed clock source 427 * @dev: device used to acquire the clock 428 * @clk: clock source acquired with devm_clk_get() 429 * 430 * Note: drivers must ensure that all clk_enable calls made on this 431 * clock source are balanced by clk_disable calls prior to calling 432 * this function. 433 * 434 * clk_put should not be called from within interrupt context. 435 */ 436void devm_clk_put(struct device *dev, struct clk *clk); 437 438/* 439 * The remaining APIs are optional for machine class support. 440 */ 441 442 443/** 444 * clk_round_rate - adjust a rate to the exact rate a clock can provide 445 * @clk: clock source 446 * @rate: desired clock rate in Hz 447 * 448 * This answers the question "if I were to pass @rate to clk_set_rate(), 449 * what clock rate would I end up with?" without changing the hardware 450 * in any way. In other words: 451 * 452 * rate = clk_round_rate(clk, r); 453 * 454 * and: 455 * 456 * clk_set_rate(clk, r); 457 * rate = clk_get_rate(clk); 458 * 459 * are equivalent except the former does not modify the clock hardware 460 * in any way. 461 * 462 * Returns rounded clock rate in Hz, or negative errno. 463 */ 464long clk_round_rate(struct clk *clk, unsigned long rate); 465 466/** 467 * clk_set_rate - set the clock rate for a clock source 468 * @clk: clock source 469 * @rate: desired clock rate in Hz 470 * 471 * Returns success (0) or negative errno. 472 */ 473int clk_set_rate(struct clk *clk, unsigned long rate); 474 475/** 476 * clk_has_parent - check if a clock is a possible parent for another 477 * @clk: clock source 478 * @parent: parent clock source 479 * 480 * This function can be used in drivers that need to check that a clock can be 481 * the parent of another without actually changing the parent. 482 * 483 * Returns true if @parent is a possible parent for @clk, false otherwise. 484 */ 485bool clk_has_parent(struct clk *clk, struct clk *parent); 486 487/** 488 * clk_set_rate_range - set a rate range for a clock source 489 * @clk: clock source 490 * @min: desired minimum clock rate in Hz, inclusive 491 * @max: desired maximum clock rate in Hz, inclusive 492 * 493 * Returns success (0) or negative errno. 494 */ 495int clk_set_rate_range(struct clk *clk, unsigned long min, unsigned long max); 496 497/** 498 * clk_set_min_rate - set a minimum clock rate for a clock source 499 * @clk: clock source 500 * @rate: desired minimum clock rate in Hz, inclusive 501 * 502 * Returns success (0) or negative errno. 503 */ 504int clk_set_min_rate(struct clk *clk, unsigned long rate); 505 506/** 507 * clk_set_max_rate - set a maximum clock rate for a clock source 508 * @clk: clock source 509 * @rate: desired maximum clock rate in Hz, inclusive 510 * 511 * Returns success (0) or negative errno. 512 */ 513int clk_set_max_rate(struct clk *clk, unsigned long rate); 514 515/** 516 * clk_set_parent - set the parent clock source for this clock 517 * @clk: clock source 518 * @parent: parent clock source 519 * 520 * Returns success (0) or negative errno. 521 */ 522int clk_set_parent(struct clk *clk, struct clk *parent); 523 524/** 525 * clk_get_parent - get the parent clock source for this clock 526 * @clk: clock source 527 * 528 * Returns struct clk corresponding to parent clock source, or 529 * valid IS_ERR() condition containing errno. 530 */ 531struct clk *clk_get_parent(struct clk *clk); 532 533/** 534 * clk_get_sys - get a clock based upon the device name 535 * @dev_id: device name 536 * @con_id: connection ID 537 * 538 * Returns a struct clk corresponding to the clock producer, or 539 * valid IS_ERR() condition containing errno. The implementation 540 * uses @dev_id and @con_id to determine the clock consumer, and 541 * thereby the clock producer. In contrast to clk_get() this function 542 * takes the device name instead of the device itself for identification. 543 * 544 * Drivers must assume that the clock source is not enabled. 545 * 546 * clk_get_sys should not be called from within interrupt context. 547 */ 548struct clk *clk_get_sys(const char *dev_id, const char *con_id); 549 550#else /* !CONFIG_HAVE_CLK */ 551 552static inline struct clk *clk_get(struct device *dev, const char *id) 553{ 554 return NULL; 555} 556 557static inline int clk_bulk_get(struct device *dev, int num_clks, 558 struct clk_bulk_data *clks) 559{ 560 return 0; 561} 562 563static inline struct clk *devm_clk_get(struct device *dev, const char *id) 564{ 565 return NULL; 566} 567 568static inline int devm_clk_bulk_get(struct device *dev, int num_clks, 569 struct clk_bulk_data *clks) 570{ 571 return 0; 572} 573 574static inline struct clk *devm_get_clk_from_child(struct device *dev, 575 struct device_node *np, const char *con_id) 576{ 577 return NULL; 578} 579 580static inline void clk_put(struct clk *clk) {} 581 582static inline void clk_bulk_put(int num_clks, struct clk_bulk_data *clks) {} 583 584static inline void devm_clk_put(struct device *dev, struct clk *clk) {} 585 586static inline int clk_enable(struct clk *clk) 587{ 588 return 0; 589} 590 591static inline int clk_bulk_enable(int num_clks, struct clk_bulk_data *clks) 592{ 593 return 0; 594} 595 596static inline void clk_disable(struct clk *clk) {} 597 598 599static inline void clk_bulk_disable(int num_clks, 600 struct clk_bulk_data *clks) {} 601 602static inline unsigned long clk_get_rate(struct clk *clk) 603{ 604 return 0; 605} 606 607static inline int clk_set_rate(struct clk *clk, unsigned long rate) 608{ 609 return 0; 610} 611 612static inline long clk_round_rate(struct clk *clk, unsigned long rate) 613{ 614 return 0; 615} 616 617static inline bool clk_has_parent(struct clk *clk, struct clk *parent) 618{ 619 return true; 620} 621 622static inline int clk_set_parent(struct clk *clk, struct clk *parent) 623{ 624 return 0; 625} 626 627static inline struct clk *clk_get_parent(struct clk *clk) 628{ 629 return NULL; 630} 631 632static inline struct clk *clk_get_sys(const char *dev_id, const char *con_id) 633{ 634 return NULL; 635} 636#endif 637 638/* clk_prepare_enable helps cases using clk_enable in non-atomic context. */ 639static inline int clk_prepare_enable(struct clk *clk) 640{ 641 int ret; 642 643 ret = clk_prepare(clk); 644 if (ret) 645 return ret; 646 ret = clk_enable(clk); 647 if (ret) 648 clk_unprepare(clk); 649 650 return ret; 651} 652 653/* clk_disable_unprepare helps cases using clk_disable in non-atomic context. */ 654static inline void clk_disable_unprepare(struct clk *clk) 655{ 656 clk_disable(clk); 657 clk_unprepare(clk); 658} 659 660static inline int clk_bulk_prepare_enable(int num_clks, 661 struct clk_bulk_data *clks) 662{ 663 int ret; 664 665 ret = clk_bulk_prepare(num_clks, clks); 666 if (ret) 667 return ret; 668 ret = clk_bulk_enable(num_clks, clks); 669 if (ret) 670 clk_bulk_unprepare(num_clks, clks); 671 672 return ret; 673} 674 675static inline void clk_bulk_disable_unprepare(int num_clks, 676 struct clk_bulk_data *clks) 677{ 678 clk_bulk_disable(num_clks, clks); 679 clk_bulk_unprepare(num_clks, clks); 680} 681 682#if defined(CONFIG_OF) && defined(CONFIG_COMMON_CLK) 683struct clk *of_clk_get(struct device_node *np, int index); 684struct clk *of_clk_get_by_name(struct device_node *np, const char *name); 685struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec); 686#else 687static inline struct clk *of_clk_get(struct device_node *np, int index) 688{ 689 return ERR_PTR(-ENOENT); 690} 691static inline struct clk *of_clk_get_by_name(struct device_node *np, 692 const char *name) 693{ 694 return ERR_PTR(-ENOENT); 695} 696static inline struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec) 697{ 698 return ERR_PTR(-ENOENT); 699} 700#endif 701 702#endif 703