blob: c436096351f84ce15d13f02fe8f3148ea9940435 [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
111For setting some of these values, the frequency table helpers might be
112helpful. See the section 2 for more information on them.
113
114
1151.3 verify
116------------
117
118When the user decides a new policy (consisting of
119"policy,governor,min,max") shall be set, this policy must be validated
120so that incompatible values can be corrected. For verifying these
121values, a frequency table helper and/or the
122cpufreq_verify_within_limits(struct cpufreq_policy *policy, unsigned
123int min_freq, unsigned int max_freq) function might be helpful. See
124section 2 for details on frequency table helpers.
125
126You need to make sure that at least one valid frequency (or operating
127range) is within policy->min and policy->max. If necessary, increase
128policy->max first, and only if this is no solution, decrease policy->min.
129
130
1311.4 target or setpolicy?
132----------------------------
133
134Most cpufreq drivers or even most cpu frequency scaling algorithms
135only allow the CPU to be set to one frequency. For these, you use the
136->target call.
137
138Some cpufreq-capable processors switch the frequency between certain
139limits on their own. These shall use the ->setpolicy call
140
141
1421.4. target
143-------------
144
145The target call has three arguments: struct cpufreq_policy *policy,
146unsigned int target_frequency, unsigned int relation.
147
148The CPUfreq driver must set the new frequency when called here. The
149actual frequency must be determined using the following rules:
150
151- keep close to "target_freq"
152- policy->min <= new_freq <= policy->max (THIS MUST BE VALID!!!)
153- if relation==CPUFREQ_REL_L, try to select a new_freq higher than or equal
154 target_freq. ("L for lowest, but no lower than")
155- if relation==CPUFREQ_REL_H, try to select a new_freq lower than or equal
156 target_freq. ("H for highest, but no higher than")
157
Chumbalkar Nagananda51555c02009-05-21 23:29:48 +0000158Here again the frequency table helper might assist you - see section 2
Linus Torvalds1da177e2005-04-16 15:20:36 -0700159for details.
160
161
1621.5 setpolicy
163---------------
164
165The setpolicy call only takes a struct cpufreq_policy *policy as
166argument. You need to set the lower limit of the in-processor or
167in-chipset dynamic frequency switching to policy->min, the upper limit
168to policy->max, and -if supported- select a performance-oriented
169setting when policy->policy is CPUFREQ_POLICY_PERFORMANCE, and a
170powersaving-oriented setting when CPUFREQ_POLICY_POWERSAVE. Also check
Wanlong Gao25eb6502011-06-13 17:53:53 +0800171the reference implementation in drivers/cpufreq/longrun.c
Linus Torvalds1da177e2005-04-16 15:20:36 -0700172
173
174
1752. Frequency Table Helpers
176==========================
177
178As most cpufreq processors only allow for being set to a few specific
179frequencies, a "frequency table" with some functions might assist in
180some work of the processor driver. Such a "frequency table" consists
181of an array of struct cpufreq_freq_table entries, with any value in
182"index" you want to use, and the corresponding frequency in
183"frequency". At the end of the table, you need to add a
184cpufreq_freq_table entry with frequency set to CPUFREQ_TABLE_END. And
185if you want to skip one entry in the table, set the frequency to
186CPUFREQ_ENTRY_INVALID. The entries don't need to be in ascending
187order.
188
189By calling cpufreq_frequency_table_cpuinfo(struct cpufreq_policy *policy,
190 struct cpufreq_frequency_table *table);
191the cpuinfo.min_freq and cpuinfo.max_freq values are detected, and
192policy->min and policy->max are set to the same values. This is
193helpful for the per-CPU initialization stage.
194
195int cpufreq_frequency_table_verify(struct cpufreq_policy *policy,
196 struct cpufreq_frequency_table *table);
197assures that at least one valid frequency is within policy->min and
198policy->max, and all other criteria are met. This is helpful for the
199->verify call.
200
201int cpufreq_frequency_table_target(struct cpufreq_policy *policy,
202 struct cpufreq_frequency_table *table,
203 unsigned int target_freq,
204 unsigned int relation,
205 unsigned int *index);
206
207is the corresponding frequency table helper for the ->target
208stage. Just pass the values to this function, and the unsigned int
209index returns the number of the frequency table entry which contains
210the frequency the CPU shall be set to. PLEASE NOTE: This is not the
211"index" which is in this cpufreq_table_entry.index, but instead
212cpufreq_table[index]. So, the new frequency is
213cpufreq_table[index].frequency, and the value you stored into the
214frequency table "index" field is
215cpufreq_table[index].index.
216