[PATCH 0/3] Documentation: Add real-time bits.

[PATCH 0/3] Documentation: Add real-time bits.

[Sebastian Andrzej Siewior]

I tried to put some real-time related documentation.
Patch #1 adds a reference and SPDX tag to seqlock.
Patch #2 extends locktypes with local_lock_nested_bh
Patch #3 adds some real-time bits.

In case there is something missing or unclear, please let me know.

Sebastian

Sebastian Andrzej Siewior (3):
  Documentation: seqlock: Add a reference label and license.
  Documentation: locking: Add local_lock_nested_bh() to locktypes
  Documentation: Add real-time

 Documentation/index.rst                 |   1 +
 Documentation/locking/locktypes.rst     |  21 ++
 Documentation/locking/seqlock.rst       |   4 +
 Documentation/real-time/differences.rst | 244 ++++++++++++++++++++++++
 Documentation/real-time/index.rst       |  18 ++
 Documentation/real-time/theory.rst      | 119 ++++++++++++
 6 files changed, 407 insertions(+)
 create mode 100644 Documentation/real-time/differences.rst
 create mode 100644 Documentation/real-time/index.rst
 create mode 100644 Documentation/real-time/theory.rst

-- 
2.50.0

[PATCH 1/3] Documentation: seqlock: Add a reference label and license.

[Sebastian Andrzej Siewior]

Add a reference label to the document so it can be crossed referenced
from another document in the tree.
While at it, add a SPDX identifier. The majority of the document has
been written Ahmed S. Darwish.

Cc: Ahmed S. Darwish <darwi@linutronix.de>
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 Documentation/locking/seqlock.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/locking/seqlock.rst b/Documentation/locking/seqlock.rst
index ec6411d02ac8f..4936b46dedc59 100644
--- a/Documentation/locking/seqlock.rst
+++ b/Documentation/locking/seqlock.rst
@@ -1,3 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _kernel_hacking_seqlock:
+
 ======================================
 Sequence counters and sequential locks
 ======================================
-- 
2.50.0

[PATCH 2/3] Documentation: locking: Add local_lock_nested_bh() to locktypes

[Sebastian Andrzej Siewior]

local_lock_nested_bh() is used within networking where applicable.
Document why it is used and how it behaves.

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 Documentation/locking/locktypes.rst | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst
index 80c914f6eae7a..4851ec1232058 100644
--- a/Documentation/locking/locktypes.rst
+++ b/Documentation/locking/locktypes.rst
@@ -204,6 +204,27 @@ per-CPU data structures on a non PREEMPT_RT kernel.
 local_lock is not suitable to protect against preemption or interrupts on a
 PREEMPT_RT kernel due to the PREEMPT_RT specific spinlock_t semantics.
 
+CPU local scope and bottom-half
+-------------------------------
+
+Per-CPU variables that are accessed only in softirq context should not rely on
+the assumption that this context is implicitly protected due to being
+non-preemptible. In a PREEMPT_RT kernel, softirq context is preemptible, and
+synchronizing every bottom-half-disabled section via implicit context results
+in an implicit per-CPU "big kernel lock."
+
+A local_lock_t together with local_lock_nested_bh() and
+local_unlock_nested_bh() for locking operations help to identify the locking
+scope.
+
+With lockdep is enabled, these functions verify that data structure access
+occurs within softirq context.
+Unlike local_lock(), local_unlock_nested_bh() does not disable preemption and
+does not add overhead when used without lockdep.
+
+On a PREEMPT_RT kernel, local_lock_t behaves as a real lock and
+local_unlock_nested_bh() serializes access to the data structure, which allows
+removal of serialization via local_bh_disable().
 
 raw_spinlock_t and spinlock_t
 =============================
-- 
2.50.0

[PATCH 3/3] Documentation: Add real-time

[Sebastian Andrzej Siewior]

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 Documentation/index.rst                 |   1 +
 Documentation/real-time/differences.rst | 244 ++++++++++++++++++++++++
 Documentation/real-time/index.rst       |  18 ++
 Documentation/real-time/theory.rst      | 119 ++++++++++++
 4 files changed, 382 insertions(+)
 create mode 100644 Documentation/real-time/differences.rst
 create mode 100644 Documentation/real-time/index.rst
 create mode 100644 Documentation/real-time/theory.rst

diff --git a/Documentation/index.rst b/Documentation/index.rst
index c0cf79a87c3a3..78c93d992b62b 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -42,6 +42,7 @@ kernel.
    Driver APIs <driver-api/index>
    Subsystems <subsystem-apis>
    Locking <locking/index>
+   Real-Time <real-time/index>
 
 Development tools and processes
 ===============================
diff --git a/Documentation/real-time/differences.rst b/Documentation/real-time/differences.rst
new file mode 100644
index 0000000000000..0b9a46a7badf4
--- /dev/null
+++ b/Documentation/real-time/differences.rst
@@ -0,0 +1,244 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _real_time_differences:
+
+========================
+Significant differences
+========================
+
+:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
+
+Preface
+=======
+
+With forced-threaded interrupts and sleeping spin locks, code paths that
+previously caused long scheduling latencies have been made preemptible and
+moved into process context. This allows the scheduler to manage them more
+effectively and respond to higher-priority tasks with reduced latency.
+
+The following chapters provide an overview of key differences between a
+PREEMPT_RT kernel and a standard, non-PREEMPT_RT kernel.
+
+Locking
+=======
+
+Spinning locks such as spinlock_t are used to provide synchronization for data
+structures accessed from both interrupt context and process context. For this
+reason, locking functions are also available with the _irq() or _irqsave()
+suffixes, which disable interrupts before acquiring the lock. This ensures that
+the lock can be safely acquired in process context when interrupts are enabled.
+
+However, on a PREEMPT_RT system, interrupts are forced-threaded and no longer
+run in hard IRQ context. As a result, there is no need to disable interrupts as
+part of the locking procedure when using spinlock_t.
+
+For low-level core components such as interrupt handling, the scheduler, or the
+timer subsystem the kernel uses raw_spinlock_t. This lock type preserves
+traditional semantics: it disables preemption and, when used with _irq() or
+_irqsave(), also disables interrupts. This ensures proper synchronization in
+critical sections that must remain non-preemptible or with interrupts disabled.
+
+Execution context
+=================
+
+Interrupt handling in a PREEMPT_RT system is invoked in process context through
+the use of threaded interrupts. Other parts of the kernel also shift their
+execution into threaded context by different mechanisms. The goal is to keep
+execution paths preemptible, allowing the scheduler to interrupt them when a
+higher-priority task needs to run.
+
+Below is an overview of the kernel subsystems involved in this transition to
+threaded, preemptible execution.
+
+Interrupt handling
+------------------
+
+All interrupts are forced-threaded in a PREEMPT_RT system. The exceptions are
+interrupts that are requested with the IRQF_NO_THREAD, IRQF_PERCPU, or
+IRQF_ONESHOT flags.
+
+The IRQF_ONESHOT flag is used together with threaded interrupts, meaning those
+registered using request_threaded_irq() and providing only a threaded handler.
+Its purpose is to keep the interrupt line masked until the threaded handler has
+completed.
+
+If a primary handler is also provided in this case, it is essential that the
+handler does not acquire any sleeping locks, as it will not be threaded. The
+handler should be minimal and must avoid introducing delays, such as
+busy-waiting on hardware registers.
+
+
+Soft interrupts, bottom half handling
+-------------------------------------
+
+Soft interrupts are raised by the interrupt handler and are executed after the
+handler returns. Since they run in thread context, they can be preempted by
+other threads. Do not assume that softirq context runs with preemption
+disabled. This means you must not rely on mechanisms like local_bh_disable() in
+process context to protect per-CPU variables. Because softirq handlers are
+preemptible under PREEMPT_RT, this approach does not provide reliable
+synchronization.
+
+If this kind of protection is required for performance reasons, consider using
+local_lock_nested_bh(). On non-PREEMPT_RT kernels, this allows lockdep to
+verify that bottom halves are disabled. On PREEMPT_RT systems, it adds the
+necessary locking to ensure proper protection.
+
+Using local_lock_nested_bh() also makes the locking scope explicit and easier
+for readers and maintainers to understand.
+
+
+per-CPU variables
+-----------------
+
+Protecting access to per-CPU variables solely by using preempt_disable() should
+be avoided, especially if the critical section has unbounded runtime or may
+call APIs that can sleep.
+
+If using a spinlock_t is considered too costly for performance reasons,
+consider using local_lock_t. On non-PREEMPT_RT configurations, this introduces
+no runtime overhead when lockdep is disabled. With lockdep enabled, it verifies
+that the lock is only acquired in process context and never from softirq or
+hard IRQ context.
+
+On a PREEMPT_RT kernel, local_lock_t is implemented using a per-CPU spinlock_t,
+which provides safe local protection for per-CPU data while keeping the system
+preemptible.
+
+Because spinlock_t on PREEMPT_RT does not disable preemption, it cannot be used
+to protect per-CPU data by relying on implicit preemption disabling. If this
+inherited preemption disabling is essential and if local_lock_t cannot be used
+due to performance constraints, brevity of the code, or abstraction boundaries
+within an API then preempt_disable_nested() may be a suitable alternative. On
+non-PREEMPT_RT kernels, it verifies with lockdep that preemption is already
+disabled. On PREEMPT_RT, it explicitly disables preemption.
+
+Timers
+------
+
+By default, an hrtimer is executed in hard interrupt context. The exception is
+timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in
+softirq context.
+
+On a PREEMPT_RT kernel, this behavior is reversed: hrtimers are executed in
+softirq context by default, typically within the ktimersd thread. This thread
+runs at the lowest real-time priority, ensuring it executes before any
+SCHED_OTHER tasks but does not interfere with higher-priority real-time
+threads. To explicitly request execution in hard interrupt context on
+PREEMPT_RT, the timer must be marked with the HRTIMER_MODE_HARD flag.
+
+Memory allocation
+-----------------
+
+The memory allocation APIs, such as kmalloc() and alloc_pages(), require a
+gfp_t flag to indicate the allocation context. On non-PREEMPT_RT kernels, it is
+necessary to use GFP_ATOMIC when allocating memory from interrupt context or
+from sections where preemption is disabled. This is because the allocator must
+not sleep in these contexts waiting for memory to become available.
+
+However, this approach does not work on PREEMPT_RT kernels. The memory
+allocator in PREEMPT_RT uses sleeping locks internally, which cannot be
+acquired when preemption is disabled. Fortunately, this is generally not a
+problem, because PREEMPT_RT moves most contexts that would traditionally run
+with preemption or interrupts disabled into threaded context, where sleeping is
+allowed.
+
+What remains problematic is code that explicitly disables preemption or
+interrupts. In such cases, memory allocation must be performed outside the
+critical section.
+
+This restriction also applies to memory deallocation routines such as kfree()
+and free_pages(), which may also involve internal locking and must not be
+called from non-preemptible contexts.
+
+IRQ work
+--------
+
+The irq_work API provides a mechanism to schedule a callback in interrupt
+context. It is designed for use in contexts where traditional scheduling is not
+possible, such as from within NMI handlers or from inside the scheduler, where
+using a workqueue would be unsafe.
+
+On non-PREEMPT_RT systems, all irq_work items are executed immediately in
+interrupt context. Items marked with IRQ_WORK_LAZY are deferred until the next
+timer tick but are still executed in interrupt context.
+
+On PREEMPT_RT systems, the execution model changes. Because irq_work callbacks
+may acquire sleeping locks or have unbounded execution time, they are handled
+in thread context by a per-CPU irq_work kernel thread. This thread runs at the
+lowest real-time priority, ensuring it executes before any SCHED_OTHER tasks
+but does not interfere with higher-priority real-time threads.
+
+The exception are work items marked with IRQ_WORK_HARD_IRQ, which are still
+executed in hard interrupt context. Lazy items (IRQ_WORK_LAZY) continue to be
+deferred until the next timer tick and are also executed by the irq_work/
+thread.
+
+RCU callbacks
+-------------
+
+RCU callbacks are invoked by default in softirq context. Their execution is
+important because, depending on the use case, they either free memory or ensure
+progress in state transitions. Running these callbacks as part of the softirq
+chain can lead to undesired situations, such as contention for CPU resources
+with other SCHED_OTHER tasks when executed within ksoftirqd.
+
+To avoid running callbacks in softirq context, the RCU subsystem provides a
+mechanism to execute them in process context instead. This behavior can be
+enabled by setting the boot command-line parameter rcutree.use_softirq=0. This
+setting is enforced in kernels configured with PREEMPT_RT.
+
+Spin until ready
+================
+
+The "spin until ready" pattern involves repeatedly checking (spinning on) the
+state of a data structure until it becomes available. This pattern assumes that
+preemption, soft interrupts, or interrupts are disabled. If the data structure
+is marked busy, it is presumed to be in use by another CPU, and spinning should
+eventually succeed as that CPU makes progress.
+
+Some examples are hrtimer_cancel() or timer_delete_sync(). These functions
+cancel timers that execute with interrupts or soft interrupts disabled. If a
+thread attempts to cancel a timer and finds it active, spinning until the
+callback completes is safe because the callback can only run on another CPU and
+will eventually finish.
+
+On PREEMPT_RT kernels, however, timer callbacks run in thread context. This
+introduces a challenge: a higher-priority thread attempting to cancel the timer
+may preempt the timer callback thread. Since the scheduler cannot migrate the
+callback thread to another CPU due to affinity constraints, spinning can result
+in livelock even on multiprocessor systems.
+
+To avoid this, both the canceling and callback sides must use a handshake
+mechanism that supports priority inheritance. This allows the canceling thread
+to suspend until the callback completes, ensuring forward progress without
+risking livelock.
+
+In order to solve the problem at the API level, the sequence locks were extended
+to allow a proper handover between the the spinning reader and the maybe
+blocked writer.
+
+Sequence locks
+--------------
+
+Sequence counters and sequential locks are documented in
+:ref:`Documentation/locking/seqlock.rst <kernel_hacking_seqlock>`.
+
+The interface has been extended to ensure proper preemption states for the
+writer and spinning reader contexts. This is achieved by embedding the writer
+serialization lock directly into the sequence counter type, resulting in
+composite types such as seqcount_spinlock_t or seqcount_mutex_t.
+
+These composite types allow readers to detect an ongoing write and actively
+boost the writer’s priority to help it complete its update instead of spinning
+and waiting for its completion.
+
+If the plain seqcount_t is used, extra care must be taken to synchronize the
+reader with the writer during updates. The writer must ensure its update is
+serialized and non-preemptible relative to the reader. This cannot be achieved
+using a regular spinlock_t because spinlock_t on PREEMPT_RT does not disable
+preemption. In such cases, using seqcount_spinlock_t is the preferred solution.
+
+However, if there is no spinning involved i.e., if the reader only needs to
+detect whether a write has started and not serialize against it then using
+seqcount_t is reasonable.
diff --git a/Documentation/real-time/index.rst b/Documentation/real-time/index.rst
new file mode 100644
index 0000000000000..3b90cd9243258
--- /dev/null
+++ b/Documentation/real-time/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============================
+Real-time Documentation
+=============================
+
+.. toctree::
+   :maxdepth: 2
+
+   theory
+   differences
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/real-time/theory.rst b/Documentation/real-time/theory.rst
new file mode 100644
index 0000000000000..3f5fdcdf2780e
--- /dev/null
+++ b/Documentation/real-time/theory.rst
@@ -0,0 +1,119 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _real_time_theory:
+
+=====================
+Theory of operation
+=====================
+
+:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
+
+Preface
+=======
+
+PREEMPT_RT transforms the Linux kernel into a real-time kernel. It achieves
+this by replacing locking primitives, such as spinlock_t, with a preemptible
+and priority-inheritance aware implementation known as rtmutex, and by enforcing
+the use of threaded interrupts. As a result, the kernel becomes fully
+preemptible, with the exception of a few critical code paths, including entry
+code, the scheduler, and low-level interrupt handling routines.
+
+This transformation places the majority of kernel execution contexts under the
+control of the scheduler and significantly increasing the number of preemption
+points. Consequently, it reduces the latency between a high-priority task
+becoming runnable and its actual execution on the CPU.
+
+Scheduling
+==========
+
+The core principles of Linux scheduling and the associated user-space API are
+documented in the man page sched(7)
+`sched(7) <https://man7.org/linux/man-pages/man7/sched.7.html>`_.
+By default, the Linux kernel uses the SCHED_OTHER scheduling policy. Under
+this policy, a task is preempted when the scheduler determines that it has
+consumed a fair share of CPU time relative to other runnable tasks. However,
+the policy does not guarantee immediate preemption when a new SCHED_OTHER task
+becomes runnable. The currently running task may continue executing.
+
+This behavior differs from that of real-time scheduling policies such as
+SCHED_FIFO. When a task with a real-time policy becomes runnable, the
+scheduler immediately selects it for execution if it has a higher priority than
+the currently running task. The task continues to run until it voluntarily
+yields the CPU, typically by blocking on an event.
+
+Sleeping spin locks
+===================
+
+The various lock types and their behavior under real-time configurations are
+described in detail in
+:ref:`Documentation/locking/locktypes.rst <kernel_hacking_locktypes>`.
+In a non-PREEMPT_RT configuration, a spinlock_t is acquired by first disabling
+preemption and then actively spinning until the lock becomes available. Once
+the lock is released, preemption is enabled. From a real-time perspective,
+this approach is undesirable because disabling preemption prevents the
+scheduler from switching to a higher-priority task, potentially increasing
+latency.
+
+To address this, PREEMPT_RT replaces spinning locks with sleeping spin locks
+that do not disable preemption. On PREEMPT_RT, spinlock_t is implemented using
+rtmutex. Instead of spinning, a task attempting to acquire a contended lock
+disables CPU migration, donates its priority to the lock owner (priority
+inheritance), and voluntarily schedules out while waiting for the lock to
+become available.
+
+Disabling CPU migration provides the same effect as disabling preemption, while
+still allowing preemption and ensuring that the task continues to run on the
+same CPU while holding a sleeping lock.
+
+Priority inheritance
+====================
+
+Lock types such as spinlock_t and mutex_t in a PREEMPT_RT enabled kernel are
+implemented on top of rtmutex, which provides support for priority inheritance
+(PI). When a task blocks on such a lock, the PI mechanism temporarily
+propagates the blocked task’s scheduling parameters to the lock owner.
+
+For example, if a SCHED_FIFO task A blocks on a lock currently held by a
+SCHED_OTHER task B, task A’s scheduling policy and priority are temporarily
+inherited by task B. After this inheritance, task A is put to sleep while
+waiting for the lock, and task B effectively becomes the highest-priority task
+in the system. This allows B to continue executing, make progress, and
+eventually release the lock.
+
+Once B releases the lock, it reverts to its original scheduling parameters, and
+task A can resume execution.
+
+Threaded interrupts
+===================
+
+Interrupt handlers are another source of code that executes with preemption
+disabled and outside the control of the scheduler. To bring interrupt handling
+under scheduler control, PREEMPT_RT enforces threaded interrupt handlers.
+
+With forced threading, interrupt handling is split into two stages. The first
+stage, the primary handler, is executed in IRQ context with interrupts disabled.
+Its sole responsibility is to wake the associated threaded handler. The second
+stage, the threaded handler, is the function passed to request_irq() as the
+interrupt handler. It runs in process context, scheduled by the kernel.
+
+From waking the interrupt thread until threaded handling is completed, the
+interrupt source is masked in the interrupt controller. This ensures that the
+device interrupt remains pending but does not retrigger the CPU, allowing the
+system to exit IRQ context and handle the interrupt in a scheduled thread.
+
+By default, the threaded handler executes with the SCHED_FIFO scheduling policy
+and a priority of 50 (MAX_RT_PRIO / 2), which is midway between the minimum and
+maximum real-time priorities.
+
+If the threaded interrupt handler raises any soft interrupts during its
+execution, those soft interrupt routines are invoked after the threaded handler
+completes, within the same thread. Preemption remains enabled during the
+execution of the soft interrupt handler.
+
+Summary
+=======
+
+By using sleeping locks and forced-threaded interrupts, PREEMPT_RT
+significantly reduces sections of code where interrupts or preemption is
+disabled, allowing the scheduler to preempt the current execution context and
+switch to a higher-priority task.
-- 
2.50.0

Re: [PATCH 1/3] Documentation: seqlock: Add a reference label and license.

[Jonathan Corbet]

Sebastian Andrzej Siewior <bigeasy@linutronix.de> writes:

> Add a reference label to the document so it can be crossed referenced
> from another document in the tree.
> While at it, add a SPDX identifier. The majority of the document has
> been written Ahmed S. Darwish.
>
> Cc: Ahmed S. Darwish <darwi@linutronix.de>
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> ---
>  Documentation/locking/seqlock.rst | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/locking/seqlock.rst b/Documentation/locking/seqlock.rst
> index ec6411d02ac8f..4936b46dedc59 100644
> --- a/Documentation/locking/seqlock.rst
> +++ b/Documentation/locking/seqlock.rst
> @@ -1,3 +1,7 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _kernel_hacking_seqlock:
> +

This will work, but you don't really need the label.  Just say
"Documentation/locking/seqlock.rst" at the other end and the
cross-reference link will happen by itself - and plain-text readers will
know where to go as well.

Thanks,

jon

Re: [PATCH 3/3] Documentation: Add real-time

[Jonathan Corbet]

Sebastian Andrzej Siewior <bigeasy@linutronix.de> writes:

> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> ---
>  Documentation/index.rst                 |   1 +
>  Documentation/real-time/differences.rst | 244 ++++++++++++++++++++++++
>  Documentation/real-time/index.rst       |  18 ++
>  Documentation/real-time/theory.rst      | 119 ++++++++++++
>  4 files changed, 382 insertions(+)
>  create mode 100644 Documentation/real-time/differences.rst
>  create mode 100644 Documentation/real-time/index.rst
>  create mode 100644 Documentation/real-time/theory.rst
>
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index c0cf79a87c3a3..78c93d992b62b 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -42,6 +42,7 @@ kernel.
>     Driver APIs <driver-api/index>
>     Subsystems <subsystem-apis>
>     Locking <locking/index>
> +   Real-Time <real-time/index>
>  
>  Development tools and processes
>  ===============================
> diff --git a/Documentation/real-time/differences.rst b/Documentation/real-time/differences.rst
> new file mode 100644
> index 0000000000000..0b9a46a7badf4
> --- /dev/null
> +++ b/Documentation/real-time/differences.rst
> @@ -0,0 +1,244 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _real_time_differences:

Here, too, you don't need this label, especially since you never
reference it.

I'll try to have a more substantive look shortly.

Thanks,

jon

Re: [PATCH 1/3] Documentation: seqlock: Add a reference label and license.

[Sebastian Andrzej Siewior]

On 2025-07-15 08:48:07 [-0600], Jonathan Corbet wrote:
> > --- a/Documentation/locking/seqlock.rst
> > +++ b/Documentation/locking/seqlock.rst
> > @@ -1,3 +1,7 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +.. _kernel_hacking_seqlock:
> > +
> 
> This will work, but you don't really need the label.  Just say
> "Documentation/locking/seqlock.rst" at the other end and the
> cross-reference link will happen by itself - and plain-text readers will
> know where to go as well.

I did
	 :ref:`Documentation/locking/seqlock.rst <kernel_hacking_seqlock>`

and you are saying just the file path without fancy :ref: is enough.
Okay. Then I keep just SPDX tag for v2.

> Thanks,
> 
> jon

Sebastian

Re: [PATCH 3/3] Documentation: Add real-time

[Sebastian Andrzej Siewior]

On 2025-07-15 08:50:16 [-0600], Jonathan Corbet wrote:
> > diff --git a/Documentation/real-time/differences.rst b/Documentation/real-time/differences.rst
> > new file mode 100644
> > index 0000000000000..0b9a46a7badf4
> > --- /dev/null
> > +++ b/Documentation/real-time/differences.rst
> > @@ -0,0 +1,244 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +.. _real_time_differences:
> 
> Here, too, you don't need this label, especially since you never
> reference it.

Okay.

> I'll try to have a more substantive look shortly.

Thank you.

> Thanks,
> 
> jon

Sebastian

Re: [PATCH 2/3] Documentation: locking: Add local_lock_nested_bh() to locktypes

[Jonathan Corbet]

Sebastian Andrzej Siewior <bigeasy@linutronix.de> writes:

> local_lock_nested_bh() is used within networking where applicable.
> Document why it is used and how it behaves.
>
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> ---
>  Documentation/locking/locktypes.rst | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
>
> diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst
> index 80c914f6eae7a..4851ec1232058 100644
> --- a/Documentation/locking/locktypes.rst
> +++ b/Documentation/locking/locktypes.rst
> @@ -204,6 +204,27 @@ per-CPU data structures on a non PREEMPT_RT kernel.
>  local_lock is not suitable to protect against preemption or interrupts on a
>  PREEMPT_RT kernel due to the PREEMPT_RT specific spinlock_t semantics.
>  
> +CPU local scope and bottom-half
> +-------------------------------
> +
> +Per-CPU variables that are accessed only in softirq context should not rely on
> +the assumption that this context is implicitly protected due to being
> +non-preemptible. In a PREEMPT_RT kernel, softirq context is preemptible, and
> +synchronizing every bottom-half-disabled section via implicit context results
> +in an implicit per-CPU "big kernel lock."
> +
> +A local_lock_t together with local_lock_nested_bh() and
> +local_unlock_nested_bh() for locking operations help to identify the locking
> +scope.
> +
> +With lockdep is enabled, these functions verify that data structure access

Did you mean *When* lockdep is enabled?

Otherwise no complaints here.

jon

Re: [PATCH 3/3] Documentation: Add real-time

[Jonathan Corbet]

Sebastian Andrzej Siewior <bigeasy@linutronix.de> writes:

> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> ---
>  Documentation/index.rst                 |   1 +
>  Documentation/real-time/differences.rst | 244 ++++++++++++++++++++++++
>  Documentation/real-time/index.rst       |  18 ++
>  Documentation/real-time/theory.rst      | 119 ++++++++++++
>  4 files changed, 382 insertions(+)
>  create mode 100644 Documentation/real-time/differences.rst
>  create mode 100644 Documentation/real-time/index.rst
>  create mode 100644 Documentation/real-time/theory.rst

So overall it looks good, but I do have one overriding question:

- Who is the audience for this documentation?

I think it's an important question to ask, because something this easily
becomes an unorganized pile of stuff that somebody thought should be
written down somewhere - better than nothing, but hard for readers to
use effectively.

A good first step would be to supply a paragraph or two in the new
Documentation/real-time/index.rst describing the nature of the
documentation and who it is intended for.

Then ... think about whether a new top-level directory under
Documentation makes sense.  I've been working for years to reduce those,
so I tend to push back a little when new ones show up.

- Is this documentation for kernel developers in general, with the idea
  of maybe helping them to not break PREEMPT_RT so often?  Then perhaps
  documentation with that focus under core-api/ makes sense.

- Is it, instead, intended as overall design documentation?  We don't
  really have a good place for that now, maybe we need a new design/
  book to gather such material.

See what I'm getting at?  I'm not saying that these docs *have* to go
somewhere else, but I do think it's worth thinking about.

Thanks,

jon

Re: [PATCH 2/3] Documentation: locking: Add local_lock_nested_bh() to locktypes

[Sebastian Andrzej Siewior]

On 2025-07-15 14:10:23 [-0600], Jonathan Corbet wrote:
…
> > +A local_lock_t together with local_lock_nested_bh() and
> > +local_unlock_nested_bh() for locking operations help to identify the locking
> > +scope.
> > +
> > +With lockdep is enabled, these functions verify that data structure access
> 
> Did you mean *When* lockdep is enabled?

Lets do "When". I most likely should have removed the "is".

> Otherwise no complaints here.
Thanks.

> 
> jon

Sebastian

Re: [PATCH 3/3] Documentation: Add real-time

[Sebastian Andrzej Siewior]

On 2025-07-15 14:29:42 [-0600], Jonathan Corbet wrote:
> So overall it looks good, but I do have one overriding question:
> 
> - Who is the audience for this documentation?
> 
> I think it's an important question to ask, because something this easily
> becomes an unorganized pile of stuff that somebody thought should be
> written down somewhere - better than nothing, but hard for readers to
> use effectively.
> 
> A good first step would be to supply a paragraph or two in the new
> Documentation/real-time/index.rst describing the nature of the
> documentation and who it is intended for.

The main audience are kernel developers.

> Then ... think about whether a new top-level directory under
> Documentation makes sense.  I've been working for years to reduce those,
> so I tend to push back a little when new ones show up.
> 
> - Is this documentation for kernel developers in general, with the idea
>   of maybe helping them to not break PREEMPT_RT so often?  Then perhaps
>   documentation with that focus under core-api/ makes sense.
> 
> - Is it, instead, intended as overall design documentation?  We don't
>   really have a good place for that now, maybe we need a new design/
>   book to gather such material.
> 
> See what I'm getting at?  I'm not saying that these docs *have* to go
> somewhere else, but I do think it's worth thinking about.

While thinking about it I moved it to core-api. There might some user
bits which in terms of setup which might fit under admin-guide.

> Thanks,
> 
> jon

Sebastian