     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  <linux@brodo.de>
		     David Kimdon <dwhedon@debian.org>



   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
--------------------------------
    This driver will be ported to new CPUFreq core soon, so
    far it will not work.


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.


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/
