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

[Steven Rostedt]

On Thu,  5 Mar 2026 21:50:12 +0100
"Ahmed S. Darwish" <darwi@xxxxxxxxxxxxx> wrote:

> Add a configuration guide for real-time kernels.
> 
> List all Kconfig options that are recommended to be either enabled or
> disabled.  Explicitly add a table of contents at the top of the document,
> so that all the options can be seen in a glance.
> 
> Whenever appropriate, link to other kernel guides; e.g. cpuidle, cpufreq,
> power management, and no_hz.
> 
> Add a summary at the end of the document warning users that there is a no
> "one size fits all solution" for configuring a real-time system.
> 

Very nice document!

> Signed-off-by: Ahmed S. Darwish <darwi@xxxxxxxxxxxxx>
> ---
>  Documentation/core-api/real-time/index.rst    |   1 +
>  .../real-time/kernel-configuration.rst        | 297 ++++++++++++++++++
>  2 files changed, 298 insertions(+)
>  create mode 100644 Documentation/core-api/real-time/kernel-configuration.rst
> 

> +``CONFIG_EFI_DISABLE_RUNTIME``
> +------------------------------
> +
> +:Expectation: enabled
> +:Severity: *medium*
> +
> +EFI is the standard boot and firmware interface for multiple
> +architectures.  EFI runtime services provide callback functions to be
> +called from the kernel; e.g., as utilized by (``CONFIG_EFI_VARS*``) or
> +(``CONFIG_RTC_DRV_EFI``).  For the former, the kernel calls into EFI to
> +update the EFI variables.
> +
> +Calling into EFI means invoking firmware callbacks.  During such
> +invocations, the system might not be able to react to interrupts and will
> +thus not be able to perform a context switch.  This can cause significant
> +latency spikes for the real-time system.


> +
> +``CONFIG_PREEMPT_RT`` enables this option by default.  If this option is
> +disabled during the kernel build, pass the following boot parameter [1]_::
> +
> +  efi=noruntime

The above reads a bit funny. Maybe reword it to:

  ``CONFIG_PREEMPT_RT`` enables this option by default. If this option is
  manually disabled at build time, the following boot parameter [1]_ may
  be used to disable EFI runtime at boot up::

Or something like that.

> +
> +There is ongoing `development work`_ to allow EFI variables access for a
> +real-time Linux system.

  .. to allow access to EFI variables for a real-time Linux system

 ?

> +``CONFIG_TRACING`` (and tracing options)
> +----------------------------------------
> +
> +:Expectation: enabled
> +:Severity: *info*
> +
> +Shipping kernels with tracing support enabled (but not actively running)
> +is highly recommended.  This will allow the users to extract more
> +information if latency problems arise.
> +
> +.. caution::
> +
> +  Users should *not* make use of tracers or trace events during production
> +  real-time kernel operation as they can add considerable overhead and
> +  degrade the system's latency.

I wonder if a special note should be called out for:

  CONFIG_IRQSOFF_TRACER and CONFIG_PREEMPT_TRACER should be avoided as they
  do incur measurable overhead even when tracing is not currently active.

Maybe the above should be added in the "Problematic debug options"?


> +Kernel Debug Options
> +====================
> +
> +Most kernel debug options add runtime overhead that increases the
> +worst-case latency.
> +
> +.. caution::
> +
> +  During development and early testing, users are encouraged to run their
> +  real-time workloads and peripherals with lockdep and other kernel debug
> +  options enabled, for a considerable amount of time.  Such workloads
> +  might trigger kernel code paths that were not triggered during the
> +  internal Linux real-time kernel development, thus helping to uncover any
> +  real-time latency issues in the kernel.

Hmm, perhaps there should be some note that connects the use of "lockdep"
with CONFIG_PROVE_LOCKING below (as that is what enables lockdep). The last
sentence above makes it sound like lockdep can uncover latency issues, but
it will most likely cause latency issues. Perhaps a bit more explanation
should be used here.

> +
> +Problematic debug options
> +-------------------------
> +
> +``CONFIG_LOCKUP_DETECTOR``
> +^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Severity: *high*
> +
> +The lockup detector creates kernel timer callbacks that execute every few
> +seconds, in hard-IRQ context, even on real-time kernels.  These periodic
> +interrupts can cause latency spikes.
> +
> +Users should use hardware watchdogs instead, which will provide a similar
> +functionality without the software-induced latency.
> +
> +``CONFIG_PROVE_LOCKING``
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Severity: *high*
> +
> +Proving the correctness of all kernel locking adds substantial overhead
> +and significantly increases worst-case latency.



> +Summary
> +=======
> +
> +There is no "one size fits all" solution for configuring a real-time Linux
> +system.  Beginning with the system real-time requirements, integrators
> +must consider the features and functions of the system's hardware, kernel,
> +and userspace.  All such components must be properly configured in order
> +to establish and constrain the system's maximum latency.
> +
> +With that in mind, any false real-time kernel configuration could cause a

  s/false/incorrect/ ?

> +new maximum latency that shows up at the wrong time and is catastrophic
> +for the real-time system's latency.
> +
> +References
> +==========
> +
> +.. [1] See :doc:`/admin-guide/kernel-parameters`
> +
> +.. _development work: https://lore.kernel.org/r/20260205115559.1625236-1-bigeasy@xxxxxxxxxxxxx
> +
> +.. _Real-Time and Graphics\: A Contradiction?: https://web.archive.org/web/20221025085614/https://linutronix.de/PDF/Realtime_and_graphics-acontradiction2021.pdf

Nice job!

-- Steve