1 /* 2 * omap-pm.h - OMAP power management interface 3 * 4 * Copyright (C) 2008-2010 Texas Instruments, Inc. 5 * Copyright (C) 2008-2010 Nokia Corporation 6 * Paul Walmsley 7 * 8 * Interface developed by (in alphabetical order): Karthik Dasu, Jouni 9 * Högander, Tony Lindgren, Rajendra Nayak, Sakari Poussa, 10 * Veeramanikandan Raju, Anand Sawant, Igor Stoppa, Paul Walmsley, 11 * Richard Woodruff 12 */ 13 14 #ifndef ASM_ARM_ARCH_OMAP_OMAP_PM_H 15 #define ASM_ARM_ARCH_OMAP_OMAP_PM_H 16 17 #include <linux/device.h> 18 #include <linux/cpufreq.h> 19 #include <linux/clk.h> 20 #include <linux/opp.h> 21 22 /* 23 * agent_id values for use with omap_pm_set_min_bus_tput(): 24 * 25 * OCP_INITIATOR_AGENT is only valid for devices that can act as 26 * initiators -- it represents the device's L3 interconnect 27 * connection. OCP_TARGET_AGENT represents the device's L4 28 * interconnect connection. 29 */ 30 #define OCP_TARGET_AGENT 1 31 #define OCP_INITIATOR_AGENT 2 32 33 /** 34 * omap_pm_if_early_init - OMAP PM init code called before clock fw init 35 * @mpu_opp_table: array ptr to struct omap_opp for MPU 36 * @dsp_opp_table: array ptr to struct omap_opp for DSP 37 * @l3_opp_table : array ptr to struct omap_opp for CORE 38 * 39 * Initialize anything that must be configured before the clock 40 * framework starts. The "_if_" is to avoid name collisions with the 41 * PM idle-loop code. 42 */ 43 int __init omap_pm_if_early_init(void); 44 45 /** 46 * omap_pm_if_init - OMAP PM init code called after clock fw init 47 * 48 * The main initialization code. OPP tables are passed in here. The 49 * "_if_" is to avoid name collisions with the PM idle-loop code. 50 */ 51 int __init omap_pm_if_init(void); 52 53 /** 54 * omap_pm_if_exit - OMAP PM exit code 55 * 56 * Exit code; currently unused. The "_if_" is to avoid name 57 * collisions with the PM idle-loop code. 58 */ 59 void omap_pm_if_exit(void); 60 61 /* 62 * Device-driver-originated constraints (via board-*.c files, platform_data) 63 */ 64 65 66 /** 67 * omap_pm_set_max_mpu_wakeup_lat - set the maximum MPU wakeup latency 68 * @dev: struct device * requesting the constraint 69 * @t: maximum MPU wakeup latency in microseconds 70 * 71 * Request that the maximum interrupt latency for the MPU to be no 72 * greater than @t microseconds. "Interrupt latency" in this case is 73 * defined as the elapsed time from the occurrence of a hardware or 74 * timer interrupt to the time when the device driver's interrupt 75 * service routine has been entered by the MPU. 76 * 77 * It is intended that underlying PM code will use this information to 78 * determine what power state to put the MPU powerdomain into, and 79 * possibly the CORE powerdomain as well, since interrupt handling 80 * code currently runs from SDRAM. Advanced PM or board*.c code may 81 * also configure interrupt controller priorities, OCP bus priorities, 82 * CPU speed(s), etc. 83 * 84 * This function will not affect device wakeup latency, e.g., time 85 * elapsed from when a device driver enables a hardware device with 86 * clk_enable(), to when the device is ready for register access or 87 * other use. To control this device wakeup latency, use 88 * omap_pm_set_max_dev_wakeup_lat() 89 * 90 * Multiple calls to omap_pm_set_max_mpu_wakeup_lat() will replace the 91 * previous t value. To remove the latency target for the MPU, call 92 * with t = -1. 93 * 94 * XXX This constraint will be deprecated soon in favor of the more 95 * general omap_pm_set_max_dev_wakeup_lat() 96 * 97 * Returns -EINVAL for an invalid argument, -ERANGE if the constraint 98 * is not satisfiable, or 0 upon success. 99 */ 100 int omap_pm_set_max_mpu_wakeup_lat(struct device *dev, long t); 101 102 103 /** 104 * omap_pm_set_min_bus_tput - set minimum bus throughput needed by device 105 * @dev: struct device * requesting the constraint 106 * @tbus_id: interconnect to operate on (OCP_{INITIATOR,TARGET}_AGENT) 107 * @r: minimum throughput (in KiB/s) 108 * 109 * Request that the minimum data throughput on the OCP interconnect 110 * attached to device @dev interconnect agent @tbus_id be no less 111 * than @r KiB/s. 112 * 113 * It is expected that the OMAP PM or bus code will use this 114 * information to set the interconnect clock to run at the lowest 115 * possible speed that satisfies all current system users. The PM or 116 * bus code will adjust the estimate based on its model of the bus, so 117 * device driver authors should attempt to specify an accurate 118 * quantity for their device use case, and let the PM or bus code 119 * overestimate the numbers as necessary to handle request/response 120 * latency, other competing users on the system, etc. On OMAP2/3, if 121 * a driver requests a minimum L4 interconnect speed constraint, the 122 * code will also need to add an minimum L3 interconnect speed 123 * constraint, 124 * 125 * Multiple calls to omap_pm_set_min_bus_tput() will replace the 126 * previous rate value for this device. To remove the interconnect 127 * throughput restriction for this device, call with r = 0. 128 * 129 * Returns -EINVAL for an invalid argument, -ERANGE if the constraint 130 * is not satisfiable, or 0 upon success. 131 */ 132 int omap_pm_set_min_bus_tput(struct device *dev, u8 agent_id, unsigned long r); 133 134 135 /** 136 * omap_pm_set_max_dev_wakeup_lat - set the maximum device enable latency 137 * @req_dev: struct device * requesting the constraint, or NULL if none 138 * @dev: struct device * to set the constraint one 139 * @t: maximum device wakeup latency in microseconds 140 * 141 * Request that the maximum amount of time necessary for a device @dev 142 * to become accessible after its clocks are enabled should be no 143 * greater than @t microseconds. Specifically, this represents the 144 * time from when a device driver enables device clocks with 145 * clk_enable(), to when the register reads and writes on the device 146 * will succeed. This function should be called before clk_disable() 147 * is called, since the power state transition decision may be made 148 * during clk_disable(). 149 * 150 * It is intended that underlying PM code will use this information to 151 * determine what power state to put the powerdomain enclosing this 152 * device into. 153 * 154 * Multiple calls to omap_pm_set_max_dev_wakeup_lat() will replace the 155 * previous wakeup latency values for this device. To remove the 156 * wakeup latency restriction for this device, call with t = -1. 157 * 158 * Returns -EINVAL for an invalid argument, -ERANGE if the constraint 159 * is not satisfiable, or 0 upon success. 160 */ 161 int omap_pm_set_max_dev_wakeup_lat(struct device *req_dev, struct device *dev, 162 long t); 163 164 165 /** 166 * omap_pm_set_max_sdma_lat - set the maximum system DMA transfer start latency 167 * @dev: struct device * 168 * @t: maximum DMA transfer start latency in microseconds 169 * 170 * Request that the maximum system DMA transfer start latency for this 171 * device 'dev' should be no greater than 't' microseconds. "DMA 172 * transfer start latency" here is defined as the elapsed time from 173 * when a device (e.g., McBSP) requests that a system DMA transfer 174 * start or continue, to the time at which data starts to flow into 175 * that device from the system DMA controller. 176 * 177 * It is intended that underlying PM code will use this information to 178 * determine what power state to put the CORE powerdomain into. 179 * 180 * Since system DMA transfers may not involve the MPU, this function 181 * will not affect MPU wakeup latency. Use set_max_cpu_lat() to do 182 * so. Similarly, this function will not affect device wakeup latency 183 * -- use set_max_dev_wakeup_lat() to affect that. 184 * 185 * Multiple calls to set_max_sdma_lat() will replace the previous t 186 * value for this device. To remove the maximum DMA latency for this 187 * device, call with t = -1. 188 * 189 * Returns -EINVAL for an invalid argument, -ERANGE if the constraint 190 * is not satisfiable, or 0 upon success. 191 */ 192 int omap_pm_set_max_sdma_lat(struct device *dev, long t); 193 194 195 /** 196 * omap_pm_set_min_clk_rate - set minimum clock rate requested by @dev 197 * @dev: struct device * requesting the constraint 198 * @clk: struct clk * to set the minimum rate constraint on 199 * @r: minimum rate in Hz 200 * 201 * Request that the minimum clock rate on the device @dev's clk @clk 202 * be no less than @r Hz. 203 * 204 * It is expected that the OMAP PM code will use this information to 205 * find an OPP or clock setting that will satisfy this clock rate 206 * constraint, along with any other applicable system constraints on 207 * the clock rate or corresponding voltage, etc. 208 * 209 * omap_pm_set_min_clk_rate() differs from the clock code's 210 * clk_set_rate() in that it considers other constraints before taking 211 * any hardware action, and may change a system OPP rather than just a 212 * clock rate. clk_set_rate() is intended to be a low-level 213 * interface. 214 * 215 * omap_pm_set_min_clk_rate() is easily open to abuse. A better API 216 * would be something like "omap_pm_set_min_dev_performance()"; 217 * however, there is no easily-generalizable concept of performance 218 * that applies to all devices. Only a device (and possibly the 219 * device subsystem) has both the subsystem-specific knowledge, and 220 * the hardware IP block-specific knowledge, to translate a constraint 221 * on "touchscreen sampling accuracy" or "number of pixels or polygons 222 * rendered per second" to a clock rate. This translation can be 223 * dependent on the hardware IP block's revision, or firmware version, 224 * and the driver is the only code on the system that has this 225 * information and can know how to translate that into a clock rate. 226 * 227 * The intended use-case for this function is for userspace or other 228 * kernel code to communicate a particular performance requirement to 229 * a subsystem; then for the subsystem to communicate that requirement 230 * to something that is meaningful to the device driver; then for the 231 * device driver to convert that requirement to a clock rate, and to 232 * then call omap_pm_set_min_clk_rate(). 233 * 234 * Users of this function (such as device drivers) should not simply 235 * call this function with some high clock rate to ensure "high 236 * performance." Rather, the device driver should take a performance 237 * constraint from its subsystem, such as "render at least X polygons 238 * per second," and use some formula or table to convert that into a 239 * clock rate constraint given the hardware type and hardware 240 * revision. Device drivers or subsystems should not assume that they 241 * know how to make a power/performance tradeoff - some device use 242 * cases may tolerate a lower-fidelity device function for lower power 243 * consumption; others may demand a higher-fidelity device function, 244 * no matter what the power consumption. 245 * 246 * Multiple calls to omap_pm_set_min_clk_rate() will replace the 247 * previous rate value for the device @dev. To remove the minimum clock 248 * rate constraint for the device, call with r = 0. 249 * 250 * Returns -EINVAL for an invalid argument, -ERANGE if the constraint 251 * is not satisfiable, or 0 upon success. 252 */ 253 int omap_pm_set_min_clk_rate(struct device *dev, struct clk *c, long r); 254 255 /* 256 * DSP Bridge-specific constraints 257 */ 258 259 /** 260 * omap_pm_dsp_get_opp_table - get OPP->DSP clock frequency table 261 * 262 * Intended for use by DSPBridge. Returns an array of OPP->DSP clock 263 * frequency entries. The final item in the array should have .rate = 264 * .opp_id = 0. 265 */ 266 const struct omap_opp *omap_pm_dsp_get_opp_table(void); 267 268 /** 269 * omap_pm_dsp_set_min_opp - receive desired OPP target ID from DSP Bridge 270 * @opp_id: target DSP OPP ID 271 * 272 * Set a minimum OPP ID for the DSP. This is intended to be called 273 * only from the DSP Bridge MPU-side driver. Unfortunately, the only 274 * information that code receives from the DSP/BIOS load estimator is the 275 * target OPP ID; hence, this interface. No return value. 276 */ 277 void omap_pm_dsp_set_min_opp(u8 opp_id); 278 279 /** 280 * omap_pm_dsp_get_opp - report the current DSP OPP ID 281 * 282 * Report the current OPP for the DSP. Since on OMAP3, the DSP and 283 * MPU share a single voltage domain, the OPP ID returned back may 284 * represent a higher DSP speed than the OPP requested via 285 * omap_pm_dsp_set_min_opp(). 286 * 287 * Returns the current VDD1 OPP ID, or 0 upon error. 288 */ 289 u8 omap_pm_dsp_get_opp(void); 290 291 292 /* 293 * CPUFreq-originated constraint 294 * 295 * In the future, this should be handled by custom OPP clocktype 296 * functions. 297 */ 298 299 /** 300 * omap_pm_cpu_get_freq_table - return a cpufreq_frequency_table array ptr 301 * 302 * Provide a frequency table usable by CPUFreq for the current chip/board. 303 * Returns a pointer to a struct cpufreq_frequency_table array or NULL 304 * upon error. 305 */ 306 struct cpufreq_frequency_table **omap_pm_cpu_get_freq_table(void); 307 308 /** 309 * omap_pm_cpu_set_freq - set the current minimum MPU frequency 310 * @f: MPU frequency in Hz 311 * 312 * Set the current minimum CPU frequency. The actual CPU frequency 313 * used could end up higher if the DSP requested a higher OPP. 314 * Intended to be called by plat-omap/cpu_omap.c:omap_target(). No 315 * return value. 316 */ 317 void omap_pm_cpu_set_freq(unsigned long f); 318 319 /** 320 * omap_pm_cpu_get_freq - report the current CPU frequency 321 * 322 * Returns the current MPU frequency, or 0 upon error. 323 */ 324 unsigned long omap_pm_cpu_get_freq(void); 325 326 327 /* 328 * Device context loss tracking 329 */ 330 331 /** 332 * omap_pm_get_dev_context_loss_count - return count of times dev has lost ctx 333 * @dev: struct device * 334 * 335 * This function returns the number of times that the device @dev has 336 * lost its internal context. This generally occurs on a powerdomain 337 * transition to OFF. Drivers use this as an optimization to avoid restoring 338 * context if the device hasn't lost it. To use, drivers should initially 339 * call this in their context save functions and store the result. Early in 340 * the driver's context restore function, the driver should call this function 341 * again, and compare the result to the stored counter. If they differ, the 342 * driver must restore device context. If the number of context losses 343 * exceeds the maximum positive integer, the function will wrap to 0 and 344 * continue counting. Returns the number of context losses for this device, 345 * or negative value upon error. 346 */ 347 int omap_pm_get_dev_context_loss_count(struct device *dev); 348 349 void omap_pm_enable_off_mode(void); 350 void omap_pm_disable_off_mode(void); 351 352 #endif 353