blob: c6a2713f624b778bc932f889d9fa1c6c648e3034 [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001/* SPDX-License-Identifier: GPL-2.0+ */
Simon Glassf26c8a82015-06-23 15:39:15 -06002/*
3 * Copyright (c) 2015 Google, Inc
4 * Written by Simon Glass <sjg@chromium.org>
Stephen Warren135aa952016-06-17 09:44:00 -06005 * Copyright (c) 2016, NVIDIA CORPORATION.
Simon Glassf26c8a82015-06-23 15:39:15 -06006 */
7
Michal Simek08d0d6f2013-11-21 13:39:02 -08008#ifndef _CLK_H_
9#define _CLK_H_
10
Jagan Teki75f98312019-02-28 00:26:52 +053011#include <dm/ofnode.h>
Patrick Delaunay6f791742020-04-27 15:29:57 +020012#include <linux/err.h>
Masahiro Yamada1221ce42016-09-21 11:28:55 +090013#include <linux/errno.h>
Masahiro Yamadaad1cf782016-01-13 13:16:09 +090014#include <linux/types.h>
15
Stephen Warren135aa952016-06-17 09:44:00 -060016/**
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 *
Lukasz Majewskia9092712019-06-24 15:50:36 +020024 * A driver that implements UCLASS_CLK is a clock provider. A provider will
Stephen Warren135aa952016-06-17 09:44:00 -060025 * often implement multiple separate clocks, since the hardware it manages
Liviu Dudau9bf86502018-09-17 17:43:08 +010026 * often has this capability. clk-uclass.h describes the interface which
Stephen Warren135aa952016-06-17 09:44:00 -060027 * 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
Masahiro Yamadaad1cf782016-01-13 13:16:09 +090033struct udevice;
34
Stephen Warren135aa952016-06-17 09:44:00 -060035/**
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.
Lukasz Majewski105db952019-06-24 15:50:38 +020044 * @rate: The clock rate (in HZ).
Lukasz Majewskia8592cd2019-06-24 15:50:39 +020045 * @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).
Stephen Warren135aa952016-06-17 09:44:00 -060048 * @id: The clock signal ID within the provider.
Andreas Dannenberg3b3969b2018-08-27 15:57:42 +053049 * @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.
Stephen Warren135aa952016-06-17 09:44:00 -060052 *
Andreas Dannenberg3b3969b2018-08-27 15:57:42 +053053 * 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
Stephen Warren135aa952016-06-17 09:44:00 -060055 * 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 */
61struct clk {
62 struct udevice *dev;
Lukasz Majewski105db952019-06-24 15:50:38 +020063 long long rate; /* in HZ */
Lukasz Majewskia8592cd2019-06-24 15:50:39 +020064 u32 flags;
Peng Fane6849e22019-08-21 13:35:03 +000065 int enable_count;
Stephen Warren135aa952016-06-17 09:44:00 -060066 /*
Andreas Dannenberg3b3969b2018-08-27 15:57:42 +053067 * Written by of_xlate. In the future, we might add more fields here.
Simon Glassf26c8a82015-06-23 15:39:15 -060068 */
Stephen Warren135aa952016-06-17 09:44:00 -060069 unsigned long id;
Andreas Dannenberg3b3969b2018-08-27 15:57:42 +053070 unsigned long data;
Simon Glassf26c8a82015-06-23 15:39:15 -060071};
72
Neil Armstronga855be82018-04-03 11:44:18 +020073/**
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 */
85struct clk_bulk {
86 struct clk *clks;
87 unsigned int count;
88};
89
Paul Burton3f96f872016-09-08 07:47:28 +010090#if CONFIG_IS_ENABLED(OF_CONTROL) && CONFIG_IS_ENABLED(CLK)
Simon Glass0d154632017-08-29 14:15:56 -060091struct phandle_1_arg;
Simon Glass7423daa2016-07-04 11:58:03 -060092int clk_get_by_index_platdata(struct udevice *dev, int index,
Simon Glass0d154632017-08-29 14:15:56 -060093 struct phandle_1_arg *cells, struct clk *clk);
Simon Glass7423daa2016-07-04 11:58:03 -060094
Simon Glasse70cc432016-01-20 19:43:02 -070095/**
Jagan Tekid7c56612020-05-01 23:45:08 +053096 * clk_get_by_index - Get/request a clock by integer index.
Simon Glasse70cc432016-01-20 19:43:02 -070097 *
Stephen Warren135aa952016-06-17 09:44:00 -060098 * 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.
Simon Glasse70cc432016-01-20 19:43:02 -0700103 *
Stephen Warren135aa952016-06-17 09:44:00 -0600104 * @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.
Simon Glasse70cc432016-01-20 19:43:02 -0700109 */
Stephen Warren135aa952016-06-17 09:44:00 -0600110int clk_get_by_index(struct udevice *dev, int index, struct clk *clk);
111
112/**
Jagan Tekid7c56612020-05-01 23:45:08 +0530113 * clk_get_by_index_nodev - Get/request a clock by integer index
Jagan Teki75f98312019-02-28 00:26:52 +0530114 * 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 */
124int clk_get_by_index_nodev(ofnode node, int index, struct clk *clk);
125
126/**
Jagan Tekid7c56612020-05-01 23:45:08 +0530127 * clk_get_bulk - Get/request all clocks of a device.
Neil Armstronga855be82018-04-03 11:44:18 +0200128 *
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 */
139int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk);
140
141/**
Jagan Tekid7c56612020-05-01 23:45:08 +0530142 * clk_get_by_name - Get/request a clock by name.
Stephen Warren135aa952016-06-17 09:44:00 -0600143 *
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 */
156int clk_get_by_name(struct udevice *dev, const char *name, struct clk *clk);
Patrice Chotardb108d8a2017-07-25 13:24:45 +0200157
158/**
Chunfeng Yund6464202020-01-09 11:35:07 +0800159 * 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 */
169int clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk);
170
171/**
Jagan Tekid7c56612020-05-01 23:45:08 +0530172 * clk_get_optional_nodev - Get/request an optinonal clock by name
Chunfeng Yund6464202020-01-09 11:35:07 +0800173 * 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 */
184int clk_get_optional_nodev(ofnode node, const char *name, struct clk *clk);
185
186/**
Jean-Jacques Hiblot52720c52019-10-22 14:00:04 +0200187 * 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 */
204struct 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 */
215struct clk *devm_clk_get_optional(struct udevice *dev, const char *id);
216
217/**
Patrice Chotardb108d8a2017-07-25 13:24:45 +0200218 * 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 */
229int clk_release_all(struct clk *clk, int count);
230
Jean-Jacques Hiblot52720c52019-10-22 14:00:04 +0200231/**
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 */
242void devm_clk_put(struct udevice *dev, struct clk *clk);
243
Masahiro Yamada021abf62016-09-26 20:45:27 +0900244#else
245static inline int clk_get_by_index(struct udevice *dev, int index,
246 struct clk *clk)
247{
248 return -ENOSYS;
249}
250
Neil Armstronga855be82018-04-03 11:44:18 +0200251static inline int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk)
252{
253 return -ENOSYS;
254}
255
Masahiro Yamada021abf62016-09-26 20:45:27 +0900256static inline int clk_get_by_name(struct udevice *dev, const char *name,
257 struct clk *clk)
258{
259 return -ENOSYS;
260}
Patrice Chotardb108d8a2017-07-25 13:24:45 +0200261
Chunfeng Yund6464202020-01-09 11:35:07 +0800262static inline int
263clk_get_by_name_nodev(ofnode node, const char *name, struct clk *clk)
264{
265 return -ENOSYS;
266}
267
268static inline int
269clk_get_optional_nodev(ofnode node, const char *name, struct clk *clk)
270{
271 return -ENOSYS;
272}
273
Patrice Chotardb108d8a2017-07-25 13:24:45 +0200274static inline int clk_release_all(struct clk *clk, int count)
275{
276 return -ENOSYS;
277}
Masahiro Yamada021abf62016-09-26 20:45:27 +0900278#endif
Simon Glasse70cc432016-01-20 19:43:02 -0700279
Philipp Tomsichf4fcba52018-01-08 13:59:18 +0100280#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).
Jean-Jacques Hiblotfd1ba292019-10-22 14:00:06 +0200288 * @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
Philipp Tomsichf4fcba52018-01-08 13:59:18 +0100291 */
Jean-Jacques Hiblotfd1ba292019-10-22 14:00:06 +0200292int clk_set_defaults(struct udevice *dev, int stage);
Philipp Tomsichf4fcba52018-01-08 13:59:18 +0100293#else
Jean-Jacques Hiblotfd1ba292019-10-22 14:00:06 +0200294static inline int clk_set_defaults(struct udevice *dev, int stage)
Philipp Tomsichf4fcba52018-01-08 13:59:18 +0100295{
296 return 0;
297}
298#endif
299
Stephen Warren135aa952016-06-17 09:44:00 -0600300/**
Neil Armstronga855be82018-04-03 11:44:18 +0200301 * 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 */
311static inline int clk_release_bulk(struct clk_bulk *bulk)
312{
313 return clk_release_all(bulk->clks, bulk->count);
314}
315
Patrick Delaunay6f791742020-04-27 15:29:57 +0200316#if CONFIG_IS_ENABLED(CLK)
Neil Armstronga855be82018-04-03 11:44:18 +0200317/**
Stephen Warren135aa952016-06-17 09:44:00 -0600318 * 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 */
331int clk_request(struct udevice *dev, struct clk *clk);
332
333/**
Jagan Tekid7c56612020-05-01 23:45:08 +0530334 * clk_free - Free a previously requested clock.
Stephen Warren135aa952016-06-17 09:44:00 -0600335 *
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 */
340int 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 */
349ulong clk_get_rate(struct clk *clk);
350
351/**
Lukasz Majewski0c660c22019-06-24 15:50:42 +0200352 * 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 */
358struct clk *clk_get_parent(struct clk *clk);
359
360/**
Lukasz Majewski4aa78302019-06-24 15:50:43 +0200361 * 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 */
367long long clk_get_parent_rate(struct clk *clk);
368
369/**
Stephen Warren135aa952016-06-17 09:44:00 -0600370 * 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 */
377ulong clk_set_rate(struct clk *clk, ulong rate);
378
379/**
Philipp Tomsichf7d10462018-01-08 11:15:08 +0100380 * 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 */
388int clk_set_parent(struct clk *clk, struct clk *parent);
389
390/**
Stephen Warren135aa952016-06-17 09:44:00 -0600391 * 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 */
397int clk_enable(struct clk *clk);
398
399/**
Neil Armstronga855be82018-04-03 11:44:18 +0200400 * 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 */
406int clk_enable_bulk(struct clk_bulk *bulk);
407
408/**
Stephen Warren135aa952016-06-17 09:44:00 -0600409 * 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 */
415int clk_disable(struct clk *clk);
416
Neil Armstronga855be82018-04-03 11:44:18 +0200417/**
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 */
424int clk_disable_bulk(struct clk_bulk *bulk);
425
Sekhar Noriacbb7cd2019-08-01 19:12:55 +0530426/**
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 */
436bool clk_is_match(const struct clk *p, const struct clk *q);
437
Lukasz Majewski2796af72019-06-24 15:50:44 +0200438/**
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 */
447int clk_get_by_id(ulong id, struct clk **clkp);
Peng Fan24576122019-07-31 07:01:23 +0000448
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 */
456bool clk_dev_binded(struct clk *clk);
Patrick Delaunay6f791742020-04-27 15:29:57 +0200457
458#else /* CONFIG_IS_ENABLED(CLK) */
459
460static inline int clk_request(struct udevice *dev, struct clk *clk)
461{
462 return -ENOSYS;
463}
464
465static inline int clk_free(struct clk *clk)
466{
467 return 0;
468}
469
470static inline ulong clk_get_rate(struct clk *clk)
471{
472 return -ENOSYS;
473}
474
475static inline struct clk *clk_get_parent(struct clk *clk)
476{
477 return ERR_PTR(-ENOSYS);
478}
479
480static inline long long clk_get_parent_rate(struct clk *clk)
481{
482 return -ENOSYS;
483}
484
485static inline ulong clk_set_rate(struct clk *clk, ulong rate)
486{
487 return -ENOSYS;
488}
489
490static inline int clk_set_parent(struct clk *clk, struct clk *parent)
491{
492 return -ENOSYS;
493}
494
495static inline int clk_enable(struct clk *clk)
496{
497 return 0;
498}
499
500static inline int clk_enable_bulk(struct clk_bulk *bulk)
501{
502 return 0;
503}
504
505static inline int clk_disable(struct clk *clk)
506{
507 return 0;
508}
509
510static inline int clk_disable_bulk(struct clk_bulk *bulk)
511{
512 return 0;
513}
514
515static inline bool clk_is_match(const struct clk *p, const struct clk *q)
516{
517 return false;
518}
519
520static inline int clk_get_by_id(ulong id, struct clk **clkp)
521{
522 return -ENOSYS;
523}
524
525static 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 */
537static inline bool clk_valid(struct clk *clk)
538{
539 return clk && !!clk->dev;
540}
541
542int soc_clk_dump(void);
543
Stephen Warren135aa952016-06-17 09:44:00 -0600544#endif
Jean-Jacques Hiblot52720c52019-10-22 14:00:04 +0200545
546#define clk_prepare_enable(clk) clk_enable(clk)
547#define clk_disable_unprepare(clk) clk_disable(clk)