Documentation/cpu-freq/cpu-drivers.rst

1 .. SPDX-License-Identifier: GPL-2.0
10 	- Dominik Brodowski  <linux@brodo.de>
11 	- Rafael J. Wysocki <rafael.j.wysocki@intel.com>
12 	- Viresh Kumar <viresh.kumar@linaro.org>
18    1.2  Per-CPU Initialization
24    2.   Frequency Table Helpers
31 So, you just got a brand-new CPU / chipset with datasheets and want to
37 ------------------
46  .name - The name of this driver.
48  .init - A pointer to the per-policy initialization function.
50  .verify - A pointer to a "verification" function.
52  .setpolicy _or_ .fast_switch _or_ .target _or_ .target_index - See
57  .flags - Hints for the cpufreq core.
59  .driver_data - cpufreq driver specific data.
61  .resolve_freq - Returns the most appropriate frequency for a target
62  frequency. Doesn't change the frequency though.
64  .get_intermediate and target_intermediate - Used to switch to stable
65  frequency while changing CPU frequency.
67  .get - Returns current frequency of the CPU.
69  .bios_limit - Returns HW/BIOS max frequency limitations for the CPU.
71  .exit - A pointer to a per-policy cleanup function called during
74  .stop_cpu - A pointer to a per-policy stop function called during
77  .suspend - A pointer to a per-policy suspend function which is called
81  .resume - A pointer to a per-policy resume function which is called
84  .ready - A pointer to a per-policy ready function which is called after
87  .attr - A pointer to a NULL-terminated list of "struct freq_attr" which
90  .boost_enabled - If set, boost frequencies are enabled.
92  .set_boost - A pointer to a per-policy function to enable/disable boost
96 1.2 Per-CPU Initialization
97 --------------------------
100 cpufreq driver registers itself, the per-policy initialization function
110 +-----------------------------------+--------------------------------------+
111 |policy->cpuinfo.min_freq _and_	    |					   |
112 |policy->cpuinfo.max_freq	    | the minimum and maximum frequency	   |
115 +-----------------------------------+--------------------------------------+
116 |policy->cpuinfo.transition_latency | the time it takes on this CPU to	   |
120 +-----------------------------------+--------------------------------------+
121 |policy->cur			    | The current operating frequency of   |
123 +-----------------------------------+--------------------------------------+
124 |policy->min,			    |					   |
125 |policy->max,			    |					   |
126 |policy->policy and, if necessary,  |					   |
127 |policy->governor		    | must contain the "default policy" for|
133 +-----------------------------------+--------------------------------------+
134 |policy->cpus			    | Update this with the masks of the	   |
138 +-----------------------------------+--------------------------------------+
140 For setting some of these values (cpuinfo.min[max]_freq, policy->min[max]), the
141 frequency table helpers might be helpful. See the section 2 for more information
146 ----------
149 "policy,governor,min,max") shall be set, this policy must be validated
153 See section 2 for details on frequency table helpers.
155 You need to make sure that at least one valid frequency (or operating
156 range) is within policy->min and policy->max. If necessary, increase
157 policy->max first, and only if this is no solution, decrease policy->min.
161 -------------------------------------------------------
163 Most cpufreq drivers or even most cpu frequency scaling algorithms
164 only allow the CPU frequency to be set to predefined fixed values. For
165 these, you use the ->target(), ->target_index() or ->fast_switch()
168 Some cpufreq capable processors switch the frequency between certain
169 limits on their own. These shall use the ->setpolicy() callback.
173 ------------------------
176 and ``unsigned int`` index (into the exposed frequency table).
178 The CPUfreq driver must set the new frequency when called here. The
179 actual frequency must be determined by freq_table[index].frequency.
181 It should always restore to earlier frequency (i.e. policy->restore_freq) in
182 case of errors, even if we switched to intermediate frequency earlier.
185 ----------
189 The CPUfreq driver must set the new frequency when called here. The
190 actual frequency must be determined using the following rules:
192 - keep close to "target_freq"
193 - policy->min <= new_freq <= policy->max (THIS MUST BE VALID!!!)
194 - if relation==CPUFREQ_REL_L, try to select a new_freq higher than or equal
196 - if relation==CPUFREQ_REL_H, try to select a new_freq lower than or equal
199 Here again the frequency table helper might assist you - see section 2
203 ----------------
205 This function is used for frequency switching from scheduler's context.
215 -------------
218 argument. You need to set the lower limit of the in-processor or
219 in-chipset dynamic frequency switching to policy->min, the upper limit
220 to policy->max, and -if supported- select a performance-oriented
221 setting when policy->policy is CPUFREQ_POLICY_PERFORMANCE, and a
222 powersaving-oriented setting when CPUFREQ_POLICY_POWERSAVE. Also check
226 --------------------------------------------
230 get_intermediate should return a stable intermediate frequency platform wants to
231 switch to, and target_intermediate() should set CPU to that frequency, before
232 jumping to the frequency corresponding to 'index'. Core will take care of
237 to intermediate frequency for some target frequency. In that case core will
238 directly call ->target_index().
240 NOTE: ->target_index() should restore to policy->restore_freq in case of
244 2. Frequency Table Helpers
248 frequencies, a "frequency table" with some functions might assist in
249 some work of the processor driver. Such a "frequency table" consists of
251 values in "driver_data", the corresponding frequency in "frequency" and
253 cpufreq_frequency_table entry with frequency set to CPUFREQ_TABLE_END.
254 And if you want to skip one entry in the table, set the frequency to
260 valid pointer in its policy->freq_table field.
263 frequency is within policy->min and policy->max, and all other criteria
264 are met. This is helpful for the ->verify call.
266 cpufreq_frequency_table_target() is the corresponding frequency table
267 helper for the ->target stage. Just pass the values to this function,
268 and this function returns the of the frequency table entry which
269 contains the frequency the CPU shall be set to.
273 cpufreq_for_each_entry(pos, table) - iterates over all entries of frequency
276 cpufreq_for_each_valid_entry(pos, table) - iterates over all entries,
278 Use arguments "pos" - a ``cpufreq_frequency_table *`` as a loop cursor and
279 "table" - the ``cpufreq_frequency_table *`` you want to iterate over.
287 		pos->frequency = ...