[PATCH v2 1/2] sched/doc: add a preemption model overview

[PATCH v2 1/2] sched/doc: add a preemption model overview

[Quchaosheng]

The scheduler documentation describes the individual scheduling classes
and various tuning knobs, but there is nothing that describes the
preemption models themselves.  The only place where they are documented
is the kernel-parameters entry for "preempt=", which explains the boot
time parameter but not the models it selects.

Add Documentation/scheduler/sched-preemption.rst, covering the four
models, how a scheduling request is honoured under each of them, and
which of them can be selected at runtime.

The overview follows the scheduling request: a wakeup makes a task
runnable, the scheduler decides what has to leave the CPU and sets
TIF_NEED_RESCHED or TIF_NEED_RESCHED_LAZY on it, and the preemption model
decides where that request is honoured.

Assisted-by: LLM
Suggested-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: Quchaosheng <quchaosheng000406@163.com>
---

Changes in v2:
- Rewrite the overview around the scheduling request instead of walking
  through resched_curr_lazy() and scheduler_tick().  Sebastian asked for the
  bird's-eye view; the code-level walkthrough was not an overview.
- Drop the measurement section.  It claimed lazy exists to avoid an IPI to
  every CPU with a runnable CFS task, which is wrong: a cross-CPU wakeup
  targets one CPU.  The point of lazy is run-to-completion, so that in-kernel
  work finishes and every lock is dropped before the CPU is given up.
- Drop the "tasks also yield contended spinlocks" wording from the model
  table; that belongs in kernel-parameters.txt, where it already is.
- Fold the debugfs file into the section on selecting the model at runtime
  instead of giving it a section of its own.
 Documentation/scheduler/index.rst            |  1 +
 Documentation/scheduler/sched-preemption.rst | 84 ++++++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 Documentation/scheduler/sched-preemption.rst

diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
index 17ce8d76befc..d6d75421756a 100644
--- a/Documentation/scheduler/index.rst
+++ b/Documentation/scheduler/index.rst
@@ -23,5 +23,6 @@ Scheduler
     sched-stats
     sched-ext
     sched-debug
+    sched-preemption
 
     text_files
diff --git a/Documentation/scheduler/sched-preemption.rst b/Documentation/scheduler/sched-preemption.rst
new file mode 100644
index 000000000000..e40c4f5f7476
--- /dev/null
+++ b/Documentation/scheduler/sched-preemption.rst
@@ -0,0 +1,84 @@
+=====================
+Scheduler preemption
+=====================
+
+The kernel can be built to run kernel code either uninterruptibly, or with
+varying degrees of preemptibility.  These are the *preemption models*.
+They apply to kernel code only: a task running in user space is always
+preempted by the scheduler, whichever model is selected.
+
+When CONFIG_PREEMPT_DYNAMIC is enabled the preemption model can additionally
+be selected at boot time with the ``preempt=`` command line parameter, without
+rebuilding the kernel.  See
+Documentation/admin-guide/kernel-parameters.txt for the parameter itself.
+The active model can also be read and changed through
+/sys/kernel/debug/sched/preempt, which exists for debugging purposes and may
+change.
+
+The models selectable at runtime are:
+
+	=========	====================================================
+	none		No preemption of kernel code other than at explicit
+			``cond_resched()`` / blocking points.
+	voluntary	As ``none``, plus ``might_sleep()`` sites.
+	full		Any section that is not explicitly preempt disabled
+			may be preempted at any time.
+	lazy		As ``full``, except that the scheduling request is
+			delayed until the return to user space or the next
+			tick, whichever comes first.  This delay does not
+			apply to real-time tasks.
+	=========	====================================================
+
+Not every model is available on every kernel.  An architecture that provides
+lazy-preempt support offers only ``full`` and ``lazy``, and ``none`` and
+``voluntary`` are rejected there.  A PREEMPT_RT kernel always offers ``full``,
+and ``lazy`` as well if the architecture provides it.
+
+The model that is actually active is reported in the boot log::
+
+	Dynamic Preempt: full
+
+Honouring a scheduling request
+==============================
+
+A wakeup makes a task runnable, and the scheduler then decides whether it
+should run.  If there is an idle CPU which is suitable then the task is moved
+there.  Otherwise the scheduler has to decide which task to preempt, and the
+task that has to leave the CPU gets a reschedule flag.  In the tracing output
+this is the ``need-resched`` column, ``N`` for TIF_NEED_RESCHED and ``l`` for
+TIF_NEED_RESCHED_LAZY.
+
+The kernel then has to honour that request.  A task executing in user space
+can always be preempted; a task executing in kernel space can only be
+preempted where it is safe to do so, and how that is decided is what
+separates the models:
+
+``none``
+	Code paths with long loops contain explicit ``cond_resched()`` calls,
+	which perform the scheduling.
+
+``voluntary``
+	As ``none``, and functions which are known to be able to block gain
+	such a call as well.
+
+``full``
+	Explicit preemption points are no longer involved.  The kernel tracks
+	whether it may be preempted and schedules once the request can be
+	honoured.
+
+``lazy``
+	As ``full``, with one difference: the request the fair scheduler sets
+	is TIF_NEED_RESCHED_LAZY, which is not honoured immediately even where
+	it could be.  It is delayed until the task returns to user space, so
+	that the in-kernel work runs to completion and every lock has been
+	dropped before the CPU is given up.  If the task has not scheduled on
+	its own by then, the request is turned into a full TIF_NEED_RESCHED on
+	the next HZ tick; this is visible as ``B`` in the ``need-resched``
+	column.
+
+Real-time tasks always use TIF_NEED_RESCHED, so the delay above does not
+apply to them.  ``lazy`` is therefore not a replacement for PREEMPT_RT: it
+keeps most of the responsiveness of ``full`` for SCHED_NORMAL tasks while
+letting them run to completion, which avoids leaving a lock behind that
+another task will immediately ask for, and avoids pushing cache-hot data out
+that would have to be pulled back in.
-- 
2.43.0

[PATCH v2 2/2] docs: kernel-parameters: fix a truncated sentence for preempt=lazy

[Quchaosheng]

The "lazy" entry ends with:

  One preemption is when the task returns to user space.

which is not a sentence.  It is a leftover from shortening "One such
preemption is when the task returns to user space."

Writing it as "preemption point" reads better than restoring the missing
word, so use that.

Fixes: f66e4a996582 ("sched/core: Update kernel boot parameters for LAZY preempt.")
Assisted-by: LLM
Suggested-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: Quchaosheng <quchaosheng000406@163.com>
---

Changes in v2:
- Use "preemption point", Sebastian's wording, instead of restoring the
  missing word.
 Documentation/admin-guide/kernel-parameters.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 33cd30996e47..83261eb6b26b 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -5453,8 +5453,8 @@ Kernel parameters
 			lazy - Scheduler controlled. Similar to full but instead
 			       of preempting the task immediately, the task gets
 			       one HZ tick time to yield itself before the
-			       preemption will be forced. One preemption is when the
-			       task returns to user space.
+			       preemption will be forced. One such preemption
+			       point is when the task returns to user space.
 
 	print-fatal-signals=
 			[KNL] debug: print fatal signals
-- 
2.43.0

Re: [PATCH v2 1/2] sched/doc: add a preemption model overview

[Sebastian Andrzej Siewior]

On 2026-09-22 16:31:00 [+0800], Quchaosheng wrote:
> The scheduler documentation describes the individual scheduling classes
> and various tuning knobs, but there is nothing that describes the
> preemption models themselves.  The only place where they are documented
> is the kernel-parameters entry for "preempt=", which explains the boot
> time parameter but not the models it selects.
…
> Assisted-by: LLM
> Suggested-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> Signed-off-by: Quchaosheng <quchaosheng000406@163.com>

This reads very nice.
Reviewed-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>

Once comment bellow.

…
> --- /dev/null
> +++ b/Documentation/scheduler/sched-preemption.rst
> @@ -0,0 +1,84 @@
…
> +separates the models:
> +
> +``none``
> +	Code paths with long loops contain explicit ``cond_resched()`` calls,
> +	which perform the scheduling.
> +
> +``voluntary``
> +	As ``none``, and functions which are known to be able to block gain
> +	such a call as well.

I know what you are trying to say but it does not sound obvious that you
refer here to cond_resched(). At least to me.

> +
> +``full``
> +	Explicit preemption points are no longer involved.  The kernel tracks
> +	whether it may be preempted and schedules once the request can be
> +	honoured.
…

Sebastian

Re: [PATCH v2 2/2] docs: kernel-parameters: fix a truncated sentence for preempt=lazy

[Sebastian Andrzej Siewior]

On 2026-09-22 16:31:01 [+0800], Quchaosheng wrote:
> The "lazy" entry ends with:
> 
>   One preemption is when the task returns to user space.
> 
> which is not a sentence.  It is a leftover from shortening "One such
> preemption is when the task returns to user space."
> 
> Writing it as "preemption point" reads better than restoring the missing
> word, so use that.
> 
> Fixes: f66e4a996582 ("sched/core: Update kernel boot parameters for LAZY preempt.")
> Assisted-by: LLM
> Suggested-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> Signed-off-by: Quchaosheng <quchaosheng000406@163.com>

Reviewed-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>

Sebastian