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