| CPU frequency and voltage scaling code in the Linux(TM) kernel | |
| L i n u x C P U F r e q | |
| C P U D r i v e r s | |
| - information for developers - | |
| Dominik Brodowski <linux@brodo.de> | |
| Clock scaling allows you to change the clock speed of the CPUs on the | |
| fly. This is a nice method to save battery power, because the lower | |
| the clock speed, the less power the CPU consumes. | |
| Contents: | |
| --------- | |
| 1. What To Do? | |
| 1.1 Initialization | |
| 1.2 Per-CPU Initialization | |
| 1.3 verify | |
| 1.4 target/target_index or setpolicy? | |
| 1.5 target/target_index | |
| 1.6 setpolicy | |
| 1.7 get_intermediate and target_intermediate | |
| 2. Frequency Table Helpers | |
| 1. What To Do? | |
| ============== | |
| So, you just got a brand-new CPU / chipset with datasheets and want to | |
| add cpufreq support for this CPU / chipset? Great. Here are some hints | |
| on what is necessary: | |
| 1.1 Initialization | |
| ------------------ | |
| First of all, in an __initcall level 7 (module_init()) or later | |
| function check whether this kernel runs on the right CPU and the right | |
| chipset. If so, register a struct cpufreq_driver with the CPUfreq core | |
| using cpufreq_register_driver() | |
| What shall this struct cpufreq_driver contain? | |
| cpufreq_driver.name - The name of this driver. | |
| cpufreq_driver.init - A pointer to the per-CPU initialization | |
| function. | |
| cpufreq_driver.verify - A pointer to a "verification" function. | |
| cpufreq_driver.setpolicy _or_ | |
| cpufreq_driver.target/ | |
| target_index - See below on the differences. | |
| And optionally | |
| cpufreq_driver.exit - A pointer to a per-CPU cleanup | |
| function called during CPU_POST_DEAD | |
| phase of cpu hotplug process. | |
| cpufreq_driver.stop_cpu - A pointer to a per-CPU stop function | |
| called during CPU_DOWN_PREPARE phase of | |
| cpu hotplug process. | |
| cpufreq_driver.resume - A pointer to a per-CPU resume function | |
| which is called with interrupts disabled | |
| and _before_ the pre-suspend frequency | |
| and/or policy is restored by a call to | |
| ->target/target_index or ->setpolicy. | |
| cpufreq_driver.attr - A pointer to a NULL-terminated list of | |
| "struct freq_attr" which allow to | |
| export values to sysfs. | |
| cpufreq_driver.get_intermediate | |
| and target_intermediate Used to switch to stable frequency while | |
| changing CPU frequency. | |
| 1.2 Per-CPU Initialization | |
| -------------------------- | |
| Whenever a new CPU is registered with the device model, or after the | |
| cpufreq driver registers itself, the per-CPU initialization function | |
| cpufreq_driver.init is called. It takes a struct cpufreq_policy | |
| *policy as argument. What to do now? | |
| If necessary, activate the CPUfreq support on your CPU. | |
| Then, the driver must fill in the following values: | |
| policy->cpuinfo.min_freq _and_ | |
| policy->cpuinfo.max_freq - the minimum and maximum frequency | |
| (in kHz) which is supported by | |
| this CPU | |
| policy->cpuinfo.transition_latency the time it takes on this CPU to | |
| switch between two frequencies in | |
| nanoseconds (if appropriate, else | |
| specify CPUFREQ_ETERNAL) | |
| policy->cur The current operating frequency of | |
| this CPU (if appropriate) | |
| policy->min, | |
| policy->max, | |
| policy->policy and, if necessary, | |
| policy->governor must contain the "default policy" for | |
| this CPU. A few moments later, | |
| cpufreq_driver.verify and either | |
| cpufreq_driver.setpolicy or | |
| cpufreq_driver.target/target_index is called | |
| with these values. | |
| For setting some of these values (cpuinfo.min[max]_freq, policy->min[max]), the | |
| frequency table helpers might be helpful. See the section 2 for more information | |
| on them. | |
| SMP systems normally have same clock source for a group of cpus. For these the | |
| .init() would be called only once for the first online cpu. Here the .init() | |
| routine must initialize policy->cpus with mask of all possible cpus (Online + | |
| Offline) that share the clock. Then the core would copy this mask onto | |
| policy->related_cpus and will reset policy->cpus to carry only online cpus. | |
| 1.3 verify | |
| ------------ | |
| When the user decides a new policy (consisting of | |
| "policy,governor,min,max") shall be set, this policy must be validated | |
| so that incompatible values can be corrected. For verifying these | |
| values, a frequency table helper and/or the | |
| cpufreq_verify_within_limits(struct cpufreq_policy *policy, unsigned | |
| int min_freq, unsigned int max_freq) function might be helpful. See | |
| section 2 for details on frequency table helpers. | |
| You need to make sure that at least one valid frequency (or operating | |
| range) is within policy->min and policy->max. If necessary, increase | |
| policy->max first, and only if this is no solution, decrease policy->min. | |
| 1.4 target/target_index or setpolicy? | |
| ---------------------------- | |
| Most cpufreq drivers or even most cpu frequency scaling algorithms | |
| only allow the CPU to be set to one frequency. For these, you use the | |
| ->target/target_index call. | |
| Some cpufreq-capable processors switch the frequency between certain | |
| limits on their own. These shall use the ->setpolicy call | |
| 1.5. target/target_index | |
| ------------- | |
| The target_index call has two arguments: struct cpufreq_policy *policy, | |
| and unsigned int index (into the exposed frequency table). | |
| The CPUfreq driver must set the new frequency when called here. The | |
| actual frequency must be determined by freq_table[index].frequency. | |
| It should always restore to earlier frequency (i.e. policy->restore_freq) in | |
| case of errors, even if we switched to intermediate frequency earlier. | |
| Deprecated: | |
| ---------- | |
| The target call has three arguments: struct cpufreq_policy *policy, | |
| unsigned int target_frequency, unsigned int relation. | |
| The CPUfreq driver must set the new frequency when called here. The | |
| actual frequency must be determined using the following rules: | |
| - keep close to "target_freq" | |
| - policy->min <= new_freq <= policy->max (THIS MUST BE VALID!!!) | |
| - if relation==CPUFREQ_REL_L, try to select a new_freq higher than or equal | |
| target_freq. ("L for lowest, but no lower than") | |
| - if relation==CPUFREQ_REL_H, try to select a new_freq lower than or equal | |
| target_freq. ("H for highest, but no higher than") | |
| Here again the frequency table helper might assist you - see section 2 | |
| for details. | |
| 1.6 setpolicy | |
| --------------- | |
| The setpolicy call only takes a struct cpufreq_policy *policy as | |
| argument. You need to set the lower limit of the in-processor or | |
| in-chipset dynamic frequency switching to policy->min, the upper limit | |
| to policy->max, and -if supported- select a performance-oriented | |
| setting when policy->policy is CPUFREQ_POLICY_PERFORMANCE, and a | |
| powersaving-oriented setting when CPUFREQ_POLICY_POWERSAVE. Also check | |
| the reference implementation in drivers/cpufreq/longrun.c | |
| 1.7 get_intermediate and target_intermediate | |
| -------------------------------------------- | |
| Only for drivers with target_index() and CPUFREQ_ASYNC_NOTIFICATION unset. | |
| get_intermediate should return a stable intermediate frequency platform wants to | |
| switch to, and target_intermediate() should set CPU to to that frequency, before | |
| jumping to the frequency corresponding to 'index'. Core will take care of | |
| sending notifications and driver doesn't have to handle them in | |
| target_intermediate() or target_index(). | |
| Drivers can return '0' from get_intermediate() in case they don't wish to switch | |
| to intermediate frequency for some target frequency. In that case core will | |
| directly call ->target_index(). | |
| NOTE: ->target_index() should restore to policy->restore_freq in case of | |
| failures as core would send notifications for that. | |
| 2. Frequency Table Helpers | |
| ========================== | |
| As most cpufreq processors only allow for being set to a few specific | |
| frequencies, a "frequency table" with some functions might assist in | |
| some work of the processor driver. Such a "frequency table" consists | |
| of an array of struct cpufreq_frequency_table entries, with any value in | |
| "driver_data" you want to use, and the corresponding frequency in | |
| "frequency". At the end of the table, you need to add a | |
| cpufreq_frequency_table entry with frequency set to CPUFREQ_TABLE_END. And | |
| if you want to skip one entry in the table, set the frequency to | |
| CPUFREQ_ENTRY_INVALID. The entries don't need to be in ascending | |
| order. | |
| By calling cpufreq_table_validate_and_show(struct cpufreq_policy *policy, | |
| struct cpufreq_frequency_table *table); | |
| the cpuinfo.min_freq and cpuinfo.max_freq values are detected, and | |
| policy->min and policy->max are set to the same values. This is | |
| helpful for the per-CPU initialization stage. | |
| int cpufreq_frequency_table_verify(struct cpufreq_policy *policy, | |
| struct cpufreq_frequency_table *table); | |
| assures that at least one valid frequency is within policy->min and | |
| policy->max, and all other criteria are met. This is helpful for the | |
| ->verify call. | |
| int cpufreq_frequency_table_target(struct cpufreq_policy *policy, | |
| unsigned int target_freq, | |
| unsigned int relation); | |
| is the corresponding frequency table helper for the ->target | |
| stage. Just pass the values to this function, and this function | |
| returns the number of the frequency table entry which contains | |
| the frequency the CPU shall be set to. | |
| The following macros can be used as iterators over cpufreq_frequency_table: | |
| cpufreq_for_each_entry(pos, table) - iterates over all entries of frequency | |
| table. | |
| cpufreq-for_each_valid_entry(pos, table) - iterates over all entries, | |
| excluding CPUFREQ_ENTRY_INVALID frequencies. | |
| Use arguments "pos" - a cpufreq_frequency_table * as a loop cursor and | |
| "table" - the cpufreq_frequency_table * you want to iterate over. | |
| For example: | |
| struct cpufreq_frequency_table *pos, *driver_freq_table; | |
| cpufreq_for_each_entry(pos, driver_freq_table) { | |
| /* Do something with pos */ | |
| pos->frequency = ... | |
| } |