About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / power / opp.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1	Operating Performance Points (OPP) Library
2	==========================================
3	
4	(C) 2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated
5	
6	Contents
7	--------
8	1. Introduction
9	2. Initial OPP List Registration
10	3. OPP Search Functions
11	4. OPP Availability Control Functions
12	5. OPP Data Retrieval Functions
13	6. Data Structures
14	
15	1. Introduction
16	===============
17	1.1 What is an Operating Performance Point (OPP)?
18	
19	Complex SoCs of today consists of a multiple sub-modules working in conjunction.
20	In an operational system executing varied use cases, not all modules in the SoC
21	need to function at their highest performing frequency all the time. To
22	facilitate this, sub-modules in a SoC are grouped into domains, allowing some
23	domains to run at lower voltage and frequency while other domains run at
24	voltage/frequency pairs that are higher.
25	
26	The set of discrete tuples consisting of frequency and voltage pairs that
27	the device will support per domain are called Operating Performance Points or
28	OPPs.
29	
30	As an example:
31	Let 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	
35	We can represent these as three OPPs as the following {Hz, uV} tuples:
36	{300000000, 1000000}
37	{800000000, 1200000}
38	{1000000000, 1300000}
39	
40	1.2 Operating Performance Points Library
41	
42	OPP library provides a set of helper functions to organize and query the OPP
43	information. The library is located in drivers/base/power/opp.c and the header
44	is located in include/linux/pm_opp.h. OPP library can be enabled by enabling
45	CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on
46	CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to
47	optionally boot at a certain OPP without needing cpufreq.
48	
49	Typical usage of the OPP library is as follows:
50	(users)		-> registers a set of default OPPs		-> (library)
51	SoC framework	-> modifies on required cases certain OPPs	-> OPP layer
52			-> queries to search/retrieve information	->
53	
54	OPP layer expects each domain to be represented by a unique device pointer. SoC
55	framework registers a set of initial OPPs per device with the OPP layer. This
56	list is expected to be an optimally small number typically around 5 per device.
57	This initial list contains a set of OPPs that the framework expects to be safely
58	enabled by default in the system.
59	
60	Note on OPP Availability:
61	------------------------
62	As the system proceeds to operate, SoC framework may choose to make certain
63	OPPs available or not available on each device based on various external
64	factors. Example usage: Thermal management or other exceptional situations where
65	SoC framework might choose to disable a higher frequency OPP to safely continue
66	operations until that OPP could be re-enabled if possible.
67	
68	OPP library facilitates this concept in it's implementation. The following
69	operational functions operate only on available opps:
70	opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, dev_pm_opp_get_freq, dev_pm_opp_get_opp_count
71	
72	dev_pm_opp_find_freq_exact is meant to be used to find the opp pointer which can then
73	be used for dev_pm_opp_enable/disable functions to make an opp available as required.
74	
75	WARNING: Users of OPP library should refresh their availability count using
76	get_opp_count if dev_pm_opp_enable/disable functions are invoked for a device, the
77	exact mechanism to trigger these or the notification mechanism to other
78	dependent subsystems such as cpufreq are left to the discretion of the SoC
79	specific framework which uses the OPP library. Similar care needs to be taken
80	care to refresh the cpufreq table in cases of these operations.
81	
82	2. Initial OPP List Registration
83	================================
84	The SoC implementation calls dev_pm_opp_add function iteratively to add OPPs per
85	device. It is expected that the SoC framework will register the OPP entries
86	optimally- typical numbers range to be less than 5. The list generated by
87	registering the OPPs is maintained by OPP library throughout the device
88	operation. The SoC framework can subsequently control the availability of the
89	OPPs dynamically using the dev_pm_opp_enable / disable functions.
90	
91	dev_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	
115	3. OPP Search Functions
116	=======================
117	High level framework such as cpufreq operates on frequencies. To map the
118	frequency back to the corresponding OPP, OPP library provides handy functions
119	to search the OPP list that OPP library internally manages. These search
120	functions return the matching pointer representing the opp if a match is
121	found, else returns error. These errors are expected to be handled by standard
122	error checks such as IS_ERR() and appropriate actions taken by the caller.
123	
124	Callers of these functions shall call dev_pm_opp_put() after they have used the
125	OPP. Otherwise the memory for the OPP will never get freed and result in
126	memleak.
127	
128	dev_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	
147	dev_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	
156	dev_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	
178	4. OPP Availability Control Functions
179	=====================================
180	A default OPP list registered with the OPP library may not cater to all possible
181	situation. The OPP library provides a set of functions to modify the
182	availability of a OPP within the OPP list. This allows SoC frameworks to have
183	fine grained dynamic control of which sets of OPPs are operationally available.
184	These functions are intended to *temporarily* remove an OPP in conditions such
185	as thermal considerations (e.g. don't use OPPx until the temperature drops).
186	
187	WARNING: Do not use these functions in interrupt context.
188	
189	dev_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	
204	dev_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	
219	5. OPP Data Retrieval Functions
220	===============================
221	Since OPP library abstracts away the OPP information, a set of functions to pull
222	information from the OPP structure is necessary. Once an OPP pointer is
223	retrieved using the search functions, the following functions can be used by SoC
224	framework to retrieve the information represented inside the OPP layer.
225	
226	dev_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	
242	dev_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	
267	dev_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	
288	6. Data Structures
289	==================
290	Typically an SoC contains multiple voltage domains which are variable. Each
291	domain is represented by a device pointer. The relationship to OPP can be
292	represented as follows:
293	SoC
294	 |- device 1
295	 |	|- opp 1 (availability, freq, voltage)
296	 |	|- opp 2 ..
297	 ...	...
298	 |	`- opp n ..
299	 |- device 2
300	 ...
301	 `- device m
302	
303	OPP library maintains a internal list that the SoC framework populates and
304	accessed by various functions as described above. However, the structures
305	representing the actual OPPs and domains are internal to the OPP library itself
306	to allow for suitable abstraction reusable across systems.
307	
308	struct 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	
319	struct 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	
323	Overall, in a simplistic view, the data structure operations is represented as
324	following:
325	
326	Initialization / modification:
327	            +-----+        /- dev_pm_opp_enable
328	dev_pm_opp_add --> | opp | <-------
329	  |         +-----+        \- dev_pm_opp_disable
330	  \-------> domain_info(device)
331	
332	Search functions:
333	             /-- dev_pm_opp_find_freq_ceil  ---\   +-----+
334	domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
335	             \-- dev_pm_opp_find_freq_floor ---/   +-----+
336	
337	Retrieval functions:
338	+-----+     /- dev_pm_opp_get_voltage
339	| opp | <---
340	+-----+     \- dev_pm_opp_get_freq
341	
342	domain_info <- dev_pm_opp_get_opp_count
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog