CPU frequency and voltage scaling code in the Linux(TM) kernel L i n u x C P U F r e q Dominik Brodowski David Kimdon 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. Supported architectures 2. User interface 2.1 /proc/cpufreq interface [2.6] 2.2. /proc/sys/cpu/ interface [2.4] 3. CPUFreq core and interfaces 3.1 General information 3.2 CPUFreq notifiers 3.3 CPUFreq architecture drivers 4. Mailing list and Links 1. Supported architectures ========================== ARM: ARM Integrator, SA 1100, SA1110 -------------------------------- No known issues. AMD Elan: SC400, SC410 -------------------------------- You need to specify the highest allowed CPU frequency as a module parameter ("max_freq") or as boot parameter ("elanfreq="). Else the available speed range will be limited to the speed at which the CPU runs while this module is loaded. VIA Cyrix Longhaul: VIA Samuel/CyrixIII, VIA Cyrix Samuel/C3, VIA Cyrix Ezra, VIA Cyrix Ezra-T -------------------------------- If you do not want to scale the Front Side Bus or voltage, pass the module parameter "dont_scale_fsb=1" or "dont_scale_voltage=1". Additionally, it is advised that you pass the current Front Side Bus speed (in MHz) to this module as module parameter "current_fsb", e.g. "current_fsb=133" for a Front Side Bus speed of 133 MHz. Intel SpeedStep: certain mobile Intel Pentium III (Coppermine), and all mobile Intel Pentium III-M (Tualatin) and mobile Intel Pentium 4 P4-Ms. -------------------------------- Unfortunately, only modern Intel ICH2-M and ICH3-M chipsets are supported yet. P4 CPU Clock Modulation: Intel Pentium 4 Xeon processors --------------------------------- Note that you can only switch the speed of two logical CPUs at once - but each phyiscal CPU may have different throttling levels. PowerNow! K6: mobile AMD K6-2+ / mobile K6-3+: -------------------------------- No known issues. Transmeta Crusoe Longrun: Transmeta Crusoe processors: -------------------------------- It is recommended to use the 2.6. /proc/cpufreq interface when using this driver 2. User Interface ================= 2.1 /proc/cpufreq interface [2.6] *********************************** Starting in the patches for kernel 2.5.33, CPUFreq uses a "policy" interface /proc/cpufreq. When you "cat" this file, you'll find something like: -- minimum CPU frequency - maximum CPU frequency - policy CPU 0 1200000 ( 75%) - 1600000 (100%) - performance -- This means the current policy allows this CPU to be run anywhere between 1.2 GHz (the value is in kHz) and 1.6 GHz with an eye towards performance. To change the policy, "echo" the desired new policy into /proc/cpufreq. Use one of the following formats: cpu_nr:min_freq:max_freq:policy cpu_nr%min_freq%max_freq%policy min_freq:max_freq:policy min_freq%max_freq%policy with cpu_nr being the CPU which shall be affected, min_freq and max_freq the lower and upper limit of the CPU core frequency in kHz, and policy either "performance" or "powersave". A few examples: root@notebook:#echo -n "0:0:0:powersave" > /proc/cpufreq sets the CPU #0 to the lowest supported frequency. root@notebook:#echo -n "1%100%100%performance" > /proc/cpufreq sets the CPU #1 to the highest supported frequency. root@notebook:#echo -n "1000000:2000000:performance" > /proc/cpufreq to set the frequency of all CPUs between 1 GHz and 2 GHz and to the policy "performance". Please note that the values you "echo" into /proc/cpufreq are validated first, and may be limited by hardware or thermal considerations. Because of this, a read from /proc/cpufreq might differ from what was written into it. When you read /proc/cpufreq for the first time after a CPUFreq driver has been initialized, you'll see the "default policy" for this driver. If this does not suit your needs, you can pass a boot parameter to the cpufreq core. Use the following syntax for this: "cpufreq=min_freq:max_freq:policy", i.e. you may not chose a specific CPU and you need to specify the limits in kHz and not in per cent. 2.2 /proc/cpufreq interface [2.4] *********************************** Previsiously (and still available as a config option), CPUFreq used a "sysctl" interface which is located in /proc/sys/cpu/0/ /proc/sys/cpu/1/ ... (SMP only) In these directories, you will find three files of importance for CPUFreq: speed-max, speed-min and speed: speed shows the current CPU frequency in kHz, speed-min the minimum supported CPU frequency, and speed-max the maximum supported CPU frequency. To change the CPU frequency, "echo" the desired CPU frequency (in kHz) to speed. For example, to set the CPU speed to the lowest/highest allowed frequency do: root@notebook:# cat /proc/sys/cpu/0/speed-min > /proc/sys/cpu/0/speed root@notebook:# cat /proc/sys/cpu/0/speed-max > /proc/sys/cpu/0/speed 3. CPUFreq core and interfaces =============================== 3.1 General information ************************* The CPUFreq core code is located in linux/kernel/cpufreq.c. This cpufreq code offers a standardized interface for the CPUFreq architecture drivers (those pieces of code that do actual frequency transitions), as well as to "notifiers". These are device drivers or other part of the kernel that need to be informed of policy changes (like thermal modules like ACPI) or of all frequency changes (like timing code) or even need to force certain speed limits (like LCD drivers on ARM architecture). Additionally, the kernel "constant" loops_per_jiffy is updated on frequency changes here. 3.2 CPUFreq notifiers *********************** CPUFreq notifiers conform to the standard kernel notifier interface. See linux/include/linux/notifier.h for details on notifiers. There are two different CPUFreq notifiers - policy notifiers and transition notifiers. 3.2.1 CPUFreq policy notifiers ****************************** These are notified when a new policy is intended to be set. Each CPUFreq policy notifier is called three times for a policy transition: 1.) During CPUFREQ_ADJUST all CPUFreq notifiers may change the limit if they see a need for this - may it be thermal considerations or hardware limitations. 2.) During CPUFREQ_INCOMPATIBLE only changes may be done in order to avoid hardware failure. 3.) And during CPUFREQ_NOTIFY all notifiers are informed of the new policy - if two hardware drivers failed to agree on a new policy before this stage, the incompatible hardware shall be shut down, and the user informed of this. The phase is specified in the second argument to the notifier. The third argument, a void *pointer, points to a struct cpufreq_policy consisting of five values: cpu, min, max, policy and max_cpu_freq. Min and max are the lower and upper frequencies (in kHz) of the new policy, policy the new policy, cpu the number of the affected CPU or CPUFREQ_ALL_CPUS for all CPUs; and max_cpu_freq the maximum supported CPU frequency. This value is given for informational purposes only. 3.2.2 CPUFreq transition notifiers ********************************** These are notified twice when the CPUfreq driver switches the CPU core frequency and this change has any external implications. The second argument specifies the phase - CPUFREQ_PRECHANGE or CPUFREQ_POSTCHANGE. The third argument is a struct cpufreq_freqs with the following values: cpu - number of the affected CPU or CPUFREQ_ALL_CPUS old - old frequency new - new frequency 3.3 CPUFreq architecture drivers ********************************** CPUFreq architecture drivers are the pieces of kernel code that actually perform CPU frequency transitions. These need to be initialized separately (separate initcalls), and may be modularized. They interact with the CPUFreq core in the following way: cpufreq_register() ------------------ cpufreq_register registers an arch driver to the CPUFreq core. Please note that only one arch driver may be registered at any time. -EBUSY is returned when an arch driver is already registered. The argument to cpufreq_register, struct cpufreq_driver *driver, is described later. cpufreq_unregister() -------------------- cpufreq_unregister unregisters an arch driver, e.g. on module unloading. Please note that there is no check done that this is called from the driver which actually registered itself to the core, so please only call this function when you are sure the arch driver got registered correctly before. cpufreq_notify_transition() --------------------------- On "dumb" hardware where only fixed frequency can be set, the driver must call cpufreq_notify_transition() once before, and once after the actual transition. struct cpufreq_driver --------------------- On initialization, the arch driver is supposed to pass a pointer to a struct cpufreq_driver *cpufreq_driver consisting of the following entries: cpufreq_verify_t verify: This is a pointer to a function with the following definition: int verify_function (struct cpufreq_policy *policy). This function must verify the new policy is within the limits supported by the CPU, and at least one supported CPU is within this range. It may be useful to use cpufreq.h / cpufreq_verify_within_limits for this. If this is called with CPUFREQ_ALL_CPUS, and there is no common subset of frequencies for all CPUs, exit with an error. cpufreq_setpolicy_t setpolicy: This is a pointer to a function with the following definition: int setpolicy_function (struct cpufreq_policy *policy). This function must set the CPU to the new policy. If it is a "dumb" CPU which only allows fixed frequencies to be set, it shall set it to the lowest within the limit for CPUFREQ_POLICY_POWERSAVE, and to the highest for CPUFREQ_POLICY_PERFORMANCE. Once CONFIG_CPU_FREQ_DYNAMIC is implemented, it can use a dynamic method to adjust the speed between the lower and upper limit. struct cpufreq_policy *policy: This is an array of NR_CPUS struct cpufreq_policies, containing the current policies set for these CPUs. Note that policy[cpu].max_cpu_freq must contain the absolute maximum CPU frequency supported by the specified cpu. In case the driver is expected to run with the 2.4.-style API (/proc/sys/cpu/.../), two more values must be passed #ifdef CONFIG_CPU_FREQ_24_API unsigned int cpu_min_freq[NR_CPUS]; unsigned int cpu_cur_freq[NR_CPUS]; #endif with cpu_min_freq[cpu] being the minimum CPU frequency supported by the CPU; and the entries in cpu_cur_freq reflecting the current speed of the appropriate CPU. Some Requirements to CPUFreq architecture drivers ------------------------------------------------- * Only call cpufreq_register() when the ability to switch CPU frequencies is _verified_ or can't be missing. Also, all other initialization must be done beofre this call, as cpfureq_register calls the driver's verify and setpolicy code for each CPU. * cpufreq_unregister() may only be called if cpufreq_register() has been successfully(!) called before. * kfree() the struct cpufreq_driver only after the call to cpufreq_unregister(), unless cpufreq_register() failed. 4. Mailing list and Links ************************* Mailing List ------------ There is a CPU frequency changing CVS commit and general list where you can report bugs, problems or submit patches. To post a message, send an email to cpufreq@www.linux.org.uk, to subscribe go to http://www.linux.org.uk/mailman/listinfo/cpufreq. Previous post to the mailing list are available to subscribers at http://www.linux.org.uk/mailman/private/cpufreq/. Links ----- the FTP archives: * ftp://ftp.linux.org.uk/pub/linux/cpufreq/ how to access the CVS repository: * http://cvs.arm.linux.org.uk/ the CPUFreq Mailing list: * http://www.linux.org.uk/mailman/listinfo/cpufreq Clock and voltage scaling for the SA-1100: * http://www.lart.tudelft.nl/projects/scaling CPUFreq project homepage * http://www.brodo.de/cpufreq/