Re: [PATCH v4 1/1] Documentation: real-time: Add kernel configuration guide

[Sebastian Andrzej Siewior]

Rafael, any comments from you? Maybe on the CPU FREQ/ IDLE part?
Anything that is missing from your point of view? Here is slim version
of what we already have ;)

On 2026-07-16 21:57:14 [+0200], Ahmed S. Darwish wrote:
> new file mode 100644
> index 000000000000..99dfc73aa4d3
> --- /dev/null
> +++ b/Documentation/core-api/real-time/kernel-configuration.rst
> @@ -0,0 +1,310 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==============================
> +Real-Time Kernel configuration
> +==============================
> +
> +.. contents:: Table of Contents
> +   :depth: 3
> +   :local:
> +
> +Introduction
> +============
> +
> +This document lists the kernel configuration options that might affect a
> +real-time kernel's worst-case latency.  It is intended for system integrators.
> +
> +Configuration options
> +=====================
> +
> +``CONFIG_CPU_FREQ``
> +-------------------
> +
> +:Expectation: enabled
> +:Severity: *high*
> +
> +The CPU frequency scaling subsystem ensures that the processor can operate
> +at its maximum supported frequency.  While, in general, bootloaders are
> +tasked with setting the CPU clock to the highest speed on boot, some do
> +not.  It is thus desirable to keep this option enabled.
> +
> +.. caution::
> +
> +  A real-time kernel is not about being "as fast as possible", however
> +  real-time requirements may demand that the CPU is clocked at a
> +  particular speed.
> +
> +``CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE``
> +-------------------------------------------
> +
> +:Expectation: enabled
> +:Severity: *high*
> +
> +Real-Time workloads expect a fixed CPU frequency during execution.  Using
> +the performance governor is an easy way to achieve that purely from kernel
> +configuration.
> +
> +This is not a blanket rule.  Some setups might prefer to clock the CPU to
> +lower speeds due to thermal packaging or other requirements.  The key is
> +that the CPU frequency remains constant once set.
> +
> +``CONFIG_CPU_IDLE``
> +-------------------
> +
> +:Expectation: enabled
> +:Severity: *info*
> +
> +CPU idle states (C-states) allow the processor to enter low-power modes
> +during periods of inactivity.  Very-low CPU idle states may require
> +flushing the CPU caches and lowering or disabling the clocking.  This can
> +lower power consumption, but it also increases the entry and exit latency
> +from such states.
> +
> +While disabling this option eliminates cpuidle-related latencies, doing so
> +can significantly impact hardware longevity, warranty, and thermal
> +behavior.  Users should cap the maximum C-state to C1 instead.  For ACPI
> +platforms, this can be achieved by using the boot parameter [1]_::
> +
> +  processor.max_cstate=1
> +
> +Higher C-states can be acceptable depending on the user workload's latency
> +requirements.  For ACPI-based platforms, use the ``cpupower idle-info``
> +command to inspect the available idle states.
> +
> +For more information, please see:
> +
> +- ``linux/tools/power/cpupower``
> +- :doc:`/admin-guide/pm/cpuidle`
> +- :doc:`/admin-guide/pm/index`
> +
…
> +``CONFIG_NO_HZ`` / ``CONFIG_NO_HZ_FULL``
> +----------------------------------------
> +
> +:Expectation: disabled
> +:Severity: *medium*
> +
> +Tickless operation can increase kernel-to-userspace transition latency due
> +to the extra accounting and state book-keeping.
> +
> +*Guidance by real-time workload type:*
> +
> +- For periodic workloads; e.g., control loops executing every 100 µs, avoid
> +  ``NO_HZ`` modes.  Consistent kernel ticks are preferable.
> +
> +- For computation-intensive workloads; e.g. extended userspace execution,
> +  ``NO_HZ_FULL`` may be beneficial.  In such cases, users should offload
> +  the kernel housekeeping to dedicated CPUs and isolate compute cores.
> +
> +See also :doc:`/timers/no_hz`.
> +
…
> +
> +Non-performance CPU frequency governors
> +---------------------------------------
> +
> +:Expectation: disabled
> +:Severity: *medium*
> +
> +To ensure reproducible system latency measurements, disable the
> +non-``PERFORMANCE`` CPU frequency governors when possible.  This avoids the
> +risk of unknown userspace tasks implicitly or explicitly setting a
> +different CPU frequency governor, and thus achieving different latency
> +results across the system's runtime.
> +
> +If disabling other frequency governors is not an option, then
> +``CONFIG_CPU_FREQ_DEFAULT_GOV_USERSPACE`` should be enabled.  In that case,
> +users should set a *stable* CPU frequency setting during the system
> +runtime, as changing the CPU frequency will increase the system latency and
> +affect latency measurements reproducibility.  If a lower CPU frequency is
> +desired, then ``CONFIG_CPU_FREQ_DEFAULT_GOV_POWERSAVE`` should be set.
> +
> +The ``ONDEMAND`` CPU frequency governor should *not* be enabled in a
> +real-time system since it dramatically affects determinism depending on the
> +workload.
> +
> +For more information, please check :doc:`/admin-guide/pm/cpufreq`.

Sebastian