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_UCLASS_H
9#define _CLK_UCLASS_H
10
11/* See clk.h for background documentation. */
12
13#include <clk.h>
14
15struct ofnode_phandle_args;
16
17/**
18 * struct clk_ops - The functions that a clock driver must implement.
19 * @of_xlate: Translate a client's device-tree (OF) clock specifier.
20 * @request: Request a translated clock.
21 * @round_rate: Adjust a rate to the exact rate a clock can provide.
22 * @get_rate: Get current clock rate.
23 * @set_rate: Set current clock rate.
24 * @set_parent: Set current clock parent
25 * @enable: Enable a clock.
26 * @disable: Disable a clock.
27 * @dump: Print clock information.
28 *
29 * The individual methods are described more fully below.
30 */
31struct clk_ops {
32	int (*of_xlate)(struct clk *clock,
33			struct ofnode_phandle_args *args);
34	int (*request)(struct clk *clock);
35	ulong (*round_rate)(struct clk *clk, ulong rate);
36	ulong (*get_rate)(struct clk *clk);
37	ulong (*set_rate)(struct clk *clk, ulong rate);
38	int (*set_parent)(struct clk *clk, struct clk *parent);
39	int (*enable)(struct clk *clk);
40	int (*disable)(struct clk *clk);
41#if IS_ENABLED(CONFIG_CMD_CLK)
42	void (*dump)(struct udevice *dev);
43#endif
44};
45
46#if 0 /* For documentation only */
47/**
48 * of_xlate() - Translate a client's device-tree (OF) clock specifier.
49 * @clock:	The clock struct to hold the translation result.
50 * @args:	The clock specifier values from device tree.
51 *
52 * The clock core calls this function as the first step in implementing
53 * a client's clk_get_by_*() call.
54 *
55 * If this function pointer is set to NULL, the clock core will use a
56 * default implementation, which assumes #clock-cells = <1>, and that
57 * the DT cell contains a simple integer clock ID.
58 *
59 * This function should be a simple translation of @args into @clock->id and
60 * (optionally) @clock->data. All other processing, allocation, or error
61 * checking should take place in request().
62 *
63 * At present, the clock API solely supports device-tree. If this
64 * changes, other xxx_xlate() functions may be added to support those
65 * other mechanisms.
66 *
67 * Return:
68 * * 0 on success
69 * * -%EINVAL if @args does not have the correct format. For example, it could
70 *   have too many/few arguments.
71 * * -%ENOENT if @args has the correct format but cannot be translated. This can
72 *   happen if translation involves a table lookup and @args is not present.
73 */
74int of_xlate(struct clk *clock, struct ofnode_phandle_args *args);
75
76/**
77 * request() - Request a translated clock.
78 * @clock:	The clock struct to request; this has been filled in by
79 *		a previoux xxx_xlate() function call, or by the caller
80 *		of clk_request().
81 *
82 * The clock core calls this function as the second step in
83 * implementing a client's clk_get_by_*() call, following a successful
84 * xxx_xlate() call, or as the only step in implementing a client's
85 * clk_request() call.
86 *
87 * This is the right place to do bounds checking (rejecting invalid or
88 * unimplemented clocks), allocate resources, or perform other setup not done
89 * during driver probe(). Most clock drivers should allocate resources in their
90 * probe() function, but it is possible to lazily initialize something here.
91 *
92 * Return:
93 * * 0 on success
94 * * -%ENOENT, if there is no clock corresponding to @clock->id and
95 *   @clock->data.
96 */
97int request(struct clk *clock);
98
99/**
100 * round_rate() - Adjust a rate to the exact rate a clock can provide.
101 * @clk:	The clock to query.
102 * @rate:	Desired clock rate in Hz.
103 *
104 * This function returns a new rate which can be provided to set_rate(). This
105 * new rate should be the closest rate to @rate which can be set without
106 * rounding. The following pseudo-code should hold::
107 *
108 *   for all rate in range(ULONG_MAX):
109 *     rounded = round_rate(clk, rate)
110 *     new_rate = set_rate(clk, rate)
111 *     assert(IS_ERR_VALUE(new_rate) || new_rate == rounded)
112 *
113 * Return:
114 * * The rounded rate in Hz on success
115 * * A negative error value from another API (such as clk_get_rate()). This
116 *   function must not return an error for any other reason.
117 */
118ulong round_rate(struct clk *clk, ulong rate);
119
120/**
121 * get_rate() - Get current clock rate.
122 * @clk:	The clock to query.
123 *
124 * This returns the current rate of a clock. If the clock is disabled, it
125 * returns the rate at which the clock would run if it was enabled. The
126 * following pseudo-code should hold::
127 *
128 *   disable(clk)
129 *   rate = get_rate(clk)
130 *   enable(clk)
131 *   assert(get_rate(clk) == rate)
132 *
133 * Return:
134 * * The rate of @clk
135 * * -%ENOSYS if this function is not implemented for @clk
136 * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing
137 *   this check in request().
138 * * Another negative error value (such as %EIO or %ECOMM) if the rate could
139 *   not be determined due to a bus error.
140 */
141ulong get_rate(struct clk *clk);
142
143/**
144 * set_rate() - Set current clock rate.
145 * @clk:	The clock to manipulate.
146 * @rate:	New clock rate in Hz.
147 *
148 * Set the rate of @clk to @rate. The actual rate may be rounded. However,
149 * excessive rounding should be avoided. It is left to the driver author's
150 * discretion when this function should attempt to round and when it should
151 * return an error. For example, a dividing clock might use the following
152 * pseudo-logic when implemening this function::
153 *
154 *   divisor = parent_rate / rate
155 *   if divisor < min || divisor > max:
156 *     return -EINVAL
157 *
158 * If there is any concern about rounding, prefer to let consumers make the
159 * decision by calling round_rate().
160 *
161 * Return:
162 * * The new rate on success
163 * * -%ENOSYS if this function is not implemented for @clk
164 * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing
165 *   this check in request().
166 * * -%EINVAL if @rate is not valid for @clk.
167 * * Another negative error value (such as %EIO or %ECOMM) if the rate could
168 *   not be set due to a bus error.
169 */
170ulong set_rate(struct clk *clk, ulong rate);
171
172/**
173 * set_parent() - Set current clock parent
174 * @clk:        The clock to manipulate.
175 * @parent:     New clock parent.
176 *
177 * Set the current parent of @clk to @parent. The rate of the clock may be
178 * modified by this call. If @clk was enabled before this function, it should
179 * remain enabled after this function, although it may be temporarily disabled
180 * if necessary.
181 *
182 * Return:
183 * * 0 on success
184 * * -%ENOSYS if this function is not implemented for @clk
185 * * -%ENOENT if @clk->id or @parent->id is invalid. Prefer using an assert
186 *   instead, and doing this check in request().
187 * * -%EINVAL if @parent is not a valid parent for @clk.
188 * * Another negative error value (such as %EIO or %ECOMM) if the parent could
189 *   not be set due to a bus error.
190 */
191int set_parent(struct clk *clk, struct clk *parent);
192
193/**
194 * enable() - Enable a clock.
195 * @clk:	The clock to manipulate.
196 *
197 * Enable (un-gate) the clock. This function should not modify the rate of the
198 * clock (see get_rate() for details).
199 *
200 * Return:
201 * * 0 on success
202 * * -%ENOSYS if this function is not implemented for @clk
203 * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing
204 *   this check in request().
205 * * Another negative error value (such as %EIO or %ECOMM) if the clock could
206 *   not be enabled due to a bus error.
207 */
208int enable(struct clk *clk);
209
210/**
211 * disable() - Disable a clock.
212 * @clk:	The clock to manipulate.
213 *
214 * Disable (gate) the clock. This function should not modify the rate of the
215 * clock (see get_rate() for details).
216 *
217 * * 0 on success
218 * * -%ENOSYS if this function is not implemented for @clk
219 * * -%ENOENT if @clk->id is invalid. Prefer using an assert instead, and doing
220 *   this check in request().
221 * * Another negative error value (such as %EIO or %ECOMM) if the clock could
222 *   not be disabled due to a bus error.
223 */
224int disable(struct clk *clk);
225
226/**
227 * dump() - Print clock information.
228 * @dev:	The clock device to dump.
229 *
230 * If present, this function is called by "clk dump" command for each
231 * bound device.
232 */
233void dump(struct udevice *dev);
234#endif
235
236#endif
237