include/linux/clk.h

   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
  19 struct device;
  20 struct clk;
  21 struct device_node;
  22 struct 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  */
  57 struct 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  */
  74 struct 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  */
  91 int 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  */
  98 int 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  */
 108 long 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  */
 118 int 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  */
 127 int 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  */
 140 bool clk_is_match(const struct clk *p, const struct clk *q);
 141
 142 #else
 143
 144 static inline int clk_notifier_register(struct clk *clk,
 145                                         struct notifier_block *nb)
 146 {
 147         return -ENOTSUPP;
 148 }
 149
 150 static inline int clk_notifier_unregister(struct clk *clk,
 151                                           struct notifier_block *nb)
 152 {
 153         return -ENOTSUPP;
 154 }
 155
 156 static inline long clk_get_accuracy(struct clk *clk)
 157 {
 158         return -ENOTSUPP;
 159 }
 160
 161 static inline long clk_set_phase(struct clk *clk, int phase)
 162 {
 163         return -ENOTSUPP;
 164 }
 165
 166 static inline long clk_get_phase(struct clk *clk)
 167 {
 168         return -ENOTSUPP;
 169 }
 170
 171 static 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
 187 int clk_prepare(struct clk *clk);
 188 #else
 189 static 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
 206 void clk_unprepare(struct clk *clk);
 207 #else
 208 static 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  */
 230 struct 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  */
 250 struct 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  */
 266 struct 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  */
 279 int 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  */
 295 void 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  */
 302 unsigned 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  */
 314 void 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  */
 327 void 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  */
 355 long 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  */
 364 int 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  */
 376 bool 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  */
 386 int 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  */
 395 int 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  */
 404 int 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  */
 413 int 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  */
 422 struct 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  */
 439 struct clk *clk_get_sys(const char *dev_id, const char *con_id);
 440
 441 #else /* !CONFIG_HAVE_CLK */
 442
 443 static inline struct clk *clk_get(struct device *dev, const char *id)
 444 {
 445         return NULL;
 446 }
 447
 448 static inline struct clk *devm_clk_get(struct device *dev, const char *id)
 449 {
 450         return NULL;
 451 }
 452
 453 static 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
 459 static inline void clk_put(struct clk *clk) {}
 460
 461 static inline void devm_clk_put(struct device *dev, struct clk *clk) {}
 462
 463 static inline int clk_enable(struct clk *clk)
 464 {
 465         return 0;
 466 }
 467
 468 static inline void clk_disable(struct clk *clk) {}
 469
 470 static inline unsigned long clk_get_rate(struct clk *clk)
 471 {
 472         return 0;
 473 }
 474
 475 static inline int clk_set_rate(struct clk *clk, unsigned long rate)
 476 {
 477         return 0;
 478 }
 479
 480 static inline long clk_round_rate(struct clk *clk, unsigned long rate)
 481 {
 482         return 0;
 483 }
 484
 485 static inline bool clk_has_parent(struct clk *clk, struct clk *parent)
 486 {
 487         return true;
 488 }
 489
 490 static inline int clk_set_parent(struct clk *clk, struct clk *parent)
 491 {
 492         return 0;
 493 }
 494
 495 static inline struct clk *clk_get_parent(struct clk *clk)
 496 {
 497         return NULL;
 498 }
 499
 500 static 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. */
 507 static 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. */
 522 static 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)
 529 struct clk *of_clk_get(struct device_node *np, int index);
 530 struct clk *of_clk_get_by_name(struct device_node *np, const char *name);
 531 struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec);
 532 #else
 533 static inline struct clk *of_clk_get(struct device_node *np, int index)
 534 {
 535         return ERR_PTR(-ENOENT);
 536 }
 537 static 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