[PATCH 0/4] sched.7 and small futex.2 updates

[PATCH 0/4] sched.7 and small futex.2 updates

[Sebastian Andrzej Siewior]

I went through sched.7 and tried to update the real-time bits.
I started looking into futex.2 but then got distracted with the condvar
part and didn't get very far.

Sebastian Andrzej Siewior (4):
  man/man7/sched.7: Update the real-time section
  man/man7/sched.7: Update the documentation references
  man/man2/futex.2: Recycle two gmane URLs
  man/man2/futex.2: Add a pointer to Linux' memory-barrier

 man/man2/futex.2 | 12 ++++-----
 man/man7/sched.7 | 66 +++++++++++++++++++++++++++++++-----------------
 2 files changed, 48 insertions(+), 30 deletions(-)

-- 
2.51.0

[PATCH 1/4] man/man7/sched.7: Update the real-time section

[Sebastian Andrzej Siewior]

Update the outdated information:
- The PREEMPT_RT patch is merged. The patch continues to exist (as of
  now) but is not mandatory.
- The patch can be still downloaded but most people use the git tree
  these days. Add a reference to it.
- CONFIG_PREEMPT_DESKTOP was never thing as far as I remember. It was
  always CONFIG_PREEMPT and its description referred to "low latency
  desktop".
- Within the PREEMPT-RT patch there was a brief window which introduced
  PREEMPT_RT_BASE and PREEMPT_RT_FULL. I am going to ignore this.
- The introduction of PREEMPT_LAZY in 6.13 moved PREEMPT_RT from a
  preemption model to an option.
- The mentioned wiki is deprecated. Update the URL to the new one.

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 man/man7/sched.7 | 58 ++++++++++++++++++++++++++++++++++--------------
 1 file changed, 41 insertions(+), 17 deletions(-)

diff --git a/man/man7/sched.7 b/man/man7/sched.7
index 3299c21dc1ad8..5da631c310636 100644
--- a/man/man7/sched.7
+++ b/man/man7/sched.7
@@ -933,16 +933,12 @@ the following to modify the autogroup nice value for
 .EE
 .in
 .SS Real-time features in the mainline Linux kernel
-.\" FIXME . Probably this text will need some minor tweaking
-.\" ask Carsten Emde about this.
+.\" The archaeologist knows about v2.6.9-mm1-V0.1-realtime-preempt
 Since Linux 2.6.18, Linux is gradually
 becoming equipped with real-time capabilities,
 most of which are derived from the former
 .I realtime\-preempt
 patch set.
-Until the patches have been completely merged into the
-mainline kernel,
-they must be installed to achieve the best real-time performance.
 These patches are named:
 .P
 .in +4n
@@ -953,24 +949,52 @@ they must be installed to achieve the best real-time performance.
 .P
 and can be downloaded from
 .UR http://www.kernel.org\:/pub\:/linux\:/kernel\:/projects\:/rt/
+.UE
+or cloned from a git tree
+.UR https://git.kernel.org\:/pub\:/scm\:/linux\:/kernel\:/git\:/rt\:/linux-stable-rt.git
 .UE .
+The individual releases are maintained as long as
+the matching LTS kernel is maintained.
 .P
-Without the patches and prior to their full inclusion into the mainline
-kernel, the kernel configuration offers only the three preemption classes
+Since 6.12 it possible to enable the real-time preemption
+without the need for any patches.
+The
+.I realtime\-patch
+continues to exist and contains support
+for not yet integrated architectures,
+drivers and features that are in development.
+.P
+Since 6.13 real-time becomes an option
+and not a preemption model.
+With this change,
+the following preemption models are available:
 .BR CONFIG_PREEMPT_NONE ,
 .BR CONFIG_PREEMPT_VOLUNTARY ,
+.BR CONFIG_PREEMPT ,
 and
-.B CONFIG_PREEMPT_DESKTOP
-which respectively provide no, some, and considerable
-reduction of the worst-case scheduling latency.
-.P
-With the patches applied or after their full inclusion into the mainline
-kernel, the additional configuration item
+.BR CONFIG_PREEMPT_LAZY .
+The real-time capabilities can be enabled with the option
 .B CONFIG_PREEMPT_RT
-becomes available.
-If this is selected, Linux is transformed into a regular
+and the preemption model be set to either
+.B CONFIG_PREEMPT
+or
+.BR CONFIG_PREEMPT_LAZY .
+The latter model is less eager to preempt
+.B SCHED_NORMAL
+tasks in an attempt to reduce lock holder preemption.
+It does not affect real-time tasks.
+.P
+With
+.B CONFIG_PREEMPT_RT
+enabled,
+Linux is transformed into a regular
 real-time operating system.
-The FIFO and RR scheduling policies are then used to run a thread
+The
+.BR SCHED_FIFO ,
+.BR SCHED_RR ,
+and
+.B SCHED_DL
+scheduling policies are then used to run a thread
 with true real-time priority and a minimum worst-case scheduling latency.
 .SH NOTES
 The
@@ -1032,5 +1056,5 @@ and
 .I \%Documentation/\:scheduler/\:sched\-nice\-design\:.txt
 .P
 Worth looking at:
-.UR http://rt.wiki.kernel.org/\:index.php
+.UR https://wiki.linuxfoundation.org/\:realtime/\:start
 .UE
-- 
2.51.0

[PATCH 2/4] man/man7/sched.7: Update the documentation references

[Sebastian Andrzej Siewior]

The section refers to .txt files but they have been moved/ renamed to
.rst some time ago. The mentioned sched-rt-group is inconvenient as
people always complained about CONFIG_RT_GROUP_SCHED.
Everything that describes CFS is not wrong but the kernel the kernel
switched to the Earliest Virtual Deadline First (EEVDF) scheduler.

Instead of updating the file links below (and adding new ones), replace
them with a link to the automatically created scheduler documetation
from that folder. This also has some EEVDF bits :)

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 man/man7/sched.7 | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/man/man7/sched.7 b/man/man7/sched.7
index 5da631c310636..2f0cb1792d02a 100644
--- a/man/man7/sched.7
+++ b/man/man7/sched.7
@@ -1048,12 +1048,8 @@ was not possible up to Linux 2.6.17.
 .I Programming for the real world \- POSIX.4
 by Bill O.\& Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0.
 .P
-The Linux kernel source files
-.IR \%Documentation/\:scheduler/\:sched\-deadline\:.txt ,
-.IR \%Documentation/\:scheduler/\:sched\-rt\-group\:.txt ,
-.IR \%Documentation/\:scheduler/\:sched\-design\-CFS\:.txt ,
-and
-.I \%Documentation/\:scheduler/\:sched\-nice\-design\:.txt
+The Linux kernel documentation for the scheduler
+.IR https://docs.kernel.org/\:scheduler
 .P
 Worth looking at:
 .UR https://wiki.linuxfoundation.org/\:realtime/\:start
-- 
2.51.0

[PATCH 3/4] man/man2/futex.2: Recycle two gmane URLs

[Sebastian Andrzej Siewior]

Based on the date in the comment, the here provided URLs should point to
the mails that the gmane URL no longer can.

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 man/man2/futex.2 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man/man2/futex.2 b/man/man2/futex.2
index 69df4036ada7f..027e91b826bf1 100644
--- a/man/man2/futex.2
+++ b/man/man2/futex.2
@@ -6,10 +6,10 @@
 .\"
 .\" FIXME Still to integrate are some points from Torvald Riegel's mail of
 .\" 2015-01-23:
-.\"       http://thread.gmane.org/gmane.linux.kernel/1703405/focus=7977
+.\"       https://lore.kernel.org/lkml/1422037788.29655.0.camel@triegel.csb
 .\"
 .\" FIXME Do we need to add some text regarding Torvald Riegel's 2015-01-24 mail
-.\"       http://thread.gmane.org/gmane.linux.kernel/1703405/focus=1873242
+.\"       https://lore.kernel.org/lkml/1422105142.29655.16.camel@triegel.csb
 .\"
 .TH futex 2 (date) "Linux man-pages (unreleased)"
 .SH NAME
-- 
2.51.0

[PATCH 4/4] man/man2/futex.2: Add a pointer to Linux' memory-barrier

[Sebastian Andrzej Siewior]

The "totally ordered with respect to concurrent operations" part refers
to memory ordering/ atomic update and has nothing to do with the inner
workings of the FUTEX code. It simply tries to express that the futex
operation will compare the supplied argument with that is written in
memory.

This might be a tad too verbose but then there is a fixme asking for
details on the sychronisation. Maybe a pointer to the memory barriers is
enough in terms of the required synchronisaton. Assuming this is related
to the memory value and not the futex internal synchronisation.

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 man/man2/futex.2 | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/man/man2/futex.2 b/man/man2/futex.2
index 027e91b826bf1..fe4a239c3812c 100644
--- a/man/man2/futex.2
+++ b/man/man2/futex.2
@@ -84,16 +84,14 @@ on the same futex word.
 .\"     would be sufficient? Or perhaps for this manual, "serialized" would
 .\"     be sufficient, with a footnote regarding "totally ordered" and a
 .\"     pointer to the memory-barrier documentation?
+Please see
+.IR https://docs.kernel.org/\:next/\:core-api/\:wrappers/\:memory-barriers.html
+for the definition of atomic operations and memory ordering.
 Thus, the futex word is used to connect the synchronization in user space
 with the implementation of blocking by the kernel.
 Analogously to an atomic
 compare-and-exchange operation that potentially changes shared memory,
 blocking via a futex is an atomic compare-and-block operation.
-.\" FIXME(Torvald Riegel):
-.\" Eventually we want to have some text in NOTES to satisfy
-.\" the reference in the following sentence
-.\"     See NOTES for a detailed specification of
-.\"     the synchronization semantics.
 .P
 One use of futexes is for implementing locks.
 The state of the lock (i.e., acquired or not acquired)
-- 
2.51.0

Re: [PATCH 3/4] man/man2/futex.2: Recycle two gmane URLs

[Carlos O'Donell]

On 8/29/25 12:01 PM, Sebastian Andrzej Siewior wrote:
> Based on the date in the comment, the here provided URLs should point to
> the mails that the gmane URL no longer can.
> 
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> ---
>   man/man2/futex.2 | 4 ++--
>   1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man2/futex.2 b/man/man2/futex.2
> index 69df4036ada7f..027e91b826bf1 100644
> --- a/man/man2/futex.2
> +++ b/man/man2/futex.2
> @@ -6,10 +6,10 @@
>   .\"
>   .\" FIXME Still to integrate are some points from Torvald Riegel's mail of
>   .\" 2015-01-23:
> -.\"       http://thread.gmane.org/gmane.linux.kernel/1703405/focus=7977
> +.\"       https://lore.kernel.org/lkml/1422037788.29655.0.camel@triegel.csb

Wrong link?

Should be this link:
https://lore.kernel.org/lkml/1422037145.27573.0.camel@triegel.csb/

Where the discussion is about the unresolved constraint to guarantee FIFO order.

>   .\"
>   .\" FIXME Do we need to add some text regarding Torvald Riegel's 2015-01-24 mail
> -.\"       http://thread.gmane.org/gmane.linux.kernel/1703405/focus=1873242
> +.\"       https://lore.kernel.org/lkml/1422105142.29655.16.camel@triegel.csb

Confirmed, this is correct.

>   .\"
>   .TH futex 2 (date) "Linux man-pages (unreleased)"
>   .SH NAME


-- 
Cheers,
Carlos.

Re: [PATCH 3/4] man/man2/futex.2: Recycle two gmane URLs

[Sebastian Andrzej Siewior]

On 2025-08-29 12:43:26 [-0400], Carlos O'Donell wrote:
> > index 69df4036ada7f..027e91b826bf1 100644
> > --- a/man/man2/futex.2
> > +++ b/man/man2/futex.2
> > @@ -6,10 +6,10 @@
> >   .\"
> >   .\" FIXME Still to integrate are some points from Torvald Riegel's mail of
> >   .\" 2015-01-23:
> > -.\"       http://thread.gmane.org/gmane.linux.kernel/1703405/focus=7977
> > +.\"       https://lore.kernel.org/lkml/1422037788.29655.0.camel@triegel.csb
> 
> Wrong link?
> 
> Should be this link:
> https://lore.kernel.org/lkml/1422037145.27573.0.camel@triegel.csb/
> 
> Where the discussion is about the unresolved constraint to guarantee FIFO order.

I thought it is the longer email, the second that day, where he made
three points. Didn't read it (yet)…

Now FIFO ordering you say. Is it glibc's side or kernel side? The kernel
sorts the futex waiters according their (task's) priority. It is not
FIFO unless the tasks are of equal priority.
So a futex requeue will take the task with the highest priority from
uaddr1 and move it to uaddr2.

Sebastian

Re: [PATCH 4/4] man/man2/futex.2: Add a pointer to Linux' memory-barrier

[Carlos O'Donell]

On 8/29/25 12:02 PM, Sebastian Andrzej Siewior wrote:
> The "totally ordered with respect to concurrent operations" part refers
> to memory ordering/ atomic update and has nothing to do with the inner
> workings of the FUTEX code. It simply tries to express that the futex
> operation will compare the supplied argument with that is written in
> memory.
> 
> This might be a tad too verbose but then there is a fixme asking for
> details on the sychronisation. Maybe a pointer to the memory barriers is
> enough in terms of the required synchronisaton. Assuming this is related
> to the memory value and not the futex internal synchronisation.
> 
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> ---
>   man/man2/futex.2 | 8 +++-----
>   1 file changed, 3 insertions(+), 5 deletions(-)
> 
> diff --git a/man/man2/futex.2 b/man/man2/futex.2
> index 027e91b826bf1..fe4a239c3812c 100644
> --- a/man/man2/futex.2
> +++ b/man/man2/futex.2
> @@ -84,16 +84,14 @@ on the same futex word.
>   .\"     would be sufficient? Or perhaps for this manual, "serialized" would
>   .\"     be sufficient, with a footnote regarding "totally ordered" and a
>   .\"     pointer to the memory-barrier documentation?
> +Please see
> +.IR https://docs.kernel.org/\:next/\:core-api/\:wrappers/\:memory-barriers.html
> +for the definition of atomic operations and memory ordering.

This seems out of place with the flow of the rest of the text.

I suggest adding this as a foot note.

>   Thus, the futex word is used to connect the synchronization in user space
>   with the implementation of blocking by the kernel.
>   Analogously to an atomic
>   compare-and-exchange operation that potentially changes shared memory,
>   blocking via a futex is an atomic compare-and-block operation.
> -.\" FIXME(Torvald Riegel):
> -.\" Eventually we want to have some text in NOTES to satisfy
> -.\" the reference in the following sentence
> -.\"     See NOTES for a detailed specification of
> -.\"     the synchronization semantics.

I think it is acceptable to link to Documentation/memory-barriers.rst, but
the truth is that this document doesn't yet provide all the notes required
to answer the questions wrt a futex. Fundamentally we use spinlocks for futexes
(and some arches use more like parisc), and spinlocks are covered in
"Implicit Kernel Memory Barrires", there isn't any direct connection between
them in the text (and doing so would create a design requirement).

>   .P
>   One use of futexes is for implementing locks.
>   The state of the lock (i.e., acquired or not acquired)


-- 
Cheers,
Carlos.

Re: [PATCH 3/4] man/man2/futex.2: Recycle two gmane URLs

[Carlos O'Donell]

On 8/29/25 1:39 PM, Sebastian Andrzej Siewior wrote:
> On 2025-08-29 12:43:26 [-0400], Carlos O'Donell wrote:
>>> index 69df4036ada7f..027e91b826bf1 100644
>>> --- a/man/man2/futex.2
>>> +++ b/man/man2/futex.2
>>> @@ -6,10 +6,10 @@
>>>    .\"
>>>    .\" FIXME Still to integrate are some points from Torvald Riegel's mail of
>>>    .\" 2015-01-23:
>>> -.\"       http://thread.gmane.org/gmane.linux.kernel/1703405/focus=7977
>>> +.\"       https://lore.kernel.org/lkml/1422037788.29655.0.camel@triegel.csb
>>
>> Wrong link?
>>
>> Should be this link:
>> https://lore.kernel.org/lkml/1422037145.27573.0.camel@triegel.csb/
>>
>> Where the discussion is about the unresolved constraint to guarantee FIFO order.
> 
> I thought it is the longer email, the second that day, where he made
> three points. Didn't read it (yet)…

Given the dates and the disjoint set of topics, my suggestion is the link above.

> Now FIFO ordering you say. Is it glibc's side or kernel side? The kernel
> sorts the futex waiters according their (task's) priority. It is not
> FIFO unless the tasks are of equal priority.

The FIFO order question was a kernel-side question wrt futex semantics.
At least that's how I read the thread. And the issue was resolved, but possibly
not documented. Documentation might include stating "FIFO ordering over all
waiters, or even a subset of waiters (at the same priority level) is not
guaranteed."

Torvald was right that for POSIX condition variables we would naturally want
a FIFO wake order so earlier sleepers are woken first.

> So a futex requeue will take the task with the highest priority from
> uaddr1 and move it to uaddr2.

Right.

-- 
Cheers,
Carlos.

Re: [PATCH 2/4] man/man7/sched.7: Update the documentation references

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2209 bytes --]

Hi Sebastian,

At 2025-08-29T18:01:58+0200, Sebastian Andrzej Siewior wrote:
> diff --git a/man/man7/sched.7 b/man/man7/sched.7
> index 5da631c310636..2f0cb1792d02a 100644
> --- a/man/man7/sched.7
> +++ b/man/man7/sched.7
> @@ -1048,12 +1048,8 @@ was not possible up to Linux 2.6.17.
>  .I Programming for the real world \- POSIX.4
>  by Bill O.\& Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0.
>  .P
> -The Linux kernel source files
> -.IR \%Documentation/\:scheduler/\:sched\-deadline\:.txt ,
> -.IR \%Documentation/\:scheduler/\:sched\-rt\-group\:.txt ,
> -.IR \%Documentation/\:scheduler/\:sched\-design\-CFS\:.txt ,
> -and
> -.I \%Documentation/\:scheduler/\:sched\-nice\-design\:.txt
> +The Linux kernel documentation for the scheduler
> +.IR https://docs.kernel.org/\:scheduler
>  .P
>  Worth looking at:
>  .UR https://wiki.linuxfoundation.org/\:realtime/\:start

This is not a gating/blocking suggestion.

You might consider adding a real hyperlink similar to the one at the
bottom of the context.

Thus, something like (hand-written diff):

-The Linux kernel source files
-.IR \%Documentation/\:scheduler/\:sched\-deadline\:.txt ,
-.IR \%Documentation/\:scheduler/\:sched\-rt\-group\:.txt ,
-.IR \%Documentation/\:scheduler/\:sched\-design\-CFS\:.txt ,
-and
-.I \%Documentation/\:scheduler/\:sched\-nice\-design\:.txt
+.UR https://docs.kernel.org/\:scheduler
+Linux kernel scheduler documentation
+.UE

Here's the description of the UR and UE macros.

groff_man(7):
     .UR uri
     .UE [trailing‐text]
            Identify uri as an RFC 3986 URI hyperlink with the text
            between the two macro calls as the link text.  An argument
            to UE is placed after the link text without intervening
            space.  uri may not be visible in the rendered document if
            hyperlinks are enabled and supported by the output driver.
            If they are not, uri is set in angle brackets after the link
            text and before trailing‐text.  If hyperlinking is enabled
            but there is no link text, uri is formatted and hyperlinked
            without angle brackets.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 4/4] man/man2/futex.2: Add a pointer to Linux' memory-barrier

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1085 bytes --]

Hi Sebastian,

At 2025-08-29T18:02:00+0200, Sebastian Andrzej Siewior wrote:
> diff --git a/man/man2/futex.2 b/man/man2/futex.2
> index 027e91b826bf1..fe4a239c3812c 100644
> --- a/man/man2/futex.2
> +++ b/man/man2/futex.2
> @@ -84,16 +84,14 @@ on the same futex word.
>  .\"     would be sufficient? Or perhaps for this manual, "serialized" would
>  .\"     be sufficient, with a footnote regarding "totally ordered" and a
>  .\"     pointer to the memory-barrier documentation?
> +Please see
> +.IR https://docs.kernel.org/\:next/\:core-api/\:wrappers/\:memory-barriers.html
> +for the definition of atomic operations and memory ordering.
>  Thus, the futex word is used to connect the synchronization in user space
>  with the implementation of blocking by the kernel.
>  Analogously to an atomic

(not a gating/blocking suggestion)

As with my previous comment, you might make the new text a hyperlink.

+See the
+.UR https://docs.kernel.org/\:next/\:core-api/\:wrappers/\:memory-barriers.html
+Linux kernel's guide to atomic operations and memory ordering
+.UE .

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 3/4] man/man2/futex.2: Recycle two gmane URLs

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1461 bytes --]

Hi Sebastian,

On Fri, Aug 29, 2025 at 06:01:59PM +0200, Sebastian Andrzej Siewior wrote:
> Based on the date in the comment, the here provided URLs should point to
> the mails that the gmane URL no longer can.
> 
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>

Thanks!  I've applied the patch.
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=2f5536dd43eaffdcb2bf00addf71aac4596c7f8c>
(use port 80).


Have a lovely day!
Alex

> ---
>  man/man2/futex.2 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man2/futex.2 b/man/man2/futex.2
> index 69df4036ada7f..027e91b826bf1 100644
> --- a/man/man2/futex.2
> +++ b/man/man2/futex.2
> @@ -6,10 +6,10 @@
>  .\"
>  .\" FIXME Still to integrate are some points from Torvald Riegel's mail of
>  .\" 2015-01-23:
> -.\"       http://thread.gmane.org/gmane.linux.kernel/1703405/focus=7977
> +.\"       https://lore.kernel.org/lkml/1422037788.29655.0.camel@triegel.csb
>  .\"
>  .\" FIXME Do we need to add some text regarding Torvald Riegel's 2015-01-24 mail
> -.\"       http://thread.gmane.org/gmane.linux.kernel/1703405/focus=1873242
> +.\"       https://lore.kernel.org/lkml/1422105142.29655.16.camel@triegel.csb
>  .\"
>  .TH futex 2 (date) "Linux man-pages (unreleased)"
>  .SH NAME
> -- 
> 2.51.0
> 

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/4] man/man7/sched.7: Update the real-time section

[Juri Lelli]

Hi!

On 29/08/25 18:01, Sebastian Andrzej Siewior wrote:

...

> -The FIFO and RR scheduling policies are then used to run a thread
> +The
> +.BR SCHED_FIFO ,
> +.BR SCHED_RR ,
> +and
> +.B SCHED_DL

I believe SCHED_DEADLINE would be more correct?

Thanks,
Juri