[PATCH v4] Documentation: real-time: Add boot parameters and task isolation section
From: Zixin Wang
Date: Sat Nov 21 2026 - 04:38:26 EST
Document the boot parameters and runtime tunables that affect the
worst-case latency of a real-time system, alongside the existing
kernel configuration guidance.
Cover CPU isolation, nohz_full, RCU callback offloading, interrupt
affinity, and C-state limits, with references to the relevant
documentation. Keep the C-state parameters next to CONFIG_CPU_IDLE
and the tickless trade-off next to CONFIG_NO_HZ, so each option stays
with its configuration guidance.
Link: https://bugzilla.kernel.org/show_bug.cgi?id=220633
Link: https://github.com/elisa-tech/wg-aerospace/issues/222
Signed-off-by: Zixin Wang <w1355457260@xxxxxxxxx>
---
Thanks Sebastian for the review.
v3 -> v4:
- Fold the C-state parameters into the CONFIG_CPU_IDLE section,
which already documents processor.max_cstate=1 and cpupower, and
drop the separate "Idle state limits" subsection.
- Point CONFIG_NO_HZ/CONFIG_NO_HZ_FULL at nohz_full= and avoid
repeating the tickless-transition explanation in the isolation
section.
- Add a CONFIG_RCU_NOCB_CPU section for rcu_nocbs= and rcu_nocb_poll,
and reference it from the isolation section.
- Remove repeated statements within the isolation section: the
domain side effect, the duplicate isolcpus=nohz/nohz_full=
description, and the nohz_full/rcu_nocbs cross-statement.
- Keep the boot parameter section focused on the cross-cutting
isolation parameters and their interactions.
Testing:
make SPHINXDIRS="core-api" htmldocs and checkpatch.pl pass.
Host boot test (AMD Ryzen 5 5600H, acpi_idle): with
processor.max_cstate=1, /sys/module/processor/parameters/max_cstate
is 1 and cpupower idle-info reports only POLL/C1; without the
parameter the host reports POLL/C1/C2/C3. intel_idle.max_cstate was
not tested because the host uses acpi_idle.
Host latency comparison (cyclictest, CPU 2 isolated, performance
governor): the idle-phase average latency was 15 us with
processor.max_cstate=1, 32 us with processor.max_cstate=2, and
248 us without a limit; the corresponding maxima were 879 us,
2407 us, and 3336 us. The tight-phase maxima were dominated by a
device IRQ (about 3.2 ms), so the idle phase is the relevant
comparison. C2 and C3 usage was confirmed by the cpuidle usage
counters.
QEMU test: the default ACPI tables have no _CST; with a small _CST
SSDT loaded via -acpitable, the guest registers POLL/C1/C2/C3, and
processor.max_cstate=1 limits them to POLL/C1. This verifies the
parameter behavior; the QEMU setup does not measure real host
C-state latency.
.../real-time/kernel-configuration.rst | 128 ++++++++++++++++++
1 file changed, 128 insertions(+)
diff --git a/Documentation/core-api/real-time/kernel-configuration.rst b/Documentation/core-api/real-time/kernel-configuration.rst
index d7f08e7b..315960cf 100644
--- a/Documentation/core-api/real-time/kernel-configuration.rst
+++ b/Documentation/core-api/real-time/kernel-configuration.rst
@@ -98,6 +98,11 @@ can be achieved by using the boot parameter [1]_::
processor.max_cstate=1
+On x86 systems using ``intel_idle``, the ``intel_idle.max_cstate=`` boot
+parameter sets the maximum C-state depth (1-9). A value of 0 disables
+``intel_idle`` and falls back to ``acpi_idle``; it does not disable
+C-states.
+
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.
@@ -179,6 +184,9 @@ the extra accounting and state book-keeping.
``NO_HZ_FULL`` may be beneficial. In such cases, users should offload the
kernel housekeeping to dedicated CPUs and isolate compute cores.
+``nohz_full=`` enables tickless operation for a set of CPUs; see
+:ref:`real_time_boot_parameters` for its interaction with ``isolcpus=``.
+
See also Documentation/timers/no_hz.rst
``CONFIG_PREEMPT_RT``
@@ -190,6 +198,36 @@ See also Documentation/timers/no_hz.rst
This option must be enabled, or the resulting kernel will not be fully
preemptible and real-time capable.
+``CONFIG_RCU_NOCB_CPU``
+-------------------------
+
+:Expectation: allowed
+:Severity: *info*
+
+Enable support for offloading RCU callback invocation from selected CPUs
+to per-CPU ``rcuo`` kthreads. The offload is selected with ``rcu_nocbs=``
+or implied by ``nohz_full=``; enabling this option alone does not change
+callback placement. Use it when RCU callback processing causes jitter on
+CPUs dedicated to latency-sensitive tasks. See
+Documentation/admin-guide/cpu-isolation.rst.
+
+``rcu_nocbs[=cpu-list]``
+ Offload RCU callback invocation from the listed CPUs to the
+ corresponding ``rcuo`` kthread, which can run on a housekeeping CPU.
+ This keeps callbacks from being invoked on the CPU that enqueued them.
+ On a non-real-time kernel this also moves invocation out of softirq
+ context; with PREEMPT_RT, callbacks already run in kthread context
+ because ``rcutree.use_softirq`` is false, and the offload only changes
+ the CPU they run on. If omitted, no CPU is offloaded at boot; the mode
+ can still be toggled at runtime through cpusets.
+
+``rcu_nocb_poll``
+ Make the ``rcuo`` kthreads poll for callbacks instead of requiring the
+ offloaded CPUs to wake them. This improves the real-time response at
+ the cost of higher power consumption, because the kthreads wake up
+ periodically to do the polling. Consider this option only when wakeup
+ latency matters more than power.
+
``CONFIG_TRACING`` (and tracing options)
----------------------------------------
@@ -216,6 +254,96 @@ just by being enabled.
These tracers do incur measurable latency overhead even when tracing is not
currently active.
+.. _real_time_boot_parameters:
+
+Boot parameters and task isolation
+==================================
+
+Kernel configuration options alone do not determine a real-time system's
+worst-case latency. Integrators commonly rely on boot parameters and
+runtime tunables as well, to keep kernel housekeeping work away from
+latency-sensitive tasks. The parameters below complement the options
+described above. Some of them correspond to a configuration option and
+are referenced from that option's section, so the configuration and
+runtime guidance stay together. Each one is documented in detail in
+Documentation/admin-guide/kernel-parameters.rst; the notes here focus on
+the aspects that matter for real-time latency. Consider these options
+only when the workload suffers from the corresponding interference;
+leave them disabled otherwise, as each of them trades flexibility or
+power for a lower worst-case latency. The notes below follow the
+decisions an integrator has to make: whether to keep tasks off a CPU,
+whether to stop its tick, and where interrupts should run. Idle state
+limits are discussed with ``CONFIG_CPU_IDLE`` above, and RCU callback
+offloading with ``CONFIG_RCU_NOCB_CPU`` above.
+For the full CPU isolation model and its limitations, see
+Documentation/admin-guide/cpu-isolation.rst.
+
+.. caution::
+
+ CPU isolation is best effort. Work that is explicitly bound to an
+ isolated CPU, such as per-CPU kernel threads, bound workqueues, and
+ interrupts, may still run there unless it is steered away. Measure
+ the resulting latency with tools such as ``osnoise``, ``timerlat``,
+ and ``rtla`` rather than assuming that an isolated CPU is free of
+ kernel noise. See Documentation/timers/no_hz.rst and
+ Documentation/tools/rtla/index.rst.
+
+CPU isolation
+-------------
+
+``isolcpus=``
+ Format: ``[flag-list,]<cpu-list>``. Isolates the listed CPUs from the
+ disturbances selected by the flag list (default: ``domain``):
+
+ ``domain``
+ Remove the CPUs from the scheduler domains. This is the default
+ when no flag is given. Domain isolation cannot be undone at
+ runtime; use cpusets when the isolated CPU set must change
+ dynamically. Isolated CPUs remain usable through CPU affinity or
+ cpusets. Unbound workqueues and unbound kernel threads are
+ confined to the housekeeping CPUs as a side effect. Consider it
+ for CPUs dedicated to a latency-sensitive workload.
+
+ ``nohz``
+ Equivalent to ``nohz_full=``; see below.
+
+ A practical configuration therefore combines ``isolcpus=`` with
+ ``nohz_full=``, ``rcu_nocbs=``, an interrupt affinity mask, and, on
+ x86 systems, a C-state limit.
+
+ Timer placement follows the same choice. By default a migratable
+ timer expires on the CPU that armed it; with ``nohz`` (or
+ ``nohz_full=``), timers and hrtimers armed on the isolated CPUs are
+ migrated to housekeeping CPUs.
+
+``nohz_full=``
+ Format: ``<cpu-list>``. Requires ``CONFIG_NO_HZ_FULL=y``. Stops the
+ scheduler tick on the listed CPUs whenever possible. The boot CPU is
+ forced outside the range to maintain timekeeping, and the RCU
+ callbacks of the listed CPUs are offloaded as if they had been
+ passed to ``rcu_nocbs=``; see the ``CONFIG_RCU_NOCB_CPU`` section
+ above. This parameter takes precedence over
+ ``CONFIG_RCU_NOCB_CPU_DEFAULT_ALL``.
+
+ The residual 1 Hz tick is offloaded to workqueues; the global
+ workqueue ``cpumask`` (/sys/devices/virtual/workqueue/cpumask) can
+ further restrict where unbound work runs.
+
+ The trade-off between tickless operation and the kernel-to-userspace
+ transition latency is described in the ``CONFIG_NO_HZ`` /
+ ``CONFIG_NO_HZ_FULL`` section above.
+
+Interrupt affinity
+------------------
+
+``irqaffinity=``
+ Format: ``<cpu-list>``. Sets the default affinity mask for
+ interrupts that do not have an explicit affinity, steering them to
+ the housekeeping CPUs. Managed interrupts are not affected by this
+ setting and cannot be redirected through ``/proc/irq/*``. Verify
+ the resulting placement in ``/proc/interrupts``. See
+ Documentation/core-api/irq/managed_irq.rst.
+
Kernel Debug Options
====================
--
2.54.0