183d290c5STom Rini /* SPDX-License-Identifier: GPL-2.0+ */
2f26c8a8eSSimon Glass /*
3f26c8a8eSSimon Glass * Copyright (c) 2015 Google, Inc
4f26c8a8eSSimon Glass * Written by Simon Glass <sjg@chromium.org>
5135aa950SStephen Warren * Copyright (c) 2016, NVIDIA CORPORATION.
6f26c8a8eSSimon Glass */
7f26c8a8eSSimon Glass
808d0d6f3SMichal Simek #ifndef _CLK_H_
908d0d6f3SMichal Simek #define _CLK_H_
1008d0d6f3SMichal Simek
111221ce45SMasahiro Yamada #include <linux/errno.h>
12ad1cf785SMasahiro Yamada #include <linux/types.h>
13ad1cf785SMasahiro Yamada
14135aa950SStephen Warren /**
15135aa950SStephen Warren * A clock is a hardware signal that oscillates autonomously at a specific
16135aa950SStephen Warren * frequency and duty cycle. Most hardware modules require one or more clock
17135aa950SStephen Warren * signal to drive their operation. Clock signals are typically generated
18135aa950SStephen Warren * externally to the HW module consuming them, by an entity this API calls a
19135aa950SStephen Warren * clock provider. This API provides a standard means for drivers to enable and
20135aa950SStephen Warren * disable clocks, and to set the rate at which they oscillate.
21135aa950SStephen Warren *
22135aa950SStephen Warren * A driver that implements UCLASS_CLOCK is a clock provider. A provider will
23135aa950SStephen Warren * often implement multiple separate clocks, since the hardware it manages
24*9bf86506SLiviu Dudau * often has this capability. clk-uclass.h describes the interface which
25135aa950SStephen Warren * clock providers must implement.
26135aa950SStephen Warren *
27135aa950SStephen Warren * Clock consumers/clients are the HW modules driven by the clock signals. This
28135aa950SStephen Warren * header file describes the API used by drivers for those HW modules.
29135aa950SStephen Warren */
30135aa950SStephen Warren
31ad1cf785SMasahiro Yamada struct udevice;
32ad1cf785SMasahiro Yamada
33f26c8a8eSSimon Glass /**
34135aa950SStephen Warren * struct clk - A handle to (allowing control of) a single clock.
35f26c8a8eSSimon Glass *
36135aa950SStephen Warren * Clients provide storage for clock handles. The content of the structure is
37135aa950SStephen Warren * managed solely by the clock API and clock drivers. A clock struct is
38135aa950SStephen Warren * initialized by "get"ing the clock struct. The clock struct is passed to all
39135aa950SStephen Warren * other clock APIs to identify which clock signal to operate upon.
40f26c8a8eSSimon Glass *
41135aa950SStephen Warren * @dev: The device which implements the clock signal.
42135aa950SStephen Warren * @id: The clock signal ID within the provider.
433b3969bdSAndreas Dannenberg * @data: An optional data field for scenarios where a single integer ID is not
443b3969bdSAndreas Dannenberg * sufficient. If used, it can be populated through an .of_xlate op and
453b3969bdSAndreas Dannenberg * processed during the various clock ops.
46f0e07516SMasahiro Yamada *
473b3969bdSAndreas Dannenberg * Should additional information to identify and configure any clock signal
483b3969bdSAndreas Dannenberg * for any provider be required in the future, the struct could be expanded to
49135aa950SStephen Warren * either (a) add more fields to allow clock providers to store additional
50135aa950SStephen Warren * information, or (b) replace the id field with an opaque pointer, which the
51135aa950SStephen Warren * provider would dynamically allocated during its .of_xlate op, and process
52135aa950SStephen Warren * during is .request op. This may require the addition of an extra op to clean
53135aa950SStephen Warren * up the allocation.
54f0e07516SMasahiro Yamada */
55135aa950SStephen Warren struct clk {
56135aa950SStephen Warren struct udevice *dev;
57135aa950SStephen Warren /*
583b3969bdSAndreas Dannenberg * Written by of_xlate. In the future, we might add more fields here.
59f26c8a8eSSimon Glass */
60135aa950SStephen Warren unsigned long id;
613b3969bdSAndreas Dannenberg unsigned long data;
62f26c8a8eSSimon Glass };
63f26c8a8eSSimon Glass
64a855be87SNeil Armstrong /**
65a855be87SNeil Armstrong * struct clk_bulk - A handle to (allowing control of) a bulk of clocks.
66a855be87SNeil Armstrong *
67a855be87SNeil Armstrong * Clients provide storage for the clock bulk. The content of the structure is
68a855be87SNeil Armstrong * managed solely by the clock API. A clock bulk struct is
69a855be87SNeil Armstrong * initialized by "get"ing the clock bulk struct.
70a855be87SNeil Armstrong * The clock bulk struct is passed to all other bulk clock APIs to apply
71a855be87SNeil Armstrong * the API to all the clock in the bulk struct.
72a855be87SNeil Armstrong *
73a855be87SNeil Armstrong * @clks: An array of clock handles.
74a855be87SNeil Armstrong * @count: The number of clock handles in the clks array.
75a855be87SNeil Armstrong */
76a855be87SNeil Armstrong struct clk_bulk {
77a855be87SNeil Armstrong struct clk *clks;
78a855be87SNeil Armstrong unsigned int count;
79a855be87SNeil Armstrong };
80a855be87SNeil Armstrong
813f96f875SPaul Burton #if CONFIG_IS_ENABLED(OF_CONTROL) && CONFIG_IS_ENABLED(CLK)
820d15463cSSimon Glass struct phandle_1_arg;
837423daa6SSimon Glass int clk_get_by_index_platdata(struct udevice *dev, int index,
840d15463cSSimon Glass struct phandle_1_arg *cells, struct clk *clk);
857423daa6SSimon Glass
86e70cc438SSimon Glass /**
87135aa950SStephen Warren * clock_get_by_index - Get/request a clock by integer index.
88e70cc438SSimon Glass *
89135aa950SStephen Warren * This looks up and requests a clock. The index is relative to the client
90135aa950SStephen Warren * device; each device is assumed to have n clocks associated with it somehow,
91135aa950SStephen Warren * and this function finds and requests one of them. The mapping of client
92135aa950SStephen Warren * device clock indices to provider clocks may be via device-tree properties,
93135aa950SStephen Warren * board-provided mapping tables, or some other mechanism.
94e70cc438SSimon Glass *
95135aa950SStephen Warren * @dev: The client device.
96135aa950SStephen Warren * @index: The index of the clock to request, within the client's list of
97135aa950SStephen Warren * clocks.
98135aa950SStephen Warren * @clock A pointer to a clock struct to initialize.
99135aa950SStephen Warren * @return 0 if OK, or a negative error code.
100e70cc438SSimon Glass */
101135aa950SStephen Warren int clk_get_by_index(struct udevice *dev, int index, struct clk *clk);
102135aa950SStephen Warren
103135aa950SStephen Warren /**
104a855be87SNeil Armstrong * clock_get_bulk - Get/request all clocks of a device.
105a855be87SNeil Armstrong *
106a855be87SNeil Armstrong * This looks up and requests all clocks of the client device; each device is
107a855be87SNeil Armstrong * assumed to have n clocks associated with it somehow, and this function finds
108a855be87SNeil Armstrong * and requests all of them in a separate structure. The mapping of client
109a855be87SNeil Armstrong * device clock indices to provider clocks may be via device-tree properties,
110a855be87SNeil Armstrong * board-provided mapping tables, or some other mechanism.
111a855be87SNeil Armstrong *
112a855be87SNeil Armstrong * @dev: The client device.
113a855be87SNeil Armstrong * @bulk A pointer to a clock bulk struct to initialize.
114a855be87SNeil Armstrong * @return 0 if OK, or a negative error code.
115a855be87SNeil Armstrong */
116a855be87SNeil Armstrong int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk);
117a855be87SNeil Armstrong
118a855be87SNeil Armstrong /**
119135aa950SStephen Warren * clock_get_by_name - Get/request a clock by name.
120135aa950SStephen Warren *
121135aa950SStephen Warren * This looks up and requests a clock. The name is relative to the client
122135aa950SStephen Warren * device; each device is assumed to have n clocks associated with it somehow,
123135aa950SStephen Warren * and this function finds and requests one of them. The mapping of client
124135aa950SStephen Warren * device clock names to provider clocks may be via device-tree properties,
125135aa950SStephen Warren * board-provided mapping tables, or some other mechanism.
126135aa950SStephen Warren *
127135aa950SStephen Warren * @dev: The client device.
128135aa950SStephen Warren * @name: The name of the clock to request, within the client's list of
129135aa950SStephen Warren * clocks.
130135aa950SStephen Warren * @clock: A pointer to a clock struct to initialize.
131135aa950SStephen Warren * @return 0 if OK, or a negative error code.
132135aa950SStephen Warren */
133135aa950SStephen Warren int clk_get_by_name(struct udevice *dev, const char *name, struct clk *clk);
134b108d8a0SPatrice Chotard
135b108d8a0SPatrice Chotard /**
136b108d8a0SPatrice Chotard * clk_release_all() - Disable (turn off)/Free an array of previously
137b108d8a0SPatrice Chotard * requested clocks.
138b108d8a0SPatrice Chotard *
139b108d8a0SPatrice Chotard * For each clock contained in the clock array, this function will check if
140b108d8a0SPatrice Chotard * clock has been previously requested and then will disable and free it.
141b108d8a0SPatrice Chotard *
142b108d8a0SPatrice Chotard * @clk: A clock struct array that was previously successfully
143b108d8a0SPatrice Chotard * requested by clk_request/get_by_*().
144b108d8a0SPatrice Chotard * @count Number of clock contained in the array
145b108d8a0SPatrice Chotard * @return zero on success, or -ve error code.
146b108d8a0SPatrice Chotard */
147b108d8a0SPatrice Chotard int clk_release_all(struct clk *clk, int count);
148b108d8a0SPatrice Chotard
149021abf69SMasahiro Yamada #else
clk_get_by_index(struct udevice * dev,int index,struct clk * clk)150021abf69SMasahiro Yamada static inline int clk_get_by_index(struct udevice *dev, int index,
151021abf69SMasahiro Yamada struct clk *clk)
152021abf69SMasahiro Yamada {
153021abf69SMasahiro Yamada return -ENOSYS;
154021abf69SMasahiro Yamada }
155021abf69SMasahiro Yamada
clk_get_bulk(struct udevice * dev,struct clk_bulk * bulk)156a855be87SNeil Armstrong static inline int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk)
157a855be87SNeil Armstrong {
158a855be87SNeil Armstrong return -ENOSYS;
159a855be87SNeil Armstrong }
160a855be87SNeil Armstrong
clk_get_by_name(struct udevice * dev,const char * name,struct clk * clk)161021abf69SMasahiro Yamada static inline int clk_get_by_name(struct udevice *dev, const char *name,
162021abf69SMasahiro Yamada struct clk *clk)
163021abf69SMasahiro Yamada {
164021abf69SMasahiro Yamada return -ENOSYS;
165021abf69SMasahiro Yamada }
166b108d8a0SPatrice Chotard
clk_release_all(struct clk * clk,int count)167b108d8a0SPatrice Chotard static inline int clk_release_all(struct clk *clk, int count)
168b108d8a0SPatrice Chotard {
169b108d8a0SPatrice Chotard return -ENOSYS;
170b108d8a0SPatrice Chotard }
171021abf69SMasahiro Yamada #endif
172e70cc438SSimon Glass
173f4fcba5cSPhilipp Tomsich #if (CONFIG_IS_ENABLED(OF_CONTROL) && !CONFIG_IS_ENABLED(OF_PLATDATA)) && \
174f4fcba5cSPhilipp Tomsich CONFIG_IS_ENABLED(CLK)
175f4fcba5cSPhilipp Tomsich /**
176f4fcba5cSPhilipp Tomsich * clk_set_defaults - Process 'assigned-{clocks/clock-parents/clock-rates}'
177f4fcba5cSPhilipp Tomsich * properties to configure clocks
178f4fcba5cSPhilipp Tomsich *
179f4fcba5cSPhilipp Tomsich * @dev: A device to process (the ofnode associated with this device
180f4fcba5cSPhilipp Tomsich * will be processed).
181f4fcba5cSPhilipp Tomsich */
182f4fcba5cSPhilipp Tomsich int clk_set_defaults(struct udevice *dev);
183f4fcba5cSPhilipp Tomsich #else
clk_set_defaults(struct udevice * dev)184f4fcba5cSPhilipp Tomsich static inline int clk_set_defaults(struct udevice *dev)
185f4fcba5cSPhilipp Tomsich {
186f4fcba5cSPhilipp Tomsich return 0;
187f4fcba5cSPhilipp Tomsich }
188f4fcba5cSPhilipp Tomsich #endif
189f4fcba5cSPhilipp Tomsich
190135aa950SStephen Warren /**
191a855be87SNeil Armstrong * clk_release_bulk() - Disable (turn off)/Free an array of previously
192a855be87SNeil Armstrong * requested clocks in a clock bulk struct.
193a855be87SNeil Armstrong *
194a855be87SNeil Armstrong * For each clock contained in the clock bulk struct, this function will check
195a855be87SNeil Armstrong * if clock has been previously requested and then will disable and free it.
196a855be87SNeil Armstrong *
197a855be87SNeil Armstrong * @clk: A clock bulk struct that was previously successfully
198a855be87SNeil Armstrong * requested by clk_get_bulk().
199a855be87SNeil Armstrong * @return zero on success, or -ve error code.
200a855be87SNeil Armstrong */
clk_release_bulk(struct clk_bulk * bulk)201a855be87SNeil Armstrong static inline int clk_release_bulk(struct clk_bulk *bulk)
202a855be87SNeil Armstrong {
203a855be87SNeil Armstrong return clk_release_all(bulk->clks, bulk->count);
204a855be87SNeil Armstrong }
205a855be87SNeil Armstrong
206a855be87SNeil Armstrong /**
207135aa950SStephen Warren * clk_request - Request a clock by provider-specific ID.
208135aa950SStephen Warren *
209135aa950SStephen Warren * This requests a clock using a provider-specific ID. Generally, this function
210135aa950SStephen Warren * should not be used, since clk_get_by_index/name() provide an interface that
211135aa950SStephen Warren * better separates clients from intimate knowledge of clock providers.
212135aa950SStephen Warren * However, this function may be useful in core SoC-specific code.
213135aa950SStephen Warren *
214135aa950SStephen Warren * @dev: The clock provider device.
215135aa950SStephen Warren * @clock: A pointer to a clock struct to initialize. The caller must
216135aa950SStephen Warren * have already initialized any field in this struct which the
217135aa950SStephen Warren * clock provider uses to identify the clock.
218135aa950SStephen Warren * @return 0 if OK, or a negative error code.
219135aa950SStephen Warren */
220135aa950SStephen Warren int clk_request(struct udevice *dev, struct clk *clk);
221135aa950SStephen Warren
222135aa950SStephen Warren /**
223135aa950SStephen Warren * clock_free - Free a previously requested clock.
224135aa950SStephen Warren *
225135aa950SStephen Warren * @clock: A clock struct that was previously successfully requested by
226135aa950SStephen Warren * clk_request/get_by_*().
227135aa950SStephen Warren * @return 0 if OK, or a negative error code.
228135aa950SStephen Warren */
229135aa950SStephen Warren int clk_free(struct clk *clk);
230135aa950SStephen Warren
231135aa950SStephen Warren /**
232135aa950SStephen Warren * clk_get_rate() - Get current clock rate.
233135aa950SStephen Warren *
234135aa950SStephen Warren * @clk: A clock struct that was previously successfully requested by
235135aa950SStephen Warren * clk_request/get_by_*().
236135aa950SStephen Warren * @return clock rate in Hz, or -ve error code.
237135aa950SStephen Warren */
238135aa950SStephen Warren ulong clk_get_rate(struct clk *clk);
239135aa950SStephen Warren
240135aa950SStephen Warren /**
241135aa950SStephen Warren * clk_set_rate() - Set current clock rate.
242135aa950SStephen Warren *
243135aa950SStephen Warren * @clk: A clock struct that was previously successfully requested by
244135aa950SStephen Warren * clk_request/get_by_*().
245135aa950SStephen Warren * @rate: New clock rate in Hz.
246135aa950SStephen Warren * @return new rate, or -ve error code.
247135aa950SStephen Warren */
248135aa950SStephen Warren ulong clk_set_rate(struct clk *clk, ulong rate);
249135aa950SStephen Warren
250135aa950SStephen Warren /**
251f7d1046dSPhilipp Tomsich * clk_set_parent() - Set current clock parent.
252f7d1046dSPhilipp Tomsich *
253f7d1046dSPhilipp Tomsich * @clk: A clock struct that was previously successfully requested by
254f7d1046dSPhilipp Tomsich * clk_request/get_by_*().
255f7d1046dSPhilipp Tomsich * @parent: A clock struct that was previously successfully requested by
256f7d1046dSPhilipp Tomsich * clk_request/get_by_*().
257f7d1046dSPhilipp Tomsich * @return new rate, or -ve error code.
258f7d1046dSPhilipp Tomsich */
259f7d1046dSPhilipp Tomsich int clk_set_parent(struct clk *clk, struct clk *parent);
260f7d1046dSPhilipp Tomsich
261f7d1046dSPhilipp Tomsich /**
262135aa950SStephen Warren * clk_enable() - Enable (turn on) a clock.
263135aa950SStephen Warren *
264135aa950SStephen Warren * @clk: A clock struct that was previously successfully requested by
265135aa950SStephen Warren * clk_request/get_by_*().
266135aa950SStephen Warren * @return zero on success, or -ve error code.
267135aa950SStephen Warren */
268135aa950SStephen Warren int clk_enable(struct clk *clk);
269135aa950SStephen Warren
270135aa950SStephen Warren /**
271a855be87SNeil Armstrong * clk_enable_bulk() - Enable (turn on) all clocks in a clock bulk struct.
272a855be87SNeil Armstrong *
273a855be87SNeil Armstrong * @bulk: A clock bulk struct that was previously successfully requested
274a855be87SNeil Armstrong * by clk_get_bulk().
275a855be87SNeil Armstrong * @return zero on success, or -ve error code.
276a855be87SNeil Armstrong */
277a855be87SNeil Armstrong int clk_enable_bulk(struct clk_bulk *bulk);
278a855be87SNeil Armstrong
279a855be87SNeil Armstrong /**
280135aa950SStephen Warren * clk_disable() - Disable (turn off) a clock.
281135aa950SStephen Warren *
282135aa950SStephen Warren * @clk: A clock struct that was previously successfully requested by
283135aa950SStephen Warren * clk_request/get_by_*().
284135aa950SStephen Warren * @return zero on success, or -ve error code.
285135aa950SStephen Warren */
286135aa950SStephen Warren int clk_disable(struct clk *clk);
287135aa950SStephen Warren
288a855be87SNeil Armstrong /**
289a855be87SNeil Armstrong * clk_disable_bulk() - Disable (turn off) all clocks in a clock bulk struct.
290a855be87SNeil Armstrong *
291a855be87SNeil Armstrong * @bulk: A clock bulk struct that was previously successfully requested
292a855be87SNeil Armstrong * by clk_get_bulk().
293a855be87SNeil Armstrong * @return zero on success, or -ve error code.
294a855be87SNeil Armstrong */
295a855be87SNeil Armstrong int clk_disable_bulk(struct clk_bulk *bulk);
296a855be87SNeil Armstrong
297135aa950SStephen Warren int soc_clk_dump(void);
298135aa950SStephen Warren
2991fe243a1SFabrice Gasnier /**
3001fe243a1SFabrice Gasnier * clk_valid() - check if clk is valid
3011fe243a1SFabrice Gasnier *
3021fe243a1SFabrice Gasnier * @clk: the clock to check
3031fe243a1SFabrice Gasnier * @return true if valid, or false
3041fe243a1SFabrice Gasnier */
clk_valid(struct clk * clk)3051fe243a1SFabrice Gasnier static inline bool clk_valid(struct clk *clk)
3061fe243a1SFabrice Gasnier {
3071fe243a1SFabrice Gasnier return !!clk->dev;
3081fe243a1SFabrice Gasnier }
309135aa950SStephen Warren #endif
310