cpu_freq: Add CPU Frequency Scaling subsystem

.. _cpu_freq:

CPU Frequency Scaling

#####################

.. toctree::

   :maxdepth: 1

   policies/index.rst

Overview

********

The CPU Frequency Scaling subsystem in Zephyr provides a framework for SoC's to dynamically adjust

their processor frequency based on a monitored metric and performance state (p-state) policy

algorithm.

Design Goals

************

The CPU Frequency Scaling subsystem aims to provide a framework that allows for any policy algorithm

to work with any p-state driver and allows for each policy to make use of one, or many, metrics to

determine an optimal CPU frequency. The subsystem should be flexible enough to allow for SoC vendors

to define custom p-states, thresholds and metrics.

P-state Policies

****************

A p-state policy is an algorithm that determines what the optimal p-state is for the CPU based on

the metrics it consumes and the thresholds defined per p-state. A policy can consume one, or many,

metrics to determine the optimal CPU frequency based on the desired statistics of the system.

See :ref:`policies <cpu_freq_policies>` for a list of standard policies.

Metrics

*******

A P-state policy should include one or more metrics to base decisions. Examples of metrics could

include percent CPU load, SoC temperature, etc.

For an example of a metric in use, see the :ref:`on_demand <on_demand_policy>` policy.

P-state Drivers

***************

A SoC supporting the CPU Freq subsystem must implement a p-state driver that implements

:c:func:`cpu_freq_pstate_set` which applies the passed in ``p_state`` to

the CPU when called.

A SoC must also provide the available p-states in devicetree by having a

:dtcompatible:`zephyr,pstate` compatible node. The SoC may also define its own p-state binding,

which extends :dtcompatible:`zephyr,pstate` to include additional properties that may be used by

the SoC's p-state driver.

Usage considerations

********************

The CPU Frequency Scaling subsystem assumes that each CPU is clocked independently and that a

p-state transition does not impact an unrelated CPU of the SoC.

The SoC supporting CPU Freq must uphold Zephyr's requirement that the system timer remains constant

over the lifetime of the program. See :ref:`Kernel Timing <kernel_timing>` for more information.

The CPU Frequency Scaling subsystem runs as a handler function to a ``k_timer``, which means it runs

in interrupt context (IRQ). The SoC p-state driver must ensure that its implementation of

:c:func:`cpu_freq_pstate_set` is IRQ context safe. If a p-state transition

cannot be completed reasonably in an IRQ context, it is recommended that the p-state driver of the

SoC implements its task as a workqueue item.

CPU Frequency Scaling subsystem is not compatible with SMP as of now since the thread can migrate

between cores during execution, causing per-CPU metrics to be attributed to the wrong CPU.

.. _cpu_freq_policies:

CPU Frequency Scaling Policies

##############################

.. toctree::

   :maxdepth: 1

   on_demand.rst

.. _on_demand_policy:

On-Demand CPU Frequency Scaling Policy

######################################

The On-Demand policy evaluates the current CPU load using the

:ref:`CPU Load subsystem <cpu_load_subsys>`, and compares it to the trigger threshold defined by the

SoC P-state definition.

The On-Demand policy will iterate through the defined P-states and select the first P-state of which

the CPU load exceeds the defined threshold.

For an example of the on-demand policy refer to the :zephyr:code-sample:`cpu_freq_on_demand` sample.

This policy is reactive. Frequency adjustments occur only after a change in system load has been

observed, so it cannot anticipate sudden high loads. The policy has no notion of task deadlines and

should not be considered as a real-time policy.

   binary_descriptors/index.rst

   console.rst

   cpu_freq/index.rst

   cpu_load/index.rst

   crypto/index

   debugging/index.rst

# Copyright (c) 2025 Analog Devices, Inc.

#

# SPDX-License-Identifier: Apache-2.0

description: Common properties for performance states (pstate)

compatible: "zephyr,pstate"

properties:

  load-threshold:

    type: int

    description: |

        CPU load threshold, in percent, for entering this performance state. Once

        the CPU load exceeds this threshold, it becomes a valid performance state

        for the P-state driver to switch to.