1 /* 2 * linux/include/linux/clk.h 3 * 4 * Copyright (C) 2004 ARM Limited. 5 * Written by Deep Blue Solutions Limited. 6 * Copyright (C) 2011-2012 Linaro Ltd <mturquette@linaro.org> 7 * 8 * This program is free software; you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License version 2 as 10 * published by the Free Software Foundation. 11 */ 12 #ifndef __LINUX_CLK_H 13 #define __LINUX_CLK_H 14 15 #include <linux/kernel.h> 16 #include <linux/notifier.h> 17 18 struct device; 19 20 struct clk; 21 22 #ifdef CONFIG_COMMON_CLK 23 24 /** 25 * DOC: clk notifier callback types 26 * 27 * PRE_RATE_CHANGE - called immediately before the clk rate is changed, 28 * to indicate that the rate change will proceed. Drivers must 29 * immediately terminate any operations that will be affected by the 30 * rate change. Callbacks may either return NOTIFY_DONE or 31 * NOTIFY_STOP. 32 * 33 * ABORT_RATE_CHANGE: called if the rate change failed for some reason 34 * after PRE_RATE_CHANGE. In this case, all registered notifiers on 35 * the clk will be called with ABORT_RATE_CHANGE. Callbacks must 36 * always return NOTIFY_DONE. 37 * 38 * POST_RATE_CHANGE - called after the clk rate change has successfully 39 * completed. Callbacks must always return NOTIFY_DONE. 40 * 41 */ 42 #define PRE_RATE_CHANGE BIT(0) 43 #define POST_RATE_CHANGE BIT(1) 44 #define ABORT_RATE_CHANGE BIT(2) 45 46 /** 47 * struct clk_notifier - associate a clk with a notifier 48 * @clk: struct clk * to associate the notifier with 49 * @notifier_head: a blocking_notifier_head for this clk 50 * @node: linked list pointers 51 * 52 * A list of struct clk_notifier is maintained by the notifier code. 53 * An entry is created whenever code registers the first notifier on a 54 * particular @clk. Future notifiers on that @clk are added to the 55 * @notifier_head. 56 */ 57 struct clk_notifier { 58 struct clk *clk; 59 struct srcu_notifier_head notifier_head; 60 struct list_head node; 61 }; 62 63 /** 64 * struct clk_notifier_data - rate data to pass to the notifier callback 65 * @clk: struct clk * being changed 66 * @old_rate: previous rate of this clk 67 * @new_rate: new rate of this clk 68 * 69 * For a pre-notifier, old_rate is the clk's rate before this rate 70 * change, and new_rate is what the rate will be in the future. For a 71 * post-notifier, old_rate and new_rate are both set to the clk's 72 * current rate (this was done to optimize the implementation). 73 */ 74 struct clk_notifier_data { 75 struct clk *clk; 76 unsigned long old_rate; 77 unsigned long new_rate; 78 }; 79 80 int clk_notifier_register(struct clk *clk, struct notifier_block *nb); 81 82 int clk_notifier_unregister(struct clk *clk, struct notifier_block *nb); 83 84 #endif /* !CONFIG_COMMON_CLK */ 85 86 /** 87 * clk_get - lookup and obtain a reference to a clock producer. 88 * @dev: device for clock "consumer" 89 * @id: clock comsumer ID 90 * 91 * Returns a struct clk corresponding to the clock producer, or 92 * valid IS_ERR() condition containing errno. The implementation 93 * uses @dev and @id to determine the clock consumer, and thereby 94 * the clock producer. (IOW, @id may be identical strings, but 95 * clk_get may return different clock producers depending on @dev.) 96 * 97 * Drivers must assume that the clock source is not enabled. 98 * 99 * clk_get should not be called from within interrupt context. 100 */ 101 struct clk *clk_get(struct device *dev, const char *id); 102 103 /** 104 * clk_prepare - prepare a clock source 105 * @clk: clock source 106 * 107 * This prepares the clock source for use. 108 * 109 * Must not be called from within atomic context. 110 */ 111 #ifdef CONFIG_HAVE_CLK_PREPARE 112 int clk_prepare(struct clk *clk); 113 #else clk_prepare(struct clk * clk)114 static inline int clk_prepare(struct clk *clk) 115 { 116 might_sleep(); 117 return 0; 118 } 119 #endif 120 121 /** 122 * clk_enable - inform the system when the clock source should be running. 123 * @clk: clock source 124 * 125 * If the clock can not be enabled/disabled, this should return success. 126 * 127 * May be called from atomic contexts. 128 * 129 * Returns success (0) or negative errno. 130 */ 131 int clk_enable(struct clk *clk); 132 133 /** 134 * clk_disable - inform the system when the clock source is no longer required. 135 * @clk: clock source 136 * 137 * Inform the system that a clock source is no longer required by 138 * a driver and may be shut down. 139 * 140 * May be called from atomic contexts. 141 * 142 * Implementation detail: if the clock source is shared between 143 * multiple drivers, clk_enable() calls must be balanced by the 144 * same number of clk_disable() calls for the clock source to be 145 * disabled. 146 */ 147 void clk_disable(struct clk *clk); 148 149 150 /** 151 * clk_unprepare - undo preparation of a clock source 152 * @clk: clock source 153 * 154 * This undoes a previously prepared clock. The caller must balance 155 * the number of prepare and unprepare calls. 156 * 157 * Must not be called from within atomic context. 158 */ 159 #ifdef CONFIG_HAVE_CLK_PREPARE 160 void clk_unprepare(struct clk *clk); 161 #else clk_unprepare(struct clk * clk)162 static inline void clk_unprepare(struct clk *clk) 163 { 164 might_sleep(); 165 } 166 #endif 167 168 /* clk_prepare_enable helps cases using clk_enable in non-atomic context. */ clk_prepare_enable(struct clk * clk)169 static inline int clk_prepare_enable(struct clk *clk) 170 { 171 int ret; 172 173 ret = clk_prepare(clk); 174 if (ret) 175 return ret; 176 ret = clk_enable(clk); 177 if (ret) 178 clk_unprepare(clk); 179 180 return ret; 181 } 182 183 /* clk_disable_unprepare helps cases using clk_disable in non-atomic context. */ clk_disable_unprepare(struct clk * clk)184 static inline void clk_disable_unprepare(struct clk *clk) 185 { 186 clk_disable(clk); 187 clk_unprepare(clk); 188 } 189 190 /** 191 * clk_get_rate - obtain the current clock rate (in Hz) for a clock source. 192 * This is only valid once the clock source has been enabled. 193 * @clk: clock source 194 */ 195 unsigned long clk_get_rate(struct clk *clk); 196 197 /** 198 * clk_put - "free" the clock source 199 * @clk: clock source 200 * 201 * Note: drivers must ensure that all clk_enable calls made on this 202 * clock source are balanced by clk_disable calls prior to calling 203 * this function. 204 * 205 * clk_put should not be called from within interrupt context. 206 */ 207 void clk_put(struct clk *clk); 208 209 210 /* 211 * The remaining APIs are optional for machine class support. 212 */ 213 214 215 /** 216 * clk_round_rate - adjust a rate to the exact rate a clock can provide 217 * @clk: clock source 218 * @rate: desired clock rate in Hz 219 * 220 * Returns rounded clock rate in Hz, or negative errno. 221 */ 222 long clk_round_rate(struct clk *clk, unsigned long rate); 223 224 /** 225 * clk_set_rate - set the clock rate for a clock source 226 * @clk: clock source 227 * @rate: desired clock rate in Hz 228 * 229 * Returns success (0) or negative errno. 230 */ 231 int clk_set_rate(struct clk *clk, unsigned long rate); 232 233 /** 234 * clk_set_parent - set the parent clock source for this clock 235 * @clk: clock source 236 * @parent: parent clock source 237 * 238 * Returns success (0) or negative errno. 239 */ 240 int clk_set_parent(struct clk *clk, struct clk *parent); 241 242 /** 243 * clk_get_parent - get the parent clock source for this clock 244 * @clk: clock source 245 * 246 * Returns struct clk corresponding to parent clock source, or 247 * valid IS_ERR() condition containing errno. 248 */ 249 struct clk *clk_get_parent(struct clk *clk); 250 251 /** 252 * clk_get_sys - get a clock based upon the device name 253 * @dev_id: device name 254 * @con_id: connection ID 255 * 256 * Returns a struct clk corresponding to the clock producer, or 257 * valid IS_ERR() condition containing errno. The implementation 258 * uses @dev_id and @con_id to determine the clock consumer, and 259 * thereby the clock producer. In contrast to clk_get() this function 260 * takes the device name instead of the device itself for identification. 261 * 262 * Drivers must assume that the clock source is not enabled. 263 * 264 * clk_get_sys should not be called from within interrupt context. 265 */ 266 struct clk *clk_get_sys(const char *dev_id, const char *con_id); 267 268 /** 269 * clk_add_alias - add a new clock alias 270 * @alias: name for clock alias 271 * @alias_dev_name: device name 272 * @id: platform specific clock name 273 * @dev: device 274 * 275 * Allows using generic clock names for drivers by adding a new alias. 276 * Assumes clkdev, see clkdev.h for more info. 277 */ 278 int clk_add_alias(const char *alias, const char *alias_dev_name, char *id, 279 struct device *dev); 280 281 #endif 282