blob: c6279c2be47c20116dc56590b450f56a96a1ad5b [file] [log] [blame]
Nishanth Menon4b875812013-02-26 23:53:02 +00001Operating Performance Points (OPP) Library
2==========================================
Nishanth Menone1f60b22010-10-13 00:13:10 +02003
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
Nishanth Menona0dd7b72014-05-05 08:33:50 -0500136. Data Structures
Nishanth Menone1f60b22010-10-13 00:13:10 +020014
151. Introduction
16===============
Nishanth Menon4b875812013-02-26 23:53:02 +0000171.1 What is an Operating Performance Point (OPP)?
18
Nishanth Menone1f60b22010-10-13 00:13:10 +020019Complex 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
Nishanth Menon4b875812013-02-26 23:53:02 +000023domains 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
Nishanth Menone1f60b22010-10-13 00:13:10 +020027the device will support per domain are called Operating Performance Points or
28OPPs.
29
Nishanth Menon4b875812013-02-26 23:53:02 +000030As 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
Nishanth Menone1f60b22010-10-13 00:13:10 +020042OPP 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
Nishanth Menone4db1c72013-09-19 16:03:52 -050044is located in include/linux/pm_opp.h. OPP library can be enabled by enabling
Nishanth Menone1f60b22010-10-13 00:13:10 +020045CONFIG_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
Nishanth Menone1f60b22010-10-13 00:13:10 +020054OPP 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:
Nishanth Menon5d4879c2013-09-19 16:03:50 -050070opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, dev_pm_opp_get_freq, dev_pm_opp_get_opp_count
Nishanth Menone1f60b22010-10-13 00:13:10 +020071
Nishanth Menon5d4879c2013-09-19 16:03:50 -050072dev_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.
Nishanth Menone1f60b22010-10-13 00:13:10 +020074
75WARNING: Users of OPP library should refresh their availability count using
Nishanth Menon5d4879c2013-09-19 16:03:50 -050076get_opp_count if dev_pm_opp_enable/disable functions are invoked for a device, the
Nishanth Menone1f60b22010-10-13 00:13:10 +020077exact 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
Nishanth Menona0dd7b72014-05-05 08:33:50 -050094RCU 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.
Nishanth Menone1f60b22010-10-13 00:13:10 +020097
982. Initial OPP List Registration
99================================
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500100The SoC implementation calls dev_pm_opp_add function iteratively to add OPPs per
Nishanth Menone1f60b22010-10-13 00:13:10 +0200101device. 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
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500105OPPs dynamically using the dev_pm_opp_enable / disable functions.
Nishanth Menone1f60b22010-10-13 00:13:10 +0200106
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500107dev_pm_opp_add - Add a new OPP for a specific domain represented by the device pointer.
Nishanth Menone1f60b22010-10-13 00:13:10 +0200108 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
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500110 with the dev_pm_opp_enable/disable functions. OPP library internally stores
Nishanth Menone1f60b22010-10-13 00:13:10 +0200111 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 */
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500121 r = dev_pm_opp_add(mpu_dev, 1000000, 900000);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200122 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
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500140dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and
Nishanth Menone1f60b22010-10-13 00:13:10 +0200141 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
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500145 find the OPP prior to call the dev_pm_opp_enable to actually make it available.
Nishanth Menone1f60b22010-10-13 00:13:10 +0200146 rcu_read_lock();
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500147 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200148 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 {
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500154 dev_pm_opp_enable(dev,1000000000);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200155 }
156
157 NOTE: This is the only search function that operates on OPPs which are
158 not available.
159
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500160dev_pm_opp_find_freq_floor - Search for an available OPP which is *at most* the
Nishanth Menone1f60b22010-10-13 00:13:10 +0200161 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();
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500167 dev_pm_opp_find_freq_floor(dev, &freq);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200168 rcu_read_unlock();
169
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500170dev_pm_opp_find_freq_ceil - Search for an available OPP which is *at least* the
Nishanth Menone1f60b22010-10-13 00:13:10 +0200171 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();
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500177 dev_pm_opp_find_freq_ceil(dev, &freq);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200178 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();
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500185 opp = dev_pm_opp_find_freq_ceil(dev, &freq);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200186 rcu_read_unlock();
187 if (!IS_ERR(opp))
188 soc_switch_to_freq_voltage(freq);
189 else
Lucas De Marchi25985ed2011-03-30 22:57:33 -0300190 /* do something when we can't satisfy the req */
Nishanth Menone1f60b22010-10-13 00:13:10 +0200191 /* 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
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500205dev_pm_opp_enable - Make a OPP available for operation.
Nishanth Menone1f60b22010-10-13 00:13:10 +0200206 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();
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500212 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200213 rcu_read_unlock();
214 /* just error check */
215 if (!IS_ERR(opp))
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500216 ret = dev_pm_opp_enable(dev, 1000000000);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200217 else
218 goto try_something_else;
219 }
220
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500221dev_pm_opp_disable - Make an OPP to be not available for operation
Nishanth Menone1f60b22010-10-13 00:13:10 +0200222 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();
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500228 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200229 rcu_read_unlock();
230 /* just error check */
231 if (!IS_ERR(opp))
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500232 ret = dev_pm_opp_disable(dev, 1000000000);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200233 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
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500244dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer.
Nishanth Menone1f60b22010-10-13 00:13:10 +0200245 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();
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500253 opp = dev_pm_opp_find_freq_ceil(dev, &freq);
254 v = dev_pm_opp_get_voltage(opp);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200255 rcu_read_unlock();
256 if (v)
257 regulator_set_voltage(.., v);
258 /* do other things */
259 }
260
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500261dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer.
Nishanth Menone1f60b22010-10-13 00:13:10 +0200262 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();
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500270 max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq);
271 requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200272 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 {
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500279 if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp))
Nishanth Menone1f60b22010-10-13 00:13:10 +0200280 return -EINVAL;
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500281 if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp))
Nishanth Menone1f60b22010-10-13 00:13:10 +0200282 return -EINVAL;
283 /* do things.. */
284 }
285
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500286dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device
Nishanth Menone1f60b22010-10-13 00:13:10 +0200287 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();
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500293 num_available = dev_pm_opp_get_opp_count(dev);
Nishanth Menone1f60b22010-10-13 00:13:10 +0200294 speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL);
295 /* populate the table in increasing order */
296 freq = 0;
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500297 while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) {
Nishanth Menone1f60b22010-10-13 00:13:10 +0200298 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
Nishanth Menona0dd7b72014-05-05 08:33:50 -05003086. Data Structures
Nishanth Menone1f60b22010-10-13 00:13:10 +0200309==================
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
Nishanth Menon47d43ba2013-09-19 16:03:51 -0500328struct dev_pm_opp - The internal data structure of OPP library which is used to
Nishanth Menone1f60b22010-10-13 00:13:10 +0200329 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
Nishanth Menon47d43ba2013-09-19 16:03:51 -0500335 WARNING: The struct dev_pm_opp pointer should not be parsed or modified by the
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500336 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.
Nishanth Menone1f60b22010-10-13 00:13:10 +0200338
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:
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500347 +-----+ /- dev_pm_opp_enable
348dev_pm_opp_add --> | opp | <-------
349 | +-----+ \- dev_pm_opp_disable
Nishanth Menone1f60b22010-10-13 00:13:10 +0200350 \-------> domain_info(device)
351
352Search functions:
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500353 /-- dev_pm_opp_find_freq_ceil ---\ +-----+
354domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
355 \-- dev_pm_opp_find_freq_floor ---/ +-----+
Nishanth Menone1f60b22010-10-13 00:13:10 +0200356
357Retrieval functions:
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500358+-----+ /- dev_pm_opp_get_voltage
Nishanth Menone1f60b22010-10-13 00:13:10 +0200359| opp | <---
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500360+-----+ \- dev_pm_opp_get_freq
Nishanth Menone1f60b22010-10-13 00:13:10 +0200361
Nishanth Menon5d4879c2013-09-19 16:03:50 -0500362domain_info <- dev_pm_opp_get_opp_count