Merge tag 'v2022.01-rc4' into next
[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 /**
93  * clk_get_by_phandle() - Get a clock by its phandle information (of-platadata)
94  *
95  * This function is used when of-platdata is enabled.
96  *
97  * This looks up a clock using the phandle info. With dtoc, each phandle in the
98  * 'clocks' property is transformed into an idx representing the device. For
99  * example:
100  *
101  *      clocks = <&dpll_mpu_ck 23>;
102  *
103  * might result in:
104  *
105  *      .clocks = {1, {23}},},
106  *
107  * indicating that the clock is udevice idx 1 in dt-plat.c with an argument of
108  * 23. This function can return a valid clock given the above information. In
109  * this example it would return a clock containing the 'dpll_mpu_ck' device and
110  * the clock ID 23.
111  *
112  * @dev: Device containing the phandle
113  * @cells: Phandle info
114  * @clock: A pointer to a clock struct to initialise
115  * @return 0 if OK, or a negative error code.
116  */
117 int clk_get_by_phandle(struct udevice *dev, const struct phandle_1_arg *cells,
118                        struct clk *clk);
119
120 /**
121  * clk_get_by_index() - Get/request a clock by integer index.
122  *
123  * This looks up and requests a clock. The index is relative to the client
124  * device; each device is assumed to have n clocks associated with it somehow,
125  * and this function finds and requests one of them. The mapping of client
126  * device clock indices to provider clocks may be via device-tree properties,
127  * board-provided mapping tables, or some other mechanism.
128  *
129  * @dev:        The client device.
130  * @index:      The index of the clock to request, within the client's list of
131  *              clocks.
132  * @clock       A pointer to a clock struct to initialize.
133  * @return 0 if OK, or a negative error code.
134  */
135 int clk_get_by_index(struct udevice *dev, int index, struct clk *clk);
136
137 /**
138  * clk_get_by_index_nodev - Get/request a clock by integer index
139  * without a device.
140  *
141  * This is a version of clk_get_by_index() that does not use a device.
142  *
143  * @node:       The client ofnode.
144  * @index:      The index of the clock to request, within the client's list of
145  *              clocks.
146  * @clock       A pointer to a clock struct to initialize.
147  * @return 0 if OK, or a negative error code.
148  */
149 int clk_get_by_index_nodev(ofnode node, int index, struct clk *clk);
150
151 /**
152  * clk_get_bulk - Get/request all clocks of a device.
153  *
154  * This looks up and requests all clocks of the client device; each device is
155  * assumed to have n clocks associated with it somehow, and this function finds
156  * and requests all of them in a separate structure. The mapping of client
157  * device clock indices to provider clocks may be via device-tree properties,
158  * board-provided mapping tables, or some other mechanism.
159  *
160  * @dev:        The client device.
161  * @bulk        A pointer to a clock bulk struct to initialize.
162  * @return 0 if OK, or a negative error code.
163  */
164 int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk);
165
166 /**
167  * clk_get_by_name - Get/request a clock by name.
168  *
169  * This looks up and requests a clock. The name is relative to the client
170  * device; each device is assumed to have n clocks associated with it somehow,
171  * and this function finds and requests one of them. The mapping of client
172  * device clock names to provider clocks may be via device-tree properties,
173  * board-provided mapping tables, or some other mechanism.
174  *
175  * @dev:        The client device.
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  * @return 0 if OK, or a negative error code.
180  */
181 int clk_get_by_name(struct udevice *dev, const char *name, struct clk *clk);
182
183 /**
184  * clk_get_by_name_nodev - Get/request a clock by name without a device.
185  *
186  * This is a version of clk_get_by_name() that does not use a device.
187  *
188  * @node:       The client ofnode.
189  * @name:       The name of the clock to request, within the client's list of
190  *              clocks.
191  * @clock:      A pointer to a clock struct to initialize.
192  * @return 0 if OK, or a negative error code.
193  */
194 int clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk);
195
196 /**
197  * clk_get_optional_nodev - Get/request an optinonal clock by name
198  *              without a device.
199  * @node:       The client ofnode.
200  * @name:       The name of the clock to request.
201  * @name:       The name of the clock to request, within the client's list of
202  *              clocks.
203  * @clock:      A pointer to a clock struct to initialize.
204  *
205  * Behaves the same as clk_get_by_name_nodev() except where there is
206  * no clock producer, in this case, skip the error number -ENODATA, and
207  * the function returns 0.
208  */
209 int clk_get_optional_nodev(ofnode node, const char *name, struct clk *clk);
210
211 /**
212  * devm_clk_get - lookup and obtain a managed reference to a clock producer.
213  * @dev: device for clock "consumer"
214  * @id: clock consumer ID
215  *
216  * Returns a struct clk corresponding to the clock producer, or
217  * valid IS_ERR() condition containing errno.  The implementation
218  * uses @dev and @id to determine the clock consumer, and thereby
219  * the clock producer.  (IOW, @id may be identical strings, but
220  * clk_get may return different clock producers depending on @dev.)
221  *
222  * Drivers must assume that the clock source is not enabled.
223  *
224  * devm_clk_get should not be called from within interrupt context.
225  *
226  * The clock will automatically be freed when the device is unbound
227  * from the bus.
228  */
229 struct clk *devm_clk_get(struct udevice *dev, const char *id);
230
231 /**
232  * devm_clk_get_optional - lookup and obtain a managed reference to an optional
233  *                         clock producer.
234  * @dev: device for clock "consumer"
235  * @id: clock consumer ID
236  *
237  * Behaves the same as devm_clk_get() except where there is no clock producer.
238  * In this case, instead of returning -ENOENT, the function returns NULL.
239  */
240 struct clk *devm_clk_get_optional(struct udevice *dev, const char *id);
241
242 /**
243  * clk_release_all() - Disable (turn off)/Free an array of previously
244  * requested clocks.
245  *
246  * For each clock contained in the clock array, this function will check if
247  * clock has been previously requested and then will disable and free it.
248  *
249  * @clk:        A clock struct array that was previously successfully
250  *              requested by clk_request/get_by_*().
251  * @count       Number of clock contained in the array
252  * @return zero on success, or -ve error code.
253  */
254 int clk_release_all(struct clk *clk, int count);
255
256 /**
257  * devm_clk_put - "free" a managed clock source
258  * @dev: device used to acquire the clock
259  * @clk: clock source acquired with devm_clk_get()
260  *
261  * Note: drivers must ensure that all clk_enable calls made on this
262  * clock source are balanced by clk_disable calls prior to calling
263  * this function.
264  *
265  * clk_put should not be called from within interrupt context.
266  */
267 void devm_clk_put(struct udevice *dev, struct clk *clk);
268
269 #else
270 static inline int clk_get_by_index(struct udevice *dev, int index,
271                                    struct clk *clk)
272 {
273         return -ENOSYS;
274 }
275
276 static inline int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk)
277 {
278         return -ENOSYS;
279 }
280
281 static inline int clk_get_by_name(struct udevice *dev, const char *name,
282                            struct clk *clk)
283 {
284         return -ENOSYS;
285 }
286
287 static inline int
288 clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk)
289 {
290         return -ENOSYS;
291 }
292
293 static inline int
294 clk_get_optional_nodev(ofnode node, const char *name, struct clk *clk)
295 {
296         return -ENOSYS;
297 }
298
299 static inline int clk_release_all(struct clk *clk, int count)
300 {
301         return -ENOSYS;
302 }
303 #endif
304
305 /**
306  * enum clk_defaults_stage - What stage clk_set_defaults() is called at
307  * @CLK_DEFAULTS_PRE: Called before probe. Setting of defaults for clocks owned
308  *                    by this clock driver will be defered until after probing.
309  * @CLK_DEFAULTS_POST: Called after probe. Only defaults for clocks owned by
310  *                     this clock driver will be set.
311  * @CLK_DEFAULTS_POST_FORCE: Called after probe, and always set defaults, even
312  *                           before relocation. Usually, defaults are not set
313  *                           pre-relocation to avoid setting them twice (when
314  *                           the device is probed again post-relocation). This
315  *                           may incur a performance cost as device tree
316  *                           properties must be parsed for a second time.
317  *                           However, when not using SPL, pre-relocation may be
318  *                           the only time we can set defaults for some clocks
319  *                           (such as those used for the RAM we will relocate
320  *                           into).
321  */
322 enum clk_defaults_stage {
323         CLK_DEFAULTS_PRE = 0,
324         CLK_DEFAULTS_POST = 1,
325         CLK_DEFAULTS_POST_FORCE,
326 };
327
328 #if CONFIG_IS_ENABLED(OF_REAL) && CONFIG_IS_ENABLED(CLK)
329 /**
330  * clk_set_defaults - Process 'assigned-{clocks/clock-parents/clock-rates}'
331  *                    properties to configure clocks
332  *
333  * @dev:        A device to process (the ofnode associated with this device
334  *              will be processed).
335  * @stage:      The stage of the probing process this function is called during.
336  */
337 int clk_set_defaults(struct udevice *dev, enum clk_defaults_stage stage);
338 #else
339 static inline int clk_set_defaults(struct udevice *dev, int stage)
340 {
341         return 0;
342 }
343 #endif
344
345 /**
346  * clk_release_bulk() - Disable (turn off)/Free an array of previously
347  * requested clocks in a clock bulk struct.
348  *
349  * For each clock contained in the clock bulk struct, this function will check
350  * if clock has been previously requested and then will disable and free it.
351  *
352  * @clk:        A clock bulk struct that was previously successfully
353  *              requested by clk_get_bulk().
354  * @return zero on success, or -ve error code.
355  */
356 static inline int clk_release_bulk(struct clk_bulk *bulk)
357 {
358         return clk_release_all(bulk->clks, bulk->count);
359 }
360
361 #if CONFIG_IS_ENABLED(CLK)
362 /**
363  * clk_request - Request a clock by provider-specific ID.
364  *
365  * This requests a clock using a provider-specific ID. Generally, this function
366  * should not be used, since clk_get_by_index/name() provide an interface that
367  * better separates clients from intimate knowledge of clock providers.
368  * However, this function may be useful in core SoC-specific code.
369  *
370  * @dev:        The clock provider device.
371  * @clock:      A pointer to a clock struct to initialize. The caller must
372  *              have already initialized any field in this struct which the
373  *              clock provider uses to identify the clock.
374  * @return 0 if OK, or a negative error code.
375  */
376 int clk_request(struct udevice *dev, struct clk *clk);
377
378 /**
379  * clk_free - Free a previously requested clock.
380  *
381  * @clock:      A clock struct that was previously successfully requested by
382  *              clk_request/get_by_*().
383  * @return 0 if OK, or a negative error code.
384  */
385 int clk_free(struct clk *clk);
386
387 /**
388  * clk_get_rate() - Get current clock rate.
389  *
390  * @clk:        A clock struct that was previously successfully requested by
391  *              clk_request/get_by_*().
392  * @return clock rate in Hz on success, 0 for invalid clock, or -ve error code
393  *         for other errors.
394  */
395 ulong clk_get_rate(struct clk *clk);
396
397 /**
398  * clk_get_parent() - Get current clock's parent.
399  *
400  * @clk:        A clock struct that was previously successfully requested by
401  *              clk_request/get_by_*().
402  * @return pointer to parent's struct clk, or error code passed as pointer
403  */
404 struct clk *clk_get_parent(struct clk *clk);
405
406 /**
407  * clk_get_parent_rate() - Get parent of current clock rate.
408  *
409  * @clk:        A clock struct that was previously successfully requested by
410  *              clk_request/get_by_*().
411  * @return clock rate in Hz, or -ve error code.
412  */
413 long long clk_get_parent_rate(struct clk *clk);
414
415 /**
416  * clk_round_rate() - Adjust a rate to the exact rate a clock can provide
417  *
418  * This answers the question "if I were to pass @rate to clk_set_rate(),
419  * what clock rate would I end up with?" without changing the hardware
420  * in any way.  In other words:
421  *
422  *   rate = clk_round_rate(clk, r);
423  *
424  * and:
425  *
426  *   rate = clk_set_rate(clk, r);
427  *
428  * are equivalent except the former does not modify the clock hardware
429  * in any way.
430  *
431  * @clk: A clock struct that was previously successfully requested by
432  *       clk_request/get_by_*().
433  * @rate: desired clock rate in Hz.
434  * @return rounded rate in Hz, or -ve error code.
435  */
436 ulong clk_round_rate(struct clk *clk, ulong rate);
437
438 /**
439  * clk_set_rate() - Set current clock rate.
440  *
441  * @clk:        A clock struct that was previously successfully requested by
442  *              clk_request/get_by_*().
443  * @rate:       New clock rate in Hz.
444  * @return new rate, or -ve error code.
445  */
446 ulong clk_set_rate(struct clk *clk, ulong rate);
447
448 /**
449  * clk_set_parent() - Set current clock parent.
450  *
451  * @clk:        A clock struct that was previously successfully requested by
452  *              clk_request/get_by_*().
453  * @parent:     A clock struct that was previously successfully requested by
454  *              clk_request/get_by_*().
455  * @return new rate, or -ve error code.
456  */
457 int clk_set_parent(struct clk *clk, struct clk *parent);
458
459 /**
460  * clk_enable() - Enable (turn on) a clock.
461  *
462  * @clk:        A clock struct that was previously successfully requested by
463  *              clk_request/get_by_*().
464  * @return zero on success, or -ve error code.
465  */
466 int clk_enable(struct clk *clk);
467
468 /**
469  * clk_enable_bulk() - Enable (turn on) all clocks in a clock bulk struct.
470  *
471  * @bulk:       A clock bulk struct that was previously successfully requested
472  *              by clk_get_bulk().
473  * @return zero on success, or -ve error code.
474  */
475 int clk_enable_bulk(struct clk_bulk *bulk);
476
477 /**
478  * clk_disable() - Disable (turn off) a clock.
479  *
480  * @clk:        A clock struct that was previously successfully requested by
481  *              clk_request/get_by_*().
482  * @return zero on success, or -ve error code.
483  */
484 int clk_disable(struct clk *clk);
485
486 /**
487  * clk_disable_bulk() - Disable (turn off) all clocks in a clock bulk struct.
488  *
489  * @bulk:       A clock bulk struct that was previously successfully requested
490  *              by clk_get_bulk().
491  * @return zero on success, or -ve error code.
492  */
493 int clk_disable_bulk(struct clk_bulk *bulk);
494
495 /**
496  * clk_is_match - check if two clk's point to the same hardware clock
497  * @p: clk compared against q
498  * @q: clk compared against p
499  *
500  * Returns true if the two struct clk pointers both point to the same hardware
501  * clock node.
502  *
503  * Returns false otherwise. Note that two NULL clks are treated as matching.
504  */
505 bool clk_is_match(const struct clk *p, const struct clk *q);
506
507 /**
508  * clk_get_by_id() - Get the clock by its ID
509  *
510  * @id: The clock ID to search for
511  *
512  * @clkp:       A pointer to clock struct that has been found among added clocks
513  *              to UCLASS_CLK
514  * @return zero on success, or -ENOENT on error
515  */
516 int clk_get_by_id(ulong id, struct clk **clkp);
517
518 /**
519  * clk_dev_binded() - Check whether the clk has a device binded
520  *
521  * @clk         A pointer to the clk
522  *
523  * @return true on binded, or false on no
524  */
525 bool clk_dev_binded(struct clk *clk);
526
527 #else /* CONFIG_IS_ENABLED(CLK) */
528
529 static inline int clk_request(struct udevice *dev, struct clk *clk)
530 {
531         return -ENOSYS;
532 }
533
534 static inline int clk_free(struct clk *clk)
535 {
536         return 0;
537 }
538
539 static inline ulong clk_get_rate(struct clk *clk)
540 {
541         return -ENOSYS;
542 }
543
544 static inline struct clk *clk_get_parent(struct clk *clk)
545 {
546         return ERR_PTR(-ENOSYS);
547 }
548
549 static inline long long clk_get_parent_rate(struct clk *clk)
550 {
551         return -ENOSYS;
552 }
553
554 static inline ulong clk_round_rate(struct clk *clk, ulong rate)
555 {
556         return -ENOSYS;
557 }
558
559 static inline ulong clk_set_rate(struct clk *clk, ulong rate)
560 {
561         return -ENOSYS;
562 }
563
564 static inline int clk_set_parent(struct clk *clk, struct clk *parent)
565 {
566         return -ENOSYS;
567 }
568
569 static inline int clk_enable(struct clk *clk)
570 {
571         return 0;
572 }
573
574 static inline int clk_enable_bulk(struct clk_bulk *bulk)
575 {
576         return 0;
577 }
578
579 static inline int clk_disable(struct clk *clk)
580 {
581         return 0;
582 }
583
584 static inline int clk_disable_bulk(struct clk_bulk *bulk)
585 {
586         return 0;
587 }
588
589 static inline bool clk_is_match(const struct clk *p, const struct clk *q)
590 {
591         return false;
592 }
593
594 static inline int clk_get_by_id(ulong id, struct clk **clkp)
595 {
596         return -ENOSYS;
597 }
598
599 static inline bool clk_dev_binded(struct clk *clk)
600 {
601         return false;
602 }
603 #endif /* CONFIG_IS_ENABLED(CLK) */
604
605 /**
606  * clk_valid() - check if clk is valid
607  *
608  * @clk:        the clock to check
609  * @return true if valid, or false
610  */
611 static inline bool clk_valid(struct clk *clk)
612 {
613         return clk && !!clk->dev;
614 }
615
616 int soc_clk_dump(void);
617
618 #endif
619
620 #define clk_prepare_enable(clk) clk_enable(clk)
621 #define clk_disable_unprepare(clk) clk_disable(clk)