1 /*
2 * Copyright (c) 2015 Google, Inc
3 * Written by Simon Glass <sjg@chromium.org>
4 * Copyright (c) 2016, NVIDIA CORPORATION.
5 *
6 * SPDX-License-Identifier: GPL-2.0+
7 */
8
9 #ifndef _CLK_H_
10 #define _CLK_H_
11
12 #include <linux/errno.h>
13 #include <linux/types.h>
14
15 /**
16 * A clock is a hardware signal that oscillates autonomously at a specific
17 * frequency and duty cycle. Most hardware modules require one or more clock
18 * signal to drive their operation. Clock signals are typically generated
19 * externally to the HW module consuming them, by an entity this API calls a
20 * clock provider. This API provides a standard means for drivers to enable and
21 * disable clocks, and to set the rate at which they oscillate.
22 *
23 * A driver that implements UCLASS_CLOCK is a clock provider. A provider will
24 * often implement multiple separate clocks, since the hardware it manages
25 * often has this capability. clock_uclass.h describes the interface which
26 * clock providers must implement.
27 *
28 * Clock consumers/clients are the HW modules driven by the clock signals. This
29 * header file describes the API used by drivers for those HW modules.
30 */
31
32 struct udevice;
33
34 /**
35 * struct clk - A handle to (allowing control of) a single clock.
36 *
37 * Clients provide storage for clock handles. The content of the structure is
38 * managed solely by the clock API and clock drivers. A clock struct is
39 * initialized by "get"ing the clock struct. The clock struct is passed to all
40 * other clock APIs to identify which clock signal to operate upon.
41 *
42 * @dev: The device which implements the clock signal.
43 * @id: The clock signal ID within the provider.
44 *
45 * Currently, the clock API assumes that a single integer ID is enough to
46 * identify and configure any clock signal for any clock provider. If this
47 * assumption becomes invalid in the future, the struct could be expanded to
48 * either (a) add more fields to allow clock providers to store additional
49 * information, or (b) replace the id field with an opaque pointer, which the
50 * provider would dynamically allocated during its .of_xlate op, and process
51 * during is .request op. This may require the addition of an extra op to clean
52 * up the allocation.
53 */
54 struct clk {
55 struct udevice *dev;
56 /*
57 * Written by of_xlate. We assume a single id is enough for now. In the
58 * future, we might add more fields here.
59 */
60 unsigned long id;
61 };
62
63 /**
64 * struct clk_bulk - A handle to (allowing control of) a bulk of clocks.
65 *
66 * Clients provide storage for the clock bulk. The content of the structure is
67 * managed solely by the clock API. A clock bulk struct is
68 * initialized by "get"ing the clock bulk struct.
69 * The clock bulk struct is passed to all other bulk clock APIs to apply
70 * the API to all the clock in the bulk struct.
71 *
72 * @clks: An array of clock handles.
73 * @count: The number of clock handles in the clks array.
74 */
75 struct clk_bulk {
76 struct clk *clks;
77 unsigned int count;
78 };
79
80 #if CONFIG_IS_ENABLED(OF_CONTROL) && CONFIG_IS_ENABLED(CLK)
81 struct phandle_1_arg;
82 int clk_get_by_index_platdata(struct udevice *dev, int index,
83 struct phandle_1_arg *cells, struct clk *clk);
84
85 /**
86 * clock_get_by_index - Get/request a clock by integer index.
87 *
88 * This looks up and requests a clock. The index is relative to the client
89 * device; each device is assumed to have n clocks associated with it somehow,
90 * and this function finds and requests one of them. The mapping of client
91 * device clock indices to provider clocks may be via device-tree properties,
92 * board-provided mapping tables, or some other mechanism.
93 *
94 * @dev: The client device.
95 * @index: The index of the clock to request, within the client's list of
96 * clocks.
97 * @clock A pointer to a clock struct to initialize.
98 * @return 0 if OK, or a negative error code.
99 */
100 int clk_get_by_index(struct udevice *dev, int index, struct clk *clk);
101
102 /**
103 * clock_get_bulk - Get/request all clocks of a device.
104 *
105 * This looks up and requests all clocks of the client device; each device is
106 * assumed to have n clocks associated with it somehow, and this function finds
107 * and requests all of them in a separate structure. The mapping of client
108 * device clock indices to provider clocks may be via device-tree properties,
109 * board-provided mapping tables, or some other mechanism.
110 *
111 * @dev: The client device.
112 * @bulk A pointer to a clock bulk struct to initialize.
113 * @return 0 if OK, or a negative error code.
114 */
115 int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk);
116
117 /**
118 * clock_get_by_name - Get/request a clock by name.
119 *
120 * This looks up and requests a clock. The name is relative to the client
121 * device; each device is assumed to have n clocks associated with it somehow,
122 * and this function finds and requests one of them. The mapping of client
123 * device clock names to provider clocks may be via device-tree properties,
124 * board-provided mapping tables, or some other mechanism.
125 *
126 * @dev: The client device.
127 * @name: The name of the clock to request, within the client's list of
128 * clocks.
129 * @clock: A pointer to a clock struct to initialize.
130 * @return 0 if OK, or a negative error code.
131 */
132 int clk_get_by_name(struct udevice *dev, const char *name, struct clk *clk);
133
134 /**
135 * clk_release_all() - Disable (turn off)/Free an array of previously
136 * requested clocks.
137 *
138 * For each clock contained in the clock array, this function will check if
139 * clock has been previously requested and then will disable and free it.
140 *
141 * @clk: A clock struct array that was previously successfully
142 * requested by clk_request/get_by_*().
143 * @count Number of clock contained in the array
144 * @return zero on success, or -ve error code.
145 */
146 int clk_release_all(struct clk *clk, int count);
147
148 #else
clk_get_by_index(struct udevice * dev,int index,struct clk * clk)149 static inline int clk_get_by_index(struct udevice *dev, int index,
150 struct clk *clk)
151 {
152 return -ENOSYS;
153 }
154
clk_get_bulk(struct udevice * dev,struct clk_bulk * bulk)155 static inline int clk_get_bulk(struct udevice *dev, struct clk_bulk *bulk)
156 {
157 return -ENOSYS;
158 }
159
clk_get_by_name(struct udevice * dev,const char * name,struct clk * clk)160 static inline int clk_get_by_name(struct udevice *dev, const char *name,
161 struct clk *clk)
162 {
163 return -ENOSYS;
164 }
165
clk_release_all(struct clk * clk,int count)166 static inline int clk_release_all(struct clk *clk, int count)
167 {
168 return -ENOSYS;
169 }
170 #endif
171
172 #if (CONFIG_IS_ENABLED(OF_CONTROL) && !CONFIG_IS_ENABLED(OF_PLATDATA)) && \
173 CONFIG_IS_ENABLED(CLK)
174 /**
175 * clk_set_defaults - Process 'assigned-{clocks/clock-parents/clock-rates}'
176 * properties to configure clocks
177 *
178 * @dev: A device to process (the ofnode associated with this device
179 * will be processed).
180 */
181 int clk_set_defaults(struct udevice *dev);
182 #else
clk_set_defaults(struct udevice * dev)183 static inline int clk_set_defaults(struct udevice *dev)
184 {
185 return 0;
186 }
187 #endif
188
189 /**
190 * clk_release_bulk() - Disable (turn off)/Free an array of previously
191 * requested clocks in a clock bulk struct.
192 *
193 * For each clock contained in the clock bulk struct, this function will check
194 * if clock has been previously requested and then will disable and free it.
195 *
196 * @clk: A clock bulk struct that was previously successfully
197 * requested by clk_get_bulk().
198 * @return zero on success, or -ve error code.
199 */
clk_release_bulk(struct clk_bulk * bulk)200 static inline int clk_release_bulk(struct clk_bulk *bulk)
201 {
202 return clk_release_all(bulk->clks, bulk->count);
203 }
204
205 /**
206 * clk_request - Request a clock by provider-specific ID.
207 *
208 * This requests a clock using a provider-specific ID. Generally, this function
209 * should not be used, since clk_get_by_index/name() provide an interface that
210 * better separates clients from intimate knowledge of clock providers.
211 * However, this function may be useful in core SoC-specific code.
212 *
213 * @dev: The clock provider device.
214 * @clock: A pointer to a clock struct to initialize. The caller must
215 * have already initialized any field in this struct which the
216 * clock provider uses to identify the clock.
217 * @return 0 if OK, or a negative error code.
218 */
219 int clk_request(struct udevice *dev, struct clk *clk);
220
221 /**
222 * clock_free - Free a previously requested clock.
223 *
224 * @clock: A clock struct that was previously successfully requested by
225 * clk_request/get_by_*().
226 * @return 0 if OK, or a negative error code.
227 */
228 int clk_free(struct clk *clk);
229
230 /**
231 * clk_get_rate() - Get current clock rate.
232 *
233 * @clk: A clock struct that was previously successfully requested by
234 * clk_request/get_by_*().
235 * @return clock rate in Hz, or -ve error code.
236 */
237 ulong clk_get_rate(struct clk *clk);
238
239 /**
240 * clk_set_rate() - Set current clock rate.
241 *
242 * @clk: A clock struct that was previously successfully requested by
243 * clk_request/get_by_*().
244 * @rate: New clock rate in Hz.
245 * @return new rate, or -ve error code.
246 */
247 ulong clk_set_rate(struct clk *clk, ulong rate);
248
249 /**
250 * clk_get_phase() - Get the phase shift of a clock signal.
251 *
252 * @clk: A clock struct that was previously successfully requested by
253 * clk_request/get_by_*().
254 * @return the phase shift of a clock node in degrees, otherwise returns
255 * -ve error code.
256 */
257 int clk_get_phase(struct clk *clk);
258
259 /**
260 * clk_set_rate() - Adjust the phase shift of a clock signal.
261 *
262 * @clk: A clock struct that was previously successfully requested by
263 * clk_request/get_by_*().
264 * @degrees: Numberof degrees the signal is shifted.
265 * @return 0 on success, or -ve error code.
266 */
267 int clk_set_phase(struct clk *clk, int degrees);
268
269 /**
270 * clk_set_parent() - Set current clock parent.
271 *
272 * @clk: A clock struct that was previously successfully requested by
273 * clk_request/get_by_*().
274 * @parent: A clock struct that was previously successfully requested by
275 * clk_request/get_by_*().
276 * @return new rate, or -ve error code.
277 */
278 int clk_set_parent(struct clk *clk, struct clk *parent);
279
280 /**
281 * clk_enable() - Enable (turn on) a clock.
282 *
283 * @clk: A clock struct that was previously successfully requested by
284 * clk_request/get_by_*().
285 * @return zero on success, or -ve error code.
286 */
287 int clk_enable(struct clk *clk);
288
289 /**
290 * clk_enable_bulk() - Enable (turn on) all clocks in a clock bulk struct.
291 *
292 * @bulk: A clock bulk struct that was previously successfully requested
293 * by clk_get_bulk().
294 * @return zero on success, or -ve error code.
295 */
296 int clk_enable_bulk(struct clk_bulk *bulk);
297
298 /**
299 * clk_disable() - Disable (turn off) a clock.
300 *
301 * @clk: A clock struct that was previously successfully requested by
302 * clk_request/get_by_*().
303 * @return zero on success, or -ve error code.
304 */
305 int clk_disable(struct clk *clk);
306
307 /**
308 * clk_disable_bulk() - Disable (turn off) all clocks in a clock bulk struct.
309 *
310 * @bulk: A clock bulk struct that was previously successfully requested
311 * by clk_get_bulk().
312 * @return zero on success, or -ve error code.
313 */
314 int clk_disable_bulk(struct clk_bulk *bulk);
315
316 int soc_clk_dump(void);
317
318 int clks_probe(void);
319
320 /**
321 * clk_valid() - check if clk is valid
322 *
323 * @clk: the clock to check
324 * @return true if valid, or false
325 */
clk_valid(struct clk * clk)326 static inline bool clk_valid(struct clk *clk)
327 {
328 return !!clk->dev;
329 }
330 #endif
331