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  * devm_clk_rate_exclusive_get - devm variant of clk_rate_exclusive_get
207  * @clk: clock source
217  * clk_rate_exclusive_put - release exclusivity over the rate control of a
219  * @clk: clock source
236 	return -ENOTSUPP;  in clk_notifier_register()
242 	return -ENOTSUPP;  in clk_notifier_unregister()
249 	return -ENOTSUPP;  in devm_clk_notifier_register()
254 	return -ENOTSUPP;  in clk_get_accuracy()
259 	return -ENOTSUPP;  in clk_set_phase()
264 	return -ENOTSUPP;  in clk_get_phase()
270 	return -ENOTSUPP;  in clk_set_duty_cycle()
300  * clk_prepare - prepare a clock source
301  * @clk: clock source
303  * This prepares the clock source for use.
312  * clk_is_enabled_when_prepared - indicate if preparing a clock also enables it.
313  * @clk: clock source
315  * Returns true if clk_prepare() implicitly enables the clock, effectively
316  * making clk_enable()/clk_disable() no-ops, false otherwise.
319  * disabling the clock also requires unpreparing it to have any material
348  * clk_unprepare - undo preparation of a clock source
349  * @clk: clock source
351  * This undoes a previously prepared clock.  The caller must balance
373  * clk_get - lookup and obtain a reference to a clock producer.
374  * @dev: device for clock "consumer"
375  * @id: clock consumer ID
377  * Returns a struct clk corresponding to the clock producer, or
379  * uses @dev and @id to determine the clock consumer, and thereby
380  * the clock producer.  (IOW, @id may be identical strings, but
381  * clk_get may return different clock producers depending on @dev.)
383  * Drivers must assume that the clock source is not enabled.
390  * clk_bulk_get - lookup and obtain a number of references to clock producer.
391  * @dev: device for clock "consumer"
402  * clock consumer, and thereby the clock producer.
403  * The clock returned is stored in each @clk_bulk_data.clk field.
405  * Drivers must assume that the clock source is not enabled.
412  * clk_bulk_get_all - lookup and obtain all available references to clock
414  * @dev: device for clock "consumer"
422  * clock references are stored in the clk_bulk_data table in @clks field.
425  * Drivers must assume that the clock source is not enabled.
433  * clk_bulk_get_optional - lookup and obtain a number of references to clock producer
434  * @dev: device for clock "consumer"
438  * Behaves the same as clk_bulk_get() except where there is no clock producer.
439  * In this case, instead of returning -ENOENT, the function returns 0 and
440  * NULL for a clk for which a clock producer could not be determined.
445  * devm_clk_bulk_get - managed get multiple clk consumers
446  * @dev: device for clock "consumer"
459  * devm_clk_bulk_get_optional - managed get multiple optional consumer clocks
460  * @dev: device for clock "consumer"
464  * Behaves the same as devm_clk_bulk_get() except where there is no clock
465  * producer.  In this case, instead of returning -ENOENT, the function returns
472  * clock consumer, and thereby the clock producer.
473  * The clock returned is stored in each @clk_bulk_data.clk field.
475  * Drivers must assume that the clock source is not enabled.
482  * devm_clk_bulk_get_all - managed get multiple clk consumers
483  * @dev: device for clock "consumer"
487  * clock references are stored in the clk_bulk_data table in @clks field.
499  * devm_clk_bulk_get_all_enable - Get and enable all clocks of the consumer (managed)
500  * @dev: device for clock "consumer"
515  * devm_clk_get - lookup and obtain a managed reference to a clock producer.
516  * @dev: device for clock "consumer"
517  * @id: clock consumer ID
521  * Return: a struct clk corresponding to the clock producer, or
523  * uses @dev and @id to determine the clock consumer, and thereby
524  * the clock producer.  (IOW, @id may be identical strings, but
525  * clk_get may return different clock producers depending on @dev.)
527  * Drivers must assume that the clock source is neither prepared nor
530  * The clock will automatically be freed when the device is unbound
536  * devm_clk_get_prepared - devm_clk_get() + clk_prepare()
537  * @dev: device for clock "consumer"
538  * @id: clock consumer ID
542  * Return: a struct clk corresponding to the clock producer, or
544  * uses @dev and @id to determine the clock consumer, and thereby
545  * the clock producer.  (IOW, @id may be identical strings, but
546  * clk_get may return different clock producers depending on @dev.)
549  * that the clock is not enabled.
551  * The clock will automatically be unprepared and freed when the device
557  * devm_clk_get_enabled - devm_clk_get() + clk_prepare_enable()
558  * @dev: device for clock "consumer"
559  * @id: clock consumer ID
563  * Return: a struct clk corresponding to the clock producer, or
565  * uses @dev and @id to determine the clock consumer, and thereby
566  * the clock producer.  (IOW, @id may be identical strings, but
567  * clk_get may return different clock producers depending on @dev.)
571  * The clock will automatically be disabled, unprepared and freed
577  * devm_clk_get_optional - lookup and obtain a managed reference to an optional
578  *			   clock producer.
579  * @dev: device for clock "consumer"
580  * @id: clock consumer ID
584  * Return: a struct clk corresponding to the clock producer, or
586  * uses @dev and @id to determine the clock consumer, and thereby
587  * the clock producer.  If no such clk is found, it returns NULL
591  * Drivers must assume that the clock source is neither prepared nor
594  * The clock will automatically be freed when the device is unbound
600  * devm_clk_get_optional_prepared - devm_clk_get_optional() + clk_prepare()
601  * @dev: device for clock "consumer"
602  * @id: clock consumer ID
606  * Return: a struct clk corresponding to the clock producer, or
608  * uses @dev and @id to determine the clock consumer, and thereby
609  * the clock producer.  If no such clk is found, it returns NULL
614  * assume that the clock is not enabled.
616  * The clock will automatically be unprepared and freed when the
622  * devm_clk_get_optional_enabled - devm_clk_get_optional() +
624  * @dev: device for clock "consumer"
625  * @id: clock consumer ID
629  * Return: a struct clk corresponding to the clock producer, or
631  * uses @dev and @id to determine the clock consumer, and thereby
632  * the clock producer.  If no such clk is found, it returns NULL
638  * The clock will automatically be disabled, unprepared and freed
644  * devm_clk_get_optional_enabled_with_rate - devm_clk_get_optional() +
647  * @dev: device for clock "consumer"
648  * @id: clock consumer ID
649  * @rate: new clock rate
653  * Return: a struct clk corresponding to the clock producer, or
655  * uses @dev and @id to determine the clock consumer, and thereby
656  * the clock producer.  If no such clk is found, it returns NULL
662  * The clock will automatically be disabled, unprepared and freed
670  * devm_get_clk_from_child - lookup and obtain a managed reference to a
671  *			     clock producer from child node.
672  * @dev: device for clock "consumer"
673  * @np: pointer to clock consumer node
674  * @con_id: clock consumer ID
677  * struct clk from the registered list of clock providers by using
680  * The clock will automatically be freed when the device is unbound
687  * clk_enable - inform the system when the clock source should be running.
688  * @clk: clock source
690  * If the clock can not be enabled/disabled, this should return success.
699  * clk_bulk_enable - inform the system when the set of clks should be running.
711  * clk_disable - inform the system when the clock source is no longer required.
712  * @clk: clock source
714  * Inform the system that a clock source is no longer required by
719  * Implementation detail: if the clock source is shared between
721  * same number of clk_disable() calls for the clock source to be
727  * clk_bulk_disable - inform the system when the set of clks is no
739  * same number of clk_bulk_disable() calls for the clock source to be
745  * clk_get_rate - obtain the current clock rate (in Hz) for a clock source.
746  *		  This is only valid once the clock source has been enabled.
747  * @clk: clock source
752  * clk_put	- "free" the clock source
753  * @clk: clock source
756  * clock source are balanced by clk_disable calls prior to calling
764  * clk_bulk_put	- "free" the clock source
769  * clock source are balanced by clk_bulk_disable calls prior to calling
777  * clk_bulk_put_all - "free" all the clock source
782  * clock source are balanced by clk_bulk_disable calls prior to calling
790  * devm_clk_put	- "free" a managed clock source
791  * @dev: device used to acquire the clock
792  * @clk: clock source acquired with devm_clk_get()
795  * clock source are balanced by clk_disable calls prior to calling
808  * clk_round_rate - adjust a rate to the exact rate a clock can provide
809  * @clk: clock source
810  * @rate: desired clock rate in Hz
813  * what clock rate would I end up with?" without changing the hardware
823  * are equivalent except the former does not modify the clock hardware
826  * Returns rounded clock rate in Hz, or negative errno.
831  * clk_set_rate - set the clock rate for a clock source
832  * @clk: clock source
833  * @rate: desired clock rate in Hz
835  * Updating the rate starts at the top-most affected clock and then
836  * walks the tree down to the bottom-most clock that needs updating.
843  * clk_set_rate_exclusive- set the clock rate and claim exclusivity over
844  *                         clock source
845  * @clk: clock source
846  * @rate: desired clock rate in Hz
860  * clk_has_parent - check if a clock is a possible parent for another
861  * @clk: clock source
862  * @parent: parent clock source
864  * This function can be used in drivers that need to check that a clock can be
872  * clk_set_rate_range - set a rate range for a clock source
873  * @clk: clock source
874  * @min: desired minimum clock rate in Hz, inclusive
875  * @max: desired maximum clock rate in Hz, inclusive
882  * clk_set_min_rate - set a minimum clock rate for a clock source
883  * @clk: clock source
884  * @rate: desired minimum clock rate in Hz, inclusive
891  * clk_set_max_rate - set a maximum clock rate for a clock source
892  * @clk: clock source
893  * @rate: desired maximum clock rate in Hz, inclusive
900  * clk_set_parent - set the parent clock source for this clock
901  * @clk: clock source
902  * @parent: parent clock source
909  * clk_get_parent - get the parent clock source for this clock
910  * @clk: clock source
912  * Returns struct clk corresponding to parent clock source, or
918  * clk_get_sys - get a clock based upon the device name
922  * Returns a struct clk corresponding to the clock producer, or
924  * uses @dev_id and @con_id to determine the clock consumer, and
925  * thereby the clock producer. In contrast to clk_get() this function
928  * Drivers must assume that the clock source is not enabled.
935  * clk_save_context - save clock context for poweroff
937  * Saves the context of the clock register for powerstates in which the
944  * clk_restore_context - restore clock context after poweroff
1139 /* clk_prepare_enable helps cases using clk_enable in non-atomic context. */
1154 /* clk_disable_unprepare helps cases using clk_disable in non-atomic context. */
1184  * clk_drop_range - Reset any range set on that clock
1185  * @clk: clock source
1195  * clk_get_optional - lookup and obtain a reference to an optional clock
1197  * @dev: device for clock "consumer"
1198  * @id: clock consumer ID
1200  * Behaves the same as clk_get() except where there is no clock producer. In
1201  * this case, instead of returning -ENOENT, the function returns NULL.
1207 	if (clk == ERR_PTR(-ENOENT))  in clk_get_optional()
1220 	return ERR_PTR(-ENOENT);  in of_clk_get()
1225 	return ERR_PTR(-ENOENT);  in of_clk_get_by_name()
1229 	return ERR_PTR(-ENOENT);  in of_clk_get_from_provider()