Add README.html and lo_graph_example.png

1 files changed, 115 insertions, 0 deletions

diff --git a/README.html b/README.html
new file mode 100644
index 0000000..494a75d
--- /dev/null
+++ b/README.html
@@ -0,0 +1,115 @@
+<h1>cputemp2maxfreq</h1>
+<p>
+ This daemon sets the cpufreq scale_max_freq setting and scales it down when
+ the CPU reaches a given temperature.
+</p>
+<h2>Why this program?</h2>
+<p>
+ I recently bought a new mainboard, an <a href="https://www.asrock.com/mb/Intel/J5040-ITX/">Asrock J5040-ITX</a>.
+ This board has a passively cooled CPU which means heat can build up when you
+ give it a GPU or CPU intensive task. It will happily heat itself up to over
+ 95&deg;C, and since i'm a Gentoo user, that happens quite a lot :-). I thought
+ it's wasn't a good idea to leave it running for hours at 95&deg;C. One
+ solution could be to add a small fan, but I hate fans and that's why i got a
+ fanless mainboard in the first place. The other solution is to reduce CPU heat
+ generation when the temperature is too high, and the best way to do that is to
+ reduce it's frequency as can be done with cpufreq within linux.<br>
+ When discovered there is no program to do that i deciced to write it myself.
+</p>
+<h2>What does this program do?</h2>
+<p>
+ It's basic function is simple: It reads the CPU's temperature sensor and if
+ the temperature is above a certain threshold it will lower scale_max_freq to
+ lower the CPU speed and allow it to cool down. When the temperature drops
+ below the threshold it will increase scalea_max_freq again to allow it to
+ reach it's full speed.
+</p>
+<p>
+ There is a lot you can tune and do with this basic function, these are the
+ options you can pass to cputemp2maxfreq:
+</p>
+<ul>
+ <li><strong>-c or -C</strong> will log data to a CSV file which can be used
+     for analysis later. See the paragraph below on how to use it with
+     LibreOffice. -c will append data, -C will overwrite an existing file</li>
+ <li><strong>-f</strong> sets the fallback frequency. In case something goes
+     wrongthe program sets the CPU frequency to it's minimum. In case that
+     fails too it will try the fallback frequency</li>
+ <li><strong>-g</strong> the cpufreq governor to use. Conservative seems to work
+     nicely with this daemon's concept. Use the special keyword
+     &quot;keep&quot; to prevent this daemon from changing the governor</li>
+ <li><strong>-i</strong> set the file for CPU temperature readout. Most sensors
+     should be available in sysfs somewhere</li>
+ <li><strong>-l</strong> set the logging mechanism to use. Possible values:
+  <ul>
+   <li><strong>none</strong>: No logging at all</li>
+   <li><strong>kmsg</strong>: Log to the kernel log so you can see it with dmesg</li>
+   <li><strong>stdout</strong>: Log to stdout, especially useful when testing/tuning</li>
+   <li><strong>syslog</strong>: Log to syslog, it will use facility Daemon and level Critical</li>
+  </ul></li>
+ <li><strong>-m</strong> log measurements (CPU temperature and frequency)</li>
+ <li><strong>-p</strong> set poll interval</li>
+ <li><strong>-s</strong> set the step size to increase/decrease CPU speed.
+     Note that this value will be multiplied by the difference between the CPU
+     temperature and the set temperature to calculate the actual change.</li>
+ <li><strong>-t</strong> set the temperature limit</li>
+</ul>
+<p>
+ To use the CSV file with libreOffice first stop the daemon to make sure all
+ data has been written. Then use LibreOffice Calc to open the CSV file. In the
+ text import dialog use the following options:
+</p>
+<ul>
+ <li>Separated by Comma</li>
+ <li>String delimited: &quot;</li>
+ <li>Other options: Only set Detect special numbers, other options should be disabled</li>
+</ul>
+<p>
+ The preview should already show a nicely formed table, so click Ok.
+</p>
+<p>
+ If the document is opened read-only, click the Edit Document button. Select
+ the whole sheet, open the Insert menu and choose Chart...
+</p>
+<p>
+ Now select Chart Type XY (Scatter) and subtype Lines Only and click Finish.
+</p>
+<p>
+ You should now have a graph and depending on the number of data points it
+ might beusefull to make it wider to give the graph some more space. Becaue
+ the CPU temperatures are much lower numbers than the frequencies it's useful
+ to add a second Y axis, to do so click on the background and choose
+ Insert/Delete axes and enable the secondary Y axis. Now click the first
+ temperature line (usually at the bottom of the chart) and choose Format Data
+ Series, and set Allign Data Series to Secondary Y axis. Do the same for the
+ second temperature line.
+</p>
+<p>The resulting graph should look like this:</p>
+<img src="lo_graph_example.png">
+<p>
+ You can clearly see the scaling this daemon does between 12:37:26 and 12:40:19.
+</p>
+<h2>How to install this program</h2>
+<p>
+ Since i'm a Gentoo user i made an ebuild provided in the gentoo directory of
+ the source code. Place it in your own overlay to use it, the suggested
+ category is sys-power. The ebuild will install the binary in /usr/sbin and
+ install an initscript so you can start the daemon on boot.
+</p>
+<p>
+ To install from source manually the best way is to <strong>git clone
+ https://code.pa4wdh.nl.eu.org/tools/cputemp2maxfreq</strong>. Change to the
+ source directory and type <strong>make</strong> to start the build proces. It
+ shouldn't take long since this is a very small program. The result should
+ be an executable called cputemp2maxfreq.
+</p>
+<h2>What can i do with this program?</h2>
+<p>
+ The daemon has two uses: Get the maximum performance from your CPU when the
+ temperature allows it, and protect the hardware from overheating.
+</p>
+<p>
+ Since i'm a Gentoo user there is a topic about this program on thei
+ <a href="https://forums.gentoo.org/viewtopic-t-1163405.html">Gentoo forums</a>.
+</p>
+<p>Happy computing!</p>