blob: 19fa98e07bf7fe79f403042d14858677f4474839 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001 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
13
14
15 Clock scaling allows you to change the clock speed of the CPUs on the
16 fly. This is a nice method to save battery power, because the lower
17 the clock speed, the less power the CPU consumes.
18
19
20Contents:
21---------
221. What To Do?
231.1 Initialization
241.2 Per-CPU Initialization
251.3 verify
261.4 target or setpolicy?
271.5 target
281.6 setpolicy
292. Frequency Table Helpers
30
31
32
331. What To Do?
34==============
35
36So, you just got a brand-new CPU / chipset with datasheets and want to
37add cpufreq support for this CPU / chipset? Great. Here are some hints
38on what is necessary:
39
40
411.1 Initialization
42------------------
43
44First of all, in an __initcall level 7 (module_init()) or later
45function check whether this kernel runs on the right CPU and the right
46chipset. If so, register a struct cpufreq_driver with the CPUfreq core
47using cpufreq_register_driver()
48
49What shall this struct cpufreq_driver contain?
50
51cpufreq_driver.name - The name of this driver.
52
53cpufreq_driver.owner - THIS_MODULE;
54
55cpufreq_driver.init - A pointer to the per-CPU initialization
56 function.
57
58cpufreq_driver.verify - A pointer to a "verification" function.
59
60cpufreq_driver.setpolicy _or_
61cpufreq_driver.target - See below on the differences.
62
63And optionally
64
65cpufreq_driver.exit - A pointer to a per-CPU cleanup function.
66
67cpufreq_driver.resume - A pointer to a per-CPU resume function
68 which is called with interrupts disabled
69 and _before_ the pre-suspend frequency
70 and/or policy is restored by a call to
71 ->target or ->setpolicy.
72
73cpufreq_driver.attr - A pointer to a NULL-terminated list of
74 "struct freq_attr" which allow to
75 export values to sysfs.
76
77
781.2 Per-CPU Initialization
79--------------------------
80
81Whenever a new CPU is registered with the device model, or after the
82cpufreq driver registers itself, the per-CPU initialization function
83cpufreq_driver.init is called. It takes a struct cpufreq_policy
84*policy as argument. What to do now?
85
86If necessary, activate the CPUfreq support on your CPU.
87
88Then, the driver must fill in the following values:
89
90policy->cpuinfo.min_freq _and_
91policy->cpuinfo.max_freq - the minimum and maximum frequency
92 (in kHz) which is supported by
93 this CPU
94policy->cpuinfo.transition_latency the time it takes on this CPU to
Mark Brownbbe237a2009-11-12 16:06:45 +000095 switch between two frequencies in
96 nanoseconds (if appropriate, else
97 specify CPUFREQ_ETERNAL)
Linus Torvalds1da177e2005-04-16 15:20:36 -070098
99policy->cur The current operating frequency of
100 this CPU (if appropriate)
101policy->min,
102policy->max,
103policy->policy and, if necessary,
104policy->governor must contain the "default policy" for
105 this CPU. A few moments later,
106 cpufreq_driver.verify and either
107 cpufreq_driver.setpolicy or
108 cpufreq_driver.target is called with
109 these values.
110
Viresh Kumareb2f50f2013-04-01 12:57:48 +0000111For setting some of these values (cpuinfo.min[max]_freq, policy->min[max]), the
112frequency table helpers might be helpful. See the section 2 for more information
113on them.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700114
Viresh Kumar951fc5f2013-01-31 02:03:53 +0000115SMP systems normally have same clock source for a group of cpus. For these the
116.init() would be called only once for the first online cpu. Here the .init()
117routine must initialize policy->cpus with mask of all possible cpus (Online +
118Offline) that share the clock. Then the core would copy this mask onto
119policy->related_cpus and will reset policy->cpus to carry only online cpus.
120
Linus Torvalds1da177e2005-04-16 15:20:36 -0700121
1221.3 verify
123------------
124
125When the user decides a new policy (consisting of
126"policy,governor,min,max") shall be set, this policy must be validated
127so that incompatible values can be corrected. For verifying these
128values, a frequency table helper and/or the
129cpufreq_verify_within_limits(struct cpufreq_policy *policy, unsigned
130int min_freq, unsigned int max_freq) function might be helpful. See
131section 2 for details on frequency table helpers.
132
133You need to make sure that at least one valid frequency (or operating
134range) is within policy->min and policy->max. If necessary, increase
135policy->max first, and only if this is no solution, decrease policy->min.
136
137
1381.4 target or setpolicy?
139----------------------------
140
141Most cpufreq drivers or even most cpu frequency scaling algorithms
142only allow the CPU to be set to one frequency. For these, you use the
143->target call.
144
145Some cpufreq-capable processors switch the frequency between certain
146limits on their own. These shall use the ->setpolicy call
147
148
1491.4. target
150-------------
151
152The target call has three arguments: struct cpufreq_policy *policy,
153unsigned int target_frequency, unsigned int relation.
154
155The CPUfreq driver must set the new frequency when called here. The
156actual frequency must be determined using the following rules:
157
158- keep close to "target_freq"
159- policy->min <= new_freq <= policy->max (THIS MUST BE VALID!!!)
160- if relation==CPUFREQ_REL_L, try to select a new_freq higher than or equal
161 target_freq. ("L for lowest, but no lower than")
162- if relation==CPUFREQ_REL_H, try to select a new_freq lower than or equal
163 target_freq. ("H for highest, but no higher than")
164
Chumbalkar Nagananda51555c02009-05-21 23:29:48 +0000165Here again the frequency table helper might assist you - see section 2
Linus Torvalds1da177e2005-04-16 15:20:36 -0700166for details.
167
168
1691.5 setpolicy
170---------------
171
172The setpolicy call only takes a struct cpufreq_policy *policy as
173argument. You need to set the lower limit of the in-processor or
174in-chipset dynamic frequency switching to policy->min, the upper limit
175to policy->max, and -if supported- select a performance-oriented
176setting when policy->policy is CPUFREQ_POLICY_PERFORMANCE, and a
177powersaving-oriented setting when CPUFREQ_POLICY_POWERSAVE. Also check
Wanlong Gao25eb6502011-06-13 17:53:53 +0800178the reference implementation in drivers/cpufreq/longrun.c
Linus Torvalds1da177e2005-04-16 15:20:36 -0700179
180
181
1822. Frequency Table Helpers
183==========================
184
185As most cpufreq processors only allow for being set to a few specific
186frequencies, a "frequency table" with some functions might assist in
187some work of the processor driver. Such a "frequency table" consists
Viresh Kumar3a7818e2013-04-01 12:57:42 +0000188of an array of struct cpufreq_frequency_table entries, with any value in
Viresh Kumar50701582013-03-30 16:25:15 +0530189"driver_data" you want to use, and the corresponding frequency in
Linus Torvalds1da177e2005-04-16 15:20:36 -0700190"frequency". At the end of the table, you need to add a
Viresh Kumar3a7818e2013-04-01 12:57:42 +0000191cpufreq_frequency_table entry with frequency set to CPUFREQ_TABLE_END. And
Linus Torvalds1da177e2005-04-16 15:20:36 -0700192if you want to skip one entry in the table, set the frequency to
193CPUFREQ_ENTRY_INVALID. The entries don't need to be in ascending
194order.
195
196By calling cpufreq_frequency_table_cpuinfo(struct cpufreq_policy *policy,
197 struct cpufreq_frequency_table *table);
198the cpuinfo.min_freq and cpuinfo.max_freq values are detected, and
199policy->min and policy->max are set to the same values. This is
200helpful for the per-CPU initialization stage.
201
202int cpufreq_frequency_table_verify(struct cpufreq_policy *policy,
203 struct cpufreq_frequency_table *table);
204assures that at least one valid frequency is within policy->min and
205policy->max, and all other criteria are met. This is helpful for the
206->verify call.
207
208int cpufreq_frequency_table_target(struct cpufreq_policy *policy,
209 struct cpufreq_frequency_table *table,
210 unsigned int target_freq,
211 unsigned int relation,
212 unsigned int *index);
213
214is the corresponding frequency table helper for the ->target
215stage. Just pass the values to this function, and the unsigned int
216index returns the number of the frequency table entry which contains
Viresh Kumar50701582013-03-30 16:25:15 +0530217the frequency the CPU shall be set to.