blob: e9d36b3e49de5b1bfa0f01277c093222e1ae2a6d [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001/*
Russell Kingf8ce2542006-01-07 16:15:52 +00002 * linux/include/linux/clk.h
Linus Torvalds1da177e2005-04-16 15:20:36 -07003 *
4 * Copyright (C) 2004 ARM Limited.
5 * Written by Deep Blue Solutions Limited.
Mike Turquetteb24764902012-03-15 23:11:19 -07006 * Copyright (C) 2011-2012 Linaro Ltd <mturquette@linaro.org>
Linus Torvalds1da177e2005-04-16 15:20:36 -07007 *
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 */
Todd Poynor686f8c52006-03-25 18:15:24 +000012#ifndef __LINUX_CLK_H
13#define __LINUX_CLK_H
Linus Torvalds1da177e2005-04-16 15:20:36 -070014
Shawn Guo9f1612d2012-07-18 11:52:22 +080015#include <linux/err.h>
Russell King40d3e0f2011-09-22 11:30:50 +010016#include <linux/kernel.h>
Mike Turquetteb24764902012-03-15 23:11:19 -070017#include <linux/notifier.h>
Russell King40d3e0f2011-09-22 11:30:50 +010018
Linus Torvalds1da177e2005-04-16 15:20:36 -070019struct device;
Linus Torvalds1da177e2005-04-16 15:20:36 -070020struct clk;
Kuninori Morimoto71a2f112016-12-05 05:23:20 +000021struct device_node;
22struct of_phandle_args;
Linus Torvalds1da177e2005-04-16 15:20:36 -070023
Mike Turquetteb24764902012-03-15 23:11:19 -070024/**
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
Soren Brinkmannfb72a052013-04-03 12:17:12 -070030 * rate change. Callbacks may either return NOTIFY_DONE, NOTIFY_OK,
31 * NOTIFY_STOP or NOTIFY_BAD.
Mike Turquetteb24764902012-03-15 23:11:19 -070032 *
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
Soren Brinkmannfb72a052013-04-03 12:17:12 -070036 * always return NOTIFY_DONE or NOTIFY_OK.
Mike Turquetteb24764902012-03-15 23:11:19 -070037 *
38 * POST_RATE_CHANGE - called after the clk rate change has successfully
Soren Brinkmannfb72a052013-04-03 12:17:12 -070039 * completed. Callbacks must always return NOTIFY_DONE or NOTIFY_OK.
Mike Turquetteb24764902012-03-15 23:11:19 -070040 *
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 */
57struct 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 */
74struct clk_notifier_data {
75 struct clk *clk;
76 unsigned long old_rate;
77 unsigned long new_rate;
78};
79
Krzysztof Kozlowskie81b87d2016-06-28 13:25:04 +020080#ifdef CONFIG_COMMON_CLK
81
Mike Turquette86bcfa22014-02-24 16:08:41 -080082/**
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 */
Mike Turquetteb24764902012-03-15 23:11:19 -070091int clk_notifier_register(struct clk *clk, struct notifier_block *nb);
92
Mike Turquette86bcfa22014-02-24 16:08:41 -080093/**
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 */
Mike Turquetteb24764902012-03-15 23:11:19 -070098int clk_notifier_unregister(struct clk *clk, struct notifier_block *nb);
99
Boris BREZILLON5279fc42013-12-21 10:34:47 +0100100/**
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 */
108long clk_get_accuracy(struct clk *clk);
109
Mike Turquettee59c5372014-02-18 21:21:25 -0800110/**
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 */
118int 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 */
127int clk_get_phase(struct clk *clk);
128
Michael Turquette3d3801e2015-02-25 09:11:01 -0800129/**
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 */
140bool clk_is_match(const struct clk *p, const struct clk *q);
141
Boris BREZILLON5279fc42013-12-21 10:34:47 +0100142#else
143
Krzysztof Kozlowskie81b87d2016-06-28 13:25:04 +0200144static inline int clk_notifier_register(struct clk *clk,
145 struct notifier_block *nb)
146{
147 return -ENOTSUPP;
148}
149
150static inline int clk_notifier_unregister(struct clk *clk,
151 struct notifier_block *nb)
152{
153 return -ENOTSUPP;
154}
155
Boris BREZILLON5279fc42013-12-21 10:34:47 +0100156static inline long clk_get_accuracy(struct clk *clk)
157{
158 return -ENOTSUPP;
159}
160
Mike Turquettee59c5372014-02-18 21:21:25 -0800161static inline long clk_set_phase(struct clk *clk, int phase)
162{
163 return -ENOTSUPP;
164}
165
166static inline long clk_get_phase(struct clk *clk)
167{
168 return -ENOTSUPP;
169}
170
Michael Turquette3d3801e2015-02-25 09:11:01 -0800171static inline bool clk_is_match(const struct clk *p, const struct clk *q)
172{
173 return p == q;
174}
175
Mark Brown7e87aed2012-04-01 15:31:23 +0100176#endif
Mike Turquetteb24764902012-03-15 23:11:19 -0700177
Linus Torvalds1da177e2005-04-16 15:20:36 -0700178/**
Viresh Kumar93abe8e2012-07-30 14:39:27 -0700179 * 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
187int clk_prepare(struct clk *clk);
188#else
189static 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
206void clk_unprepare(struct clk *clk);
207#else
208static inline void clk_unprepare(struct clk *clk)
209{
210 might_sleep();
211}
212#endif
213
214#ifdef CONFIG_HAVE_CLK
215/**
Linus Torvalds1da177e2005-04-16 15:20:36 -0700216 * clk_get - lookup and obtain a reference to a clock producer.
217 * @dev: device for clock "consumer"
Jan-Simon Möllera58b3a42012-07-23 20:48:56 +0200218 * @id: clock consumer ID
Linus Torvalds1da177e2005-04-16 15:20:36 -0700219 *
220 * Returns a struct clk corresponding to the clock producer, or
Russell Kingea3f4ea2005-04-27 18:19:55 +0100221 * 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.)
Russell Kingf47fc0a2006-01-03 18:34:20 +0000225 *
226 * Drivers must assume that the clock source is not enabled.
Alex Raimondif7ad1602008-10-15 22:02:03 -0700227 *
228 * clk_get should not be called from within interrupt context.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700229 */
230struct clk *clk_get(struct device *dev, const char *id);
231
232/**
Mark Browna8a97db2012-04-05 11:42:09 +0100233 * devm_clk_get - lookup and obtain a managed reference to a clock producer.
234 * @dev: device for clock "consumer"
Jan-Simon Möllera58b3a42012-07-23 20:48:56 +0200235 * @id: clock consumer ID
Mark Browna8a97db2012-04-05 11:42:09 +0100236 *
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 */
250struct clk *devm_clk_get(struct device *dev, const char *id);
251
252/**
Kuninori Morimoto71a2f112016-12-05 05:23:20 +0000253 * 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 */
266struct clk *devm_get_clk_from_child(struct device *dev,
267 struct device_node *np, const char *con_id);
268
269/**
Linus Torvalds1da177e2005-04-16 15:20:36 -0700270 * 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 *
Russell King40d3e0f2011-09-22 11:30:50 +0100275 * May be called from atomic contexts.
276 *
Linus Torvalds1da177e2005-04-16 15:20:36 -0700277 * Returns success (0) or negative errno.
278 */
279int 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
Russell Kingf47fc0a2006-01-03 18:34:20 +0000284 *
285 * Inform the system that a clock source is no longer required by
286 * a driver and may be shut down.
287 *
Russell King40d3e0f2011-09-22 11:30:50 +0100288 * May be called from atomic contexts.
289 *
Russell Kingf47fc0a2006-01-03 18:34:20 +0000290 * 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700294 */
295void clk_disable(struct clk *clk);
296
297/**
Linus Torvalds1da177e2005-04-16 15:20:36 -0700298 * 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 */
302unsigned long clk_get_rate(struct clk *clk);
303
304/**
305 * clk_put - "free" the clock source
306 * @clk: clock source
Russell Kingf47fc0a2006-01-03 18:34:20 +0000307 *
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.
Alex Raimondif7ad1602008-10-15 22:02:03 -0700311 *
312 * clk_put should not be called from within interrupt context.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700313 */
314void clk_put(struct clk *clk);
315
Mark Browna8a97db2012-04-05 11:42:09 +0100316/**
317 * devm_clk_put - "free" a managed clock source
Masanari Iidada3dae52014-09-09 01:27:23 +0900318 * @dev: device used to acquire the clock
Mark Browna8a97db2012-04-05 11:42:09 +0100319 * @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 */
327void devm_clk_put(struct device *dev, struct clk *clk);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700328
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 *
Russell Kingd2d14a72015-03-14 15:12:35 +0000339 * 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 *
Linus Torvalds1da177e2005-04-16 15:20:36 -0700353 * Returns rounded clock rate in Hz, or negative errno.
354 */
355long clk_round_rate(struct clk *clk, unsigned long rate);
Rob Herring8b7730d2012-04-09 15:24:59 -0500356
Linus Torvalds1da177e2005-04-16 15:20:36 -0700357/**
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 */
364int clk_set_rate(struct clk *clk, unsigned long rate);
Rob Herring8b7730d2012-04-09 15:24:59 -0500365
Linus Torvalds1da177e2005-04-16 15:20:36 -0700366/**
Thierry Reding4e88f3d2015-01-21 17:13:00 +0100367 * 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 */
376bool clk_has_parent(struct clk *clk, struct clk *parent);
377
378/**
Tomeu Vizoso1c8e6002015-01-23 12:03:31 +0100379 * 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 */
386int 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 */
395int 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 */
404int clk_set_max_rate(struct clk *clk, unsigned long rate);
405
406/**
Linus Torvalds1da177e2005-04-16 15:20:36 -0700407 * 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 */
413int 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 */
422struct clk *clk_get_parent(struct clk *clk);
423
Sascha Hauer05fd8e72009-03-07 12:55:49 +0100424/**
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 */
439struct clk *clk_get_sys(const char *dev_id, const char *con_id);
440
Viresh Kumar93abe8e2012-07-30 14:39:27 -0700441#else /* !CONFIG_HAVE_CLK */
442
443static inline struct clk *clk_get(struct device *dev, const char *id)
444{
445 return NULL;
446}
447
448static inline struct clk *devm_clk_get(struct device *dev, const char *id)
449{
450 return NULL;
451}
452
Kuninori Morimoto71a2f112016-12-05 05:23:20 +0000453static 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
Viresh Kumar93abe8e2012-07-30 14:39:27 -0700459static inline void clk_put(struct clk *clk) {}
460
461static inline void devm_clk_put(struct device *dev, struct clk *clk) {}
462
463static inline int clk_enable(struct clk *clk)
464{
465 return 0;
466}
467
468static inline void clk_disable(struct clk *clk) {}
469
470static inline unsigned long clk_get_rate(struct clk *clk)
471{
472 return 0;
473}
474
475static inline int clk_set_rate(struct clk *clk, unsigned long rate)
476{
477 return 0;
478}
479
480static inline long clk_round_rate(struct clk *clk, unsigned long rate)
481{
482 return 0;
483}
484
Thierry Reding4e88f3d2015-01-21 17:13:00 +0100485static inline bool clk_has_parent(struct clk *clk, struct clk *parent)
486{
487 return true;
488}
489
Viresh Kumar93abe8e2012-07-30 14:39:27 -0700490static inline int clk_set_parent(struct clk *clk, struct clk *parent)
491{
492 return 0;
493}
494
495static inline struct clk *clk_get_parent(struct clk *clk)
496{
497 return NULL;
498}
499
Daniel Lezcanob81ea962016-06-02 22:44:49 +0200500static inline struct clk *clk_get_sys(const char *dev_id, const char *con_id)
501{
502 return NULL;
503}
Viresh Kumar93abe8e2012-07-30 14:39:27 -0700504#endif
505
506/* clk_prepare_enable helps cases using clk_enable in non-atomic context. */
507static 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. */
522static inline void clk_disable_unprepare(struct clk *clk)
523{
524 clk_disable(clk);
525 clk_unprepare(clk);
526}
527
Rob Herring137f8a72012-07-18 11:52:23 +0800528#if defined(CONFIG_OF) && defined(CONFIG_COMMON_CLK)
Grant Likely766e6a42012-04-09 14:50:06 -0500529struct clk *of_clk_get(struct device_node *np, int index);
530struct clk *of_clk_get_by_name(struct device_node *np, const char *name);
531struct clk *of_clk_get_from_provider(struct of_phandle_args *clkspec);
532#else
533static inline struct clk *of_clk_get(struct device_node *np, int index)
534{
Shawn Guo9f1612d2012-07-18 11:52:22 +0800535 return ERR_PTR(-ENOENT);
Grant Likely766e6a42012-04-09 14:50:06 -0500536}
537static inline struct clk *of_clk_get_by_name(struct device_node *np,
538 const char *name)
539{
Shawn Guo9f1612d2012-07-18 11:52:22 +0800540 return ERR_PTR(-ENOENT);
Grant Likely766e6a42012-04-09 14:50:06 -0500541}
542#endif
543
Linus Torvalds1da177e2005-04-16 15:20:36 -0700544#endif