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