Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 | ||
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 | ||
20 | Contents: | |
21 | --------- | |
22 | 1. What To Do? | |
23 | 1.1 Initialization | |
24 | 1.2 Per-CPU Initialization | |
25 | 1.3 verify | |
26 | 1.4 target or setpolicy? | |
27 | 1.5 target | |
28 | 1.6 setpolicy | |
29 | 2. Frequency Table Helpers | |
30 | ||
31 | ||
32 | ||
33 | 1. What To Do? | |
34 | ============== | |
35 | ||
36 | So, you just got a brand-new CPU / chipset with datasheets and want to | |
37 | add cpufreq support for this CPU / chipset? Great. Here are some hints | |
38 | on what is necessary: | |
39 | ||
40 | ||
41 | 1.1 Initialization | |
42 | ------------------ | |
43 | ||
44 | First of all, in an __initcall level 7 (module_init()) or later | |
45 | function check whether this kernel runs on the right CPU and the right | |
46 | chipset. If so, register a struct cpufreq_driver with the CPUfreq core | |
47 | using cpufreq_register_driver() | |
48 | ||
49 | What shall this struct cpufreq_driver contain? | |
50 | ||
51 | cpufreq_driver.name - The name of this driver. | |
52 | ||
53 | cpufreq_driver.owner - THIS_MODULE; | |
54 | ||
55 | cpufreq_driver.init - A pointer to the per-CPU initialization | |
56 | function. | |
57 | ||
58 | cpufreq_driver.verify - A pointer to a "verification" function. | |
59 | ||
60 | cpufreq_driver.setpolicy _or_ | |
61 | cpufreq_driver.target - See below on the differences. | |
62 | ||
63 | And optionally | |
64 | ||
65 | cpufreq_driver.exit - A pointer to a per-CPU cleanup function. | |
66 | ||
67 | cpufreq_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 | ||
73 | cpufreq_driver.attr - A pointer to a NULL-terminated list of | |
74 | "struct freq_attr" which allow to | |
75 | export values to sysfs. | |
76 | ||
77 | ||
78 | 1.2 Per-CPU Initialization | |
79 | -------------------------- | |
80 | ||
81 | Whenever a new CPU is registered with the device model, or after the | |
82 | cpufreq driver registers itself, the per-CPU initialization function | |
83 | cpufreq_driver.init is called. It takes a struct cpufreq_policy | |
84 | *policy as argument. What to do now? | |
85 | ||
86 | If necessary, activate the CPUfreq support on your CPU. | |
87 | ||
88 | Then, the driver must fill in the following values: | |
89 | ||
90 | policy->cpuinfo.min_freq _and_ | |
91 | policy->cpuinfo.max_freq - the minimum and maximum frequency | |
92 | (in kHz) which is supported by | |
93 | this CPU | |
94 | policy->cpuinfo.transition_latency the time it takes on this CPU to | |
bbe237aa MB |
95 | switch between two frequencies in |
96 | nanoseconds (if appropriate, else | |
97 | specify CPUFREQ_ETERNAL) | |
1da177e4 LT |
98 | |
99 | policy->cur The current operating frequency of | |
100 | this CPU (if appropriate) | |
101 | policy->min, | |
102 | policy->max, | |
103 | policy->policy and, if necessary, | |
104 | policy->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 | ||
111 | For setting some of these values, the frequency table helpers might be | |
112 | helpful. See the section 2 for more information on them. | |
113 | ||
951fc5f4 VK |
114 | SMP systems normally have same clock source for a group of cpus. For these the |
115 | .init() would be called only once for the first online cpu. Here the .init() | |
116 | routine must initialize policy->cpus with mask of all possible cpus (Online + | |
117 | Offline) that share the clock. Then the core would copy this mask onto | |
118 | policy->related_cpus and will reset policy->cpus to carry only online cpus. | |
119 | ||
1da177e4 LT |
120 | |
121 | 1.3 verify | |
122 | ------------ | |
123 | ||
124 | When the user decides a new policy (consisting of | |
125 | "policy,governor,min,max") shall be set, this policy must be validated | |
126 | so that incompatible values can be corrected. For verifying these | |
127 | values, a frequency table helper and/or the | |
128 | cpufreq_verify_within_limits(struct cpufreq_policy *policy, unsigned | |
129 | int min_freq, unsigned int max_freq) function might be helpful. See | |
130 | section 2 for details on frequency table helpers. | |
131 | ||
132 | You need to make sure that at least one valid frequency (or operating | |
133 | range) is within policy->min and policy->max. If necessary, increase | |
134 | policy->max first, and only if this is no solution, decrease policy->min. | |
135 | ||
136 | ||
137 | 1.4 target or setpolicy? | |
138 | ---------------------------- | |
139 | ||
140 | Most cpufreq drivers or even most cpu frequency scaling algorithms | |
141 | only allow the CPU to be set to one frequency. For these, you use the | |
142 | ->target call. | |
143 | ||
144 | Some cpufreq-capable processors switch the frequency between certain | |
145 | limits on their own. These shall use the ->setpolicy call | |
146 | ||
147 | ||
148 | 1.4. target | |
149 | ------------- | |
150 | ||
151 | The target call has three arguments: struct cpufreq_policy *policy, | |
152 | unsigned int target_frequency, unsigned int relation. | |
153 | ||
154 | The CPUfreq driver must set the new frequency when called here. The | |
155 | actual frequency must be determined using the following rules: | |
156 | ||
157 | - keep close to "target_freq" | |
158 | - policy->min <= new_freq <= policy->max (THIS MUST BE VALID!!!) | |
159 | - if relation==CPUFREQ_REL_L, try to select a new_freq higher than or equal | |
160 | target_freq. ("L for lowest, but no lower than") | |
161 | - if relation==CPUFREQ_REL_H, try to select a new_freq lower than or equal | |
162 | target_freq. ("H for highest, but no higher than") | |
163 | ||
51555c0e | 164 | Here again the frequency table helper might assist you - see section 2 |
1da177e4 LT |
165 | for details. |
166 | ||
167 | ||
168 | 1.5 setpolicy | |
169 | --------------- | |
170 | ||
171 | The setpolicy call only takes a struct cpufreq_policy *policy as | |
172 | argument. You need to set the lower limit of the in-processor or | |
173 | in-chipset dynamic frequency switching to policy->min, the upper limit | |
174 | to policy->max, and -if supported- select a performance-oriented | |
175 | setting when policy->policy is CPUFREQ_POLICY_PERFORMANCE, and a | |
176 | powersaving-oriented setting when CPUFREQ_POLICY_POWERSAVE. Also check | |
25eb650a | 177 | the reference implementation in drivers/cpufreq/longrun.c |
1da177e4 LT |
178 | |
179 | ||
180 | ||
181 | 2. Frequency Table Helpers | |
182 | ========================== | |
183 | ||
184 | As most cpufreq processors only allow for being set to a few specific | |
185 | frequencies, a "frequency table" with some functions might assist in | |
186 | some work of the processor driver. Such a "frequency table" consists | |
187 | of an array of struct cpufreq_freq_table entries, with any value in | |
188 | "index" you want to use, and the corresponding frequency in | |
189 | "frequency". At the end of the table, you need to add a | |
190 | cpufreq_freq_table entry with frequency set to CPUFREQ_TABLE_END. And | |
191 | if you want to skip one entry in the table, set the frequency to | |
192 | CPUFREQ_ENTRY_INVALID. The entries don't need to be in ascending | |
193 | order. | |
194 | ||
195 | By calling cpufreq_frequency_table_cpuinfo(struct cpufreq_policy *policy, | |
196 | struct cpufreq_frequency_table *table); | |
197 | the cpuinfo.min_freq and cpuinfo.max_freq values are detected, and | |
198 | policy->min and policy->max are set to the same values. This is | |
199 | helpful for the per-CPU initialization stage. | |
200 | ||
201 | int cpufreq_frequency_table_verify(struct cpufreq_policy *policy, | |
202 | struct cpufreq_frequency_table *table); | |
203 | assures that at least one valid frequency is within policy->min and | |
204 | policy->max, and all other criteria are met. This is helpful for the | |
205 | ->verify call. | |
206 | ||
207 | int cpufreq_frequency_table_target(struct cpufreq_policy *policy, | |
208 | struct cpufreq_frequency_table *table, | |
209 | unsigned int target_freq, | |
210 | unsigned int relation, | |
211 | unsigned int *index); | |
212 | ||
213 | is the corresponding frequency table helper for the ->target | |
214 | stage. Just pass the values to this function, and the unsigned int | |
215 | index returns the number of the frequency table entry which contains | |
216 | the frequency the CPU shall be set to. PLEASE NOTE: This is not the | |
217 | "index" which is in this cpufreq_table_entry.index, but instead | |
218 | cpufreq_table[index]. So, the new frequency is | |
219 | cpufreq_table[index].frequency, and the value you stored into the | |
220 | frequency table "index" field is | |
221 | cpufreq_table[index].index. | |
222 |