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