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