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