
CPUCLOCK USER GUIDE
-------------------

+image: cpuclock.png 

SYNOPSYS
--------
Cpuclock is a utility program to adjust the nominal CPU clock speed and monitor the effect on CPU power usage and temperature. Thermal throttling (CPU speed reduction to limit temperature) can also be quantified. 

+image:cpuclock2.png

REQUIRED PROGRAMS
-----------------
The following packages are required (Debian/Ubuntu package names):
xdg-utils, binutils, powerstat, linux-tools-generic

USAGE
-----
$ cpuclock

The sudo password will be requested (required to change the CPU clock). 

The power usage and temperature are sampled and shown every 3 seconds. If nothing significant is running, it shows the power usage and temperature for the idle CPU status, normally only a few watts.

Set the CPU clock speed and the number of parallel threads (1-99). You can see the impact on CPU power with the next sample. The temperature will slowly rise and approach equilibrium after a few minutes.

When the clock speed is changed, a compute loop is run in one thread for one second. Loop iterations is saved as the standard performance value for the current CPU clock speed. The actual performance is measured and displayed in the dialog window. 
Actual performance is defined as:
   (total iterations) / (sample time) / (thread count) 
                      / (standard performance) * 100
This gives a value in percent. 100% means that all threads are performing at the standard level. If there is no thermal throttling, and if the thread count is within the number of CPU P-cores, the number should be close to 100%. If E-cores are included, the number will go down to reflect the slower performance of E-cores. If the temperature is over 100°C, thermal throttling may also reduce the performance. 

EXAMPLE RESULTS   Intel Core i5 13600K
---------------
No load power usage: 3 watts.
Full load power and equilibrium temperature for selected clock speeds:
   GHz  watts   °C
   ----------------
   1.0    17    50
   2.0    31    59
   3.0    63    80
   4.0   128    99   temperature throttling active

LIMITATIONS
-----------
Cpuclock uses the programs listed below. The powerstat format was made for humans, not computers. Any future format changes would likely cause cpuclock to fail. Cpuclock may also fail for non-Intel or older processors, or for older releases of Linux. 

$ cat /sys/devices/system/cpu/cpufreq/policy1/*
$ powerstat -R
$ cpupower frequency-set -u N.NGHz

CONTACT
-------
mkornelix@gmail.com

UNINSTALL
---------
Debian package: use command: sudo apt remove cpuclock
Tarball: use command: sudo make uninstall
Binary package: delete 'cpuclock' files in $HOME/.local/* 
   

