1 /* SPDX-License-Identifier: GPL-2.0-only */
3  *  linux/include/linux/clk.h
7  *  Copyright (C) 2011-2012 Linaro Ltd <[email protected]>
17 struct clk;
22  * DOC: clk notifier callback types
24  * PRE_RATE_CHANGE - called immediately before the clk rate is changed,
25  *     to indicate that the rate change will proceed.  Drivers must
27  *     rate change.  Callbacks may either return NOTIFY_DONE, NOTIFY_OK,
30  * ABORT_RATE_CHANGE: called if the rate change failed for some reason
32  *     the clk will be called with ABORT_RATE_CHANGE. Callbacks must
35  * POST_RATE_CHANGE - called after the clk rate change has successfully
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
51  * particular @clk.  Future notifiers on that @clk are added to the
55 	struct clk			*clk;  member
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
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).
72 	struct clk		*clk;  member
78  * struct clk_bulk_data - Data used for bulk clk operations.
81  * @clk: struct clk * to store the associated clock
83  * The CLK APIs provide a series of clk_bulk_() API calls as
89 	struct clk		*clk;  member
95  * clk_notifier_register - register a clock rate-change notifier callback
96  * @clk: clock whose rate we are interested in
103 int clk_notifier_register(struct clk *clk, struct notifier_block *nb);
106  * clk_notifier_unregister - unregister a clock rate-change notifier callback
107  * @clk: clock whose rate we are no longer interested in
110 int clk_notifier_unregister(struct clk *clk, struct notifier_block *nb);
113  * devm_clk_notifier_register - register a managed rate-change notifier callback
115  * @clk: clock whose rate we are interested in
118  * Returns 0 on success, -EERROR otherwise
120 int devm_clk_notifier_register(struct device *dev, struct clk *clk,
124  * clk_get_accuracy - obtain the clock accuracy in ppb (parts per billion)
126  * @clk: clock source
131 long clk_get_accuracy(struct clk *clk);
134  * clk_set_phase - adjust the phase shift of a clock signal
135  * @clk: clock signal source
139  * success, -EERROR otherwise.
141 int clk_set_phase(struct clk *clk, int degrees);
144  * clk_get_phase - return the phase shift of a clock signal
145  * @clk: clock signal source
148  * -EERROR.
150 int clk_get_phase(struct clk *clk);
153  * clk_set_duty_cycle - adjust the duty cycle ratio of a clock signal
154  * @clk: clock signal source
159  * success, -EERROR otherwise.
161 int clk_set_duty_cycle(struct clk *clk, unsigned int num, unsigned int den);
164  * clk_get_scaled_duty_cycle - return the duty cycle ratio of a clock signal
165  * @clk: clock signal source
169  * returns -EERROR.
171 int clk_get_scaled_duty_cycle(struct clk *clk, unsigned int scale);
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
178  * Returns true if the two struct clk pointers both point to the same hardware
184 bool clk_is_match(const struct clk *p, const struct clk *q);
187  * clk_rate_exclusive_get - get exclusivity over the rate control of a
189  * @clk: clock source
191  * This function allows drivers to get exclusive control over the rate of a
193  * opereation which could alter the rate of the provider or cause glitches
196  * the rate effectively gets locked as exclusivity can't be preempted.
202 int clk_rate_exclusive_get(struct clk *clk);
205  * devm_clk_rate_exclusive_get - devm variant of clk_rate_exclusive_get
207  * @clk: clock source
209  * Calls clk_rate_exclusive_get() on @clk and registers a devm cleanup handler
214 int devm_clk_rate_exclusive_get(struct device *dev, struct clk *clk);
217  * clk_rate_exclusive_put - release exclusivity over the rate control of a
219  * @clk: clock source
229 void clk_rate_exclusive_put(struct clk *clk);
233 static inline int clk_notifier_register(struct clk *clk,  in clk_notifier_register()  argument
236 	return -ENOTSUPP;  in clk_notifier_register()
239 static inline int clk_notifier_unregister(struct clk *clk,  in clk_notifier_unregister()  argument
242 	return -ENOTSUPP;  in clk_notifier_unregister()
246 					     struct clk *clk,  in devm_clk_notifier_register()  argument
249 	return -ENOTSUPP;  in devm_clk_notifier_register()
252 static inline long clk_get_accuracy(struct clk *clk)  in clk_get_accuracy()  argument
254 	return -ENOTSUPP;  in clk_get_accuracy()
257 static inline long clk_set_phase(struct clk *clk, int phase)  in clk_set_phase()  argument
259 	return -ENOTSUPP;  in clk_set_phase()
262 static inline long clk_get_phase(struct clk *clk)  in clk_get_phase()  argument
264 	return -ENOTSUPP;  in clk_get_phase()
267 static inline int clk_set_duty_cycle(struct clk *clk, unsigned int num,  in clk_set_duty_cycle()  argument
270 	return -ENOTSUPP;  in clk_set_duty_cycle()
273 static inline unsigned int clk_get_scaled_duty_cycle(struct clk *clk,  in clk_get_scaled_duty_cycle()  argument
279 static inline bool clk_is_match(const struct clk *p, const struct clk *q)  in clk_is_match()
284 static inline int clk_rate_exclusive_get(struct clk *clk)  in clk_rate_exclusive_get()  argument
289 static inline int devm_clk_rate_exclusive_get(struct device *dev, struct clk *clk)  in devm_clk_rate_exclusive_get()  argument
294 static inline void clk_rate_exclusive_put(struct clk *clk) {}  in clk_rate_exclusive_put()  argument
300  * clk_prepare - prepare a clock source
301  * @clk: clock source
307 int clk_prepare(struct clk *clk);
312  * clk_is_enabled_when_prepared - indicate if preparing a clock also enables it.
313  * @clk: clock source
316  * making clk_enable()/clk_disable() no-ops, false otherwise.
326 bool clk_is_enabled_when_prepared(struct clk *clk);
328 static inline int clk_prepare(struct clk *clk)  in clk_prepare()  argument
341 static inline bool clk_is_enabled_when_prepared(struct clk *clk)  in clk_is_enabled_when_prepared()  argument
348  * clk_unprepare - undo preparation of a clock source
349  * @clk: clock source
357 void clk_unprepare(struct clk *clk);
360 static inline void clk_unprepare(struct clk *clk)  in clk_unprepare()  argument
373  * clk_get - lookup and obtain a reference to a clock producer.
377  * Returns a struct clk corresponding to the clock producer, or
387 struct clk *clk_get(struct device *dev, const char *id);
390  * clk_bulk_get - lookup and obtain a number of references to clock producer.
395  * This helper function allows drivers to get several clk consumers in one
396  * operation. If any of the clk cannot be acquired then any clks
403  * The clock returned is stored in each @clk_bulk_data.clk field.
412  * clk_bulk_get_all - lookup and obtain all available references to clock
417  * This helper function allows drivers to get all clk consumers in one
418  * operation. If any of the clk cannot be acquired then any clks
433  * clk_bulk_get_optional - lookup and obtain a number of references to 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
452  * This helper function allows drivers to get several clk
459  * devm_clk_bulk_get_optional - managed get multiple optional consumer clocks
465  * producer.  In this case, instead of returning -ENOENT, the function returns
466  * NULL for given clk. It is assumed all clocks in clk_bulk_data are optional.
469  * successfully or for any clk there was no clk provider available, otherwise
473  * The clock returned is stored in each @clk_bulk_data.clk field.
482  * devm_clk_bulk_get_all - managed get multiple clk consumers
490  * This helper function allows drivers to get several clk
499  * devm_clk_bulk_get_all_enabled - Get and enable all clocks of the consumer (managed)
517  * devm_clk_get - lookup and obtain a managed reference to a clock producer.
523  * Return: a struct clk corresponding to the clock producer, or
535 struct clk *devm_clk_get(struct device *dev, const char *id);
538  * devm_clk_get_prepared - devm_clk_get() + clk_prepare()
544  * Return: a struct clk corresponding to the clock producer, or
550  * The returned clk (if valid) is prepared. Drivers must however assume
556 struct clk *devm_clk_get_prepared(struct device *dev, const char *id);
559  * devm_clk_get_enabled - devm_clk_get() + clk_prepare_enable()
565  * Return: a struct clk corresponding to the clock producer, or
571  * The returned clk (if valid) is prepared and enabled.
576 struct clk *devm_clk_get_enabled(struct device *dev, const char *id);
579  * devm_clk_get_optional - lookup and obtain a managed reference to an optional
586  * Return: a struct clk corresponding to the clock producer, or
589  * the clock producer.  If no such clk is found, it returns NULL
590  * which serves as a dummy clk.  That's the only difference compared
599 struct clk *devm_clk_get_optional(struct device *dev, const char *id);
602  * devm_clk_get_optional_prepared - devm_clk_get_optional() + clk_prepare()
608  * Return: a struct clk corresponding to the clock producer, or
611  * the clock producer.  If no such clk is found, it returns NULL
612  * which serves as a dummy clk.  That's the only difference compared
615  * The returned clk (if valid) is prepared. Drivers must however
621 struct clk *devm_clk_get_optional_prepared(struct device *dev, const char *id);
624  * devm_clk_get_optional_enabled - devm_clk_get_optional() +
631  * Return: a struct clk corresponding to the clock producer, or
634  * the clock producer.  If no such clk is found, it returns NULL
635  * which serves as a dummy clk.  That's the only difference compared
638  * The returned clk (if valid) is prepared and enabled.
643 struct clk *devm_clk_get_optional_enabled(struct device *dev, const char *id);
646  * devm_clk_get_optional_enabled_with_rate - devm_clk_get_optional() +
651  * @rate: new clock rate
655  * Return: a struct clk corresponding to the clock producer, or
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
662  * The returned clk (if valid) is prepared and enabled and rate was set.
667 struct clk *devm_clk_get_optional_enabled_with_rate(struct device *dev,
669 						    unsigned long rate);
672  * devm_get_clk_from_child - lookup and obtain a managed reference to a
679  * struct clk from the registered list of clock providers by using
685 struct clk *devm_get_clk_from_child(struct device *dev,
689  * clk_enable - inform the system when the clock source should be running.
690  * @clk: clock source
698 int clk_enable(struct clk *clk);
701  * clk_bulk_enable - inform the system when the set of clks should be running.
713  * clk_disable - inform the system when the clock source is no longer required.
714  * @clk: clock source
726 void clk_disable(struct clk *clk);
729  * clk_bulk_disable - inform the system when the set of clks is no
747  * clk_get_rate - obtain the current clock rate (in Hz) for a clock source.
749  * @clk: clock source
751 unsigned long clk_get_rate(struct clk *clk);
754  * clk_put	- "free" the clock source
755  * @clk: clock source
763 void clk_put(struct clk *clk);
766  * clk_bulk_put	- "free" the clock source
779  * clk_bulk_put_all - "free" all the clock source
792  * devm_clk_put	- "free" a managed clock source
794  * @clk: clock source acquired with devm_clk_get()
802 void devm_clk_put(struct device *dev, struct clk *clk);
810  * clk_round_rate - adjust a rate to the exact rate a clock can provide
811  * @clk: clock source
812  * @rate: desired clock rate in Hz
814  * This answers the question "if I were to pass @rate to clk_set_rate(),
815  * what clock rate would I end up with?" without changing the hardware
818  *   rate = clk_round_rate(clk, r);
822  *   clk_set_rate(clk, r);
823  *   rate = clk_get_rate(clk);
828  * Returns rounded clock rate in Hz, or negative errno.
830 long clk_round_rate(struct clk *clk, unsigned long rate);
833  * clk_set_rate - set the clock rate for a clock source
834  * @clk: clock source
835  * @rate: desired clock rate in Hz
837  * Updating the rate starts at the top-most affected clock and then
838  * walks the tree down to the bottom-most clock that needs updating.
842 int clk_set_rate(struct clk *clk, unsigned long rate);
845  * clk_set_rate_exclusive- set the clock rate and claim exclusivity over
847  * @clk: clock source
848  * @rate: desired clock rate in Hz
850  * This helper function allows drivers to atomically set the rate of a producer
851  * and claim exclusivity over the rate control of the producer.
859 int clk_set_rate_exclusive(struct clk *clk, unsigned long rate);
862  * clk_has_parent - check if a clock is a possible parent for another
863  * @clk: clock source
869  * Returns true if @parent is a possible parent for @clk, false otherwise.
871 bool clk_has_parent(const struct clk *clk, const struct clk *parent);
874  * clk_set_rate_range - set a rate range for a clock source
875  * @clk: clock source
876  * @min: desired minimum clock rate in Hz, inclusive
877  * @max: desired maximum clock rate in Hz, inclusive
881 int clk_set_rate_range(struct clk *clk, unsigned long min, unsigned long max);
884  * clk_set_min_rate - set a minimum clock rate for a clock source
885  * @clk: clock source
886  * @rate: desired minimum clock rate in Hz, inclusive
890 int clk_set_min_rate(struct clk *clk, unsigned long rate);
893  * clk_set_max_rate - set a maximum clock rate for a clock source
894  * @clk: clock source
895  * @rate: desired maximum clock rate in Hz, inclusive
899 int clk_set_max_rate(struct clk *clk, unsigned long rate);
902  * clk_set_parent - set the parent clock source for this clock
903  * @clk: clock source
908 int clk_set_parent(struct clk *clk, struct clk *parent);
911  * clk_get_parent - get the parent clock source for this clock
912  * @clk: clock source
914  * Returns struct clk corresponding to parent clock source, or
917 struct clk *clk_get_parent(struct clk *clk);
920  * clk_get_sys - get a clock based upon the device name
924  * Returns a struct clk corresponding to the clock producer, or
934 struct clk *clk_get_sys(const char *dev_id, const char *con_id);
937  * clk_save_context - save clock context for poweroff
946  * clk_restore_context - restore clock context after poweroff
955 static inline struct clk *clk_get(struct device *dev, const char *id)  in clk_get()
978 static inline struct clk *devm_clk_get(struct device *dev, const char *id)  in devm_clk_get()
983 static inline struct clk *devm_clk_get_prepared(struct device *dev,  in devm_clk_get_prepared()
989 static inline struct clk *devm_clk_get_enabled(struct device *dev,  in devm_clk_get_enabled()
995 static inline struct clk *devm_clk_get_optional(struct device *dev,  in devm_clk_get_optional()
1001 static inline struct clk *devm_clk_get_optional_prepared(struct device *dev,  in devm_clk_get_optional_prepared()
1007 static inline struct clk *devm_clk_get_optional_enabled(struct device *dev,  in devm_clk_get_optional_enabled()
1013 static inline struct clk *
1015 					unsigned long rate)  in devm_clk_get_optional_enabled_with_rate()  argument
1045 static inline struct clk *devm_get_clk_from_child(struct device *dev,  in devm_get_clk_from_child()
1051 static inline void clk_put(struct clk *clk) {}  in clk_put()  argument
1057 static inline void devm_clk_put(struct device *dev, struct clk *clk) {}  in devm_clk_put()  argument
1059 static inline int clk_enable(struct clk *clk)  in clk_enable()  argument
1070 static inline void clk_disable(struct clk *clk) {}  in clk_disable()  argument
1076 static inline unsigned long clk_get_rate(struct clk *clk)  in clk_get_rate()  argument
1081 static inline int clk_set_rate(struct clk *clk, unsigned long rate)  in clk_set_rate()  argument
1086 static inline int clk_set_rate_exclusive(struct clk *clk, unsigned long rate)  in clk_set_rate_exclusive()  argument
1091 static inline long clk_round_rate(struct clk *clk, unsigned long rate)  in clk_round_rate()  argument
1096 static inline bool clk_has_parent(struct clk *clk, struct clk *parent)  in clk_has_parent()  argument
1101 static inline int clk_set_rate_range(struct clk *clk, unsigned long min,  in clk_set_rate_range()  argument
1102 				     unsigned long max)  in clk_set_rate_range()  argument
1107 static inline int clk_set_min_rate(struct clk *clk, unsigned long rate)  in clk_set_min_rate()  argument
1112 static inline int clk_set_max_rate(struct clk *clk, unsigned long rate)  in clk_set_max_rate()  argument
1117 static inline int clk_set_parent(struct clk *clk, struct clk *parent)  in clk_set_parent()  argument
1122 static inline struct clk *clk_get_parent(struct clk *clk)  in clk_get_parent()  argument
1127 static inline struct clk *clk_get_sys(const char *dev_id, const char *con_id)  in clk_get_sys()
1141 /* clk_prepare_enable helps cases using clk_enable in non-atomic context. */
1142 static inline int clk_prepare_enable(struct clk *clk)  in clk_prepare_enable()  argument
1146 	ret = clk_prepare(clk);  in clk_prepare_enable()
1149 	ret = clk_enable(clk);  in clk_prepare_enable()
1151 		clk_unprepare(clk);  in clk_prepare_enable()
1156 /* clk_disable_unprepare helps cases using clk_disable in non-atomic context. */
1157 static inline void clk_disable_unprepare(struct clk *clk)  in clk_disable_unprepare()  argument
1159 	clk_disable(clk);  in clk_disable_unprepare()
1160 	clk_unprepare(clk);  in clk_disable_unprepare()
1186  * clk_drop_range - Reset any range set on that clock
1187  * @clk: clock source
1191 static inline int clk_drop_range(struct clk *clk)  in clk_drop_range()  argument
1193 	return clk_set_rate_range(clk, 0, ULONG_MAX);  in clk_drop_range()
1197  * clk_get_optional - lookup and obtain a reference to an optional clock
1203  * this case, instead of returning -ENOENT, the function returns NULL.
1205 static inline struct clk *clk_get_optional(struct device *dev, const char *id)  in clk_get_optional()
1207 	struct clk *clk = clk_get(dev, id);  in clk_get_optional()  local
1209 	if (clk == ERR_PTR(-ENOENT))  in clk_get_optional()
1212 	return clk;  in clk_get_optional()
1216 struct clk *of_clk_get(struct device_node *np, int index);
1217 struct clk *of_clk_get_by_name(struct device_node *np, const char *name);
1218 struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec);
1220 static inline struct clk *of_clk_get(struct device_node *np, int index)  in of_clk_get()
1222 	return ERR_PTR(-ENOENT);  in of_clk_get()
1224 static inline struct clk *of_clk_get_by_name(struct device_node *np,  in of_clk_get_by_name()
1227 	return ERR_PTR(-ENOENT);  in of_clk_get_by_name()
1229 static inline struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec)  in of_clk_get_from_provider()
1231 	return ERR_PTR(-ENOENT);  in of_clk_get_from_provider()