From: Zixin Wang <w1355457260@gmail.com>
To: linux-doc@vger.kernel.org
Cc: linux-rt-devel@lists.linux.dev, bigeasy@linutronix.de,
clrkwllms@kernel.org, rostedt@goodmis.org, corbet@lwn.net,
linux-kernel@vger.kernel.org, Zixin Wang <w1355457260@gmail.com>
Subject: [PATCH] Documentation: real-time: Add boot parameters and task isolation section
Date: Fri, 20 Nov 2026 13:42:42 +0800 [thread overview]
Message-ID: <20261120054242.523606-1-w1355457260@gmail.com> (raw)
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, idle states, and real-time throttling, with references to
the relevant documentation.
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@gmail.com>
---
.../real-time/kernel-configuration.rst | 134 ++++++++++++++++++
1 file changed, 134 insertions(+)
diff --git a/Documentation/core-api/real-time/kernel-configuration.rst b/Documentation/core-api/real-time/kernel-configuration.rst
index d7f08e7b..65532496 100644
--- a/Documentation/core-api/real-time/kernel-configuration.rst
+++ b/Documentation/core-api/real-time/kernel-configuration.rst
@@ -216,6 +216,140 @@ just by being enabled.
These tracers do incur measurable latency overhead even when tracing is not
currently active.
+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. 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. For the full CPU
+isolation model and its limitations, see
+Documentation/admin-guide/cpu-isolation.rst.
+
+.. caution::
+
+ CPU isolation is best effort. Unbound workqueues, kernel threads,
+ timers, and interrupts may still run on isolated CPUs unless they are
+ explicitly 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>``. Removes the listed CPUs from the
+ scheduler's general load balancing so that runnable tasks are not
+ placed there automatically. The optional flag list selects the type
+ of isolation:
+
+ ``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.
+
+ ``nohz``
+ Stop the tick when a single task runs and offload kernel noise,
+ including RCU callbacks. This is equivalent to ``nohz_full=``.
+ The residual 1 Hz tick is offloaded to workqueues, which must be
+ affined to housekeeping CPUs through the global workqueue
+ ``cpumask``; by default that workqueue may run on any CPU.
+
+ ``managed_irq``
+ Prevent managed interrupts from being targeted at isolated CPUs
+ when their automatically computed affinity mask also contains
+ housekeeping CPUs. This is best effort and has no effect when the
+ mask contains isolated CPUs only. See
+ Documentation/core-api/irq/managed_irq.rst.
+
+ ``isolcpus=`` only influences task placement. It does not stop
+ kernel threads, timers, or interrupts that are already affined to
+ the isolated CPUs. A practical configuration therefore combines it
+ with ``nohz_full=``, ``rcu_nocbs=``, an interrupt affinity mask, and
+ a C-state limit.
+
+``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=``. This parameter takes precedence over
+ ``CONFIG_RCU_NOCB_CPU_DEFAULT_ALL``.
+
+ Tickless operation can increase the kernel-to-userspace transition
+ latency, so it is most useful for workloads that execute in
+ userspace for long periods with few syscalls. Periodic workloads
+ with short periods may prefer a consistent tick instead.
+
+RCU callback offloading
+-----------------------
+
+``rcu_nocbs[=cpu-list]``
+ In kernels built with ``CONFIG_RCU_NOCB_CPU=y``, move RCU callback
+ invocation for the listed CPUs out of softirq context and into
+ per-CPU ``rcuo`` kthreads. This reduces OS jitter on the offloaded
+ CPUs. If the argument is omitted, no CPU is offloaded at boot, but
+ the mode can be toggled at runtime through cpusets. ``nohz_full=``
+ implies the same offload for the CPUs it lists.
+
+``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.
+
+Interrupt affinity
+------------------
+
+``irqaffinity=``
+ Format: ``<cpu-list>``. Sets the default affinity mask for
+ interrupts that do not have an explicit affinity. Managed
+ interrupts, such as MSI-X queue interrupts, derive their affinity
+ from the device queue mask instead and cannot be changed through
+ ``/proc/irq/*``. Combine ``irqaffinity=`` with the ``managed_irq``
+ flag of ``isolcpus=`` to keep interrupts away from isolated CPUs
+ where possible. See Documentation/core-api/irq/managed_irq.rst.
+
+Idle state limits
+-----------------
+
+``processor.max_cstate=``
+ ACPI platforms only. Limits the deepest C-state the processor may
+ enter. ``processor.max_cstate=1`` caps the processor at C1 and
+ avoids the entry and exit latency, cache flushing, and clock effects
+ of deeper states. A value of 9 overrides any DMI blacklist limit.
+
+``intel_idle.max_cstate=``
+ x86 platforms using ``intel_idle`` only. A value between 1 and 9
+ specifies the maximum C-state depth. A value of 0 disables
+ ``intel_idle`` and falls back to ``acpi_idle``; it does not disable
+ C-states.
+
+Deeper C-states save power but increase wakeup latency. Choose the
+shallowest state that still meets the platform's power and thermal
+requirements, and validate the result with the tools listed above.
+
+Real-time throttling
+--------------------
+
+``kernel.sched_rt_runtime_us``
+ This sysctl, normally set at boot through a ``sysctl.d``
+ configuration file, limits the CPU time available to real-time
+ scheduling during ``kernel.sched_rt_period_us``. The default of
+ 950000 us per 1000000 us reserves 5% of the CPU for non-real-time
+ tasks. A value of -1 removes the limit, allowing real-time tasks to
+ use the full period; do this only after validating the workload,
+ because a runaway real-time task can then starve the rest of the
+ system. Recent kernels require the runtime/period ratio to stay
+ above 0.05 to preserve bandwidth for the fair deadline server. See
+ Documentation/scheduler/sched-rt-group.rst.
+
Kernel Debug Options
====================
--
2.54.0
next reply other threads:[~2026-11-20 5:42 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-20 5:42 Zixin Wang [this message]
2026-11-20 5:49 ` sashiko-bot
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261120054242.523606-1-w1355457260@gmail.com \
--to=w1355457260@gmail.com \
--cc=bigeasy@linutronix.de \
--cc=clrkwllms@kernel.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-rt-devel@lists.linux.dev \
--cc=rostedt@goodmis.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®