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 #if CONFIG_IS_ENABLED(OF_CONTROL) && CONFIG_IS_ENABLED(CLK) 64 struct phandle_1_arg; 65 int clk_get_by_index_platdata(struct udevice *dev, int index, 66 struct phandle_1_arg *cells, struct clk *clk); 67 68 /** 69 * clock_get_by_index - Get/request a clock by integer index. 70 * 71 * This looks up and requests a clock. The index is relative to the client 72 * device; each device is assumed to have n clocks associated with it somehow, 73 * and this function finds and requests one of them. The mapping of client 74 * device clock indices to provider clocks may be via device-tree properties, 75 * board-provided mapping tables, or some other mechanism. 76 * 77 * @dev: The client device. 78 * @index: The index of the clock to request, within the client's list of 79 * clocks. 80 * @clock A pointer to a clock struct to initialize. 81 * @return 0 if OK, or a negative error code. 82 */ 83 int clk_get_by_index(struct udevice *dev, int index, struct clk *clk); 84 85 /** 86 * clock_get_by_name - Get/request a clock by name. 87 * 88 * This looks up and requests a clock. The name 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 names 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 * @name: The name 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_name(struct udevice *dev, const char *name, struct clk *clk); 101 102 /** 103 * clk_release_all() - Disable (turn off)/Free an array of previously 104 * requested clocks. 105 * 106 * For each clock contained in the clock array, this function will check if 107 * clock has been previously requested and then will disable and free it. 108 * 109 * @clk: A clock struct array that was previously successfully 110 * requested by clk_request/get_by_*(). 111 * @count Number of clock contained in the array 112 * @return zero on success, or -ve error code. 113 */ 114 int clk_release_all(struct clk *clk, int count); 115 116 #else 117 static inline int clk_get_by_index(struct udevice *dev, int index, 118 struct clk *clk) 119 { 120 return -ENOSYS; 121 } 122 123 static inline int clk_get_by_name(struct udevice *dev, const char *name, 124 struct clk *clk) 125 { 126 return -ENOSYS; 127 } 128 129 static inline int clk_release_all(struct clk *clk, int count) 130 { 131 return -ENOSYS; 132 } 133 134 #endif 135 136 #if (CONFIG_IS_ENABLED(OF_CONTROL) && !CONFIG_IS_ENABLED(OF_PLATDATA)) && \ 137 CONFIG_IS_ENABLED(CLK) 138 /** 139 * clk_set_defaults - Process 'assigned-{clocks/clock-parents/clock-rates}' 140 * properties to configure clocks 141 * 142 * @dev: A device to process (the ofnode associated with this device 143 * will be processed). 144 */ 145 int clk_set_defaults(struct udevice *dev); 146 #else 147 static inline int clk_set_defaults(struct udevice *dev) 148 { 149 return 0; 150 } 151 #endif 152 153 /** 154 * clk_request - Request a clock by provider-specific ID. 155 * 156 * This requests a clock using a provider-specific ID. Generally, this function 157 * should not be used, since clk_get_by_index/name() provide an interface that 158 * better separates clients from intimate knowledge of clock providers. 159 * However, this function may be useful in core SoC-specific code. 160 * 161 * @dev: The clock provider device. 162 * @clock: A pointer to a clock struct to initialize. The caller must 163 * have already initialized any field in this struct which the 164 * clock provider uses to identify the clock. 165 * @return 0 if OK, or a negative error code. 166 */ 167 int clk_request(struct udevice *dev, struct clk *clk); 168 169 /** 170 * clock_free - Free a previously requested clock. 171 * 172 * @clock: A clock struct that was previously successfully requested by 173 * clk_request/get_by_*(). 174 * @return 0 if OK, or a negative error code. 175 */ 176 int clk_free(struct clk *clk); 177 178 /** 179 * clk_get_rate() - Get current clock rate. 180 * 181 * @clk: A clock struct that was previously successfully requested by 182 * clk_request/get_by_*(). 183 * @return clock rate in Hz, or -ve error code. 184 */ 185 ulong clk_get_rate(struct clk *clk); 186 187 /** 188 * clk_set_rate() - Set current clock rate. 189 * 190 * @clk: A clock struct that was previously successfully requested by 191 * clk_request/get_by_*(). 192 * @rate: New clock rate in Hz. 193 * @return new rate, or -ve error code. 194 */ 195 ulong clk_set_rate(struct clk *clk, ulong rate); 196 197 /** 198 * clk_set_parent() - Set current clock parent. 199 * 200 * @clk: A clock struct that was previously successfully requested by 201 * clk_request/get_by_*(). 202 * @parent: A clock struct that was previously successfully requested by 203 * clk_request/get_by_*(). 204 * @return new rate, or -ve error code. 205 */ 206 int clk_set_parent(struct clk *clk, struct clk *parent); 207 208 /** 209 * clk_enable() - Enable (turn on) a clock. 210 * 211 * @clk: A clock struct that was previously successfully requested by 212 * clk_request/get_by_*(). 213 * @return zero on success, or -ve error code. 214 */ 215 int clk_enable(struct clk *clk); 216 217 /** 218 * clk_disable() - Disable (turn off) a clock. 219 * 220 * @clk: A clock struct that was previously successfully requested by 221 * clk_request/get_by_*(). 222 * @return zero on success, or -ve error code. 223 */ 224 int clk_disable(struct clk *clk); 225 226 int soc_clk_dump(void); 227 228 #endif 229