clk.h

   1/* SPDX-License-Identifier: GPL-2.0-only */
   2/*
   3 *  linux/include/linux/clk.h
   4 *
   5 *  Copyright (C) 2004 ARM Limited.
   6 *  Written by Deep Blue Solutions Limited.
   7 *  Copyright (C) 2011-2012 Linaro Ltd <mturquette@linaro.org>
   8 */
   9#ifndef __LINUX_CLK_H
  10#define __LINUX_CLK_H
  11
  12#include <linux/err.h>
  13#include <linux/kernel.h>
  14#include <linux/notifier.h>
  15
  16struct device;
  17struct clk;
  18struct device_node;
  19struct of_phandle_args;
  20
  21/**
  22 * DOC: clk notifier callback types
  23 *
  24 * PRE_RATE_CHANGE - called immediately before the clk rate is changed,
  25 *     to indicate that the rate change will proceed.  Drivers must
  26 *     immediately terminate any operations that will be affected by the
  27 *     rate change.  Callbacks may either return NOTIFY_DONE, NOTIFY_OK,
  28 *     NOTIFY_STOP or NOTIFY_BAD.
  29 *
  30 * ABORT_RATE_CHANGE: called if the rate change failed for some reason
  31 *     after PRE_RATE_CHANGE.  In this case, all registered notifiers on
  32 *     the clk will be called with ABORT_RATE_CHANGE. Callbacks must
  33 *     always return NOTIFY_DONE or NOTIFY_OK.
  34 *
  35 * POST_RATE_CHANGE - called after the clk rate change has successfully
  36 *     completed.  Callbacks must always return NOTIFY_DONE or NOTIFY_OK.
  37 *
  38 */
  39#define PRE_RATE_CHANGE			BIT(0)
  40#define POST_RATE_CHANGE		BIT(1)
  41#define ABORT_RATE_CHANGE		BIT(2)
  42
  43/**
  44 * struct clk_notifier - associate a clk with a notifier
  45 * @clk: struct clk * to associate the notifier with
  46 * @notifier_head: a blocking_notifier_head for this clk
  47 * @node: linked list pointers
  48 *
  49 * A list of struct clk_notifier is maintained by the notifier code.
  50 * An entry is created whenever code registers the first notifier on a
  51 * particular @clk.  Future notifiers on that @clk are added to the
  52 * @notifier_head.
  53 */
  54struct clk_notifier {
  55	struct clk			*clk;
  56	struct srcu_notifier_head	notifier_head;
  57	struct list_head		node;
  58};
  59
  60/**
  61 * struct clk_notifier_data - rate data to pass to the notifier callback
  62 * @clk: struct clk * being changed
  63 * @old_rate: previous rate of this clk
  64 * @new_rate: new rate of this clk
  65 *
  66 * For a pre-notifier, old_rate is the clk's rate before this rate
  67 * change, and new_rate is what the rate will be in the future.  For a
  68 * post-notifier, old_rate and new_rate are both set to the clk's
  69 * current rate (this was done to optimize the implementation).
  70 */
  71struct clk_notifier_data {
  72	struct clk		*clk;
  73	unsigned long		old_rate;
  74	unsigned long		new_rate;
  75};
  76
  77/**
  78 * struct clk_bulk_data - Data used for bulk clk operations.
  79 *
  80 * @id: clock consumer ID
  81 * @clk: struct clk * to store the associated clock
  82 *
  83 * The CLK APIs provide a series of clk_bulk_() API calls as
  84 * a convenience to consumers which require multiple clks.  This
  85 * structure is used to manage data for these calls.
  86 */
  87struct clk_bulk_data {
  88	const char		*id;
  89	struct clk		*clk;
  90};
  91
  92#ifdef CONFIG_COMMON_CLK
  93
  94/**
  95 * clk_notifier_register - register a clock rate-change notifier callback
  96 * @clk: clock whose rate we are interested in
  97 * @nb: notifier block with callback function pointer
  98 *
  99 * ProTip: debugging across notifier chains can be frustrating. Make sure that
 100 * your notifier callback function prints a nice big warning in case of
 101 * failure.
 102 */
 103int clk_notifier_register(struct clk *clk, struct notifier_block *nb);
 104
 105/**
 106 * clk_notifier_unregister - unregister a clock rate-change notifier callback
 107 * @clk: clock whose rate we are no longer interested in
 108 * @nb: notifier block which will be unregistered
 109 */
 110int clk_notifier_unregister(struct clk *clk, struct notifier_block *nb);
 111
 112/**
 113 * devm_clk_notifier_register - register a managed rate-change notifier callback
 114 * @dev: device for clock "consumer"
 115 * @clk: clock whose rate we are interested in
 116 * @nb: notifier block with callback function pointer
 117 *
 118 * Returns 0 on success, -EERROR otherwise
 119 */
 120int devm_clk_notifier_register(struct device *dev, struct clk *clk,
 121			       struct notifier_block *nb);
 122
 123/**
 124 * clk_get_accuracy - obtain the clock accuracy in ppb (parts per billion)
 125 *		      for a clock source.
 126 * @clk: clock source
 127 *
 128 * This gets the clock source accuracy expressed in ppb.
 129 * A perfect clock returns 0.
 130 */
 131long clk_get_accuracy(struct clk *clk);
 132
 133/**
 134 * clk_set_phase - adjust the phase shift of a clock signal
 135 * @clk: clock signal source
 136 * @degrees: number of degrees the signal is shifted
 137 *
 138 * Shifts the phase of a clock signal by the specified degrees. Returns 0 on
 139 * success, -EERROR otherwise.
 140 */
 141int clk_set_phase(struct clk *clk, int degrees);
 142
 143/**
 144 * clk_get_phase - return the phase shift of a clock signal
 145 * @clk: clock signal source
 146 *
 147 * Returns the phase shift of a clock node in degrees, otherwise returns
 148 * -EERROR.
 149 */
 150int clk_get_phase(struct clk *clk);
 151
 152/**
 153 * clk_set_duty_cycle - adjust the duty cycle ratio of a clock signal
 154 * @clk: clock signal source
 155 * @num: numerator of the duty cycle ratio to be applied
 156 * @den: denominator of the duty cycle ratio to be applied
 157 *
 158 * Adjust the duty cycle of a clock signal by the specified ratio. Returns 0 on
 159 * success, -EERROR otherwise.
 160 */
 161int clk_set_duty_cycle(struct clk *clk, unsigned int num, unsigned int den);
 162
 163/**
 164 * clk_get_scaled_duty_cycle - return the duty cycle ratio of a clock signal
 165 * @clk: clock signal source
 166 * @scale: scaling factor to be applied to represent the ratio as an integer
 167 *
 168 * Returns the duty cycle ratio multiplied by the scale provided, otherwise
 169 * returns -EERROR.
 170 */
 171int clk_get_scaled_duty_cycle(struct clk *clk, unsigned int scale);
 172
 173/**
 174 * clk_is_match - check if two clk's point to the same hardware clock
 175 * @p: clk compared against q
 176 * @q: clk compared against p
 177 *
 178 * Returns true if the two struct clk pointers both point to the same hardware
 179 * clock node. Put differently, returns true if @p and @q
 180 * share the same &struct clk_core object.
 181 *
 182 * Returns false otherwise. Note that two NULL clks are treated as matching.
 183 */
 184bool clk_is_match(const struct clk *p, const struct clk *q);
 185
 186/**
 187 * clk_rate_exclusive_get - get exclusivity over the rate control of a
 188 *                          producer
 189 * @clk: clock source
 190 *
 191 * This function allows drivers to get exclusive control over the rate of a
 192 * provider. It prevents any other consumer to execute, even indirectly,
 193 * opereation which could alter the rate of the provider or cause glitches
 194 *
 195 * If exlusivity is claimed more than once on clock, even by the same driver,
 196 * the rate effectively gets locked as exclusivity can't be preempted.
 197 *
 198 * Must not be called from within atomic context.
 199 *
 200 * Returns success (0) or negative errno.
 201 */
 202int clk_rate_exclusive_get(struct clk *clk);
 203
 204/**
 205 * devm_clk_rate_exclusive_get - devm variant of clk_rate_exclusive_get
 206 * @dev: device the exclusivity is bound to
 207 * @clk: clock source
 208 *
 209 * Calls clk_rate_exclusive_get() on @clk and registers a devm cleanup handler
 210 * on @dev to call clk_rate_exclusive_put().
 211 *
 212 * Must not be called from within atomic context.
 213 */
 214int devm_clk_rate_exclusive_get(struct device *dev, struct clk *clk);
 215
 216/**
 217 * clk_rate_exclusive_put - release exclusivity over the rate control of a
 218 *                          producer
 219 * @clk: clock source
 220 *
 221 * This function allows drivers to release the exclusivity it previously got
 222 * from clk_rate_exclusive_get()
 223 *
 224 * The caller must balance the number of clk_rate_exclusive_get() and
 225 * clk_rate_exclusive_put() calls.
 226 *
 227 * Must not be called from within atomic context.
 228 */
 229void clk_rate_exclusive_put(struct clk *clk);
 230
 231/**
 232 * clk_save_context - save clock context for poweroff
 233 *
 234 * Saves the context of the clock register for powerstates in which the
 235 * contents of the registers will be lost. Occurs deep within the suspend
 236 * code so locking is not necessary.
 237 */
 238int clk_save_context(void);
 239
 240/**
 241 * clk_restore_context - restore clock context after poweroff
 242 *
 243 * This occurs with all clocks enabled. Occurs deep within the resume code
 244 * so locking is not necessary.
 245 */
 246void clk_restore_context(void);
 247
 248#else
 249
 250static inline int clk_notifier_register(struct clk *clk,
 251					struct notifier_block *nb)
 252{
 253	return -ENOTSUPP;
 254}
 255
 256static inline int clk_notifier_unregister(struct clk *clk,
 257					  struct notifier_block *nb)
 258{
 259	return -ENOTSUPP;
 260}
 261
 262static inline int devm_clk_notifier_register(struct device *dev,
 263					     struct clk *clk,
 264					     struct notifier_block *nb)
 265{
 266	return -ENOTSUPP;
 267}
 268
 269static inline long clk_get_accuracy(struct clk *clk)
 270{
 271	return -ENOTSUPP;
 272}
 273
 274static inline long clk_set_phase(struct clk *clk, int phase)
 275{
 276	return -ENOTSUPP;
 277}
 278
 279static inline long clk_get_phase(struct clk *clk)
 280{
 281	return -ENOTSUPP;
 282}
 283
 284static inline int clk_set_duty_cycle(struct clk *clk, unsigned int num,
 285				     unsigned int den)
 286{
 287	return -ENOTSUPP;
 288}
 289
 290static inline unsigned int clk_get_scaled_duty_cycle(struct clk *clk,
 291						     unsigned int scale)
 292{
 293	return 0;
 294}
 295
 296static inline bool clk_is_match(const struct clk *p, const struct clk *q)
 297{
 298	return p == q;
 299}
 300
 301static inline int clk_rate_exclusive_get(struct clk *clk)
 302{
 303	return 0;
 304}
 305
 306static inline int devm_clk_rate_exclusive_get(struct device *dev, struct clk *clk)
 307{
 308	return 0;
 309}
 310
 311static inline void clk_rate_exclusive_put(struct clk *clk) {}
 312
 313static inline int clk_save_context(void)
 314{
 315	return 0;
 316}
 317
 318static inline void clk_restore_context(void) {}
 319
 320#endif
 321
 322#ifdef CONFIG_HAVE_CLK_PREPARE
 323/**
 324 * clk_prepare - prepare a clock source
 325 * @clk: clock source
 326 *
 327 * This prepares the clock source for use.
 328 *
 329 * Must not be called from within atomic context.
 330 */
 331int clk_prepare(struct clk *clk);
 332int __must_check clk_bulk_prepare(int num_clks,
 333				  const struct clk_bulk_data *clks);
 334
 335/**
 336 * clk_is_enabled_when_prepared - indicate if preparing a clock also enables it.
 337 * @clk: clock source
 338 *
 339 * Returns true if clk_prepare() implicitly enables the clock, effectively
 340 * making clk_enable()/clk_disable() no-ops, false otherwise.
 341 *
 342 * This is of interest mainly to the power management code where actually
 343 * disabling the clock also requires unpreparing it to have any material
 344 * effect.
 345 *
 346 * Regardless of the value returned here, the caller must always invoke
 347 * clk_enable() or clk_prepare_enable()  and counterparts for usage counts
 348 * to be right.
 349 */
 350bool clk_is_enabled_when_prepared(struct clk *clk);
 351#else
 352static inline int clk_prepare(struct clk *clk)
 353{
 354	might_sleep();
 355	return 0;
 356}
 357
 358static inline int __must_check
 359clk_bulk_prepare(int num_clks, const struct clk_bulk_data *clks)
 360{
 361	might_sleep();
 362	return 0;
 363}
 364
 365static inline bool clk_is_enabled_when_prepared(struct clk *clk)
 366{
 367	return false;
 368}
 369#endif
 370
 371/**
 372 * clk_unprepare - undo preparation of a clock source
 373 * @clk: clock source
 374 *
 375 * This undoes a previously prepared clock.  The caller must balance
 376 * the number of prepare and unprepare calls.
 377 *
 378 * Must not be called from within atomic context.
 379 */
 380#ifdef CONFIG_HAVE_CLK_PREPARE
 381void clk_unprepare(struct clk *clk);
 382void clk_bulk_unprepare(int num_clks, const struct clk_bulk_data *clks);
 383#else
 384static inline void clk_unprepare(struct clk *clk)
 385{
 386	might_sleep();
 387}
 388static inline void clk_bulk_unprepare(int num_clks,
 389				      const struct clk_bulk_data *clks)
 390{
 391	might_sleep();
 392}
 393#endif
 394
 395#ifdef CONFIG_HAVE_CLK
 396/**
 397 * clk_get - lookup and obtain a reference to a clock producer.
 398 * @dev: device for clock "consumer"
 399 * @id: clock consumer ID
 400 *
 401 * Returns a struct clk corresponding to the clock producer, or
 402 * valid IS_ERR() condition containing errno.  The implementation
 403 * uses @dev and @id to determine the clock consumer, and thereby
 404 * the clock producer.  (IOW, @id may be identical strings, but
 405 * clk_get may return different clock producers depending on @dev.)
 406 *
 407 * Drivers must assume that the clock source is not enabled.
 408 *
 409 * clk_get should not be called from within interrupt context.
 410 */
 411struct clk *clk_get(struct device *dev, const char *id);
 412
 413/**
 414 * clk_bulk_get - lookup and obtain a number of references to clock producer.
 415 * @dev: device for clock "consumer"
 416 * @num_clks: the number of clk_bulk_data
 417 * @clks: the clk_bulk_data table of consumer
 418 *
 419 * This helper function allows drivers to get several clk consumers in one
 420 * operation. If any of the clk cannot be acquired then any clks
 421 * that were obtained will be freed before returning to the caller.
 422 *
 423 * Returns 0 if all clocks specified in clk_bulk_data table are obtained
 424 * successfully, or valid IS_ERR() condition containing errno.
 425 * The implementation uses @dev and @clk_bulk_data.id to determine the
 426 * clock consumer, and thereby the clock producer.
 427 * The clock returned is stored in each @clk_bulk_data.clk field.
 428 *
 429 * Drivers must assume that the clock source is not enabled.
 430 *
 431 * clk_bulk_get should not be called from within interrupt context.
 432 */
 433int __must_check clk_bulk_get(struct device *dev, int num_clks,
 434			      struct clk_bulk_data *clks);
 435/**
 436 * clk_bulk_get_all - lookup and obtain all available references to clock
 437 *		      producer.
 438 * @dev: device for clock "consumer"
 439 * @clks: pointer to the clk_bulk_data table of consumer
 440 *
 441 * This helper function allows drivers to get all clk consumers in one
 442 * operation. If any of the clk cannot be acquired then any clks
 443 * that were obtained will be freed before returning to the caller.
 444 *
 445 * Returns a positive value for the number of clocks obtained while the
 446 * clock references are stored in the clk_bulk_data table in @clks field.
 447 * Returns 0 if there're none and a negative value if something failed.
 448 *
 449 * Drivers must assume that the clock source is not enabled.
 450 *
 451 * clk_bulk_get should not be called from within interrupt context.
 452 */
 453int __must_check clk_bulk_get_all(struct device *dev,
 454				  struct clk_bulk_data **clks);
 455
 456/**
 457 * clk_bulk_get_optional - lookup and obtain a number of references to clock producer
 458 * @dev: device for clock "consumer"
 459 * @num_clks: the number of clk_bulk_data
 460 * @clks: the clk_bulk_data table of consumer
 461 *
 462 * Behaves the same as clk_bulk_get() except where there is no clock producer.
 463 * In this case, instead of returning -ENOENT, the function returns 0 and
 464 * NULL for a clk for which a clock producer could not be determined.
 465 */
 466int __must_check clk_bulk_get_optional(struct device *dev, int num_clks,
 467				       struct clk_bulk_data *clks);
 468/**
 469 * devm_clk_bulk_get - managed get multiple clk consumers
 470 * @dev: device for clock "consumer"
 471 * @num_clks: the number of clk_bulk_data
 472 * @clks: the clk_bulk_data table of consumer
 473 *
 474 * Return 0 on success, an errno on failure.
 475 *
 476 * This helper function allows drivers to get several clk
 477 * consumers in one operation with management, the clks will
 478 * automatically be freed when the device is unbound.
 479 */
 480int __must_check devm_clk_bulk_get(struct device *dev, int num_clks,
 481				   struct clk_bulk_data *clks);
 482/**
 483 * devm_clk_bulk_get_optional - managed get multiple optional consumer clocks
 484 * @dev: device for clock "consumer"
 485 * @num_clks: the number of clk_bulk_data
 486 * @clks: pointer to the clk_bulk_data table of consumer
 487 *
 488 * Behaves the same as devm_clk_bulk_get() except where there is no clock
 489 * producer.  In this case, instead of returning -ENOENT, the function returns
 490 * NULL for given clk. It is assumed all clocks in clk_bulk_data are optional.
 491 *
 492 * Returns 0 if all clocks specified in clk_bulk_data table are obtained
 493 * successfully or for any clk there was no clk provider available, otherwise
 494 * returns valid IS_ERR() condition containing errno.
 495 * The implementation uses @dev and @clk_bulk_data.id to determine the
 496 * clock consumer, and thereby the clock producer.
 497 * The clock returned is stored in each @clk_bulk_data.clk field.
 498 *
 499 * Drivers must assume that the clock source is not enabled.
 500 *
 501 * clk_bulk_get should not be called from within interrupt context.
 502 */
 503int __must_check devm_clk_bulk_get_optional(struct device *dev, int num_clks,
 504					    struct clk_bulk_data *clks);
 505/**
 506 * devm_clk_bulk_get_all - managed get multiple clk consumers
 507 * @dev: device for clock "consumer"
 508 * @clks: pointer to the clk_bulk_data table of consumer
 509 *
 510 * Returns a positive value for the number of clocks obtained while the
 511 * clock references are stored in the clk_bulk_data table in @clks field.
 512 * Returns 0 if there're none and a negative value if something failed.
 513 *
 514 * This helper function allows drivers to get several clk
 515 * consumers in one operation with management, the clks will
 516 * automatically be freed when the device is unbound.
 517 */
 518
 519int __must_check devm_clk_bulk_get_all(struct device *dev,
 520				       struct clk_bulk_data **clks);
 521
 522/**
 523 * devm_clk_bulk_get_all_enabled - Get and enable all clocks of the consumer (managed)
 524 * @dev: device for clock "consumer"
 525 * @clks: pointer to the clk_bulk_data table of consumer
 526 *
 527 * Returns a positive value for the number of clocks obtained while the
 528 * clock references are stored in the clk_bulk_data table in @clks field.
 529 * Returns 0 if there're none and a negative value if something failed.
 530 *
 531 * This helper function allows drivers to get all clocks of the
 532 * consumer and enables them in one operation with management.
 533 * The clks will automatically be disabled and freed when the device
 534 * is unbound.
 535 */
 536
 537int __must_check devm_clk_bulk_get_all_enabled(struct device *dev,
 538					       struct clk_bulk_data **clks);
 539
 540/**
 541 * devm_clk_get - lookup and obtain a managed reference to a clock producer.
 542 * @dev: device for clock "consumer"
 543 * @id: clock consumer ID
 544 *
 545 * Context: May sleep.
 546 *
 547 * Return: a struct clk corresponding to the clock producer, or
 548 * valid IS_ERR() condition containing errno.  The implementation
 549 * uses @dev and @id to determine the clock consumer, and thereby
 550 * the clock producer.  (IOW, @id may be identical strings, but
 551 * clk_get may return different clock producers depending on @dev.)
 552 *
 553 * Drivers must assume that the clock source is neither prepared nor
 554 * enabled.
 555 *
 556 * The clock will automatically be freed when the device is unbound
 557 * from the bus.
 558 */
 559struct clk *devm_clk_get(struct device *dev, const char *id);
 560
 561/**
 562 * devm_clk_get_prepared - devm_clk_get() + clk_prepare()
 563 * @dev: device for clock "consumer"
 564 * @id: clock consumer ID
 565 *
 566 * Context: May sleep.
 567 *
 568 * Return: a struct clk corresponding to the clock producer, or
 569 * valid IS_ERR() condition containing errno.  The implementation
 570 * uses @dev and @id to determine the clock consumer, and thereby
 571 * the clock producer.  (IOW, @id may be identical strings, but
 572 * clk_get may return different clock producers depending on @dev.)
 573 *
 574 * The returned clk (if valid) is prepared. Drivers must however assume
 575 * that the clock is not enabled.
 576 *
 577 * The clock will automatically be unprepared and freed when the device
 578 * is unbound from the bus.
 579 */
 580struct clk *devm_clk_get_prepared(struct device *dev, const char *id);
 581
 582/**
 583 * devm_clk_get_enabled - devm_clk_get() + clk_prepare_enable()
 584 * @dev: device for clock "consumer"
 585 * @id: clock consumer ID
 586 *
 587 * Context: May sleep.
 588 *
 589 * Return: a struct clk corresponding to the clock producer, or
 590 * valid IS_ERR() condition containing errno.  The implementation
 591 * uses @dev and @id to determine the clock consumer, and thereby
 592 * the clock producer.  (IOW, @id may be identical strings, but
 593 * clk_get may return different clock producers depending on @dev.)
 594 *
 595 * The returned clk (if valid) is prepared and enabled.
 596 *
 597 * The clock will automatically be disabled, unprepared and freed
 598 * when the device is unbound from the bus.
 599 */
 600struct clk *devm_clk_get_enabled(struct device *dev, const char *id);
 601
 602/**
 603 * devm_clk_get_optional - lookup and obtain a managed reference to an optional
 604 *			   clock producer.
 605 * @dev: device for clock "consumer"
 606 * @id: clock consumer ID
 607 *
 608 * Context: May sleep.
 609 *
 610 * Return: a struct clk corresponding to the clock producer, or
 611 * valid IS_ERR() condition containing errno.  The implementation
 612 * uses @dev and @id to determine the clock consumer, and thereby
 613 * the clock producer.  If no such clk is found, it returns NULL
 614 * which serves as a dummy clk.  That's the only difference compared
 615 * to devm_clk_get().
 616 *
 617 * Drivers must assume that the clock source is neither prepared nor
 618 * enabled.
 619 *
 620 * The clock will automatically be freed when the device is unbound
 621 * from the bus.
 622 */
 623struct clk *devm_clk_get_optional(struct device *dev, const char *id);
 624
 625/**
 626 * devm_clk_get_optional_prepared - devm_clk_get_optional() + clk_prepare()
 627 * @dev: device for clock "consumer"
 628 * @id: clock consumer ID
 629 *
 630 * Context: May sleep.
 631 *
 632 * Return: a struct clk corresponding to the clock producer, or
 633 * valid IS_ERR() condition containing errno.  The implementation
 634 * uses @dev and @id to determine the clock consumer, and thereby
 635 * the clock producer.  If no such clk is found, it returns NULL
 636 * which serves as a dummy clk.  That's the only difference compared
 637 * to devm_clk_get_prepared().
 638 *
 639 * The returned clk (if valid) is prepared. Drivers must however
 640 * assume that the clock is not enabled.
 641 *
 642 * The clock will automatically be unprepared and freed when the
 643 * device is unbound from the bus.
 644 */
 645struct clk *devm_clk_get_optional_prepared(struct device *dev, const char *id);
 646
 647/**
 648 * devm_clk_get_optional_enabled - devm_clk_get_optional() +
 649 *                                 clk_prepare_enable()
 650 * @dev: device for clock "consumer"
 651 * @id: clock consumer ID
 652 *
 653 * Context: May sleep.
 654 *
 655 * Return: a struct clk corresponding to the clock producer, or
 656 * valid IS_ERR() condition containing errno.  The implementation
 657 * uses @dev and @id to determine the clock consumer, and thereby
 658 * the clock producer.  If no such clk is found, it returns NULL
 659 * which serves as a dummy clk.  That's the only difference compared
 660 * to devm_clk_get_enabled().
 661 *
 662 * The returned clk (if valid) is prepared and enabled.
 663 *
 664 * The clock will automatically be disabled, unprepared and freed
 665 * when the device is unbound from the bus.
 666 */
 667struct clk *devm_clk_get_optional_enabled(struct device *dev, const char *id);
 668
 669/**
 670 * devm_clk_get_optional_enabled_with_rate - devm_clk_get_optional() +
 671 *                                           clk_set_rate() +
 672 *                                           clk_prepare_enable()
 673 * @dev: device for clock "consumer"
 674 * @id: clock consumer ID
 675 * @rate: new clock rate
 676 *
 677 * Context: May sleep.
 678 *
 679 * Return: a struct clk corresponding to the clock producer, or
 680 * valid IS_ERR() condition containing errno.  The implementation
 681 * uses @dev and @id to determine the clock consumer, and thereby
 682 * the clock producer.  If no such clk is found, it returns NULL
 683 * which serves as a dummy clk.  That's the only difference compared
 684 * to devm_clk_get_enabled().
 685 *
 686 * The returned clk (if valid) is prepared and enabled and rate was set.
 687 *
 688 * The clock will automatically be disabled, unprepared and freed
 689 * when the device is unbound from the bus.
 690 */
 691struct clk *devm_clk_get_optional_enabled_with_rate(struct device *dev,
 692						    const char *id,
 693						    unsigned long rate);
 694
 695/**
 696 * devm_get_clk_from_child - lookup and obtain a managed reference to a
 697 *			     clock producer from child node.
 698 * @dev: device for clock "consumer"
 699 * @np: pointer to clock consumer node
 700 * @con_id: clock consumer ID
 701 *
 702 * This function parses the clocks, and uses them to look up the
 703 * struct clk from the registered list of clock providers by using
 704 * @np and @con_id
 705 *
 706 * The clock will automatically be freed when the device is unbound
 707 * from the bus.
 708 */
 709struct clk *devm_get_clk_from_child(struct device *dev,
 710				    struct device_node *np, const char *con_id);
 711
 712/**
 713 * clk_enable - inform the system when the clock source should be running.
 714 * @clk: clock source
 715 *
 716 * If the clock can not be enabled/disabled, this should return success.
 717 *
 718 * May be called from atomic contexts.
 719 *
 720 * Returns success (0) or negative errno.
 721 */
 722int clk_enable(struct clk *clk);
 723
 724/**
 725 * clk_bulk_enable - inform the system when the set of clks should be running.
 726 * @num_clks: the number of clk_bulk_data
 727 * @clks: the clk_bulk_data table of consumer
 728 *
 729 * May be called from atomic contexts.
 730 *
 731 * Returns success (0) or negative errno.
 732 */
 733int __must_check clk_bulk_enable(int num_clks,
 734				 const struct clk_bulk_data *clks);
 735
 736/**
 737 * clk_disable - inform the system when the clock source is no longer required.
 738 * @clk: clock source
 739 *
 740 * Inform the system that a clock source is no longer required by
 741 * a driver and may be shut down.
 742 *
 743 * May be called from atomic contexts.
 744 *
 745 * Implementation detail: if the clock source is shared between
 746 * multiple drivers, clk_enable() calls must be balanced by the
 747 * same number of clk_disable() calls for the clock source to be
 748 * disabled.
 749 */
 750void clk_disable(struct clk *clk);
 751
 752/**
 753 * clk_bulk_disable - inform the system when the set of clks is no
 754 *		      longer required.
 755 * @num_clks: the number of clk_bulk_data
 756 * @clks: the clk_bulk_data table of consumer
 757 *
 758 * Inform the system that a set of clks is no longer required by
 759 * a driver and may be shut down.
 760 *
 761 * May be called from atomic contexts.
 762 *
 763 * Implementation detail: if the set of clks is shared between
 764 * multiple drivers, clk_bulk_enable() calls must be balanced by the
 765 * same number of clk_bulk_disable() calls for the clock source to be
 766 * disabled.
 767 */
 768void clk_bulk_disable(int num_clks, const struct clk_bulk_data *clks);
 769
 770/**
 771 * clk_get_rate - obtain the current clock rate (in Hz) for a clock source.
 772 *		  This is only valid once the clock source has been enabled.
 773 * @clk: clock source
 774 */
 775unsigned long clk_get_rate(struct clk *clk);
 776
 777/**
 778 * clk_put	- "free" the clock source
 779 * @clk: clock source
 780 *
 781 * Note: drivers must ensure that all clk_enable calls made on this
 782 * clock source are balanced by clk_disable calls prior to calling
 783 * this function.
 784 *
 785 * clk_put should not be called from within interrupt context.
 786 */
 787void clk_put(struct clk *clk);
 788
 789/**
 790 * clk_bulk_put	- "free" the clock source
 791 * @num_clks: the number of clk_bulk_data
 792 * @clks: the clk_bulk_data table of consumer
 793 *
 794 * Note: drivers must ensure that all clk_bulk_enable calls made on this
 795 * clock source are balanced by clk_bulk_disable calls prior to calling
 796 * this function.
 797 *
 798 * clk_bulk_put should not be called from within interrupt context.
 799 */
 800void clk_bulk_put(int num_clks, struct clk_bulk_data *clks);
 801
 802/**
 803 * clk_bulk_put_all - "free" all the clock source
 804 * @num_clks: the number of clk_bulk_data
 805 * @clks: the clk_bulk_data table of consumer
 806 *
 807 * Note: drivers must ensure that all clk_bulk_enable calls made on this
 808 * clock source are balanced by clk_bulk_disable calls prior to calling
 809 * this function.
 810 *
 811 * clk_bulk_put_all should not be called from within interrupt context.
 812 */
 813void clk_bulk_put_all(int num_clks, struct clk_bulk_data *clks);
 814
 815/**
 816 * devm_clk_put	- "free" a managed clock source
 817 * @dev: device used to acquire the clock
 818 * @clk: clock source acquired with devm_clk_get()
 819 *
 820 * Note: drivers must ensure that all clk_enable calls made on this
 821 * clock source are balanced by clk_disable calls prior to calling
 822 * this function.
 823 *
 824 * clk_put should not be called from within interrupt context.
 825 */
 826void devm_clk_put(struct device *dev, struct clk *clk);
 827
 828/*
 829 * The remaining APIs are optional for machine class support.
 830 */
 831
 832
 833/**
 834 * clk_round_rate - adjust a rate to the exact rate a clock can provide
 835 * @clk: clock source
 836 * @rate: desired clock rate in Hz
 837 *
 838 * This answers the question "if I were to pass @rate to clk_set_rate(),
 839 * what clock rate would I end up with?" without changing the hardware
 840 * in any way.  In other words:
 841 *
 842 *   rate = clk_round_rate(clk, r);
 843 *
 844 * and:
 845 *
 846 *   clk_set_rate(clk, r);
 847 *   rate = clk_get_rate(clk);
 848 *
 849 * are equivalent except the former does not modify the clock hardware
 850 * in any way.
 851 *
 852 * Returns rounded clock rate in Hz, or negative errno.
 853 */
 854long clk_round_rate(struct clk *clk, unsigned long rate);
 855
 856/**
 857 * clk_set_rate - set the clock rate for a clock source
 858 * @clk: clock source
 859 * @rate: desired clock rate in Hz
 860 *
 861 * Updating the rate starts at the top-most affected clock and then
 862 * walks the tree down to the bottom-most clock that needs updating.
 863 *
 864 * Returns success (0) or negative errno.
 865 */
 866int clk_set_rate(struct clk *clk, unsigned long rate);
 867
 868/**
 869 * clk_set_rate_exclusive- set the clock rate and claim exclusivity over
 870 *                         clock source
 871 * @clk: clock source
 872 * @rate: desired clock rate in Hz
 873 *
 874 * This helper function allows drivers to atomically set the rate of a producer
 875 * and claim exclusivity over the rate control of the producer.
 876 *
 877 * It is essentially a combination of clk_set_rate() and
 878 * clk_rate_exclusite_get(). Caller must balance this call with a call to
 879 * clk_rate_exclusive_put()
 880 *
 881 * Returns success (0) or negative errno.
 882 */
 883int clk_set_rate_exclusive(struct clk *clk, unsigned long rate);
 884
 885/**
 886 * clk_has_parent - check if a clock is a possible parent for another
 887 * @clk: clock source
 888 * @parent: parent clock source
 889 *
 890 * This function can be used in drivers that need to check that a clock can be
 891 * the parent of another without actually changing the parent.
 892 *
 893 * Returns true if @parent is a possible parent for @clk, false otherwise.
 894 */
 895bool clk_has_parent(const struct clk *clk, const struct clk *parent);
 896
 897/**
 898 * clk_set_rate_range - set a rate range for a clock source
 899 * @clk: clock source
 900 * @min: desired minimum clock rate in Hz, inclusive
 901 * @max: desired maximum clock rate in Hz, inclusive
 902 *
 903 * Returns success (0) or negative errno.
 904 */
 905int clk_set_rate_range(struct clk *clk, unsigned long min, unsigned long max);
 906
 907/**
 908 * clk_set_min_rate - set a minimum clock rate for a clock source
 909 * @clk: clock source
 910 * @rate: desired minimum clock rate in Hz, inclusive
 911 *
 912 * Returns success (0) or negative errno.
 913 */
 914int clk_set_min_rate(struct clk *clk, unsigned long rate);
 915
 916/**
 917 * clk_set_max_rate - set a maximum clock rate for a clock source
 918 * @clk: clock source
 919 * @rate: desired maximum clock rate in Hz, inclusive
 920 *
 921 * Returns success (0) or negative errno.
 922 */
 923int clk_set_max_rate(struct clk *clk, unsigned long rate);
 924
 925/**
 926 * clk_set_parent - set the parent clock source for this clock
 927 * @clk: clock source
 928 * @parent: parent clock source
 929 *
 930 * Returns success (0) or negative errno.
 931 */
 932int clk_set_parent(struct clk *clk, struct clk *parent);
 933
 934/**
 935 * clk_get_parent - get the parent clock source for this clock
 936 * @clk: clock source
 937 *
 938 * Returns struct clk corresponding to parent clock source, or
 939 * valid IS_ERR() condition containing errno.
 940 */
 941struct clk *clk_get_parent(struct clk *clk);
 942
 943/**
 944 * clk_get_sys - get a clock based upon the device name
 945 * @dev_id: device name
 946 * @con_id: connection ID
 947 *
 948 * Returns a struct clk corresponding to the clock producer, or
 949 * valid IS_ERR() condition containing errno.  The implementation
 950 * uses @dev_id and @con_id to determine the clock consumer, and
 951 * thereby the clock producer. In contrast to clk_get() this function
 952 * takes the device name instead of the device itself for identification.
 953 *
 954 * Drivers must assume that the clock source is not enabled.
 955 *
 956 * clk_get_sys should not be called from within interrupt context.
 957 */
 958struct clk *clk_get_sys(const char *dev_id, const char *con_id);
 959
 960#else /* !CONFIG_HAVE_CLK */
 961
 962static inline struct clk *clk_get(struct device *dev, const char *id)
 963{
 964	return NULL;
 965}
 966
 967static inline int __must_check clk_bulk_get(struct device *dev, int num_clks,
 968					    struct clk_bulk_data *clks)
 969{
 970	return 0;
 971}
 972
 973static inline int __must_check clk_bulk_get_optional(struct device *dev,
 974				int num_clks, struct clk_bulk_data *clks)
 975{
 976	return 0;
 977}
 978
 979static inline int __must_check clk_bulk_get_all(struct device *dev,
 980					 struct clk_bulk_data **clks)
 981{
 982	return 0;
 983}
 984
 985static inline struct clk *devm_clk_get(struct device *dev, const char *id)
 986{
 987	return NULL;
 988}
 989
 990static inline struct clk *devm_clk_get_prepared(struct device *dev,
 991						const char *id)
 992{
 993	return NULL;
 994}
 995
 996static inline struct clk *devm_clk_get_enabled(struct device *dev,
 997					       const char *id)
 998{
 999	return NULL;
1000}
1001
1002static inline struct clk *devm_clk_get_optional(struct device *dev,
1003						const char *id)
1004{
1005	return NULL;
1006}
1007
1008static inline struct clk *devm_clk_get_optional_prepared(struct device *dev,
1009							 const char *id)
1010{
1011	return NULL;
1012}
1013
1014static inline struct clk *devm_clk_get_optional_enabled(struct device *dev,
1015							const char *id)
1016{
1017	return NULL;
1018}
1019
1020static inline struct clk *
1021devm_clk_get_optional_enabled_with_rate(struct device *dev, const char *id,
1022					unsigned long rate)
1023{
1024	return NULL;
1025}
1026
1027static inline int __must_check devm_clk_bulk_get(struct device *dev, int num_clks,
1028						 struct clk_bulk_data *clks)
1029{
1030	return 0;
1031}
1032
1033static inline int __must_check devm_clk_bulk_get_optional(struct device *dev,
1034				int num_clks, struct clk_bulk_data *clks)
1035{
1036	return 0;
1037}
1038
1039static inline int __must_check devm_clk_bulk_get_all(struct device *dev,
1040						     struct clk_bulk_data **clks)
1041{
1042
1043	return 0;
1044}
1045
1046static inline int __must_check devm_clk_bulk_get_all_enabled(struct device *dev,
1047						struct clk_bulk_data **clks)
1048{
1049	return 0;
1050}
1051
1052static inline struct clk *devm_get_clk_from_child(struct device *dev,
1053				struct device_node *np, const char *con_id)
1054{
1055	return NULL;
1056}
1057
1058static inline void clk_put(struct clk *clk) {}
1059
1060static inline void clk_bulk_put(int num_clks, struct clk_bulk_data *clks) {}
1061
1062static inline void clk_bulk_put_all(int num_clks, struct clk_bulk_data *clks) {}
1063
1064static inline void devm_clk_put(struct device *dev, struct clk *clk) {}
1065
1066static inline int clk_enable(struct clk *clk)
1067{
1068	return 0;
1069}
1070
1071static inline int __must_check clk_bulk_enable(int num_clks,
1072					       const struct clk_bulk_data *clks)
1073{
1074	return 0;
1075}
1076
1077static inline void clk_disable(struct clk *clk) {}
1078
1079
1080static inline void clk_bulk_disable(int num_clks,
1081				    const struct clk_bulk_data *clks) {}
1082
1083static inline unsigned long clk_get_rate(struct clk *clk)
1084{
1085	return 0;
1086}
1087
1088static inline int clk_set_rate(struct clk *clk, unsigned long rate)
1089{
1090	return 0;
1091}
1092
1093static inline int clk_set_rate_exclusive(struct clk *clk, unsigned long rate)
1094{
1095	return 0;
1096}
1097
1098static inline long clk_round_rate(struct clk *clk, unsigned long rate)
1099{
1100	return 0;
1101}
1102
1103static inline bool clk_has_parent(struct clk *clk, struct clk *parent)
1104{
1105	return true;
1106}
1107
1108static inline int clk_set_rate_range(struct clk *clk, unsigned long min,
1109				     unsigned long max)
1110{
1111	return 0;
1112}
1113
1114static inline int clk_set_min_rate(struct clk *clk, unsigned long rate)
1115{
1116	return 0;
1117}
1118
1119static inline int clk_set_max_rate(struct clk *clk, unsigned long rate)
1120{
1121	return 0;
1122}
1123
1124static inline int clk_set_parent(struct clk *clk, struct clk *parent)
1125{
1126	return 0;
1127}
1128
1129static inline struct clk *clk_get_parent(struct clk *clk)
1130{
1131	return NULL;
1132}
1133
1134static inline struct clk *clk_get_sys(const char *dev_id, const char *con_id)
1135{
1136	return NULL;
1137}
1138
1139#endif
1140
1141/* clk_prepare_enable helps cases using clk_enable in non-atomic context. */
1142static inline int clk_prepare_enable(struct clk *clk)
1143{
1144	int ret;
1145
1146	ret = clk_prepare(clk);
1147	if (ret)
1148		return ret;
1149	ret = clk_enable(clk);
1150	if (ret)
1151		clk_unprepare(clk);
1152
1153	return ret;
1154}
1155
1156/* clk_disable_unprepare helps cases using clk_disable in non-atomic context. */
1157static inline void clk_disable_unprepare(struct clk *clk)
1158{
1159	clk_disable(clk);
1160	clk_unprepare(clk);
1161}
1162
1163static inline int __must_check
1164clk_bulk_prepare_enable(int num_clks, const struct clk_bulk_data *clks)
1165{
1166	int ret;
1167
1168	ret = clk_bulk_prepare(num_clks, clks);
1169	if (ret)
1170		return ret;
1171	ret = clk_bulk_enable(num_clks, clks);
1172	if (ret)
1173		clk_bulk_unprepare(num_clks, clks);
1174
1175	return ret;
1176}
1177
1178static inline void clk_bulk_disable_unprepare(int num_clks,
1179					      const struct clk_bulk_data *clks)
1180{
1181	clk_bulk_disable(num_clks, clks);
1182	clk_bulk_unprepare(num_clks, clks);
1183}
1184
1185/**
1186 * clk_drop_range - Reset any range set on that clock
1187 * @clk: clock source
1188 *
1189 * Returns success (0) or negative errno.
1190 */
1191static inline int clk_drop_range(struct clk *clk)
1192{
1193	return clk_set_rate_range(clk, 0, ULONG_MAX);
1194}
1195
1196/**
1197 * clk_get_optional - lookup and obtain a reference to an optional clock
1198 *		      producer.
1199 * @dev: device for clock "consumer"
1200 * @id: clock consumer ID
1201 *
1202 * Behaves the same as clk_get() except where there is no clock producer. In
1203 * this case, instead of returning -ENOENT, the function returns NULL.
1204 */
1205static inline struct clk *clk_get_optional(struct device *dev, const char *id)
1206{
1207	struct clk *clk = clk_get(dev, id);
1208
1209	if (clk == ERR_PTR(-ENOENT))
1210		return NULL;
1211
1212	return clk;
1213}
1214
1215#if defined(CONFIG_OF) && defined(CONFIG_COMMON_CLK)
1216struct clk *of_clk_get(struct device_node *np, int index);
1217struct clk *of_clk_get_by_name(struct device_node *np, const char *name);
1218struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec);
1219#else
1220static inline struct clk *of_clk_get(struct device_node *np, int index)
1221{
1222	return ERR_PTR(-ENOENT);
1223}
1224static inline struct clk *of_clk_get_by_name(struct device_node *np,
1225					     const char *name)
1226{
1227	return ERR_PTR(-ENOENT);
1228}
1229static inline struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec)
1230{
1231	return ERR_PTR(-ENOENT);
1232}
1233#endif
1234
1235#endif