1 /* SPDX-License-Identifier: GPL-2.0+ */
3 * Copyright (c) 2015 Google, Inc
5 * Copyright (c) 2016, NVIDIA CORPORATION.
11 #include <dm/ofnode.h>
12 #include <linux/err.h>
13 #include <linux/errno.h>
14 #include <linux/types.h>
19 * A clock is a hardware signal that oscillates autonomously at a specific
20 * frequency and duty cycle. Most hardware modules require one or more clock
21 * signal to drive their operation. Clock signals are typically generated
22 * externally to the HW module consuming them, by an entity this API calls a
23 * clock provider. This API provides a standard means for drivers to enable and
24 * disable clocks, and to set the rate at which they oscillate.
26 * A driver that implements UCLASS_CLK is a clock provider. A provider will
27 * often implement multiple separate clocks, since the hardware it manages
28 * often has this capability. clk-uclass.h describes the interface which
29 * clock providers must implement.
31 * Clock consumers/clients are the HW modules driven by the clock signals. This
32 * header file describes the API used by drivers for those HW modules.
38 * struct clk - A handle to (allowing control of) a single clock.
39 * @dev: The device which implements the clock signal.
40 * @rate: The clock rate (in HZ).
41 * @flags: Flags used across common clock structure (e.g. %CLK_)
42 * Clock IP blocks specific flags (i.e. mux, div, gate, etc) are defined
43 * in struct's for those devices (e.g. &struct clk_mux).
44 * @enable_count: The number of times this clock has been enabled.
45 * @id: The clock signal ID within the provider.
46 * @data: An optional data field for scenarios where a single integer ID is not
47 * sufficient. If used, it can be populated through an .of_xlate op and
48 * processed during the various clock ops.
50 * Clients provide storage for clock handles. The content of the structure is
51 * managed solely by the clock API and clock drivers. A clock struct is
52 * initialized by "get"ing the clock struct. The clock struct is passed to all
53 * other clock APIs to identify which clock signal to operate upon.
55 * Should additional information to identify and configure any clock signal
56 * for any provider be required in the future, the struct could be expanded to
57 * either (a) add more fields to allow clock providers to store additional
58 * information, or (b) replace the id field with an opaque pointer, which the
59 * provider would dynamically allocated during its .of_xlate op, and process
60 * during is .request op. This may require the addition of an extra op to clean
65 long long rate; /* in HZ */
69 * Written by of_xlate. In the future, we might add more fields here.
76 * struct clk_bulk - A handle to (allowing control of) a bulk of clocks.
77 * @clks: An array of clock handles.
78 * @count: The number of clock handles in the clks array.
80 * Clients provide storage for the clock bulk. The content of the structure is
81 * managed solely by the clock API. A clock bulk struct is
82 * initialized by "get"ing the clock bulk struct.
83 * The clock bulk struct is passed to all other bulk clock APIs to apply
84 * the API to all the clock in the bulk struct.
93 #if CONFIG_IS_ENABLED(OF_CONTROL) && CONFIG_IS_ENABLED(CLK)
95 * clk_get_by_phandle() - Get a clock by its phandle information (of-platadata)
96 * @dev: Device containing the phandle
97 * @cells: Phandle info
98 * @clk: A pointer to a clock struct to initialise
100 * This function is used when of-platdata is enabled.
102 * This looks up a clock using the phandle info. With dtoc, each phandle in the
103 * 'clocks' property is transformed into an idx representing the device.
106 * clocks = <&dpll_mpu_ck 23>;
110 * .clocks = {1, {23}},},
112 * indicating that the clock is udevice idx 1 in dt-plat.c with an argument of
113 * 23. This function can return a valid clock given the above information. In
114 * this example it would return a clock containing the 'dpll_mpu_ck' device and
117 * Return: 0 if OK, or a negative error code.
119 int clk_get_by_phandle(struct udevice *dev, const struct phandle_1_arg *cells,
123 * clk_get_by_index() - Get/request a clock by integer index.
124 * @dev: The client device.
125 * @index: The index of the clock to request, within the client's list of
127 * @clk: A pointer to a clock struct to initialize.
129 * This looks up and requests a clock. The index is relative to the client
130 * device; each device is assumed to have n clocks associated with it somehow,
131 * and this function finds and requests one of them. 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.
135 * Return: 0 if OK, or a negative error code.
137 int clk_get_by_index(struct udevice *dev, int index, struct clk *clk);
140 * clk_get_by_index_nodev() - Get/request a clock by integer index without a
142 * @node: The client ofnode.
143 * @index: The index of the clock to request, within the client's list of
145 * @clk: A pointer to a clock struct to initialize.
147 * Return: 0 if OK, or a negative error code.
149 int clk_get_by_index_nodev(ofnode node, int index, struct clk *clk);
152 * clk_get_bulk() - Get/request all clocks of a device.
153 * @dev: The client device.
154 * @bulk: A pointer to a clock bulk struct to initialize.
156 * This looks up and requests all clocks of the client device; each device is
157 * assumed to have n clocks associated with it somehow, and this function finds
158 * and requests all of them in a separate structure. The mapping of client
159 * device clock indices to provider clocks may be via device-tree properties,
160 * board-provided mapping tables, or some other mechanism.
162 * Return: 0 if OK, or a negative error code.
164 int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk);
167 * clk_get_by_name() - Get/request a clock by name.
168 * @dev: The client device.
169 * @name: The name of the clock to request, within the client's list of
170 * clocks, or NULL to request the first clock in the list.
171 * @clk: A pointer to a clock struct to initialize.
173 * This looks up and requests a clock. The name is relative to the client
174 * device; each device is assumed to have n clocks associated with it somehow,
175 * and this function finds and requests one of them. The mapping of client
176 * device clock names to provider clocks may be via device-tree properties,
177 * board-provided mapping tables, or some other mechanism.
179 * Return: 0 if OK, or a negative error code.
181 int clk_get_by_name(struct udevice *dev, const char *name, struct clk *clk);
184 * clk_get_by_name_nodev - Get/request a clock by name without a device.
185 * @node: The client ofnode.
186 * @name: The name of the clock to request, within the client's list of
187 * clocks, or NULL to request the first clock in the list.
188 * @clk: A pointer to a clock struct to initialize.
190 * Return: 0 if OK, or a negative error code.
192 int clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk);
195 * devm_clk_get() - lookup and obtain a managed reference to a clock producer.
196 * @dev: device for clock "consumer"
197 * @id: clock consumer ID
199 * The implementation uses @dev and @id to determine the clock consumer, and
200 * thereby the clock producer. (IOW, @id may be identical strings, but clk_get
201 * may return different clock producers depending on @dev.)
203 * Drivers must assume that the clock source is not enabled.
205 * The clock will automatically be freed when the device is unbound
209 * a struct clk corresponding to the clock producer, or
210 * valid IS_ERR() condition containing errno
212 struct clk *devm_clk_get(struct udevice *dev, const char *id);
215 * devm_clk_get_optional() - lookup and obtain a managed reference to an
216 * optional clock producer.
217 * @dev: device for clock "consumer"
218 * @id: clock consumer ID
220 * Behaves the same as devm_clk_get() except where there is no clock producer.
221 * In this case, instead of returning -%ENOENT, the function returns NULL.
223 static inline struct clk *devm_clk_get_optional(struct udevice *dev,
227 struct clk *clk = devm_clk_get(dev, id);
230 if (ret == -ENODATA || ret == -ENOENT)
237 * clk_release_all() - Disable (turn off)/Free an array of previously
239 * @clk: A clock struct array that was previously successfully
240 * requested by clk_request/get_by_*().
241 * @count: Number of clock contained in the array
243 * For each clock contained in the clock array, this function will check if
244 * clock has been previously requested and then will disable and free it.
246 * Return: zero on success, or -ve error code.
248 int clk_release_all(struct clk *clk, unsigned int count);
251 * devm_clk_put - "free" a managed clock source
252 * @dev: device used to acquire the clock
253 * @clk: clock source acquired with devm_clk_get()
255 * Note: drivers must ensure that all clk_enable calls made on this
256 * clock source are balanced by clk_disable calls prior to calling
259 * clk_put should not be called from within interrupt context.
261 void devm_clk_put(struct udevice *dev, struct clk *clk);
265 static inline int clk_get_by_phandle(struct udevice *dev, const
266 struct phandle_1_arg *cells,
272 static inline int clk_get_by_index(struct udevice *dev, int index,
278 static inline int clk_get_by_index_nodev(ofnode node, int index,
284 static inline int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk)
289 static inline int clk_get_by_name(struct udevice *dev, const char *name,
295 static inline struct clk *devm_clk_get(struct udevice *dev, const char *id)
297 return ERR_PTR(-ENOSYS);
300 static inline struct clk *devm_clk_get_optional(struct udevice *dev,
303 return ERR_PTR(-ENOSYS);
307 clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk)
312 static inline int clk_release_all(struct clk *clk, unsigned int count)
317 static inline void devm_clk_put(struct udevice *dev, struct clk *clk)
323 * clk_get_by_name_optional() - Get/request a optional clock by name.
324 * @dev: The client device.
325 * @name: The name of the clock to request, within the client's list of
327 * @clk: A pointer to a clock struct to initialize.
329 * Behaves the same as clk_get_by_name(), except when there is no clock
330 * provider. In the latter case, return 0.
332 * Return: 0 if OK, or a negative error code.
334 static inline int clk_get_by_name_optional(struct udevice *dev,
335 const char *name, struct clk *clk)
339 ret = clk_get_by_name(dev, name, clk);
340 if (ret == -ENODATA || ret == -ENOENT)
347 * clk_get_by_name_nodev_optional - Get/request an optinonal clock by name
349 * @node: The client ofnode.
350 * @name: The name of the clock to request, within the client's list of
352 * @clk: A pointer to a clock struct to initialize.
354 * Behaves the same as clk_get_by_name_nodev() except where there is
355 * no clock producer, in this case, skip the error number -%ENODATA, and
356 * the function returns 0.
358 static inline int clk_get_by_name_nodev_optional(ofnode node, const char *name,
363 ret = clk_get_by_name_nodev(node, name, clk);
364 if (ret == -ENODATA || ret == -ENOENT)
371 * enum clk_defaults_stage - What stage clk_set_defaults() is called at
372 * @CLK_DEFAULTS_PRE: Called before probe. Setting of defaults for clocks owned
373 * by this clock driver will be defered until after probing.
374 * @CLK_DEFAULTS_POST: Called after probe. Only defaults for clocks owned by
375 * this clock driver will be set.
376 * @CLK_DEFAULTS_POST_FORCE: Called after probe, and always set defaults, even
377 * before relocation. Usually, defaults are not set
378 * pre-relocation to avoid setting them twice (when
379 * the device is probed again post-relocation). This
380 * may incur a performance cost as device tree
381 * properties must be parsed for a second time.
382 * However, when not using SPL, pre-relocation may be
383 * the only time we can set defaults for some clocks
384 * (such as those used for the RAM we will relocate
387 enum clk_defaults_stage {
388 CLK_DEFAULTS_PRE = 0,
389 CLK_DEFAULTS_POST = 1,
390 CLK_DEFAULTS_POST_FORCE,
393 #if CONFIG_IS_ENABLED(OF_REAL) && CONFIG_IS_ENABLED(CLK)
395 * clk_set_defaults - Process ``assigned-{clocks/clock-parents/clock-rates}``
396 * properties to configure clocks
397 * @dev: A device to process (the ofnode associated with this device
398 * will be processed).
399 * @stage: The stage of the probing process this function is called during.
401 * Return: zero on success, or -ve error code.
403 int clk_set_defaults(struct udevice *dev, enum clk_defaults_stage stage);
405 static inline int clk_set_defaults(struct udevice *dev, int stage)
412 * clk_release_bulk() - Disable (turn off)/Free an array of previously
413 * requested clocks in a clock bulk struct.
414 * @bulk: A clock bulk struct that was previously successfully
415 * requested by clk_get_bulk().
417 * For each clock contained in the clock bulk struct, this function will check
418 * if clock has been previously requested and then will disable and free it.
420 * Return: zero on success, or -ve error code.
422 static inline int clk_release_bulk(struct clk_bulk *bulk)
424 return clk_release_all(bulk->clks, bulk->count);
427 #if CONFIG_IS_ENABLED(CLK)
429 * clk_request() - Request a clock by provider-specific ID.
430 * @dev: The clock provider device.
431 * @clk: A pointer to a clock struct to initialize. The caller must
432 * have already initialized any field in this struct which the
433 * clock provider uses to identify the clock.
435 * This requests a clock using a provider-specific ID. Generally, this function
436 * should not be used, since clk_get_by_index/name() provide an interface that
437 * better separates clients from intimate knowledge of clock providers.
438 * However, this function may be useful in core SoC-specific code.
440 * Return: 0 if OK, or a negative error code.
442 int clk_request(struct udevice *dev, struct clk *clk);
445 * clk_free() - Free a previously requested clock.
446 * @clk: A clock struct that was previously successfully requested by
447 * clk_request/get_by_*().
449 * Free resources allocated by clk_request() (or any clk_get_* function).
451 void clk_free(struct clk *clk);
454 * clk_get_rate() - Get current clock rate.
455 * @clk: A clock struct that was previously successfully requested by
456 * clk_request/get_by_*().
458 * Return: clock rate in Hz on success, 0 for invalid clock, or -ve error code
461 ulong clk_get_rate(struct clk *clk);
464 * clk_get_parent() - Get current clock's parent.
465 * @clk: A clock struct that was previously successfully requested by
466 * clk_request/get_by_*().
468 * Return: pointer to parent's struct clk, or error code passed as pointer
470 struct clk *clk_get_parent(struct clk *clk);
473 * clk_get_parent_rate() - Get parent of current clock rate.
474 * @clk: A clock struct that was previously successfully requested by
475 * clk_request/get_by_*().
477 * Return: clock rate in Hz, or -ve error code.
479 ulong clk_get_parent_rate(struct clk *clk);
482 * clk_round_rate() - Adjust a rate to the exact rate a clock can provide
483 * @clk: A clock struct that was previously successfully requested by
484 * clk_request/get_by_*().
485 * @rate: desired clock rate in Hz.
487 * This answers the question "if I were to pass @rate to clk_set_rate(),
488 * what clock rate would I end up with?" without changing the hardware
489 * in any way. In other words::
491 * rate = clk_round_rate(clk, r);
495 * rate = clk_set_rate(clk, r);
497 * are equivalent except the former does not modify the clock hardware
500 * Return: rounded rate in Hz, or -ve error code.
502 ulong clk_round_rate(struct clk *clk, ulong rate);
505 * clk_set_rate() - Set current clock rate.
506 * @clk: A clock struct that was previously successfully requested by
507 * clk_request/get_by_*().
508 * @rate: New clock rate in Hz.
510 * Return: new rate, or -ve error code.
512 ulong clk_set_rate(struct clk *clk, ulong rate);
515 * clk_set_parent() - Set current clock parent.
516 * @clk: A clock struct that was previously successfully requested by
517 * clk_request/get_by_*().
518 * @parent: A clock struct that was previously successfully requested by
519 * clk_request/get_by_*().
521 * Return: new rate, or -ve error code.
523 int clk_set_parent(struct clk *clk, struct clk *parent);
526 * clk_enable() - Enable (turn on) a clock.
527 * @clk: A clock struct that was previously successfully requested by
528 * clk_request/get_by_*().
530 * Return: zero on success, or -ve error code.
532 int clk_enable(struct clk *clk);
535 * clk_enable_bulk() - Enable (turn on) all clocks in a clock bulk struct.
536 * @bulk: A clock bulk struct that was previously successfully requested
539 * Return: zero on success, or -ve error code.
541 int clk_enable_bulk(struct clk_bulk *bulk);
544 * clk_disable() - Disable (turn off) a clock.
545 * @clk: A clock struct that was previously successfully requested by
546 * clk_request/get_by_*().
548 * Return: zero on success, or -ve error code.
550 int clk_disable(struct clk *clk);
553 * clk_disable_bulk() - Disable (turn off) all clocks in a clock bulk struct.
554 * @bulk: A clock bulk struct that was previously successfully requested
557 * Return: zero on success, or -ve error code.
559 int clk_disable_bulk(struct clk_bulk *bulk);
562 * clk_is_match - check if two clk's point to the same hardware clock
563 * @p: clk compared against q
564 * @q: clk compared against p
567 * %true if the two struct clk pointers both point to the same hardware clock
568 * node, and %false otherwise. Note that two %NULL clks are treated as matching.
570 bool clk_is_match(const struct clk *p, const struct clk *q);
573 * clk_get_by_id() - Get the clock by its ID
574 * @id: The clock ID to search for
575 * @clkp: A pointer to clock struct that has been found among added clocks
578 * Return: zero on success, or -ENOENT on error
580 int clk_get_by_id(ulong id, struct clk **clkp);
583 * clk_dev_binded() - Check whether the clk has a device binded
584 * @clk: A pointer to the clk
586 * Return: true on binded, or false on no
588 bool clk_dev_binded(struct clk *clk);
590 #else /* CONFIG_IS_ENABLED(CLK) */
592 static inline int clk_request(struct udevice *dev, struct clk *clk)
597 static inline void clk_free(struct clk *clk)
602 static inline ulong clk_get_rate(struct clk *clk)
607 static inline struct clk *clk_get_parent(struct clk *clk)
609 return ERR_PTR(-ENOSYS);
612 static inline ulong clk_get_parent_rate(struct clk *clk)
617 static inline ulong clk_round_rate(struct clk *clk, ulong rate)
622 static inline ulong clk_set_rate(struct clk *clk, ulong rate)
627 static inline int clk_set_parent(struct clk *clk, struct clk *parent)
632 static inline int clk_enable(struct clk *clk)
637 static inline int clk_enable_bulk(struct clk_bulk *bulk)
642 static inline int clk_disable(struct clk *clk)
647 static inline int clk_disable_bulk(struct clk_bulk *bulk)
652 static inline bool clk_is_match(const struct clk *p, const struct clk *q)
657 static inline int clk_get_by_id(ulong id, struct clk **clkp)
662 static inline bool clk_dev_binded(struct clk *clk)
666 #endif /* CONFIG_IS_ENABLED(CLK) */
669 * clk_valid() - check if clk is valid
670 * @clk: the clock to check
672 * Return: true if valid, or false
674 static inline bool clk_valid(struct clk *clk)
676 return clk && !!clk->dev;
679 int soc_clk_dump(void);
683 #define clk_prepare_enable(clk) clk_enable(clk)
684 #define clk_disable_unprepare(clk) clk_disable(clk)