blob: 0c007e250cd1f9a38de0ebe6ced205fe6d9378d4 [file] [log] [blame]
rjw1f884582022-01-06 17:20:42 +08001Operating 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
822. Initial OPP List Registration
83================================
84The SoC implementation calls dev_pm_opp_add function iteratively to add OPPs per
85device. It is expected that the SoC framework will register the OPP entries
86optimally- typical numbers range to be less than 5. The list generated by
87registering the OPPs is maintained by OPP library throughout the device
88operation. The SoC framework can subsequently control the availability of the
89OPPs dynamically using the dev_pm_opp_enable / disable functions.
90
91dev_pm_opp_add - Add a new OPP for a specific domain represented by the device pointer.
92 The OPP is defined using the frequency and voltage. Once added, the OPP
93 is assumed to be available and control of it's availability can be done
94 with the dev_pm_opp_enable/disable functions. OPP library internally stores
95 and manages this information in the opp struct. This function may be
96 used by SoC framework to define a optimal list as per the demands of
97 SoC usage environment.
98
99 WARNING: Do not use this function in interrupt context.
100
101 Example:
102 soc_pm_init()
103 {
104 /* Do things */
105 r = dev_pm_opp_add(mpu_dev, 1000000, 900000);
106 if (!r) {
107 pr_err("%s: unable to register mpu opp(%d)\n", r);
108 goto no_cpufreq;
109 }
110 /* Do cpufreq things */
111 no_cpufreq:
112 /* Do remaining things */
113 }
114
1153. OPP Search Functions
116=======================
117High level framework such as cpufreq operates on frequencies. To map the
118frequency back to the corresponding OPP, OPP library provides handy functions
119to search the OPP list that OPP library internally manages. These search
120functions return the matching pointer representing the opp if a match is
121found, else returns error. These errors are expected to be handled by standard
122error checks such as IS_ERR() and appropriate actions taken by the caller.
123
124Callers of these functions shall call dev_pm_opp_put() after they have used the
125OPP. Otherwise the memory for the OPP will never get freed and result in
126memleak.
127
128dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and
129 availability. This function is especially useful to enable an OPP which
130 is not available by default.
131 Example: In a case when SoC framework detects a situation where a
132 higher frequency could be made available, it can use this function to
133 find the OPP prior to call the dev_pm_opp_enable to actually make it available.
134 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
135 dev_pm_opp_put(opp);
136 /* dont operate on the pointer.. just do a sanity check.. */
137 if (IS_ERR(opp)) {
138 pr_err("frequency not disabled!\n");
139 /* trigger appropriate actions.. */
140 } else {
141 dev_pm_opp_enable(dev,1000000000);
142 }
143
144 NOTE: This is the only search function that operates on OPPs which are
145 not available.
146
147dev_pm_opp_find_freq_floor - Search for an available OPP which is *at most* the
148 provided frequency. This function is useful while searching for a lesser
149 match OR operating on OPP information in the order of decreasing
150 frequency.
151 Example: To find the highest opp for a device:
152 freq = ULONG_MAX;
153 opp = dev_pm_opp_find_freq_floor(dev, &freq);
154 dev_pm_opp_put(opp);
155
156dev_pm_opp_find_freq_ceil - Search for an available OPP which is *at least* the
157 provided frequency. This function is useful while searching for a
158 higher match OR operating on OPP information in the order of increasing
159 frequency.
160 Example 1: To find the lowest opp for a device:
161 freq = 0;
162 opp = dev_pm_opp_find_freq_ceil(dev, &freq);
163 dev_pm_opp_put(opp);
164 Example 2: A simplified implementation of a SoC cpufreq_driver->target:
165 soc_cpufreq_target(..)
166 {
167 /* Do stuff like policy checks etc. */
168 /* Find the best frequency match for the req */
169 opp = dev_pm_opp_find_freq_ceil(dev, &freq);
170 dev_pm_opp_put(opp);
171 if (!IS_ERR(opp))
172 soc_switch_to_freq_voltage(freq);
173 else
174 /* do something when we can't satisfy the req */
175 /* do other stuff */
176 }
177
1784. OPP Availability Control Functions
179=====================================
180A default OPP list registered with the OPP library may not cater to all possible
181situation. The OPP library provides a set of functions to modify the
182availability of a OPP within the OPP list. This allows SoC frameworks to have
183fine grained dynamic control of which sets of OPPs are operationally available.
184These functions are intended to *temporarily* remove an OPP in conditions such
185as thermal considerations (e.g. don't use OPPx until the temperature drops).
186
187WARNING: Do not use these functions in interrupt context.
188
189dev_pm_opp_enable - Make a OPP available for operation.
190 Example: Lets say that 1GHz OPP is to be made available only if the
191 SoC temperature is lower than a certain threshold. The SoC framework
192 implementation might choose to do something as follows:
193 if (cur_temp < temp_low_thresh) {
194 /* Enable 1GHz if it was disabled */
195 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
196 dev_pm_opp_put(opp);
197 /* just error check */
198 if (!IS_ERR(opp))
199 ret = dev_pm_opp_enable(dev, 1000000000);
200 else
201 goto try_something_else;
202 }
203
204dev_pm_opp_disable - Make an OPP to be not available for operation
205 Example: Lets say that 1GHz OPP is to be disabled if the temperature
206 exceeds a threshold value. The SoC framework implementation might
207 choose to do something as follows:
208 if (cur_temp > temp_high_thresh) {
209 /* Disable 1GHz if it was enabled */
210 opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
211 dev_pm_opp_put(opp);
212 /* just error check */
213 if (!IS_ERR(opp))
214 ret = dev_pm_opp_disable(dev, 1000000000);
215 else
216 goto try_something_else;
217 }
218
2195. OPP Data Retrieval Functions
220===============================
221Since OPP library abstracts away the OPP information, a set of functions to pull
222information from the OPP structure is necessary. Once an OPP pointer is
223retrieved using the search functions, the following functions can be used by SoC
224framework to retrieve the information represented inside the OPP layer.
225
226dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer.
227 Example: At a cpufreq transition to a different frequency, SoC
228 framework requires to set the voltage represented by the OPP using
229 the regulator framework to the Power Management chip providing the
230 voltage.
231 soc_switch_to_freq_voltage(freq)
232 {
233 /* do things */
234 opp = dev_pm_opp_find_freq_ceil(dev, &freq);
235 v = dev_pm_opp_get_voltage(opp);
236 dev_pm_opp_put(opp);
237 if (v)
238 regulator_set_voltage(.., v);
239 /* do other things */
240 }
241
242dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer.
243 Example: Lets say the SoC framework uses a couple of helper functions
244 we could pass opp pointers instead of doing additional parameters to
245 handle quiet a bit of data parameters.
246 soc_cpufreq_target(..)
247 {
248 /* do things.. */
249 max_freq = ULONG_MAX;
250 max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq);
251 requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq);
252 if (!IS_ERR(max_opp) && !IS_ERR(requested_opp))
253 r = soc_test_validity(max_opp, requested_opp);
254 dev_pm_opp_put(max_opp);
255 dev_pm_opp_put(requested_opp);
256 /* do other things */
257 }
258 soc_test_validity(..)
259 {
260 if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp))
261 return -EINVAL;
262 if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp))
263 return -EINVAL;
264 /* do things.. */
265 }
266
267dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device
268 Example: Lets say a co-processor in the SoC needs to know the available
269 frequencies in a table, the main processor can notify as following:
270 soc_notify_coproc_available_frequencies()
271 {
272 /* Do things */
273 num_available = dev_pm_opp_get_opp_count(dev);
274 speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL);
275 /* populate the table in increasing order */
276 freq = 0;
277 while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) {
278 speeds[i] = freq;
279 freq++;
280 i++;
281 dev_pm_opp_put(opp);
282 }
283
284 soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available);
285 /* Do other things */
286 }
287
2886. Data Structures
289==================
290Typically an SoC contains multiple voltage domains which are variable. Each
291domain is represented by a device pointer. The relationship to OPP can be
292represented as follows:
293SoC
294 |- device 1
295 | |- opp 1 (availability, freq, voltage)
296 | |- opp 2 ..
297 ... ...
298 | `- opp n ..
299 |- device 2
300 ...
301 `- device m
302
303OPP library maintains a internal list that the SoC framework populates and
304accessed by various functions as described above. However, the structures
305representing the actual OPPs and domains are internal to the OPP library itself
306to allow for suitable abstraction reusable across systems.
307
308struct dev_pm_opp - The internal data structure of OPP library which is used to
309 represent an OPP. In addition to the freq, voltage, availability
310 information, it also contains internal book keeping information required
311 for the OPP library to operate on. Pointer to this structure is
312 provided back to the users such as SoC framework to be used as a
313 identifier for OPP in the interactions with OPP layer.
314
315 WARNING: The struct dev_pm_opp pointer should not be parsed or modified by the
316 users. The defaults of for an instance is populated by dev_pm_opp_add, but the
317 availability of the OPP can be modified by dev_pm_opp_enable/disable functions.
318
319struct device - This is used to identify a domain to the OPP layer. The
320 nature of the device and it's implementation is left to the user of
321 OPP library such as the SoC framework.
322
323Overall, in a simplistic view, the data structure operations is represented as
324following:
325
326Initialization / modification:
327 +-----+ /- dev_pm_opp_enable
328dev_pm_opp_add --> | opp | <-------
329 | +-----+ \- dev_pm_opp_disable
330 \-------> domain_info(device)
331
332Search functions:
333 /-- dev_pm_opp_find_freq_ceil ---\ +-----+
334domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
335 \-- dev_pm_opp_find_freq_floor ---/ +-----+
336
337Retrieval functions:
338+-----+ /- dev_pm_opp_get_voltage
339| opp | <---
340+-----+ \- dev_pm_opp_get_freq
341
342domain_info <- dev_pm_opp_get_opp_count