include/linux/clk.h

1 /* SPDX-License-Identifier: GPL-2.0-only */
7  *  Copyright (C) 2011-2012 Linaro Ltd <mturquette@linaro.org>
24  * PRE_RATE_CHANGE - called immediately before the clk rate is changed,
35  * POST_RATE_CHANGE - called after the clk rate change has successfully
44  * struct clk_notifier - associate a clk with a notifier
61  * struct clk_notifier_data - rate data to pass to the notifier callback
66  * For a pre-notifier, old_rate is the clk's rate before this rate
68  * post-notifier, old_rate and new_rate are both set to the clk's
78  * struct clk_bulk_data - Data used for bulk clk operations.
80  * @id: clock consumer ID
81  * @clk: struct clk * to store the associated clock
95  * clk_notifier_register - register a clock rate-change notifier callback
96  * @clk: clock whose rate we are interested in
106  * clk_notifier_unregister - unregister a clock rate-change notifier callback
107  * @clk: clock whose rate we are no longer interested in
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
118  * Returns 0 on success, -EERROR otherwise
124  * clk_get_accuracy - obtain the clock accuracy in ppb (parts per billion)
125  *		      for a clock source.
126  * @clk: clock source
128  * This gets the clock source accuracy expressed in ppb.
129  * A perfect clock returns 0.
134  * clk_set_phase - adjust the phase shift of a clock signal
135  * @clk: clock signal source
138  * Shifts the phase of a clock signal by the specified degrees. Returns 0 on
139  * success, -EERROR otherwise.
144  * clk_get_phase - return the phase shift of a clock signal
145  * @clk: clock signal source
147  * Returns the phase shift of a clock node in degrees, otherwise returns
148  * -EERROR.
153  * clk_set_duty_cycle - adjust the duty cycle ratio of a clock signal
154  * @clk: clock signal source
158  * Adjust the duty cycle of a clock signal by the specified ratio. Returns 0 on
159  * success, -EERROR otherwise.
164  * clk_get_scaled_duty_cycle - return the duty cycle ratio of a clock signal
165  * @clk: clock signal source
169  * returns -EERROR.
174  * clk_is_match - check if two clk's point to the same hardware clock
179  * clock node. Put differently, returns true if @p and @q
187  * clk_rate_exclusive_get - get exclusivity over the rate control of a
189  * @clk: clock source
195  * If exlusivity is claimed more than once on clock, even by the same driver,
205  * clk_rate_exclusive_put - release exclusivity over the rate control of a
207  * @clk: clock source
224 	return -ENOTSUPP;  in clk_notifier_register()
230 	return -ENOTSUPP;  in clk_notifier_unregister()
237 	return -ENOTSUPP;  in devm_clk_notifier_register()
242 	return -ENOTSUPP;  in clk_get_accuracy()
247 	return -ENOTSUPP;  in clk_set_phase()
252 	return -ENOTSUPP;  in clk_get_phase()
258 	return -ENOTSUPP;  in clk_set_duty_cycle()
283  * clk_prepare - prepare a clock source
284  * @clk: clock source
286  * This prepares the clock source for use.
295  * clk_is_enabled_when_prepared - indicate if preparing a clock also enables it.
296  * @clk: clock source
298  * Returns true if clk_prepare() implicitly enables the clock, effectively
299  * making clk_enable()/clk_disable() no-ops, false otherwise.
302  * disabling the clock also requires unpreparing it to have any material
331  * clk_unprepare - undo preparation of a clock source
332  * @clk: clock source
334  * This undoes a previously prepared clock.  The caller must balance
356  * clk_get - lookup and obtain a reference to a clock producer.
357  * @dev: device for clock "consumer"
358  * @id: clock consumer ID
360  * Returns a struct clk corresponding to the clock producer, or
362  * uses @dev and @id to determine the clock consumer, and thereby
363  * the clock producer.  (IOW, @id may be identical strings, but
364  * clk_get may return different clock producers depending on @dev.)
366  * Drivers must assume that the clock source is not enabled.
373  * clk_bulk_get - lookup and obtain a number of references to clock producer.
374  * @dev: device for clock "consumer"
385  * clock consumer, and thereby the clock producer.
386  * The clock returned is stored in each @clk_bulk_data.clk field.
388  * Drivers must assume that the clock source is not enabled.
395  * clk_bulk_get_all - lookup and obtain all available references to clock
397  * @dev: device for clock "consumer"
405  * clock references are stored in the clk_bulk_data table in @clks field.
408  * Drivers must assume that the clock source is not enabled.
416  * clk_bulk_get_optional - lookup and obtain a number of references to clock producer
417  * @dev: device for clock "consumer"
421  * Behaves the same as clk_bulk_get() except where there is no clock producer.
422  * In this case, instead of returning -ENOENT, the function returns 0 and
423  * NULL for a clk for which a clock producer could not be determined.
428  * devm_clk_bulk_get - managed get multiple clk consumers
429  * @dev: device for clock "consumer"
442  * devm_clk_bulk_get_optional - managed get multiple optional consumer clocks
443  * @dev: device for clock "consumer"
447  * Behaves the same as devm_clk_bulk_get() except where there is no clock
448  * producer.  In this case, instead of returning -ENOENT, the function returns
455  * clock consumer, and thereby the clock producer.
456  * The clock returned is stored in each @clk_bulk_data.clk field.
458  * Drivers must assume that the clock source is not enabled.
465  * devm_clk_bulk_get_all - managed get multiple clk consumers
466  * @dev: device for clock "consumer"
470  * clock references are stored in the clk_bulk_data table in @clks field.
482  * devm_clk_get - lookup and obtain a managed reference to a clock producer.
483  * @dev: device for clock "consumer"
484  * @id: clock consumer ID
488  * Return: a struct clk corresponding to the clock producer, or
490  * uses @dev and @id to determine the clock consumer, and thereby
491  * the clock producer.  (IOW, @id may be identical strings, but
492  * clk_get may return different clock producers depending on @dev.)
494  * Drivers must assume that the clock source is neither prepared nor
497  * The clock will automatically be freed when the device is unbound
503  * devm_clk_get_prepared - devm_clk_get() + clk_prepare()
504  * @dev: device for clock "consumer"
505  * @id: clock consumer ID
509  * Return: a struct clk corresponding to the clock producer, or
511  * uses @dev and @id to determine the clock consumer, and thereby
512  * the clock producer.  (IOW, @id may be identical strings, but
513  * clk_get may return different clock producers depending on @dev.)
516  * that the clock is not enabled.
518  * The clock will automatically be unprepared and freed when the device
524  * devm_clk_get_enabled - devm_clk_get() + clk_prepare_enable()
525  * @dev: device for clock "consumer"
526  * @id: clock consumer ID
530  * Return: a struct clk corresponding to the clock producer, or
532  * uses @dev and @id to determine the clock consumer, and thereby
533  * the clock producer.  (IOW, @id may be identical strings, but
534  * clk_get may return different clock producers depending on @dev.)
538  * The clock will automatically be disabled, unprepared and freed
544  * devm_clk_get_optional - lookup and obtain a managed reference to an optional
545  *			   clock producer.
546  * @dev: device for clock "consumer"
547  * @id: clock consumer ID
551  * Return: a struct clk corresponding to the clock producer, or
553  * uses @dev and @id to determine the clock consumer, and thereby
554  * the clock producer.  If no such clk is found, it returns NULL
558  * Drivers must assume that the clock source is neither prepared nor
561  * The clock will automatically be freed when the device is unbound
567  * devm_clk_get_optional_prepared - devm_clk_get_optional() + clk_prepare()
568  * @dev: device for clock "consumer"
569  * @id: clock consumer ID
573  * Return: a struct clk corresponding to the clock producer, or
575  * uses @dev and @id to determine the clock consumer, and thereby
576  * the clock producer.  If no such clk is found, it returns NULL
581  * assume that the clock is not enabled.
583  * The clock will automatically be unprepared and freed when the
589  * devm_clk_get_optional_enabled - devm_clk_get_optional() +
591  * @dev: device for clock "consumer"
592  * @id: clock consumer ID
596  * Return: a struct clk corresponding to the clock producer, or
598  * uses @dev and @id to determine the clock consumer, and thereby
599  * the clock producer.  If no such clk is found, it returns NULL
605  * The clock will automatically be disabled, unprepared and freed
611  * devm_get_clk_from_child - lookup and obtain a managed reference to a
612  *			     clock producer from child node.
613  * @dev: device for clock "consumer"
614  * @np: pointer to clock consumer node
615  * @con_id: clock consumer ID
618  * struct clk from the registered list of clock providers by using
621  * The clock will automatically be freed when the device is unbound
628  * clk_enable - inform the system when the clock source should be running.
629  * @clk: clock source
631  * If the clock can not be enabled/disabled, this should return success.
640  * clk_bulk_enable - inform the system when the set of clks should be running.
652  * clk_disable - inform the system when the clock source is no longer required.
653  * @clk: clock source
655  * Inform the system that a clock source is no longer required by
660  * Implementation detail: if the clock source is shared between
662  * same number of clk_disable() calls for the clock source to be
668  * clk_bulk_disable - inform the system when the set of clks is no
680  * same number of clk_bulk_disable() calls for the clock source to be
686  * clk_get_rate - obtain the current clock rate (in Hz) for a clock source.
687  *		  This is only valid once the clock source has been enabled.
688  * @clk: clock source
693  * clk_put	- "free" the clock source
694  * @clk: clock source
697  * clock source are balanced by clk_disable calls prior to calling
705  * clk_bulk_put	- "free" the clock source
710  * clock source are balanced by clk_bulk_disable calls prior to calling
718  * clk_bulk_put_all - "free" all the clock source
723  * clock source are balanced by clk_bulk_disable calls prior to calling
731  * devm_clk_put	- "free" a managed clock source
732  * @dev: device used to acquire the clock
733  * @clk: clock source acquired with devm_clk_get()
736  * clock source are balanced by clk_disable calls prior to calling
749  * clk_round_rate - adjust a rate to the exact rate a clock can provide
750  * @clk: clock source
751  * @rate: desired clock rate in Hz
754  * what clock rate would I end up with?" without changing the hardware
764  * are equivalent except the former does not modify the clock hardware
767  * Returns rounded clock rate in Hz, or negative errno.
772  * clk_set_rate - set the clock rate for a clock source
773  * @clk: clock source
774  * @rate: desired clock rate in Hz
776  * Updating the rate starts at the top-most affected clock and then
777  * walks the tree down to the bottom-most clock that needs updating.
784  * clk_set_rate_exclusive- set the clock rate and claim exclusivity over
785  *                         clock source
786  * @clk: clock source
787  * @rate: desired clock rate in Hz
801  * clk_has_parent - check if a clock is a possible parent for another
802  * @clk: clock source
803  * @parent: parent clock source
805  * This function can be used in drivers that need to check that a clock can be
813  * clk_set_rate_range - set a rate range for a clock source
814  * @clk: clock source
815  * @min: desired minimum clock rate in Hz, inclusive
816  * @max: desired maximum clock rate in Hz, inclusive
823  * clk_set_min_rate - set a minimum clock rate for a clock source
824  * @clk: clock source
825  * @rate: desired minimum clock rate in Hz, inclusive
832  * clk_set_max_rate - set a maximum clock rate for a clock source
833  * @clk: clock source
834  * @rate: desired maximum clock rate in Hz, inclusive
841  * clk_set_parent - set the parent clock source for this clock
842  * @clk: clock source
843  * @parent: parent clock source
850  * clk_get_parent - get the parent clock source for this clock
851  * @clk: clock source
853  * Returns struct clk corresponding to parent clock source, or
859  * clk_get_sys - get a clock based upon the device name
863  * Returns a struct clk corresponding to the clock producer, or
865  * uses @dev_id and @con_id to determine the clock consumer, and
866  * thereby the clock producer. In contrast to clk_get() this function
869  * Drivers must assume that the clock source is not enabled.
876  * clk_save_context - save clock context for poweroff
878  * Saves the context of the clock register for powerstates in which the
885  * clk_restore_context - restore clock context after poweroff
1067 /* clk_prepare_enable helps cases using clk_enable in non-atomic context. */
1082 /* clk_disable_unprepare helps cases using clk_disable in non-atomic context. */
1112  * clk_drop_range - Reset any range set on that clock
1113  * @clk: clock source
1123  * clk_get_optional - lookup and obtain a reference to an optional clock
1125  * @dev: device for clock "consumer"
1126  * @id: clock consumer ID
1128  * Behaves the same as clk_get() except where there is no clock producer. In
1129  * this case, instead of returning -ENOENT, the function returns NULL.
1135 	if (clk == ERR_PTR(-ENOENT))  in clk_get_optional()
1148 	return ERR_PTR(-ENOENT);  in of_clk_get()
1153 	return ERR_PTR(-ENOENT);  in of_clk_get_by_name()
1157 	return ERR_PTR(-ENOENT);  in of_clk_get_from_provider()