About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / power / opp.txt




Custom Search

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