Documentation/cpu-freq/cpu-drivers.txt

   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 The cpufreq table is verified automatically by the core if the policy contains a
 263 valid pointer in its policy->freq_table field.
 264
 265 cpufreq_frequency_table_verify() assures that at least one valid
 266 frequency is within policy->min and policy->max, and all other criteria
 267 are met. This is helpful for the ->verify call.
 268
 269 cpufreq_frequency_table_target() is the corresponding frequency table
 270 helper for the ->target stage. Just pass the values to this function,
 271 and this function returns the of the frequency table entry which
 272 contains the frequency the CPU shall be set to.
 273
 274 The following macros can be used as iterators over cpufreq_frequency_table:
 275
 276 cpufreq_for_each_entry(pos, table) - iterates over all entries of frequency
 277 table.
 278
 279 cpufreq_for_each_valid_entry(pos, table) - iterates over all entries,
 280 excluding CPUFREQ_ENTRY_INVALID frequencies.
 281 Use arguments "pos" - a cpufreq_frequency_table * as a loop cursor and
 282 "table" - the cpufreq_frequency_table * you want to iterate over.
 283
 284 For example:
 285
 286         struct cpufreq_frequency_table *pos, *driver_freq_table;
 287
 288         cpufreq_for_each_entry(pos, driver_freq_table) {
 289                 /* Do something with pos */
 290                 pos->frequency = ...
 291         }
 292
 293 If you need to work with the position of pos within driver_freq_table,
 294 do not subtract the pointers, as it is quite costly. Instead, use the
 295 macros cpufreq_for_each_entry_idx() and cpufreq_for_each_valid_entry_idx().