Commit 9b48c576 authored by Dominik Brodowski's avatar Dominik Brodowski Committed by Linus Torvalds

[PATCH] cpufreq (5/5): update documentation

update CPUfreq documentation, and move it to extra directory.
parent 912fd3b6
...@@ -56,6 +56,8 @@ computone.txt ...@@ -56,6 +56,8 @@ computone.txt
- info on Computone Intelliport II/Plus Multiport Serial Driver - info on Computone Intelliport II/Plus Multiport Serial Driver
cpqarray.txt cpqarray.txt
- info on using Compaq's SMART2 Intelligent Disk Array Controllers. - info on using Compaq's SMART2 Intelligent Disk Array Controllers.
cpufreq/
- info on CPU frequency and voltage scaling
cris/ cris/
- directory with info about Linux on CRIS architecture. - directory with info about Linux on CRIS architecture.
devices.txt devices.txt
......
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 F r e q C o r e
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. CPUFreq core and interfaces
2. CPUFreq notifiers
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 (ex. thermal modules like ACPI) or of all
frequency changes (ex. 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.
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.
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.
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
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 or setpolicy?
1.5 target
1.6 setpolicy
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 neccessary:
1.1 Initialization
------------------
First of all, in an __initcall level 7 or later (preferrably
module_init() so that your driver is modularized) 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 "verfication" funciton.
cpufreq_driver.setpolicy _or_
cpufreq_driver.target - See below on the differences.
And optionally
cpufreq_driver.exit - A pointer to a per-CPU cleanup function.
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 fucntion
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 (unlock that
register etc.).
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 (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 neccessary,
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 is called with
these values.
For setting some of these values, the frequency table helpers might be
helpful. See the section 2 for more information on them.
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 fist, and only if this is no solution, decreas policy->min.
1.4 target 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 call.
Some cpufreq-capable processors switch the frequency between certain
limits on their own. These shall use the ->setpolicy call
1.4. target
-------------
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 3
for details.
1.5 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 arch/i386/kernel/cpu/cpufreq/longrun.c
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_freq_table entries, with any value in
"index" you want to use, and the corresponding frequency in
"frequency". At the end of the table, you need to add a
cpufreq_freq_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_frequency_table_cpuinfo(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,
struct cpufreq_frequency_table *table,
unsigned int target_freq,
unsigned int relation,
unsigned int *index);
is the corresponding frequency table helper for the ->target
stage. Just pass the values to this function, and the unsigned int
index returns the number of the frequency table entry which contains
the frequency the CPU shall be set to. PLEASE NOTE: This is not the
"index" which is in this cpufreq_table_entry.index, but instead
cpufreq_table[index]. So, the new frequency is
cpufreq_table[index].frequency, and the value you stored into the
frequency table "index" field is
cpufreq_table[index].index.
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 F r e q G o v e r n o r s
- information for users and 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 is a CPUFreq Governor?
2. Governors In the Linux Kernel
2.1 Performance
2.2 Powersave
2.3 Userspace
3. The Governor Interface in the CPUfreq Core
1. What Is A CPUFreq Governor?
==============================
Most cpufreq drivers (in fact, all except one, longrun) or even most
cpu frequency scaling algorithms only offer the CPU to be set to one
frequency. In order to offer dynamic frequency scaling, the cpufreq
core must be able to tell these drivers of a "target frequency". So
these specific drivers will be transformed to offer a "->target"
call instead of the existing "->setpolicy" call. For "longrun", all
stays the same, though.
How to decide what frequency within the CPUfreq policy should be used?
That's done using "cpufreq governors". Two are already in this patch
-- they're the already existing "powersave" and "performance" which
set the frequency statically to the lowest or highest frequency,
respectively. At least two more such governors will be ready for
addition in the near future, but likely many more as there are various
different theories and models about dynamic frequency scaling
around. Using such a generic interface as cpufreq offers to scaling
governors, these can be tested extensively, and the best one can be
selected for each specific use.
Basically, it's the following flow graph:
CPU can be set to switch independetly | CPU can only be set
within specific "limits" | to specific frequencies
"CPUfreq policy"
consists of frequency limits (policy->{min,max})
and CPUfreq governor to be used
/ \
/ \
/ the cpufreq governor decides
/ (dynamically or statically)
/ what target_freq to set within
/ the limits of policy->{min,max}
/ \
/ \
Using the ->setpolicy call, Using the ->target call,
the limits and the the frequency closest
"policy" is set. to target_freq is set.
It is assured that it
is within policy->{min,max}
2. Governors In the Linux Kernel
================================
2.1 Performance
---------------
The CPUfreq governor "performance" sets the CPU statically to the
highest frequency within the borders of scaling_min_freq and
scaling_max_freq.
2.1 Powersave
-------------
The CPUfreq governor "powersave" sets the CPU statically to the
lowest frequency within the borders of scaling_min_freq and
scaling_max_freq.
2.2 Userspace
-------------
The CPUfreq governor "userspace" allows the user, or any userspace
program running with UID "root", to set the CPU to a specifc frequency
by making a sysfs file "scaling_setspeed" available in the CPU-device
directory.
3. The Governor Interface in the CPUfreq Core
=============================================
A new governor must register itself with the CPUfreq core using
"cpufreq_register_governor". The struct cpufreq_governor, which has to
be passed to that function, must contain the following values:
governor->name - A unique name for this governor
governor->governor - The governor callback function
governor->owner - .THIS_MODULE for the governor module (if
appropriate)
The governor->governor callback is called with the current (or to-be-set)
cpufreq_policy struct for that CPU, and an unsigned int event. The
following events are currently defined:
CPUFREQ_GOV_START: This governor shall start its duty for the CPU
policy->cpu
CPUFREQ_GOV_STOP: This governor shall end its duty for the CPU
policy->cpu
CPUFREQ_GOV_LIMITS: The limits for CPU policy->cpu have changed to
policy->min and policy->max.
If you need other "events" externally of your driver, _only_ use the
cpufreq_governor_l(unsigned int cpu, unsigned int event) call to the
CPUfreq core to ensure proper locking.
The CPUfreq governor may call the CPU processor driver using one of
these two functions:
inline int cpufreq_driver_target(struct cpufreq_policy *policy,
unsigned int target_freq,
unsigned int relation);
inline int cpufreq_driver_target_l(struct cpufreq_policy *policy,
unsigned int target_freq,
unsigned int relation);
target_freq must be within policy->min and policy->max, of course.
What's the difference between these two functions? When your governor
still is in a direct code path of a call to governor->governor, the
cpufreq_driver_sem lock is still held in the cpufreq core, and there's
no need to lock it again (in fact, this would cause a deadlock). So
use cpufreq_driver_target only in these cases. In all other cases (for
example, when there's a "daemonized" function that wakes up every
second), use cpufreq_driver_target_l to lock the cpufreq_driver_sem
before the command is passed to the cpufreq processor driver.
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>
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.
Documents in this directory:
----------------------------
core.txt - General description of the CPUFreq core and
of CPUFreq notifiers
cpu-drivers.txt - How to implement a new cpufreq processor driver
governors.txt - What are cpufreq governors and how to
implement them?
index.txt - File index, Mailing list and Links (this document)
user-guide.txt - User Guide to CPUFreq
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
CPU frequency and voltage scaling code in the Linux(TM) kernel
L i n u x C P U F r e q
U S E R G U I D E
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. Supported Architectures and Processors
1.1 ARM
1.2 x86
1.3 sparc64
2. "Policy" / "Governor"?
2.1 Policy
2.2 Governor
3. How to change the CPU cpufreq policy and/or speed
3.1 Preferred interface: sysfs
3.2 Deprecated interfaces
1. Supported Architectures and Processors
=========================================
1.1 ARM
-------
The following ARM processors are supported by cpufreq:
ARM Integrator
ARM-SA1100
ARM-SA1110
1.2 x86
-------
The following processors for the x86 architecture are supported by cpufreq:
AMD Elan - SC400, SC410
AMD mobile K6-2+
AMD mobile K6-3+
Cyrix Media GXm
Intel mobile PIII [*] and Intel mobile PIII-M on certain chipsets
Intel Pentium 4, Intel Xeon
National Semiconductors Geode GX
Transmeta Crusoe
varios processors on some ACPI 2.0-compatible systems [**]
[*] only certain Intel mobile PIII processors are supported. If you
know that you own a speedstep-capable processor, pass the option
"speedstep_coppermine=1" to the module speedstep.o
[**] Only if "ACPI Processor Performance States" are available
to the ACPI<->BIOS interface.
1.3 sparc64
-----------
The following processors for the sparc64 architecture are supported by
cpufreq:
UltraSPARC-III
2. "Policy" / "Governor" ?
==========================
Some CPU frequency scaling-capable processor switch between varios
frequencies and operating voltages "on the fly" without any kernel or
user involvement. This guarantuees very fast switching to a frequency
which is high enough to serve the user's needs, but low enough to save
power.
2.1 Policy
----------
On these systems, all you can do is select the lower and upper
frequency limit as well as whether you want more aggressive
power-saving or more instantly avaialble processing power.
2.2 Governor
------------
On all other cpufreq implementations, these boundaries still need to
be set. Then, a "governor" must be selected. Such a "governor" decides
what speed the processor shall run within the boundaries. One such
"governor" is the "userspace" governor. This one allows the user - or
a yet-to-implement userspace program - to decide what specific speed
the processor shall run at.
3. How to change the CPU cpufreq policy and/or speed
====================================================
3.1 Preferred Interface: sysfs
------------------------------
The preferred interface is located in the sysfs filesystem. If you
mounted it at /sys, the cpufreq interface is located in the
cpu-device directory (e.g. /sys/devices/sys/cpu0/ for the first
CPU).
cpuinfo_min_freq : this file shows the minimum operating
frequency the processor can run at(in kHz)
cpuinfo_max_freq : this file shows the maximum operating
frequency the processor can run at(in kHz)
scaling_driver : this file shows what cpufreq driver is
used to set the frequency on this CPU
available_scaling_governors : this file shows the CPUfreq governors
available in this kernel. You can see the
currently activated governor in
scaling_governor, and by "echoing" the name of another
governor you can change it. Please note
that some governors won't load - they only
work on some specific architectures or
processors.
scaling_min_freq and
scaling_max_freq show the current "policy limits" (in
kHz). By echoing new values into these
files, you can change these limits.
If you have selected the "userspace" governor which allows you to
set the CPU operating frequency to a specific value, you can read out
the current frequency in
scaling_setspeed. By "echoing" a new frequency into this
you can change the speed of the CPU,
but only within the limits of
scaling_min_freq and scaling_max_freq.
3.2 Deprecated Interfaces
-------------------------
Depending on your kernel configuration, you might find the following
cpufreq-related files:
/proc/cpufreq
/proc/sys/cpu/*/speed
/proc/sys/cpu/*/speed-min
/proc/sys/cpu/*/speed-max
These are files for deprecated interfaces to cpufreq, which offer far
less functionality. Because of this, these interfaces aren't described
here.
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment