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