path: root/cputemp2maxfreq.8

.TH cputemp2maxfreq 8 "2024-08-24"
.SH NAME
cputemp2maxfreq \- Daemon to scale scale_max_freq down as CPU temperature rises
.SH SYNOPSIS
.B cputemp2maxfreq
[\fIOPTION\fR]...
.SH DESCRIPTION
Set the \fBscale_max_freq\fR of a CPU to a lower value as the CPU temperature rises. This effectively keeps the CPU cooler than it would be without. This allows passive cooling for low-power systems or helps to keep the fan noise of temperature controlled fans lower.
.sp
To do this the program periodically reads the temperature sensor of your CPU and makes changes to the \fBcpufreq\fR settings. It also has some logging facilities to get a sense of what's going on while it's running.
.SH OPTIONS
Scaling options:
.sp
\fB\-d\fP \fIdelay\fP
.RS 4
Set the transition latency in us or use the "auto" for autodetect, defauls to \fBauto\fR. Valid values are 0...100000.
.sp
The transition delay is the time it takes to adapt to new \fBcpufreq\fR settings. As a safety measure, when the program sets a new value it verifies if it succeeded by reading it again and expecting to read the value it has just set. To do this it has to wait for the transition delay. For most CPU's this autodetection will work, but if the program exists because it fails to set some value there is a good chance the transition delay needs to be set manually. A good value to start with is 50000, increase by 10000 until it's stable.
.RE
.sp
\fB-f\fP \fIfrequency\fP
.RS 4
Set fallback frequency in KHz, defaults to \fB2000000\fR (2GHz).
.sp
As a safety measure the program tries to set the CPU to it's lowest frequency when it exits. What that fails it's next try is the fallback frequency.
.RE
.sp
\fB-g\fP \fIgovernor\fP
.RS 4
Set the cpufreq governor to use, use "keep" to keep current governor. Defauls to \fBconservative\fR.
.sp
Any governor is allowed as long as it's available in your kernel. The conservative governor seems to play nice with the function of this program. The actual CPU frequecy is changed depending on the load on the system. If the CPU heats up to much, this program will take action to make sure it stays within limits. Once the load disappears the CPU frequency is lowered by the governor and allows the CPU to cool down, and this program allows the CPU to reach higher clocks as long as temperatures allow it.
.RE
.sp
\fB-i\fP \fIsensor\fR
.RS 4
Set the input file for the temperature readout. This can be specified as a full path to a file (starting with /), as a sensor name or as "auto" for autodetection. For more information see the \fBSELECTING THE RIGHT SENSOR\fR section for more information.
.RE
.sp
\fB-k\fP
.RS 4
Without this option the CPU frequency is set to it's lowest speed on exit of this program. With this option (short for keep) it keeps the latest state on normal exit. On error the CPU frequency is still set to it's lowest speed.
.RE
.sp
\fB-p\fP \fItime\fR
.RS 4
Time between two polls in seconds, defaults to \fB10\fR.
.RE
.sp
\fB-P\fP \fICPU ID\fR
.RS 4
Physical CPU number to control, this is intended for multi-CPU systems (systems with more than one physical CPU on the motherboard, it is not needed for multi-core systems). This option accepts a number for or "all" for all CPU's and defaults to \fBall\fR. For more information see the \fBMULTI CPU SYSTEMS\fR section for more information. 
.RE
.sp
\fB-s\fP \fIstep\fR
.RS 4
Sets the step size in KHz when changing the CPU's maximum allowed frequency and defaults to \fB100000\fR KHz (100MHz). The actual step size is calculated as the temperature difference from the target temperature multiplied by this step size.
.RE
.sp
\fB-t\fP \fItemperature\fR
.RS 4
Sets the target temperature, defaults to \fB70\fR degrees celsius. Above this temperature the maximum CPU frequency will be decreased, below this temperature the maximum CPU frequency increased. Be aware it that it is a \fItarget\fR temperature, not a maximum, so your CPU will have to heat up above this before action is taken.
.RE
.PP
Logging options:
.sp
\fB-c\fP \fIfile\fR
.RS 4
Write a CSV file called \fIfile\fR for later analysis, append data if the file already exists.
.RE
.sp
\fB-C\fP \fIfile\fR
.RS 4
Same as \fB-c\fR but overwrite an existing file.
.sp
.RE
\fB-l\fP \fIlogger\fR
.RS 4
Type of logging to use, valid values are: \fBnone\fR, \fBkmesg\fR, \fBstdout\fR and \fBsyslog\fR, defaults to \fBstdout\fR.
.RS 4
\fBnone\fR does not log at all
.sp
\fBkmesg\fR will log to the kernel buffer, readable via \fBdmesg(1)\fR
.sp
\fBstdout\fR will log to stdout, so output will appear on your terminal
.sp
\fBsyslog\fR will log to a syslog daemon, where it will appear depends on the syslog daemon configuration
.RE
.RE
\fB-m\fR
.RS 4
Log measurements (CPU temperature and frequency) via logger
.RE
\fB-u\fR
.RS 4
Use unixtime timestamps in logs and CSV. When not set de detault is to use timestamp format \fBYYYY-MM-DD HH:MM:SS\fR.
.RE
.PP
Other options:
.sp
\fB-h\fR
.RS 4
Display a help text with a short description of all the options.
.RE
.sp
\fB-v\fR
.RS 4
Display version and license information.
.RE
.SH SELECTING THE RIGHT SENSOR
In most cases the sensor autodetection should deliver usable results. If it doesn't you can either select a sensor by it's name or by the full path to it's readout file (usually somewhere in \fBsysfs(5)\fR). Most sensors can be found under \fB/sys/class/hwmon\fR. For most sensors there is a file called \fBtemp\fIX\fB_label\fR which can be used for identification. If this is usable, selecting the sensor by it's name is preferred over selecting it by filename as the filename could change with system changes or reboots.
.sp
If you think you found a useful sensor, read it's value repeatedly and vary the load on the system. If you need a command to increase the load without actually doing anything useful use: \fBdd if=/dev/urandom of=/dev/null bs=1024k\fR. This will generate random data (which is very CPU intensive) and discard the data. Start it as many times as you have CPU cores in your computer to have a greater effect. Now look at your sensor data, the temperature should rise quickly after starting those commands. If that's happening, this is the right sensor to use. If it doesn't, stop all the load-generating commands and go to the next sensor.
.SH MULTI CPU SYSTEMS
In multi-CPU systems the CPU's can have different workloads (and this different temperatures) and different frequencies. In order to facilitate this, the \fB-P\fR is used to select the CPU to control. This means you'll have to run a separate instance of this program for every CPU. In this way you can select the right sensor (\fB-i\fR) and the right CPU (\fB-P\fR) together to get the desired result.
.sp
When the \fB-P\fR option is used, a sensor called \fBPackage id <CPU number>\fR is automatically added to the autodetection list. This will work fine for most Intel based systems. For AMD based systems the situation is a but more difficult as the \fBk10temp\fR kernel module is loaded for every CPU and there is no automatic way to know which belong together.
.SH SEE ALSO
\fBsysfs(5)\fR
.sp
\fIDocumentation/admin-guide/pm/cpufreq.rst\fR in the Linux kernel source tree contains useful information about \fBcpufreq\fR which is used to set the CPU's speed limits.
.sp
Souce code of this program can be found at:
.br
\fBhttps://code.pa4wdh.nl.eu.org/tools/cputemp2maxfreq/\fR
.sp
Discussion can be found here:
.br
\fBhttps://forums.gentoo.org/viewtopic-t-1163405.html\fR