2002-09-28 09:29:22

by Dominik Brodowski

[permalink] [raw]
Subject: [2.5.39] (4/5) CPUfreq Documentation

CPUFreq documentation for 2.5.39:
CREDITS one further CREDIT entry
Documentation/cpufreq documentation of CPU frequency and voltage scaling
support in the Linux kernel.
MAINTAINERS one further MAINTAINERS entry
arch/i386/Config.help Config.help texts for i386 CPUFreq drivers

diff -ruN linux-2539original/CREDITS linux/CREDITS
--- linux-2539original/CREDITS Sun Sep 22 09:00:00 2002
+++ linux/CREDITS Sat Sep 28 09:30:00 2002
@@ -438,6 +438,13 @@
S: 411 13 Goteborg
S: Sweden

+N: Dominik Brodowski
+E: [email protected]
+W: http://www.brodo.de/
+P: 1024D/725B37C6 190F 3E77 9C89 3B6D BECD 46EE 67C3 0308 725B 37C6
+D: parts of CPUFreq code, ACPI bugfixes
+S: Tuebingen, Germany
+
N: Andries Brouwer
E: [email protected]
D: random Linux hacker
diff -ruN linux-2539original/Documentation/cpufreq linux/Documentation/cpufreq
--- linux-2539original/Documentation/cpufreq Thu Jan 1 01:00:00 1970
+++ linux/Documentation/cpufreq Sat Sep 28 09:30:00 2002
@@ -0,0 +1,361 @@
+ 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 <[email protected]>
+ David Kimdon <[email protected]>
+
+
+
+ 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:
+--------------------------------
+ Does not work with the 2.4. /proc/sys/cpu/ interface.
+
+
+
+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:
+
[email protected]:#echo -n "0:0:0:powersave" > /proc/cpufreq
+ sets the CPU #0 to the lowest supported frequency.
+
[email protected]:#echo -n "1%100%100%performance" > /proc/cpufreq
+ sets the CPU #1 to the highest supported frequency.
+
[email protected]:#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:
+
[email protected]:# cat /proc/sys/cpu/0/speed-min > /proc/sys/cpu/0/speed
[email protected]:# 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:
+ void 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.
+
+cpufreq_setpolicy_t setpolicy: This is a pointer to a function with
+ the following definition:
+ void 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[0].max_cpu_freq must contain the
+ absolute maximum CPU frequency supported by _all_ CPUs.
+
+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;
+ unsigned int cpu_cur_freq[NR_CPUS];
+#endif
+ with cpu_min_freq being the minimum CPU frequency supported by
+ the CPUs; 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
+* 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.
+* Be aware that there is currently no error management in the
+ setpolicy() code in the CPUFreq core. So only call yourself a
+ cpufreq_driver if you are really a working cpufreq_driver!
+
+
+
+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 [email protected]http://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/
diff -ruN linux-2539original/MAINTAINERS linux/MAINTAINERS
--- linux-2539original/MAINTAINERS Sun Sep 22 09:00:00 2002
+++ linux/MAINTAINERS Sat Sep 28 09:30:00 2002
@@ -364,6 +364,11 @@
W: http://www.fi.muni.cz/~kas/cosa/
S: Maintained

+CPU FREQUENCY DRIVERS
+L: [email protected]http://www.linux.org.uk
+W: http://www.brodo.de/cpufreq/
+S: Maintained
+
CPUID/MSR DRIVER
P: H. Peter Anvin
M: [email protected]
diff -ruN linux-2539original/arch/i386/Config.help linux/arch/i386/Config.help
--- linux-2539original/arch/i386/Config.help Sun Sep 22 09:30:00 2002
+++ linux/arch/i386/Config.help Sat Sep 28 09:30:00 2002
@@ -839,7 +839,71 @@
CONFIG_X86_MCE_P4THERMAL
Enabling this feature will cause a message to be printed when the P4
enters thermal throttling.
-
+
+CONFIG_CPU_FREQ
+ Clock scaling allows you to change the clock speed of CPUs on the
+ fly. This is a nice method to save battery power on notebooks,
+ because the lower the clock speed, the less power the CPU consumes.
+
+ For more information, take a look at linux/Documentation/cpufreq or
+ at <http://www.brodo.de/cpufreq/>
+
+ If in doubt, say N.
+
+CONFIG_X86_POWERNOW_K6
+ This adds the CPUFreq driver for mobile AMD K6-2+ and mobile
+ AMD K6-3+ processors.
+
+ For details, take a look at linux/Documentation/cpufreq.
+
+ If in doubt, say N.
+
+CONFIG_X86_P4_CLOCKMOD
+ This adds the CPUFreq driver for Intel Pentium 4 / XEON
+ processors.
+
+ For details, take a look at linux/Documentation/cpufreq.
+
+ If in doubt, say N.
+
+CONFIG_ELAN_CPUFREQ
+ This adds the CPUFreq driver for AMD Elan SC400 and SC410
+ processors.
+
+ You need to specify the processor maximum speed as boot
+ parameter: elanfreq=maxspeed (in kHz) or as module
+ parameter "max_freq".
+
+ For details, take a look at linux/Documentation/cpufreq.
+
+ If in doubt, say N.
+
+CONFIG_X86_LONGHAUL
+ This adds the CPUFreq driver for VIA Samuel/CyrixIII,
+ VIA Cyrix Samuel/C3, VIA Cyrix Ezra and VIA Cyrix Ezra-T
+ processors.
+
+ For details, take a look at linux/Documentation/cpufreq.
+
+ If in doubt, say N.
+
+CONFIG_X86_SPEEDSTEP
+ This adds the CPUFreq driver for certain mobile Intel Pentium III
+ (Coppermine), all mobile Intel Pentium III-M (Tulatin) and all
+ mobile Intel Pentium 4 P4-Ms.
+
+ For details, take a look at linux/Documentation/cpufreq.
+
+ If in doubt, say N.
+
+CONFIG_X86_LONGRUN
+ This adds the CPUFreq driver for Transmeta Crusoe processors which
+ support LongRun.
+
+ For details, take a look at linux/Documentation/cpufreq.
+
+ If in doubt, say N.
+
CONFIG_TOSHIBA
This adds a driver to safely access the System Management Mode of
the CPU on Toshiba portables with a genuine Toshiba BIOS. It does


2002-10-01 22:21:43

by Pavel Machek

[permalink] [raw]
Subject: Re: [2.5.39] (4/5) CPUfreq Documentation

Hi!

> +--
> + minimum CPU frequency - maximum CPU frequency - policy
> +CPU 0 1200000 ( 75%) - 1600000 (100%) - performance
> +--

Ugh, another interce that tries to look nice, this time with "-" as
separator.... Ugly, ugly. Whats wrong with one-value-per-file?!

Pavel

--
Philips Velo 1: 1"x4"x8", 300gram, 60, 12MB, 40bogomips, linux, mutt,
details at http://atrey.karlin.mff.cuni.cz/~pavel/velo/index.html.