1Operating Performance Points (OPP) Library 2========================================== 3 4(C) 2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated 5 6Contents 7-------- 81. Introduction 92. Initial OPP List Registration 103. OPP Search Functions 114. OPP Availability Control Functions 125. OPP Data Retrieval Functions 136. Data Structures 14 151. Introduction 16=============== 171.1 What is an Operating Performance Point (OPP)? 18 19Complex SoCs of today consists of a multiple sub-modules working in conjunction. 20In an operational system executing varied use cases, not all modules in the SoC 21need to function at their highest performing frequency all the time. To 22facilitate this, sub-modules in a SoC are grouped into domains, allowing some 23domains to run at lower voltage and frequency while other domains run at 24voltage/frequency pairs that are higher. 25 26The set of discrete tuples consisting of frequency and voltage pairs that 27the device will support per domain are called Operating Performance Points or 28OPPs. 29 30As an example: 31Let us consider an MPU device which supports the following: 32{300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V}, 33{1GHz at minimum voltage of 1.3V} 34 35We can represent these as three OPPs as the following {Hz, uV} tuples: 36{300000000, 1000000} 37{800000000, 1200000} 38{1000000000, 1300000} 39 401.2 Operating Performance Points Library 41 42OPP library provides a set of helper functions to organize and query the OPP 43information. The library is located in drivers/base/power/opp.c and the header 44is located in include/linux/pm_opp.h. OPP library can be enabled by enabling 45CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on 46CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to 47optionally boot at a certain OPP without needing cpufreq. 48 49Typical usage of the OPP library is as follows: 50(users) -> registers a set of default OPPs -> (library) 51SoC framework -> modifies on required cases certain OPPs -> OPP layer 52 -> queries to search/retrieve information -> 53 54OPP layer expects each domain to be represented by a unique device pointer. SoC 55framework registers a set of initial OPPs per device with the OPP layer. This 56list is expected to be an optimally small number typically around 5 per device. 57This initial list contains a set of OPPs that the framework expects to be safely 58enabled by default in the system. 59 60Note on OPP Availability: 61------------------------ 62As the system proceeds to operate, SoC framework may choose to make certain 63OPPs available or not available on each device based on various external 64factors. Example usage: Thermal management or other exceptional situations where 65SoC framework might choose to disable a higher frequency OPP to safely continue 66operations until that OPP could be re-enabled if possible. 67 68OPP library facilitates this concept in it's implementation. The following 69operational functions operate only on available opps: 70opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, dev_pm_opp_get_freq, dev_pm_opp_get_opp_count 71 72dev_pm_opp_find_freq_exact is meant to be used to find the opp pointer which can then 73be used for dev_pm_opp_enable/disable functions to make an opp available as required. 74 75WARNING: Users of OPP library should refresh their availability count using 76get_opp_count if dev_pm_opp_enable/disable functions are invoked for a device, the 77exact mechanism to trigger these or the notification mechanism to other 78dependent subsystems such as cpufreq are left to the discretion of the SoC 79specific framework which uses the OPP library. Similar care needs to be taken 80care to refresh the cpufreq table in cases of these operations. 81 82WARNING on OPP List locking mechanism: 83------------------------------------------------- 84OPP library uses RCU for exclusivity. RCU allows the query functions to operate 85in multiple contexts and this synchronization mechanism is optimal for a read 86intensive operations on data structure as the OPP library caters to. 87 88To ensure that the data retrieved are sane, the users such as SoC framework 89should ensure that the section of code operating on OPP queries are locked 90using RCU read locks. The opp_find_freq_{exact,ceil,floor}, 91opp_get_{voltage, freq, opp_count} fall into this category. 92 93opp_{add,enable,disable} are updaters which use mutex and implement it's own 94RCU locking mechanisms. These functions should *NOT* be called under RCU locks 95and other contexts that prevent blocking functions in RCU or mutex operations 96from working. 97 982. Initial OPP List Registration 99================================ 100The SoC implementation calls dev_pm_opp_add function iteratively to add OPPs per 101device. It is expected that the SoC framework will register the OPP entries 102optimally- typical numbers range to be less than 5. The list generated by 103registering the OPPs is maintained by OPP library throughout the device 104operation. The SoC framework can subsequently control the availability of the 105OPPs dynamically using the dev_pm_opp_enable / disable functions. 106 107dev_pm_opp_add - Add a new OPP for a specific domain represented by the device pointer. 108 The OPP is defined using the frequency and voltage. Once added, the OPP 109 is assumed to be available and control of it's availability can be done 110 with the dev_pm_opp_enable/disable functions. OPP library internally stores 111 and manages this information in the opp struct. This function may be 112 used by SoC framework to define a optimal list as per the demands of 113 SoC usage environment. 114 115 WARNING: Do not use this function in interrupt context. 116 117 Example: 118 soc_pm_init() 119 { 120 /* Do things */ 121 r = dev_pm_opp_add(mpu_dev, 1000000, 900000); 122 if (!r) { 123 pr_err("%s: unable to register mpu opp(%d)\n", r); 124 goto no_cpufreq; 125 } 126 /* Do cpufreq things */ 127 no_cpufreq: 128 /* Do remaining things */ 129 } 130 1313. OPP Search Functions 132======================= 133High level framework such as cpufreq operates on frequencies. To map the 134frequency back to the corresponding OPP, OPP library provides handy functions 135to search the OPP list that OPP library internally manages. These search 136functions return the matching pointer representing the opp if a match is 137found, else returns error. These errors are expected to be handled by standard 138error checks such as IS_ERR() and appropriate actions taken by the caller. 139 140dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and 141 availability. This function is especially useful to enable an OPP which 142 is not available by default. 143 Example: In a case when SoC framework detects a situation where a 144 higher frequency could be made available, it can use this function to 145 find the OPP prior to call the dev_pm_opp_enable to actually make it available. 146 rcu_read_lock(); 147 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false); 148 rcu_read_unlock(); 149 /* dont operate on the pointer.. just do a sanity check.. */ 150 if (IS_ERR(opp)) { 151 pr_err("frequency not disabled!\n"); 152 /* trigger appropriate actions.. */ 153 } else { 154 dev_pm_opp_enable(dev,1000000000); 155 } 156 157 NOTE: This is the only search function that operates on OPPs which are 158 not available. 159 160dev_pm_opp_find_freq_floor - Search for an available OPP which is *at most* the 161 provided frequency. This function is useful while searching for a lesser 162 match OR operating on OPP information in the order of decreasing 163 frequency. 164 Example: To find the highest opp for a device: 165 freq = ULONG_MAX; 166 rcu_read_lock(); 167 dev_pm_opp_find_freq_floor(dev, &freq); 168 rcu_read_unlock(); 169 170dev_pm_opp_find_freq_ceil - Search for an available OPP which is *at least* the 171 provided frequency. This function is useful while searching for a 172 higher match OR operating on OPP information in the order of increasing 173 frequency. 174 Example 1: To find the lowest opp for a device: 175 freq = 0; 176 rcu_read_lock(); 177 dev_pm_opp_find_freq_ceil(dev, &freq); 178 rcu_read_unlock(); 179 Example 2: A simplified implementation of a SoC cpufreq_driver->target: 180 soc_cpufreq_target(..) 181 { 182 /* Do stuff like policy checks etc. */ 183 /* Find the best frequency match for the req */ 184 rcu_read_lock(); 185 opp = dev_pm_opp_find_freq_ceil(dev, &freq); 186 rcu_read_unlock(); 187 if (!IS_ERR(opp)) 188 soc_switch_to_freq_voltage(freq); 189 else 190 /* do something when we can't satisfy the req */ 191 /* do other stuff */ 192 } 193 1944. OPP Availability Control Functions 195===================================== 196A default OPP list registered with the OPP library may not cater to all possible 197situation. The OPP library provides a set of functions to modify the 198availability of a OPP within the OPP list. This allows SoC frameworks to have 199fine grained dynamic control of which sets of OPPs are operationally available. 200These functions are intended to *temporarily* remove an OPP in conditions such 201as thermal considerations (e.g. don't use OPPx until the temperature drops). 202 203WARNING: Do not use these functions in interrupt context. 204 205dev_pm_opp_enable - Make a OPP available for operation. 206 Example: Lets say that 1GHz OPP is to be made available only if the 207 SoC temperature is lower than a certain threshold. The SoC framework 208 implementation might choose to do something as follows: 209 if (cur_temp < temp_low_thresh) { 210 /* Enable 1GHz if it was disabled */ 211 rcu_read_lock(); 212 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false); 213 rcu_read_unlock(); 214 /* just error check */ 215 if (!IS_ERR(opp)) 216 ret = dev_pm_opp_enable(dev, 1000000000); 217 else 218 goto try_something_else; 219 } 220 221dev_pm_opp_disable - Make an OPP to be not available for operation 222 Example: Lets say that 1GHz OPP is to be disabled if the temperature 223 exceeds a threshold value. The SoC framework implementation might 224 choose to do something as follows: 225 if (cur_temp > temp_high_thresh) { 226 /* Disable 1GHz if it was enabled */ 227 rcu_read_lock(); 228 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true); 229 rcu_read_unlock(); 230 /* just error check */ 231 if (!IS_ERR(opp)) 232 ret = dev_pm_opp_disable(dev, 1000000000); 233 else 234 goto try_something_else; 235 } 236 2375. OPP Data Retrieval Functions 238=============================== 239Since OPP library abstracts away the OPP information, a set of functions to pull 240information from the OPP structure is necessary. Once an OPP pointer is 241retrieved using the search functions, the following functions can be used by SoC 242framework to retrieve the information represented inside the OPP layer. 243 244dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer. 245 Example: At a cpufreq transition to a different frequency, SoC 246 framework requires to set the voltage represented by the OPP using 247 the regulator framework to the Power Management chip providing the 248 voltage. 249 soc_switch_to_freq_voltage(freq) 250 { 251 /* do things */ 252 rcu_read_lock(); 253 opp = dev_pm_opp_find_freq_ceil(dev, &freq); 254 v = dev_pm_opp_get_voltage(opp); 255 rcu_read_unlock(); 256 if (v) 257 regulator_set_voltage(.., v); 258 /* do other things */ 259 } 260 261dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer. 262 Example: Lets say the SoC framework uses a couple of helper functions 263 we could pass opp pointers instead of doing additional parameters to 264 handle quiet a bit of data parameters. 265 soc_cpufreq_target(..) 266 { 267 /* do things.. */ 268 max_freq = ULONG_MAX; 269 rcu_read_lock(); 270 max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq); 271 requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq); 272 if (!IS_ERR(max_opp) && !IS_ERR(requested_opp)) 273 r = soc_test_validity(max_opp, requested_opp); 274 rcu_read_unlock(); 275 /* do other things */ 276 } 277 soc_test_validity(..) 278 { 279 if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp)) 280 return -EINVAL; 281 if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp)) 282 return -EINVAL; 283 /* do things.. */ 284 } 285 286dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device 287 Example: Lets say a co-processor in the SoC needs to know the available 288 frequencies in a table, the main processor can notify as following: 289 soc_notify_coproc_available_frequencies() 290 { 291 /* Do things */ 292 rcu_read_lock(); 293 num_available = dev_pm_opp_get_opp_count(dev); 294 speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL); 295 /* populate the table in increasing order */ 296 freq = 0; 297 while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) { 298 speeds[i] = freq; 299 freq++; 300 i++; 301 } 302 rcu_read_unlock(); 303 304 soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available); 305 /* Do other things */ 306 } 307 3086. Data Structures 309================== 310Typically an SoC contains multiple voltage domains which are variable. Each 311domain is represented by a device pointer. The relationship to OPP can be 312represented as follows: 313SoC 314 |- device 1 315 | |- opp 1 (availability, freq, voltage) 316 | |- opp 2 .. 317 ... ... 318 | `- opp n .. 319 |- device 2 320 ... 321 `- device m 322 323OPP library maintains a internal list that the SoC framework populates and 324accessed by various functions as described above. However, the structures 325representing the actual OPPs and domains are internal to the OPP library itself 326to allow for suitable abstraction reusable across systems. 327 328struct dev_pm_opp - The internal data structure of OPP library which is used to 329 represent an OPP. In addition to the freq, voltage, availability 330 information, it also contains internal book keeping information required 331 for the OPP library to operate on. Pointer to this structure is 332 provided back to the users such as SoC framework to be used as a 333 identifier for OPP in the interactions with OPP layer. 334 335 WARNING: The struct dev_pm_opp pointer should not be parsed or modified by the 336 users. The defaults of for an instance is populated by dev_pm_opp_add, but the 337 availability of the OPP can be modified by dev_pm_opp_enable/disable functions. 338 339struct device - This is used to identify a domain to the OPP layer. The 340 nature of the device and it's implementation is left to the user of 341 OPP library such as the SoC framework. 342 343Overall, in a simplistic view, the data structure operations is represented as 344following: 345 346Initialization / modification: 347 +-----+ /- dev_pm_opp_enable 348dev_pm_opp_add --> | opp | <------- 349 | +-----+ \- dev_pm_opp_disable 350 \-------> domain_info(device) 351 352Search functions: 353 /-- dev_pm_opp_find_freq_ceil ---\ +-----+ 354domain_info<---- dev_pm_opp_find_freq_exact -----> | opp | 355 \-- dev_pm_opp_find_freq_floor ---/ +-----+ 356 357Retrieval functions: 358+-----+ /- dev_pm_opp_get_voltage 359| opp | <--- 360+-----+ \- dev_pm_opp_get_freq 361 362domain_info <- dev_pm_opp_get_opp_count 363