About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / power / opp.txt




Custom Search

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.