.. include:: /keyword.rst

=====================
CPU Frequency Scaling
=====================

MediaTek IoT platform supports dynamic CPU frequency scaling to allow users to adjust CPU frequencies at
runtime to meet requirements of applications. |IOT-YOCTO| implements the driver which leverages Linux
CPUFreq framework to provide the capability. The de facto, familiar user space interfaces are provided
so that developers can use their own tools to tweak system performance.

For more information about Linux CPUFreq subsystem, please refer to
`kernel document <https://www.kernel.org/doc/html/latest/admin-guide/pm/cpufreq.html>`_ and
`Arch Linux wiki <https://wiki.archlinux.org/title/CPU_frequency_scaling>`_.

The following sections will describe `cpufreq` interface provided by |IOT-YOCTO|.

.. contents:: Sections
    :local:
    :depth: 1

`sysfs` attributes
==================
We can list content of the directory ``/sys/devices/system/cpu/cpufreq``:

.. prompt:: bash # auto

    # ls -l /sys/devices/system/cpu/cpufreq
    total 0
    drwxr-xr-x 4 root root 0 Sep 20 10:46 policy0

Where the subfolder ``policyX`` represents a policy object in `cpufreq` subsystem, which is a set
of CPUs sharing the same P-state controlling interface. In the ``policyX`` subfolder, there are
`sysfs` attributes exported:

.. prompt:: bash # auto

    # ls -l /sys/devices/system/cpu/cpufreq/policyX
    total 0
    -r--r--r-- 1 root root 4096 Sep 20 17:29 affected_cpus
    -r-------- 1 root root 4096 Sep 20 17:54 cpuinfo_cur_freq
    -r--r--r-- 1 root root 4096 Sep 20 17:54 cpuinfo_max_freq
    -r--r--r-- 1 root root 4096 Sep 20 17:54 cpuinfo_min_freq
    -r--r--r-- 1 root root 4096 Sep 20 17:54 cpuinfo_transition_latency
    -r--r--r-- 1 root root 4096 Sep 20 17:29 related_cpus
    -r--r--r-- 1 root root 4096 Sep 20 17:54 scaling_available_frequencies
    -r--r--r-- 1 root root 4096 Sep 20 17:54 scaling_available_governors
    -r--r--r-- 1 root root 4096 Sep 20 10:46 scaling_cur_freq
    -r--r--r-- 1 root root 4096 Sep 20 17:54 scaling_driver
    -rw-r--r-- 1 root root 4096 Sep 20 10:47 scaling_governor
    -rw-r--r-- 1 root root 4096 Sep 20 17:54 scaling_max_freq
    -rw-r--r-- 1 root root 4096 Sep 20 17:54 scaling_min_freq
    -rw-r--r-- 1 root root 4096 Sep 20 17:54 scaling_setspeed
    drwxr-xr-x 2 root root    0 Sep 20 17:54 schedutil
    drwxr-xr-x 2 root root    0 Sep 20 17:54 stats

To read CPUs belonging to this policy object, run the command:

.. prompt:: bash # auto

    # cat /sys/devices/system/cpu/cpufreq/policyX/related_cpus
    0 1 2 3

Note that all policy-specific operations (e.g. changing governor, setting frequencies, etc.)
affects all CPUs belonging to the same policy.

To read current CPU frequency, run the command:

.. prompt:: bash # auto

    # cat /sys/devices/system/cpu/cpufreq/policyX/scaling_cur_freq
    1308000

Note the unit of the value is KHz.

To list current supported frequencies, run:

.. prompt:: bash # auto

    # cat /sys/devices/system/cpu/cpufreq/policyX/scaling_available_frequencies

To list current supported frequency governors, run:

.. prompt:: bash # auto

    # cat /sys/devices/system/cpu/cpufreq/policyX/scaling_available_governors
    ondemand userspace performance schedutil

Note the default governor is *schedutil*, which uses CPU utilization data of the in-kernel scheduler
to determine CPU frequencies.

To keep CPU running at the highest frequency, run:

.. prompt:: bash # auto

    # echo performance > /sys/devices/system/cpu/cpufreq/policyX/scaling_governor

Note the highest frequency will be capped by the frequency set in ``scaling_max_freq``. The user
can use the attribute to limit the highest frequency the governor can set.

To disable automatic scaling in kernel and let userspace application determine frequencies,
run:

.. prompt:: bash # auto

    # echo userspace > /sys/devices/system/cpu/cpufreq/policyX/scaling_governor
    # echo <FREQ> > /sys/devices/system/cpu/cpufreq/policyX/scaling_setspeed

Statistics
==========

If the kernel configuration *CONFIG_CPU_FREQ_STAT* is enabled, another subfolder ``stats`` will be
created under the ``policyX`` folder, which contains read-only attributes to examine statistics.

Here is list of attributes:

.. prompt:: bash # auto

    # ls -l > /sys/devices/system/cpu/cpufreq/policyX/stats
    total 0
    --w------- 1 root root 4096 Sep 20 14:27 reset
    -r--r--r-- 1 root root 4096 Sep 20 13:58 time_in_state
    -r--r--r-- 1 root root 4096 Sep 20 13:58 total_trans
    -r--r--r-- 1 root root 4096 Sep 20 13:58 trans_table

To read the amount of time spent in each frequency, run:

.. prompt:: bash # auto

    # cat /sys/devices/system/cpu/cpufreq/policyX/stats/time_in_state
    850000 1334115
    918000 166
    987000 72
    1056000 31
    1125000 5
    1216000 16
    1308000 130
    1400000 14
    1466000 19
    1533000 4
    1633000 3
    1700000 3
    1767000 8674
    1834000 1713
    1917000 1
    2001000 233393

The first column represents the supported frequency, and the second one is the time the CPU spends
at that frequency. The time unit is 10ms.

The attribute *total_trans* gives total number of frequency transition happened:

.. prompt:: bash # auto

    # cat /sys/devices/system/cpu/cpufreq/policyX/stats/total_trans
    533

The attribute *trans_table* gives detailed information of frequency transition:

.. code:: text

    # cat /sys/devices/system/cpu/cpufreq/policyX/stats/trans_table
       From  :    To
             :    850000    918000    987000   1056000   1125000   1216000   1308000   1400000   1466000 ...
       850000:         0        15        11         4         1         1       126         5         2
       918000:        18         0         2         0         0         1         1         0         1
       987000:        18         1         0         1         0         1         1         0         0
      1056000:         6         1         1         0         1         0         2         1         0
      1125000:         1         2         3         1         0         2         0         0         2
      1216000:         3         3         1         4         4         0         6         1         0
      1308000:       107         0         4         1         3        14         0        11         1
      1400000:        10         0         0         1         0         1         5         0         6
      1466000:         2         0         0         0         2         1         0         4         0
      ...

The output is a two dimension matrix with *i* rows and *j* columns, where each cell represents the
number of transition happened from *Freq_i* to *Freq_j*.

The counters in statistics are accumulated since the driver (``cpufreq_stats``) is loaded or counters are reset.
The counters can be reset by running the command:

.. prompt:: bash # auto

    # echo 1 > /sys/devices/system/cpu/cpufreq/policyX/stats/reset

Note the value written to the attribute doesn't matter. It is the write operation causing reset of counters.