Merge tag 'u-boot-imx-20200511' of https://gitlab.denx.de/u-boot/custodians/u-boot-imx
[platform/kernel/u-boot.git] / include / clk.h
1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3  * Copyright (c) 2015 Google, Inc
4  * Written by Simon Glass <sjg@chromium.org>
5  * Copyright (c) 2016, NVIDIA CORPORATION.
6  */
7
8 #ifndef _CLK_H_
9 #define _CLK_H_
10
11 #include <dm/ofnode.h>
12 #include <linux/err.h>
13 #include <linux/errno.h>
14 #include <linux/types.h>
15
16 /**
17  * A clock is a hardware signal that oscillates autonomously at a specific
18  * frequency and duty cycle. Most hardware modules require one or more clock
19  * signal to drive their operation. Clock signals are typically generated
20  * externally to the HW module consuming them, by an entity this API calls a
21  * clock provider. This API provides a standard means for drivers to enable and
22  * disable clocks, and to set the rate at which they oscillate.
23  *
24  * A driver that implements UCLASS_CLK is a clock provider. A provider will
25  * often implement multiple separate clocks, since the hardware it manages
26  * often has this capability. clk-uclass.h describes the interface which
27  * clock providers must implement.
28  *
29  * Clock consumers/clients are the HW modules driven by the clock signals. This
30  * header file describes the API used by drivers for those HW modules.
31  */
32
33 struct udevice;
34
35 /**
36  * struct clk - A handle to (allowing control of) a single clock.
37  *
38  * Clients provide storage for clock handles. The content of the structure is
39  * managed solely by the clock API and clock drivers. A clock struct is
40  * initialized by "get"ing the clock struct. The clock struct is passed to all
41  * other clock APIs to identify which clock signal to operate upon.
42  *
43  * @dev: The device which implements the clock signal.
44  * @rate: The clock rate (in HZ).
45  * @flags: Flags used across common clock structure (e.g. CLK_)
46  *         Clock IP blocks specific flags (i.e. mux, div, gate, etc) are defined
47  *         in struct's for those devices (e.g. struct clk_mux).
48  * @id: The clock signal ID within the provider.
49  * @data: An optional data field for scenarios where a single integer ID is not
50  *        sufficient. If used, it can be populated through an .of_xlate op and
51  *        processed during the various clock ops.
52  *
53  * Should additional information to identify and configure any clock signal
54  * for any provider be required in the future, the struct could be expanded to
55  * either (a) add more fields to allow clock providers to store additional
56  * information, or (b) replace the id field with an opaque pointer, which the
57  * provider would dynamically allocated during its .of_xlate op, and process
58  * during is .request op. This may require the addition of an extra op to clean
59  * up the allocation.
60  */
61 struct clk {
62         struct udevice *dev;
63         long long rate; /* in HZ */
64         u32 flags;
65         int enable_count;
66         /*
67          * Written by of_xlate. In the future, we might add more fields here.
68          */
69         unsigned long id;
70         unsigned long data;
71 };
72
73 /**
74  * struct clk_bulk - A handle to (allowing control of) a bulk of clocks.
75  *
76  * Clients provide storage for the clock bulk. The content of the structure is
77  * managed solely by the clock API. A clock bulk struct is
78  * initialized by "get"ing the clock bulk struct.
79  * The clock bulk struct is passed to all other bulk clock APIs to apply
80  * the API to all the clock in the bulk struct.
81  *
82  * @clks: An array of clock handles.
83  * @count: The number of clock handles in the clks array.
84  */
85 struct clk_bulk {
86         struct clk *clks;
87         unsigned int count;
88 };
89
90 #if CONFIG_IS_ENABLED(OF_CONTROL) && CONFIG_IS_ENABLED(CLK)
91 struct phandle_1_arg;
92 int clk_get_by_index_platdata(struct udevice *dev, int index,
93                               struct phandle_1_arg *cells, struct clk *clk);
94
95 /**
96  * clk_get_by_index - Get/request a clock by integer index.
97  *
98  * This looks up and requests a clock. The index is relative to the client
99  * device; each device is assumed to have n clocks associated with it somehow,
100  * and this function finds and requests one of them. The mapping of client
101  * device clock indices to provider clocks may be via device-tree properties,
102  * board-provided mapping tables, or some other mechanism.
103  *
104  * @dev:        The client device.
105  * @index:      The index of the clock to request, within the client's list of
106  *              clocks.
107  * @clock       A pointer to a clock struct to initialize.
108  * @return 0 if OK, or a negative error code.
109  */
110 int clk_get_by_index(struct udevice *dev, int index, struct clk *clk);
111
112 /**
113  * clk_get_by_index_nodev - Get/request a clock by integer index
114  * without a device.
115  *
116  * This is a version of clk_get_by_index() that does not use a device.
117  *
118  * @node:       The client ofnode.
119  * @index:      The index of the clock to request, within the client's list of
120  *              clocks.
121  * @clock       A pointer to a clock struct to initialize.
122  * @return 0 if OK, or a negative error code.
123  */
124 int clk_get_by_index_nodev(ofnode node, int index, struct clk *clk);
125
126 /**
127  * clk_get_bulk - Get/request all clocks of a device.
128  *
129  * This looks up and requests all clocks of the client device; each device is
130  * assumed to have n clocks associated with it somehow, and this function finds
131  * and requests all of them in a separate structure. The mapping of client
132  * device clock indices to provider clocks may be via device-tree properties,
133  * board-provided mapping tables, or some other mechanism.
134  *
135  * @dev:        The client device.
136  * @bulk        A pointer to a clock bulk struct to initialize.
137  * @return 0 if OK, or a negative error code.
138  */
139 int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk);
140
141 /**
142  * clk_get_by_name - Get/request a clock by name.
143  *
144  * This looks up and requests a clock. The name is relative to the client
145  * device; each device is assumed to have n clocks associated with it somehow,
146  * and this function finds and requests one of them. The mapping of client
147  * device clock names to provider clocks may be via device-tree properties,
148  * board-provided mapping tables, or some other mechanism.
149  *
150  * @dev:        The client device.
151  * @name:       The name of the clock to request, within the client's list of
152  *              clocks.
153  * @clock:      A pointer to a clock struct to initialize.
154  * @return 0 if OK, or a negative error code.
155  */
156 int clk_get_by_name(struct udevice *dev, const char *name, struct clk *clk);
157
158 /**
159  * clk_get_by_name_nodev - Get/request a clock by name without a device.
160  *
161  * This is a version of clk_get_by_name() that does not use a device.
162  *
163  * @node:       The client ofnode.
164  * @name:       The name of the clock to request, within the client's list of
165  *              clocks.
166  * @clock:      A pointer to a clock struct to initialize.
167  * @return 0 if OK, or a negative error code.
168  */
169 int clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk);
170
171 /**
172  * clk_get_optional_nodev - Get/request an optinonal clock by name
173  *              without a device.
174  * @node:       The client ofnode.
175  * @name:       The name of the clock to request.
176  * @name:       The name of the clock to request, within the client's list of
177  *              clocks.
178  * @clock:      A pointer to a clock struct to initialize.
179  *
180  * Behaves the same as clk_get_by_name_nodev() except where there is
181  * no clock producer, in this case, skip the error number -ENODATA, and
182  * the function returns 0.
183  */
184 int clk_get_optional_nodev(ofnode node, const char *name, struct clk *clk);
185
186 /**
187  * devm_clk_get - lookup and obtain a managed reference to a clock producer.
188  * @dev: device for clock "consumer"
189  * @id: clock consumer ID
190  *
191  * Returns a struct clk corresponding to the clock producer, or
192  * valid IS_ERR() condition containing errno.  The implementation
193  * uses @dev and @id to determine the clock consumer, and thereby
194  * the clock producer.  (IOW, @id may be identical strings, but
195  * clk_get may return different clock producers depending on @dev.)
196  *
197  * Drivers must assume that the clock source is not enabled.
198  *
199  * devm_clk_get should not be called from within interrupt context.
200  *
201  * The clock will automatically be freed when the device is unbound
202  * from the bus.
203  */
204 struct clk *devm_clk_get(struct udevice *dev, const char *id);
205
206 /**
207  * devm_clk_get_optional - lookup and obtain a managed reference to an optional
208  *                         clock producer.
209  * @dev: device for clock "consumer"
210  * @id: clock consumer ID
211  *
212  * Behaves the same as devm_clk_get() except where there is no clock producer.
213  * In this case, instead of returning -ENOENT, the function returns NULL.
214  */
215 struct clk *devm_clk_get_optional(struct udevice *dev, const char *id);
216
217 /**
218  * clk_release_all() - Disable (turn off)/Free an array of previously
219  * requested clocks.
220  *
221  * For each clock contained in the clock array, this function will check if
222  * clock has been previously requested and then will disable and free it.
223  *
224  * @clk:        A clock struct array that was previously successfully
225  *              requested by clk_request/get_by_*().
226  * @count       Number of clock contained in the array
227  * @return zero on success, or -ve error code.
228  */
229 int clk_release_all(struct clk *clk, int count);
230
231 /**
232  * devm_clk_put - "free" a managed clock source
233  * @dev: device used to acquire the clock
234  * @clk: clock source acquired with devm_clk_get()
235  *
236  * Note: drivers must ensure that all clk_enable calls made on this
237  * clock source are balanced by clk_disable calls prior to calling
238  * this function.
239  *
240  * clk_put should not be called from within interrupt context.
241  */
242 void devm_clk_put(struct udevice *dev, struct clk *clk);
243
244 #else
245 static inline int clk_get_by_index(struct udevice *dev, int index,
246                                    struct clk *clk)
247 {
248         return -ENOSYS;
249 }
250
251 static inline int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk)
252 {
253         return -ENOSYS;
254 }
255
256 static inline int clk_get_by_name(struct udevice *dev, const char *name,
257                            struct clk *clk)
258 {
259         return -ENOSYS;
260 }
261
262 static inline int
263 clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk)
264 {
265         return -ENOSYS;
266 }
267
268 static inline int
269 clk_get_optional_nodev(ofnode node, const char *name, struct clk *clk)
270 {
271         return -ENOSYS;
272 }
273
274 static inline int clk_release_all(struct clk *clk, int count)
275 {
276         return -ENOSYS;
277 }
278 #endif
279
280 #if (CONFIG_IS_ENABLED(OF_CONTROL) && !CONFIG_IS_ENABLED(OF_PLATDATA)) && \
281         CONFIG_IS_ENABLED(CLK)
282 /**
283  * clk_set_defaults - Process 'assigned-{clocks/clock-parents/clock-rates}'
284  *                    properties to configure clocks
285  *
286  * @dev:        A device to process (the ofnode associated with this device
287  *              will be processed).
288  * @stage:      A integer. 0 indicates that this is called before the device
289  *              is probed. 1 indicates that this is called just after the
290  *              device has been probed
291  */
292 int clk_set_defaults(struct udevice *dev, int stage);
293 #else
294 static inline int clk_set_defaults(struct udevice *dev, int stage)
295 {
296         return 0;
297 }
298 #endif
299
300 /**
301  * clk_release_bulk() - Disable (turn off)/Free an array of previously
302  * requested clocks in a clock bulk struct.
303  *
304  * For each clock contained in the clock bulk struct, this function will check
305  * if clock has been previously requested and then will disable and free it.
306  *
307  * @clk:        A clock bulk struct that was previously successfully
308  *              requested by clk_get_bulk().
309  * @return zero on success, or -ve error code.
310  */
311 static inline int clk_release_bulk(struct clk_bulk *bulk)
312 {
313         return clk_release_all(bulk->clks, bulk->count);
314 }
315
316 #if CONFIG_IS_ENABLED(CLK)
317 /**
318  * clk_request - Request a clock by provider-specific ID.
319  *
320  * This requests a clock using a provider-specific ID. Generally, this function
321  * should not be used, since clk_get_by_index/name() provide an interface that
322  * better separates clients from intimate knowledge of clock providers.
323  * However, this function may be useful in core SoC-specific code.
324  *
325  * @dev:        The clock provider device.
326  * @clock:      A pointer to a clock struct to initialize. The caller must
327  *              have already initialized any field in this struct which the
328  *              clock provider uses to identify the clock.
329  * @return 0 if OK, or a negative error code.
330  */
331 int clk_request(struct udevice *dev, struct clk *clk);
332
333 /**
334  * clk_free - Free a previously requested clock.
335  *
336  * @clock:      A clock struct that was previously successfully requested by
337  *              clk_request/get_by_*().
338  * @return 0 if OK, or a negative error code.
339  */
340 int clk_free(struct clk *clk);
341
342 /**
343  * clk_get_rate() - Get current clock rate.
344  *
345  * @clk:        A clock struct that was previously successfully requested by
346  *              clk_request/get_by_*().
347  * @return clock rate in Hz, or -ve error code.
348  */
349 ulong clk_get_rate(struct clk *clk);
350
351 /**
352  * clk_get_parent() - Get current clock's parent.
353  *
354  * @clk:        A clock struct that was previously successfully requested by
355  *              clk_request/get_by_*().
356  * @return pointer to parent's struct clk, or error code passed as pointer
357  */
358 struct clk *clk_get_parent(struct clk *clk);
359
360 /**
361  * clk_get_parent_rate() - Get parent of current clock rate.
362  *
363  * @clk:        A clock struct that was previously successfully requested by
364  *              clk_request/get_by_*().
365  * @return clock rate in Hz, or -ve error code.
366  */
367 long long clk_get_parent_rate(struct clk *clk);
368
369 /**
370  * clk_set_rate() - Set current clock rate.
371  *
372  * @clk:        A clock struct that was previously successfully requested by
373  *              clk_request/get_by_*().
374  * @rate:       New clock rate in Hz.
375  * @return new rate, or -ve error code.
376  */
377 ulong clk_set_rate(struct clk *clk, ulong rate);
378
379 /**
380  * clk_set_parent() - Set current clock parent.
381  *
382  * @clk:        A clock struct that was previously successfully requested by
383  *              clk_request/get_by_*().
384  * @parent:     A clock struct that was previously successfully requested by
385  *              clk_request/get_by_*().
386  * @return new rate, or -ve error code.
387  */
388 int clk_set_parent(struct clk *clk, struct clk *parent);
389
390 /**
391  * clk_enable() - Enable (turn on) a clock.
392  *
393  * @clk:        A clock struct that was previously successfully requested by
394  *              clk_request/get_by_*().
395  * @return zero on success, or -ve error code.
396  */
397 int clk_enable(struct clk *clk);
398
399 /**
400  * clk_enable_bulk() - Enable (turn on) all clocks in a clock bulk struct.
401  *
402  * @bulk:       A clock bulk struct that was previously successfully requested
403  *              by clk_get_bulk().
404  * @return zero on success, or -ve error code.
405  */
406 int clk_enable_bulk(struct clk_bulk *bulk);
407
408 /**
409  * clk_disable() - Disable (turn off) a clock.
410  *
411  * @clk:        A clock struct that was previously successfully requested by
412  *              clk_request/get_by_*().
413  * @return zero on success, or -ve error code.
414  */
415 int clk_disable(struct clk *clk);
416
417 /**
418  * clk_disable_bulk() - Disable (turn off) all clocks in a clock bulk struct.
419  *
420  * @bulk:       A clock bulk struct that was previously successfully requested
421  *              by clk_get_bulk().
422  * @return zero on success, or -ve error code.
423  */
424 int clk_disable_bulk(struct clk_bulk *bulk);
425
426 /**
427  * clk_is_match - check if two clk's point to the same hardware clock
428  * @p: clk compared against q
429  * @q: clk compared against p
430  *
431  * Returns true if the two struct clk pointers both point to the same hardware
432  * clock node.
433  *
434  * Returns false otherwise. Note that two NULL clks are treated as matching.
435  */
436 bool clk_is_match(const struct clk *p, const struct clk *q);
437
438 /**
439  * clk_get_by_id() - Get the clock by its ID
440  *
441  * @id: The clock ID to search for
442  *
443  * @clkp:       A pointer to clock struct that has been found among added clocks
444  *              to UCLASS_CLK
445  * @return zero on success, or -ENOENT on error
446  */
447 int clk_get_by_id(ulong id, struct clk **clkp);
448
449 /**
450  * clk_dev_binded() - Check whether the clk has a device binded
451  *
452  * @clk         A pointer to the clk
453  *
454  * @return true on binded, or false on no
455  */
456 bool clk_dev_binded(struct clk *clk);
457
458 #else /* CONFIG_IS_ENABLED(CLK) */
459
460 static inline int clk_request(struct udevice *dev, struct clk *clk)
461 {
462         return -ENOSYS;
463 }
464
465 static inline int clk_free(struct clk *clk)
466 {
467         return 0;
468 }
469
470 static inline ulong clk_get_rate(struct clk *clk)
471 {
472         return -ENOSYS;
473 }
474
475 static inline struct clk *clk_get_parent(struct clk *clk)
476 {
477         return ERR_PTR(-ENOSYS);
478 }
479
480 static inline long long clk_get_parent_rate(struct clk *clk)
481 {
482         return -ENOSYS;
483 }
484
485 static inline ulong clk_set_rate(struct clk *clk, ulong rate)
486 {
487         return -ENOSYS;
488 }
489
490 static inline int clk_set_parent(struct clk *clk, struct clk *parent)
491 {
492         return -ENOSYS;
493 }
494
495 static inline int clk_enable(struct clk *clk)
496 {
497         return 0;
498 }
499
500 static inline int clk_enable_bulk(struct clk_bulk *bulk)
501 {
502         return 0;
503 }
504
505 static inline int clk_disable(struct clk *clk)
506 {
507         return 0;
508 }
509
510 static inline int clk_disable_bulk(struct clk_bulk *bulk)
511 {
512         return 0;
513 }
514
515 static inline bool clk_is_match(const struct clk *p, const struct clk *q)
516 {
517         return false;
518 }
519
520 static inline int clk_get_by_id(ulong id, struct clk **clkp)
521 {
522         return -ENOSYS;
523 }
524
525 static inline bool clk_dev_binded(struct clk *clk)
526 {
527         return false;
528 }
529 #endif /* CONFIG_IS_ENABLED(CLK) */
530
531 /**
532  * clk_valid() - check if clk is valid
533  *
534  * @clk:        the clock to check
535  * @return true if valid, or false
536  */
537 static inline bool clk_valid(struct clk *clk)
538 {
539         return clk && !!clk->dev;
540 }
541
542 int soc_clk_dump(void);
543
544 #endif
545
546 #define clk_prepare_enable(clk) clk_enable(clk)
547 #define clk_disable_unprepare(clk) clk_disable(clk)