[linux-2.6-block.git] / Documentation / cpu-freq / user-guide.txt

     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 and ARM64
1.2 x86
1.3 sparc64
1.4 ppc
1.5 SuperH
1.6 Blackfin

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


1. Supported Architectures and Processors
=========================================

1.1 ARM and ARM64
-----------------

Almost all ARM and ARM64 platforms support CPU frequency scaling.

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+
AMD mobile Duron
AMD mobile Athlon
AMD Opteron
AMD Athlon 64
Cyrix Media GXm
Intel mobile PIII and Intel mobile PIII-M on certain chipsets
Intel Pentium 4, Intel Xeon
Intel Pentium M (Centrino)
National Semiconductors Geode GX
Transmeta Crusoe
Transmeta Efficeon
VIA Cyrix 3 / C3
various processors on some ACPI 2.0-compatible systems [*]
And many more

[*] 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


1.4 ppc
-------

Several "PowerBook" and "iBook2" notebooks are supported.
The following POWER processors are supported in powernv mode:
POWER8
POWER9

1.5 SuperH
----------

All SuperH processors supporting rate rounding through the clock
framework are supported by cpufreq.

1.6 Blackfin
------------

The following Blackfin processors are supported by cpufreq:

BF522, BF523, BF524, BF525, BF526, BF527, Rev 0.1 or higher
BF531, BF532, BF533, Rev 0.3 or higher
BF534, BF536, BF537, Rev 0.2 or higher
BF561, Rev 0.3 or higher
BF542, BF544, BF547, BF548, BF549, Rev 0.1 or higher


2. "Policy" / "Governor" ?
==========================

Some CPU frequency scaling-capable processor switch between various
frequencies and operating voltages "on the fly" without any kernel or
user involvement. This guarantees 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 available 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 a subdirectory
"cpufreq" within the cpu-device directory
(e.g. /sys/devices/system/cpu/cpu0/cpufreq/ for the first CPU).

affected_cpus :			List of Online CPUs that require software
				coordination of frequency.

cpuinfo_cur_freq :		Current frequency of the CPU as obtained from
				the hardware, in KHz. This is the frequency
				the CPU actually runs at.

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) 

cpuinfo_transition_latency	The time it takes on this CPU to
				switch between two frequencies in nano
				seconds. If unknown or known to be
				that high that the driver does not
				work with the ondemand governor, -1
				(CPUFREQ_ETERNAL) will be returned.
				Using this information can be useful
				to choose an appropriate polling
				frequency for a kernel governor or
				userspace daemon. Make sure to not
				switch the frequency too often
				resulting in performance loss.

related_cpus :			List of Online + Offline CPUs that need software
				coordination of frequency.

scaling_available_frequencies : List of available frequencies, in KHz.

scaling_available_governors :	this file shows the CPUfreq governors
				available in this kernel. You can see the
				currently activated governor in

scaling_cur_freq :		Current frequency of the CPU as determined by
				the governor and cpufreq core, in KHz. This is
				the frequency the kernel thinks the CPU runs
				at.

scaling_driver :		this file shows what cpufreq driver is
				used to set the frequency on this CPU

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.
				NOTE: when setting a policy you need to
				first set scaling_max_freq, then
				scaling_min_freq.

scaling_setspeed		This can be read to get the currently programmed
				value by the governor. This can be written to
				change the current frequency for a group of
				CPUs, represented by a policy. This is supported
				currently only by the userspace governor.

bios_limit :			If the BIOS tells the OS to limit a CPU to
				lower frequencies, the user can read out the
				maximum available frequency from this file.
				This typically can happen through (often not
				intended) BIOS settings, restrictions
				triggered through a service processor or other
				BIOS/HW based implementations.
				This does not cover thermal ACPI limitations
				which can be detected through the generic
				thermal driver.

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.
Commit	Line	Data
1da177e4 LT	1	CPU frequency and voltage scaling code in the Linux(TM) kernel
	2
	3
	4	L i n u x C P U F r e q
	5
	6	U S E R G U I D E
	7
	8
	9	Dominik Brodowski <linux@brodo.de>
	10
	11
	12
	13	Clock scaling allows you to change the clock speed of the CPUs on the
	14	fly. This is a nice method to save battery power, because the lower
	15	the clock speed, the less power the CPU consumes.
	16
	17
	18	Contents:
	19	---------
	20	1. Supported Architectures and Processors
7de962c0	21	1.1 ARM and ARM64
1da177e4 LT	22	1.2 x86
	23	1.3 sparc64
	24	1.4 ppc
	25	1.5 SuperH
121fe86b	26	1.6 Blackfin
1da177e4 LT	27
	28	2. "Policy" / "Governor"?
	29	2.1 Policy
	30	2.2 Governor
	31
	32	3. How to change the CPU cpufreq policy and/or speed
	33	3.1 Preferred interface: sysfs
1da177e4 LT	34
	35
	36
	37	1. Supported Architectures and Processors
	38	=========================================
	39
7de962c0 VK	40	1.1 ARM and ARM64
7de962c0 VK	41	-----------------
1da177e4	42
7de962c0	43	Almost all ARM and ARM64 platforms support CPU frequency scaling.
1da177e4 LT	44
	45	1.2 x86
	46	-------
	47
	48	The following processors for the x86 architecture are supported by cpufreq:
	49
	50	AMD Elan - SC400, SC410
	51	AMD mobile K6-2+
	52	AMD mobile K6-3+
	53	AMD mobile Duron
	54	AMD mobile Athlon
	55	AMD Opteron
	56	AMD Athlon 64
	57	Cyrix Media GXm
	58	Intel mobile PIII and Intel mobile PIII-M on certain chipsets
	59	Intel Pentium 4, Intel Xeon
	60	Intel Pentium M (Centrino)
	61	National Semiconductors Geode GX
	62	Transmeta Crusoe
	63	Transmeta Efficeon
	64	VIA Cyrix 3 / C3
	65	various processors on some ACPI 2.0-compatible systems [*]
7de962c0	66	And many more
1da177e4 LT	67
	68	[*] Only if "ACPI Processor Performance States" are available
	69	to the ACPI<->BIOS interface.
	70
	71
	72	1.3 sparc64
	73	-----------
	74
	75	The following processors for the sparc64 architecture are supported by
	76	cpufreq:
	77
	78	UltraSPARC-III
	79
	80
	81	1.4 ppc
	82	-------
	83
	84	Several "PowerBook" and "iBook2" notebooks are supported.
843e4d1e SB	85	The following POWER processors are supported in powernv mode:
	86	POWER8
	87	POWER9
1da177e4 LT	88
	89	1.5 SuperH
	90	----------
	91
8a655053 PM	92	All SuperH processors supporting rate rounding through the clock
8a655053 PM	93	framework are supported by cpufreq.
1da177e4	94
121fe86b RG	95	1.6 Blackfin
	96	------------
	97
	98	The following Blackfin processors are supported by cpufreq:
	99
	100	BF522, BF523, BF524, BF525, BF526, BF527, Rev 0.1 or higher
	101	BF531, BF532, BF533, Rev 0.3 or higher
	102	BF534, BF536, BF537, Rev 0.2 or higher
	103	BF561, Rev 0.3 or higher
	104	BF542, BF544, BF547, BF548, BF549, Rev 0.1 or higher
	105
1da177e4 LT	106
	107	2. "Policy" / "Governor" ?
	108	==========================
	109
	110	Some CPU frequency scaling-capable processor switch between various
	111	frequencies and operating voltages "on the fly" without any kernel or
	112	user involvement. This guarantees very fast switching to a frequency
	113	which is high enough to serve the user's needs, but low enough to save
	114	power.
	115
	116
	117	2.1 Policy
	118	----------
	119
	120	On these systems, all you can do is select the lower and upper
	121	frequency limit as well as whether you want more aggressive
	122	power-saving or more instantly available processing power.
	123
	124
	125	2.2 Governor
	126	------------
	127
	128	On all other cpufreq implementations, these boundaries still need to
	129	be set. Then, a "governor" must be selected. Such a "governor" decides
	130	what speed the processor shall run within the boundaries. One such
	131	"governor" is the "userspace" governor. This one allows the user - or
	132	a yet-to-implement userspace program - to decide what specific speed
	133	the processor shall run at.
	134
	135
	136	3. How to change the CPU cpufreq policy and/or speed
	137	====================================================
	138
	139	3.1 Preferred Interface: sysfs
	140	------------------------------
	141
	142	The preferred interface is located in the sysfs filesystem. If you
	143	mounted it at /sys, the cpufreq interface is located in a subdirectory
	144	"cpufreq" within the cpu-device directory
	145	(e.g. /sys/devices/system/cpu/cpu0/cpufreq/ for the first CPU).
	146
7de962c0 VK	147	affected_cpus : List of Online CPUs that require software
	148	coordination of frequency.
	149
	150	cpuinfo_cur_freq : Current frequency of the CPU as obtained from
	151	the hardware, in KHz. This is the frequency
	152	the CPU actually runs at.
	153
1da177e4 LT	154	cpuinfo_min_freq : this file shows the minimum operating
1da177e4 LT	155	frequency the processor can run at(in kHz)
7de962c0	156
1da177e4 LT	157	cpuinfo_max_freq : this file shows the maximum operating
1da177e4 LT	158	frequency the processor can run at(in kHz)
7de962c0	159
ed129784 TR	160	cpuinfo_transition_latency The time it takes on this CPU to
	161	switch between two frequencies in nano
	162	seconds. If unknown or known to be
	163	that high that the driver does not
	164	work with the ondemand governor, -1
	165	(CPUFREQ_ETERNAL) will be returned.
	166	Using this information can be useful
	167	to choose an appropriate polling
	168	frequency for a kernel governor or
	169	userspace daemon. Make sure to not
	170	switch the frequency too often
	171	resulting in performance loss.
7de962c0 VK	172
	173	related_cpus : List of Online + Offline CPUs that need software
	174	coordination of frequency.
	175
	176	scaling_available_frequencies : List of available frequencies, in KHz.
1da177e4 LT	177
	178	scaling_available_governors : this file shows the CPUfreq governors
	179	available in this kernel. You can see the
	180	currently activated governor in
	181
7de962c0 VK	182	scaling_cur_freq : Current frequency of the CPU as determined by
	183	the governor and cpufreq core, in KHz. This is
	184	the frequency the kernel thinks the CPU runs
	185	at.
	186
	187	scaling_driver : this file shows what cpufreq driver is
	188	used to set the frequency on this CPU
	189
1da177e4 LT	190	scaling_governor, and by "echoing" the name of another
	191	governor you can change it. Please note
	192	that some governors won't load - they only
	193	work on some specific architectures or
	194	processors.
605400a8	195
9c9a43ed	196	scaling_min_freq and
1da177e4 LT	197	scaling_max_freq show the current "policy limits" (in
	198	kHz). By echoing new values into these
	199	files, you can change these limits.
9c9a43ed MD	200	NOTE: when setting a policy you need to
	201	first set scaling_max_freq, then
	202	scaling_min_freq.
1da177e4	203
7de962c0 VK	204	scaling_setspeed This can be read to get the currently programmed
	205	value by the governor. This can be written to
	206	change the current frequency for a group of
	207	CPUs, represented by a policy. This is supported
	208	currently only by the userspace governor.
1da177e4	209
e2f74f35 TR	210	bios_limit : If the BIOS tells the OS to limit a CPU to
	211	lower frequencies, the user can read out the
	212	maximum available frequency from this file.
	213	This typically can happen through (often not
	214	intended) BIOS settings, restrictions
	215	triggered through a service processor or other
	216	BIOS/HW based implementations.
	217	This does not cover thermal ACPI limitations
	218	which can be detected through the generic
	219	thermal driver.
	220
1da177e4 LT	221	If you have selected the "userspace" governor which allows you to
	222	set the CPU operating frequency to a specific value, you can read out
	223	the current frequency in
	224
	225	scaling_setspeed. By "echoing" a new frequency into this
	226	you can change the speed of the CPU,
	227	but only within the limits of
	228	scaling_min_freq and scaling_max_freq.