About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / cpu-freq / cpu-drivers.txt




Custom Search

Based on kernel version 4.13.3. Page generated on 2017-09-23 13:54 EST.

1	     CPU frequency and voltage scaling code in the Linux(TM) kernel
2	
3	
4			         L i n u x    C P U F r e q
5	
6				   C P U   D r i v e r s 
7	
8			       - information for developers -
9	
10	
11			    Dominik Brodowski  <linux@brodo.de>
12			Rafael J. Wysocki <rafael.j.wysocki@intel.com>
13			   Viresh Kumar <viresh.kumar@linaro.org>
14	
15	
16	
17	   Clock scaling allows you to change the clock speed of the CPUs on the
18	    fly. This is a nice method to save battery power, because the lower
19	            the clock speed, the less power the CPU consumes.
20	
21	
22	Contents:
23	---------
24	1.   What To Do?
25	1.1  Initialization
26	1.2  Per-CPU Initialization
27	1.3  verify
28	1.4  target/target_index or setpolicy?
29	1.5  target/target_index
30	1.6  setpolicy
31	1.7  get_intermediate and target_intermediate
32	2.   Frequency Table Helpers
33	
34	
35	
36	1. What To Do?
37	==============
38	
39	So, you just got a brand-new CPU / chipset with datasheets and want to
40	add cpufreq support for this CPU / chipset? Great. Here are some hints
41	on what is necessary:
42	
43	
44	1.1 Initialization
45	------------------
46	
47	First of all, in an __initcall level 7 (module_init()) or later
48	function check whether this kernel runs on the right CPU and the right
49	chipset. If so, register a struct cpufreq_driver with the CPUfreq core
50	using cpufreq_register_driver()
51	
52	What shall this struct cpufreq_driver contain? 
53	
54	 .name - The name of this driver.
55	
56	 .init - A pointer to the per-policy initialization function.
57	
58	 .verify - A pointer to a "verification" function.
59	
60	 .setpolicy _or_ .fast_switch _or_ .target _or_ .target_index - See
61	 below on the differences.
62	
63	And optionally
64	
65	 .flags - Hints for the cpufreq core.
66	
67	 .driver_data - cpufreq driver specific data.
68	
69	 .resolve_freq - Returns the most appropriate frequency for a target
70	 frequency. Doesn't change the frequency though.
71	
72	 .get_intermediate and target_intermediate - Used to switch to stable
73	 frequency while changing CPU frequency.
74	
75	 .get - Returns current frequency of the CPU.
76	
77	 .bios_limit - Returns HW/BIOS max frequency limitations for the CPU.
78	
79	 .exit - A pointer to a per-policy cleanup function called during
80	 CPU_POST_DEAD phase of cpu hotplug process.
81	
82	 .stop_cpu - A pointer to a per-policy stop function called during
83	 CPU_DOWN_PREPARE phase of cpu hotplug process.
84	
85	 .suspend - A pointer to a per-policy suspend function which is called
86	 with interrupts disabled and _after_ the governor is stopped for the
87	 policy.
88	
89	 .resume - A pointer to a per-policy resume function which is called
90	 with interrupts disabled and _before_ the governor is started again.
91	
92	 .ready - A pointer to a per-policy ready function which is called after
93	 the policy is fully initialized.
94	
95	 .attr - A pointer to a NULL-terminated list of "struct freq_attr" which
96	 allow to export values to sysfs.
97	
98	 .boost_enabled - If set, boost frequencies are enabled.
99	
100	 .set_boost - A pointer to a per-policy function to enable/disable boost
101	 frequencies.
102	
103	
104	1.2 Per-CPU Initialization
105	--------------------------
106	
107	Whenever a new CPU is registered with the device model, or after the
108	cpufreq driver registers itself, the per-policy initialization function
109	cpufreq_driver.init is called if no cpufreq policy existed for the CPU.
110	Note that the .init() and .exit() routines are called only once for the
111	policy and not for each CPU managed by the policy. It takes a struct
112	cpufreq_policy *policy as argument. What to do now?
113	
114	If necessary, activate the CPUfreq support on your CPU.
115	
116	Then, the driver must fill in the following values:
117	
118	policy->cpuinfo.min_freq _and_
119	policy->cpuinfo.max_freq -	the minimum and maximum frequency 
120					(in kHz) which is supported by 
121					this CPU
122	policy->cpuinfo.transition_latency   the time it takes on this CPU to
123					switch between two frequencies in
124					nanoseconds (if appropriate, else
125					specify CPUFREQ_ETERNAL)
126	
127	policy->cur			The current operating frequency of
128					this CPU (if appropriate)
129	policy->min, 
130	policy->max, 
131	policy->policy and, if necessary,
132	policy->governor		must contain the "default policy" for
133					this CPU. A few moments later,
134					cpufreq_driver.verify and either
135					cpufreq_driver.setpolicy or
136					cpufreq_driver.target/target_index is called
137					with these values.
138	policy->cpus			Update this with the masks of the
139					(online + offline) CPUs that do DVFS
140					along with this CPU (i.e.  that share
141					clock/voltage rails with it).
142	
143	For setting some of these values (cpuinfo.min[max]_freq, policy->min[max]), the
144	frequency table helpers might be helpful. See the section 2 for more information
145	on them.
146	
147	
148	1.3 verify
149	----------
150	
151	When the user decides a new policy (consisting of
152	"policy,governor,min,max") shall be set, this policy must be validated
153	so that incompatible values can be corrected. For verifying these
154	values cpufreq_verify_within_limits(struct cpufreq_policy *policy,
155	unsigned int min_freq, unsigned int max_freq) function might be helpful.
156	See section 2 for details on frequency table helpers.
157	
158	You need to make sure that at least one valid frequency (or operating
159	range) is within policy->min and policy->max. If necessary, increase
160	policy->max first, and only if this is no solution, decrease policy->min.
161	
162	
163	1.4 target or target_index or setpolicy or fast_switch?
164	-------------------------------------------------------
165	
166	Most cpufreq drivers or even most cpu frequency scaling algorithms 
167	only allow the CPU frequency to be set to predefined fixed values. For
168	these, you use the ->target(), ->target_index() or ->fast_switch()
169	callbacks.
170	
171	Some cpufreq capable processors switch the frequency between certain
172	limits on their own. These shall use the ->setpolicy() callback.
173	
174	
175	1.5. target/target_index
176	------------------------
177	
178	The target_index call has two arguments: struct cpufreq_policy *policy,
179	and unsigned int index (into the exposed frequency table).
180	
181	The CPUfreq driver must set the new frequency when called here. The
182	actual frequency must be determined by freq_table[index].frequency.
183	
184	It should always restore to earlier frequency (i.e. policy->restore_freq) in
185	case of errors, even if we switched to intermediate frequency earlier.
186	
187	Deprecated:
188	----------
189	The target call has three arguments: struct cpufreq_policy *policy,
190	unsigned int target_frequency, unsigned int relation.
191	
192	The CPUfreq driver must set the new frequency when called here. The
193	actual frequency must be determined using the following rules:
194	
195	- keep close to "target_freq"
196	- policy->min <= new_freq <= policy->max (THIS MUST BE VALID!!!)
197	- if relation==CPUFREQ_REL_L, try to select a new_freq higher than or equal
198	  target_freq. ("L for lowest, but no lower than")
199	- if relation==CPUFREQ_REL_H, try to select a new_freq lower than or equal
200	  target_freq. ("H for highest, but no higher than")
201	
202	Here again the frequency table helper might assist you - see section 2
203	for details.
204	
205	1.6. fast_switch
206	----------------
207	
208	This function is used for frequency switching from scheduler's context.
209	Not all drivers are expected to implement it, as sleeping from within
210	this callback isn't allowed. This callback must be highly optimized to
211	do switching as fast as possible.
212	
213	This function has two arguments: struct cpufreq_policy *policy and
214	unsigned int target_frequency.
215	
216	
217	1.7 setpolicy
218	-------------
219	
220	The setpolicy call only takes a struct cpufreq_policy *policy as
221	argument. You need to set the lower limit of the in-processor or
222	in-chipset dynamic frequency switching to policy->min, the upper limit
223	to policy->max, and -if supported- select a performance-oriented
224	setting when policy->policy is CPUFREQ_POLICY_PERFORMANCE, and a
225	powersaving-oriented setting when CPUFREQ_POLICY_POWERSAVE. Also check
226	the reference implementation in drivers/cpufreq/longrun.c
227	
228	1.8 get_intermediate and target_intermediate
229	--------------------------------------------
230	
231	Only for drivers with target_index() and CPUFREQ_ASYNC_NOTIFICATION unset.
232	
233	get_intermediate should return a stable intermediate frequency platform wants to
234	switch to, and target_intermediate() should set CPU to that frequency, before
235	jumping to the frequency corresponding to 'index'. Core will take care of
236	sending notifications and driver doesn't have to handle them in
237	target_intermediate() or target_index().
238	
239	Drivers can return '0' from get_intermediate() in case they don't wish to switch
240	to intermediate frequency for some target frequency. In that case core will
241	directly call ->target_index().
242	
243	NOTE: ->target_index() should restore to policy->restore_freq in case of
244	failures as core would send notifications for that.
245	
246	
247	2. Frequency Table Helpers
248	==========================
249	
250	As most cpufreq processors only allow for being set to a few specific
251	frequencies, a "frequency table" with some functions might assist in
252	some work of the processor driver. Such a "frequency table" consists of
253	an array of struct cpufreq_frequency_table entries, with driver specific
254	values in "driver_data", the corresponding frequency in "frequency" and
255	flags set. At the end of the table, you need to add a
256	cpufreq_frequency_table entry with frequency set to CPUFREQ_TABLE_END.
257	And if you want to skip one entry in the table, set the frequency to
258	CPUFREQ_ENTRY_INVALID. The entries don't need to be in sorted in any
259	particular order, but if they are cpufreq core will do DVFS a bit
260	quickly for them as search for best match is faster.
261	
262	By calling cpufreq_table_validate_and_show(), the cpuinfo.min_freq and
263	cpuinfo.max_freq values are detected, and policy->min and policy->max
264	are set to the same values. This is helpful for the per-CPU
265	initialization stage.
266	
267	cpufreq_frequency_table_verify() assures that at least one valid
268	frequency is within policy->min and policy->max, and all other criteria
269	are met. This is helpful for the ->verify call.
270	
271	cpufreq_frequency_table_target() is the corresponding frequency table
272	helper for the ->target stage. Just pass the values to this function,
273	and this function returns the of the frequency table entry which
274	contains the frequency the CPU shall be set to.
275	
276	The following macros can be used as iterators over cpufreq_frequency_table:
277	
278	cpufreq_for_each_entry(pos, table) - iterates over all entries of frequency
279	table.
280	
281	cpufreq_for_each_valid_entry(pos, table) - iterates over all entries,
282	excluding CPUFREQ_ENTRY_INVALID frequencies.
283	Use arguments "pos" - a cpufreq_frequency_table * as a loop cursor and
284	"table" - the cpufreq_frequency_table * you want to iterate over.
285	
286	For example:
287	
288		struct cpufreq_frequency_table *pos, *driver_freq_table;
289	
290		cpufreq_for_each_entry(pos, driver_freq_table) {
291			/* Do something with pos */
292			pos->frequency = ...
293		}
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.