CPUClock
========

Temperature control version
+++++++++++++++++++++++++++

Important: CPUClock is only of use on modern hardware that is capable
of switching the CPU between two or more speed settings. This means
hardware such as the OMAP3, OMAP4, or OMAP5.

When run, CPUClock, the GUI frontend and/or the module, makes some
checks on the OS and hardware. If the hardware is unsuitable, CPUClock
will not run. If the OS is an old version, then CPUClock may run, but
some of the functionality may be disabled.

Background
----------
The following description uses extracts from a post by Jeffrey Lee in
the ROOL forum (with permission).

RISC OS does several things to control the speed of the CPU:

There is the CPU clock driver sitting in the HAL. This allows the
Portable module to change the clock speed between a number of preset
settings (referred to as "OPP"s in TIs docs). Each OPP defines a
clock speed and core voltage. Although the hardware is capable of
using arbitrary clock speeds and voltages, TIs docs suggest that
sticking to the standard OPPs is the best in terms of reducing
heat/power drain. On BB-xM the clock driver also makes use of
SmartReflex, which allows the hardware to fine-tune the core voltage
in real time, typically resulting in a lower voltage being used than
that specified by the OPP.

In terms of how this all hooks into RISC OS, Portable_Speed, which is
the original speed control SWI that was used by the A4, is used to
select between preselected fast and slow speeds. Portable_Speed2
is a new SWI which allows the available speeds to be enumerated, and
selection of which speed is the fast one and which is the slow one. By
default the fastest speed (1GHz for xM, 620/700MHz for BB) is chosen
as the fast one and the slowest speed (300MHz for xM, 125MHz? for
BB) is chosen as the slow one. The main user of Portable_Speed is
the Wimp, which will switch the CPU to the slow speed if it thinks the
machine is idle.

The Portable module also provides wait-for-idle functionality
(Portable_Idle), which allows the CPU to be put to sleep until the
next interrupt. Portable_Idle is a new SWI that was added for the
Stork, and due to the cancellation of the project it probably isnt
being used in all the places that it could be. However the Wimp does
know how to use it, as well as a couple of other places (e.g. OS_Byte
19 & OS_ReadC), so if youre sat idling in the desktop the machine
should spend most of its time with the CPU halted.

If you want to force the CPU to run at a particular speed, the
recommended way is to use Portable_Speed2 to set the slow & fast
speeds to the desired values. There is nothing in the OS that will
override these settings.

Installation
------------
For a new installation, simply drag and drop the CPUClock application
into the directory of your choice.

If you have a previous copy of CPUClock you should move the old
version of CPUClock somewhere safe and replace it with the new
version.

Basic operation
---------------
Version 2 of CPUClock operates in the following way.

* It monitors and displays the current CPU clock speed
* It monitors and displays the CPU die temperature
* It can reduce the cpu clock speed if the cpu temperature exceeds a
  user defined limit, and revert to the fast speed when the
  temperature falls within the set limits

To run the application, double click on it's icon in a filer window.
This will load the GUI front end onto the iconbar. It will also load
the CPUClock module (if not already active). It is this module that
monitors the cpu temperature, and adjusts the cpu clock speed if
necessary. A module is used for this since it remains active even if
the wimp enters a single-tasking state when e.g. a task stops polling
during a processor intensive operation.

The iconbar icon will show the cpu clock speed as the OS switches
between fast and slow, as shown below for a PandaBoard-ES. There is
also a user option to include a coloured status indication of the cpu
temperature in the iconbar icon. See the description of options in
choices below.

Clicking on the iconbar icon with Select (or using the iconbar menu)
will open the status window, which will show the cpu speed, the
temperature, and will allow changing the fast (and slow) speed
setting, although there is little to be gained by increasing the slow
speed. More details are given below.

CPU speed only operation
------------------------
If CPUClock finds the OS does not support all the functions required
for measurement of temperature and auto-control of cpu temperature and
clock speed, then it may revert to simply displaying the cpu clock
speed (see below). In this case it may be more useful to revert to
using version 1.10 of CPUClock instead. See the page on versions.

The Iconbar Menu
++++++++++++++++

Info
----
A standard application info box, including a button to go to the web
site to check for later versions.

Help...
-------
Runs the help file (this one).

Module info
-----------
Following this option right brings up a small window showing the
current setup of the CPUClock module. This should correspond to the
choices settings in the CPUClock frontend, if nothing else has changed
the settings.

Status...
---------
Opens the CPU clock speed status window (see below). Clicking on the
iconbar icon with Select will also open the CPU status window.

Choices...
----------
This opens the application choices window (see below). The choices
window can also be opened by a right click on the iconbar icon.

Statistics
----------
Following this option right brings up a submenu with the following
options.

Save data
~~~~~~~~~
This option will download the stored statistical data from the
CPUClock module, and save it as specified in the Statistics tab of the
Choices window.

Clear data
~~~~~~~~~~
This will clear all the statistical data, resetting all the
accumulated data values to zero. The storing of the data will then
restart.

Open directory
~~~~~~~~~~~~~~
The saved data files are located within the Stats directory in the
CPUClock application directory. This option will open the directory to
ease access to the saved data files.

Quit
----
This terminates the frontend application immediately, but leaves the
module active. In addition, following the submenu arrow right leads to
a menu with two options. Frontend only will terminate the GUI
application. Selecting Module also will terminate the frontend and
RMKill the module. Terminating just the GUI frontend means that the
module will remain active and continue to operate in the background,
monitoring the cpu die temperature, and reducing the cpu clock speed
if the temperature exceeds the set value.

The Choices... dialogue
+++++++++++++++++++++++

The choices dialogue has a set of action buttons at the bottom of the
window.

The actions available are:

Set
---
This will use the new settings with immediate effect, and they will be
used until CPUClock is quit.

Save
----
This will use the new settings, as in Set above, and will also save
the settings to disc, so they will be used when CPUClock is run in the
future.

Cancel
------
Close the dialogue and ignore any changes made since it was opened.

At the top of the window are three tabs, labelled Application,  Module
and Statistics. The first two sections control the application and
module specific settings, the third tab settings apply to both the
module and the front end.

The settings that can be changed are as follows.

Application
-----------

Poll idle delay/cs
~~~~~~~~~~~~~~~~~~
CPUClock checks the current speed of the cpu periodically, and writes
the value under the iconbar icon, and in to the status window if it is
open. The delay between checks can be adjusted using the bump arrors
at the right. The value is in centiseconds. The default delay is 100cs
(1s). Long delays may miss short bursts of cpu activity, while short
delays may actually load the cpu. The temperatures of the cpu and the
case (if applicable) are updated at the same time.

Iconbar icon at right
~~~~~~~~~~~~~~~~~~~~~
When an application installs an icon on the iconbar, by default it is
installed at the left end of the right hand side icons. Thus the
position is variable. If you wish to keep an eye on the cpu speed, it
might be useful to have the iconbar icon in a relatively constant
position. If this is ticked, then the iconbar icon will be installed
to the right of the normal application icons (some applications have a
high priority for positioning, e.g. the task or display managers, and
CPUClock does not install to the right of these). Note that CPUClock
will need to be quit and restarted before the change will take place.
You will be offered the option of restarting immediately, or waiting.

Open status on launch
~~~~~~~~~~~~~~~~~~~~~
If this is ticked, then CPUClock will open the status window whenever
it is first loaded. The position at which it will be opened can be set
by moving the status window to the position of your choice, then
ticking the option Save position now. If choices are now saved, the
current position of the status window will be saved as well. The
requirement to tick this option means that the setting is not changed
when choices are saved at other times, unless a new position is
specifically set. Note that the status window will always be opened at
the smaller size.

The CPUClock iconbar icon, by default, shows the cpu clock speed as it
changes with cpu load. CPUClock can also give a colour coded
indication of the cpu temperature status. The next section controls
what form this indication takes.

Show colour-coded status
~~~~~~~~~~~~~~~~~~~~~~~~
This turns the colour coding on. The colour is shown either as a
background to the text under the iconbar icon or as a background to
the whole icon. This is set by the two radio icons, Text background
and Whole icon. A further option Show low temperature as green toggles
between a green background or no background for the low temperature
condition.
			

Module
------

The module settings are used to control the operation of the CPUClock
module.

Enable auto control
~~~~~~~~~~~~~~~~~~~
If this option is ticked then CPUClock will enable the cpu temperature
regulation in the CPUClock module. The module will reduce the fast
speed setting if the temperature exceeds the set maximum value. If it
is unticked the CPUClock frontend will simply monitor and display the
cpu speed and cpu die temperature.

If the auto speed control is enabled, then the following settings will
influence how the control will be actioned.

Maximum temperature/C
~~~~~~~~~~~~~~~~~~~~~~
This value (in C) sets the maximum cpu temperature that is allowed
before the cpu speed will be reduced. The maximum working temperature
for a particular cpu will be found in the reference manual for the
board. However, as a rough guide, 65 - 70C is probably a suitable
upper limit. 60 would be even safer for long term use.

Differential/C
~~~~~~~~~~~~~~~
This value (in C) sets the number of degrees by which the temperature
must fall below the maximum setting before the cpu speed will be
increased again. A setting of 3 or 4C is usually suitable.

Use rolling average temperature
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the temperature of the cpu die is close to the maximum temperature
setting, the short term fluctuations (always present) may trigger the
regulation. If this is felt to be a problem, the module can be set to
keep a running average of the last four temperature readings. This
smooths out the temperature fluctuations, but at the same time the
regulation operation will be slower. The default setting is for there
not to be averaging.

Statistics
----------
The statistics settings are used to control how the CPUClock module
and front end deal with producing and using the temperature
statistics.

Enable statistics production
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If this option is ticked, then the module will collect the statistics for temperature variation. The GUI front end will allow the collected data to be saved to file for subsequent viewing or analysis.

Stats accumulation time
~~~~~~~~~~~~~~~~~~~~~~~
This allows the setting of the time slot (in seconds) over which the
the cpu maximum and minimum temperatures are determined. This can be
varied in the range 5 to 60 seconds. The maximum and minimum
temperatures in each period will be recorded. These values will be
mirrored by the values shown in the status window.

This setting does not effect the collection of raw data. The raw
temperature data is collected each time the temperature is read - this
time is set in the Module tab, described above.

Statistics file format
~~~~~~~~~~~~~~~~~~~~~~
This section is used to set the file format of the data file.
Currently, there are three formats.

CSV is a simple comma separated format, which can be loaded in to
various spreadsheet type applications.

MultiPlot format allows the data to be loaded into the author's
!MultiPlot application

ChartDraw format allows the data to be loaded into the author's
!ChartDraw application

Both applications !ChartDraw and !MultiPlot can be obtained from the
author's web site (see the Contact page) or via !Store or !Packman.

The CPU clock speed status window
+++++++++++++++++++++++++++++++++

Clicking SELECT on the oconbar icon (or using the iconbar menu) will
open the Status window. This may take two forms. The default window
shows the cpu clock speed and the cpu die temperature.

However, it is possible that the board is fitted with the CJE RTC
module with temperature sensor. This sensor measures the temperature
close to the board, which will be a function of the ambient case
temperature. Assuming CPUClock has detected the presence of the board,
an additional field showing the ambient case temperature will be
present. CJE products such as the PandaRO or RapidO Ig are so fitted.
The boards can also be user fitted to a PandaBoard-ES for example.

The display will show the current cpu clock speed (switching between
the 'fast' and 'slow' speeds depending upon how hard the CPU is
working), the cpu die temperature, and the ambient case temperature if
the board is fitted with a sensor. The small coloured icon to the
right of the cpu temperature changes from green to orange to red as
the cpu temperature approaches and then exceeds the set temperature
limit (see Choices).

Note that the CPUClock front end updates the values, by default, every
1 second using wimp NULL poll-idle events. See Choices (above). If the
wimp is not multitasking at that instant, e.g. processing an image,
then the display cannot be updated. However, in general use you should
see the speed being switched between 'fast' and 'slow' as you do
things in the desktop. Note that the module will continue to get the
temperature and do any auto-controlling required in the background,
even if the front end is not being updated.

Clicking on the 'maximise' icon at the top right of the status window
title bar will extend it. It will now show some additional status
information and two additional fields, showing the configured settings
for the 'fast' and 'slow' speeds.

The additional status information summarises the temperature variation
of the cpu over the past minute of operation. This comprises the
average temperature, the maximum temperature reached, and the minimum
temperature reached. There is also an indication of the fraction of
time spent in a throttled state (expressed as a percentage). This is
updated each minute. Remember that the status window is only updated
if the wimp is issuing poll events. The statistics are done by the
module, so will still be produced if the wimp stops multitasking for a
period.

At the bottom of the window are two fields showing the configured
'Fast' and 'Slow' speeds. (Note the figure shown below is of a simpler
status window used in an earlier vesion). Clicking on the popup menu
button to the right of the 'Fast' or 'Slow' field will raise a menu
listing the allowable CPU clock speeds. Selecting one of these speeds
will reset the 'Fast' or 'Slow' setting as appropriate to this new
value. This is a 'permanent' setting in the sense that it will remain
in force until either specifically changed again, or the machine is
rebooted.

Reducing the 'Fast' speed may be beneficial in high ambient
temperature conditions. It is unlikely there will be any benefit in
raising the 'Slow' speed, since this is used when the processor is
idling.

CPU speed only mode
~~~~~~~~~~~~~~~~~~~
If CPUClock is running in cpu speed only mode, then a much simpler
status window is used. This contains a field to display the current
cpu speed, and the two popup menu buttons and associated display
fields to set the fast (and slow) cpu speeds.


Contact
+++++++
All communication about the CPUClock frontend and the CPUClock module
should be directed to Chris Johnson
(Email:chris@chris-johnson.org.uk). Suggestions for new features are
always welcome.

Web site
++++++++
Chris Johnson's web site is at
http://www.chris-johnson.org.uk/index.html, with his RISC OS software
at http://www.chris-johnson.org.uk/software/index.html.

Screenshots
+++++++++++
All the screen shots in these pages were obtained using Snapper, a
versatile screen capture application.

Snapper is available from
http://www.chris-johnson.org.uk/software/snap.html

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Versions
++++++++

There are three different versions of CPUClock, which have different
purposes, or are for specific types of hardware.

Version 2
---------
This is the latest version, in which the core functionality is now in
the CPUClock module. This means the cpu temperature monitoring and
auto- regulation of cpu clock speed will continue in the background
even if the wimp enters a non-multi-tasking mode.

This version requires RISC OS 5.23 later than Jan 10th 2016,
preferably later than Mar 10th 2016.

This version should run on OMAP3, OMAP4, IGEPv5 and Ti hardware. As of
1st Mar 2018, the latest version of the OS supplied for the iMX6
(ARMX6) does not fully support the latest API required, thus version
1.1 should be used.

Version 1.1 - Automatic CPU temperature control via CPUTmpMon
-------------------------------------------------------------
This version integrates with CPUTmpMon (which reads the CPU die
temperature) to allow the CPU speed to be moderated automatically if
the CPU temperature rises above a preset level (user choice).
Different versions of CPUTmpMon, which are required for different
hardware, are supplied within CPUClock, and the correct version should
be run by CPUClock.

This version should run on OMAP3, OMAP4, iMX6, and IGEPv5 hardware.

Configure tool version
----------------------
This is a Boot-Configuration tool version. Once installed it will
appear in Boot-Configuration (double click !Boot in the root
directory). It allows the fast (and slow) cpu speed to be set, and the
setting will be retained over a reboot or reset. This version does not
give a continuous display of cpu speed, but is intended only to set
the cpu speed - useful in hot weather to keep the cpu temperature
down.

This version should run on all hardware.

These versions can all be obtained from the web site
http://www.chris-johnson.org.uk/software/cpuclock.html


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Licence
+++++++

Copyright (c) 2012, Chris Johnson
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

CPUClock is  Chris Johnson, 2012
Email:chris@chris-johnson.org.uk
Document last modified on 1st June, 2016
