[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

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

[Sebastian Andrzej Siewior]

On 2025-08-30 02:28:57 [-0500], G. Branden Robinson wrote:
> Hi Sebastian,
Hi Branden,

> > -.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

Thank you for the suggestion. I keep The UR macro as you suggested but I
move the description before the UR macro. The reason is that once it is
as suggested, `man' does not show the link anymore. I can click on the
link via `man -H' but I would prefer to see it right away.

Sebastian

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

[Sebastian Andrzej Siewior]

On 2025-09-02 09:24:28 [+0200], Juri Lelli wrote:
> 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?

yes, thanks.

> Thanks,
> Juri

Sebastian

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

[G. Branden Robinson]

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

[CC list pruned heavily]

Hi Sebastian,

At 2025-09-08T15:51:34+0200, Sebastian Andrzej Siewior wrote:
> On 2025-08-30 02:28:57 [-0500], G. Branden Robinson wrote:
> > 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
> 
> Thank you for the suggestion. I keep The UR macro as you suggested but
> I move the description before the UR macro. The reason is that once it
> is as suggested, `man' does not show the link anymore. I can click on
> the link via `man -H' but I would prefer to see it right away.

Hmm, that sounds like a bug.  What versions of man(1) and groff is your
system running?

$ man --version # This will fail if it's mandoc(1)'s "man".
$ groff --version

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

[Sebastian Andrzej Siewior]

On 2025-08-29 13:46:19 [-0400], Carlos O'Donell wrote:
> 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).

There might be two things to it. The spinlocks are used in kernel and
synchronize the kernel internal state. The memory barriers might be
important in regard to how the futex word should be updated atomically.

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

Sebastian

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

[Sebastian Andrzej Siewior]

On 2025-09-08 09:11:02 [-0500], G. Branden Robinson wrote:
> [CC list pruned heavily]
> 
> Hi Sebastian,
Hi Branden,

> Hmm, that sounds like a bug.  What versions of man(1) and groff is your
> system running?

Just to be clear: The following
| .P
| .UR https://docs.kernel.org/\:scheduler
| The Linux kernel documentation for the scheduler
| .UE
| .P
| Worth looking at:
| .UR https://wiki.linuxfoundation.org/\:realtime/\:start
| .UE

rendered via "man $file" as:
|
|       The Linux kernel documentation for the scheduler
|
|       Worth looking at: https://wiki.linuxfoundation.org/realtime/start

> $ man --version # This will fail if it's mandoc(1)'s "man".
> $ groff --version

man 2.13.1
GNU grops (groff) version 1.23.0
GNU troff (groff) version 1.23.0

> Regards,
> Branden

Sebastian

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

[G. Branden Robinson]

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

Hi Sebastian,

At 2025-09-08T16:25:08+0200, Sebastian Andrzej Siewior wrote:
> On 2025-09-08 09:11:02 [-0500], G. Branden Robinson wrote:
> > Hmm, that sounds like a bug.  What versions of man(1) and groff is
> > your system running?
> 
> Just to be clear: The following
> | .P
> | .UR https://docs.kernel.org/\:scheduler
> | The Linux kernel documentation for the scheduler
> | .UE
> | .P
> | Worth looking at:
> | .UR https://wiki.linuxfoundation.org/\:realtime/\:start
> | .UE
> 
> rendered via "man $file" as:
> |
> |       The Linux kernel documentation for the scheduler
> |
> |       Worth looking at: https://wiki.linuxfoundation.org/realtime/start

Understood.  It might be the problem I think it is.

> > $ man --version # This will fail if it's mandoc(1)'s "man".
> > $ groff --version
> 
> man 2.13.1
> GNU grops (groff) version 1.23.0
> GNU troff (groff) version 1.23.0

Okay.  What terminal type are you using?  xterm, gnome-terminal, Linux
VT, etc.?

Also, try this:

$ MANROFFOPT=-rU0 man $your_sched_page

Regards,
Branden

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

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

[Sebastian Andrzej Siewior]

On 2025-09-08 09:29:15 [-0500], G. Branden Robinson wrote:
> Hi Sebastian,
Hi Branden,

> > > $ man --version # This will fail if it's mandoc(1)'s "man".
> > > $ groff --version
> > 
> > man 2.13.1
> > GNU grops (groff) version 1.23.0
> > GNU troff (groff) version 1.23.0
> 
> Okay.  What terminal type are you using?  xterm, gnome-terminal, Linux
> VT, etc.?

lxterminal 0.4.1-1

> Also, try this:
> 
> $ MANROFFOPT=-rU0 man $your_sched_page

So this renders is as

| The Linux kernel documentation for the scheduler ⟨https://docs.kernel.org/scheduler⟩

which would be okay. So the problem is more on my end then?

> Regards,
> Branden

Sebastian

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

[G. Branden Robinson]

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

Hi Sebastian,

At 2025-09-08T16:34:11+0200, Sebastian Andrzej Siewior wrote:
> On 2025-09-08 09:29:15 [-0500], G. Branden Robinson wrote:
> > Okay.  What terminal type are you using?  xterm, gnome-terminal,
> > Linux VT, etc.?
> 
> lxterminal 0.4.1-1
> 
> > Also, try this:
> > 
> > $ MANROFFOPT=-rU0 man $your_sched_page
> 
> So this renders is as
> 
> | The Linux kernel documentation for the scheduler ⟨https://docs.kernel.org/scheduler⟩
> 
> which would be okay. So the problem is more on my end then?

Yes and no.  You've done nothing wrong, but your system configuration is
manifesting a problem.  It sounds like lxterminal doesn't support OSC 8
escape sequences[1], but handles unsupported ECMA-48 escape sequences
correctly, ignoring them instead of making the terminal screen a mess.

This same problem was raised by Helge Kreutzmann last month.  I expect
we're starting to see it more frequently because groff 1.23.0 (released
July 2023) finally made it into a Debian stable release, and there are
even more Debian users than I suspected.

https://lore.kernel.org/linux-man/20250825230420.2dl2kkchtmkwjge7@illithid/

There are a number of workarounds while the community sorts out an
end-to-end solution that will involve cooperation between grotty(1) [on
my plate], ncurses/terminfo, and, ideally, terminal emulator
maintainers.  (Strictly speaking, the last group doesn't _need_ to be
involved; anybody could submit patches to ncurses's terminfo database to
advertise relevant terminal types' support for a so-far-unnamed
capability representing OSC 8 support.)  Beyond those mentioned at the
top of the foregoing mail, here's another approach you could put in your
(more or less POSIX-conforming) shell's startup file.

case "$TERM" in
xterm*) MANROFFOPT=-rU0 ;;
*) ;;
esac
export MANROFFOPT

(I don't see a terminal type entry for "lxterminal" in ncurses's
"terminfo.src" file; this isn't a problem as long as lxterminal _very
faithfully_ emulates xterm.  If it doesn't, an lxterminal developer or
power user should probably submit a type description.  This is true
irrespective of OSC 8 support.)

I'm sorry for the difficulty; advancing the terminal emulation state of
the art takes the work of multiple pairs of hands.

Regards,
Branden

[1] https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda

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

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

[Sebastian Andrzej Siewior]

On 2025-09-08 10:02:48 [-0500], G. Branden Robinson wrote:
> Hi Sebastian,
Hi Branden,

> There are a number of workarounds while the community sorts out an
> end-to-end solution that will involve cooperation between grotty(1) [on
> my plate], ncurses/terminfo, and, ideally, terminal emulator
> maintainers.  (Strictly speaking, the last group doesn't _need_ to be
> involved; anybody could submit patches to ncurses's terminfo database to
> advertise relevant terminal types' support for a so-far-unnamed
> capability representing OSC 8 support.)  Beyond those mentioned at the
> top of the foregoing mail, here's another approach you could put in your
> (more or less POSIX-conforming) shell's startup file.
> 
> case "$TERM" in
> xterm*) MANROFFOPT=-rU0 ;;
> *) ;;
> esac
> export MANROFFOPT

I see. TERM says xterm-256color so that will work. It also works for
screen.xterm-256color and tmux-256color. 

Do you suggest everyone should use that?
Is this something that regressed recently (you mentioned that Debian
stable is using 2.13.1 and more people use it than expected) or was this
always like this?
I could try to route this towards Debian in case it helps.

> (I don't see a terminal type entry for "lxterminal" in ncurses's
> "terminfo.src" file; this isn't a problem as long as lxterminal _very
> faithfully_ emulates xterm.  If it doesn't, an lxterminal developer or
> power user should probably submit a type description.  This is true
> irrespective of OSC 8 support.)

Based on $TERM I would hope so ;)

> I'm sorry for the difficulty; advancing the terminal emulation state of
> the art takes the work of multiple pairs of hands.

No worries. Would you _now_ say that you would prefer the "title" before
UE macro (as suggested) or before the UR macro (without a URL
description).

> Regards,
> Branden

Sebastian

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

[G. Branden Robinson]

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

Hi Sebastian,

At 2025-09-08T17:44:13+0200, Sebastian Andrzej Siewior wrote:
> On 2025-09-08 10:02:48 [-0500], G. Branden Robinson wrote:
> > There are a number of workarounds while the community sorts out an
> > end-to-end solution that will involve cooperation between grotty(1)
> > [on my plate], ncurses/terminfo, and, ideally, terminal emulator
> > maintainers.  (Strictly speaking, the last group doesn't _need_ to
> > be involved; anybody could submit patches to ncurses's terminfo
> > database to advertise relevant terminal types' support for a
> > so-far-unnamed capability representing OSC 8 support.)  Beyond those
> > mentioned at the top of the foregoing mail, here's another approach
> > you could put in your (more or less POSIX-conforming) shell's
> > startup file.
> > 
> > case "$TERM" in
> > xterm*) MANROFFOPT=-rU0 ;;
> > *) ;;
> > esac
> > export MANROFFOPT
> 
> I see. TERM says xterm-256color so that will work. It also works for
> screen.xterm-256color and tmux-256color. 

I would not necessarily have expected the latter given that the
glob-like pattern I proposed should not have matched them.  However,
being terminal multiplexors, they may be doing something clever.  If it
works, and you're happy, I'm happy!

> Do you suggest everyone should use that?

Not necessarily.  I know for a fact that gnome-terminal supports OSC 8,
but when you launch it, it does not update its process environment to
include "TERM=vte" prior to forking a shell.  But neither does it
inherit a $TERM from whatever process launches it; instead, and
consistently with comments in "terminfo.src", it appears to
`putenv("TERM=xterm-256color")`, which, according to Thomas Dickey, is
incorrect in several respects.  I know that Thomas is pretty reluctant
to add OSC 8 support to xterm, so unless we both (1) get a terminfo
capability to express the availability of a hyperlink feature[1] and (2)
can convince gnome-terminal's developers to advertise a more accurate
terminal type when launching the shell it attaches to its
pseudoterminal, there's not much hope for progress here.

> Is this something that regressed recently (you mentioned that Debian
> stable is using 2.13.1 and more people use it than expected)

It's the version of groff that matters here, not man-db.

> or was this always like this?

groff 1.23.0 introduced support for OSC 8.  In the stock GNU version,
support for it was not enabled by default on terminals.

In Debian's package, it _is_ enabled by default on terminals.

https://sources.debian.org/src/groff/1.23.0-9/debian/patches/man-hyperlinks.patch

And in the forthcoming groff 1.24 release, unless I back out the change,
it also will be.

> I could try to route this towards Debian in case it helps.

Colin Watson is the package maintainer; technically, I'm the
co-maintainer but have not contributed greatly to package maintenance.
He's aware of the issue.  It may be that Debian should revert this
patch, and will need to patch it again the other way when groff 1.24
gets released.  A package maintainer's users are thousands of people; in
my role as groff's GNU maintainer, my users are mostly package
maintainers (a hundred people as a very generous estimate, most of whom
the groff mailing list never hears from) and people enthusiastic about
building and installing groff from source; this audience has
above-average familiarity with groff.

I don't know that there is a good solution benefitting everyone that
doesn't involve getting terminal emulator maintainers to cooperate
better with ncurses generally and the terminfo database specifically.

> > (I don't see a terminal type entry for "lxterminal" in ncurses's
> > "terminfo.src" file; this isn't a problem as long as lxterminal
> > _very faithfully_ emulates xterm.  If it doesn't, an lxterminal
> > developer or power user should probably submit a type description.
> > This is true irrespective of OSC 8 support.)
> 
> Based on $TERM I would hope so ;)

Well, gnome-terminal claims the same thing, but the veracity of the
claim leaves much to be desired according to the comments in
"terminfo.src".

https://github.com/ThomasDickey/ncurses-snapshots/blob/5f58399b2de47ed14bdfe3a0cb149293b27893d5/misc/terminfo.src#L6394

I can't say much about lxterminal except that it seems to work enough
like xterm in brief experiments with rendering moderately complex groff
man pages (like grotty(1)).  As noted earlier, the version I have
appears not to support OSC 8, but xterm-256color doesn't either so I
don't see a problem with it.

> > I'm sorry for the difficulty; advancing the terminal emulation state
> > of the art takes the work of multiple pairs of hands.
> 
> No worries. Would you _now_ say that you would prefer the "title"
> before UE macro (as suggested) or before the UR macro (without a URL
> description).

If by "title" you mean what I call the "link text", that should go
between the `UR` and `UE`.  For now I recommend composing man pages
"correctly", meaning with recourse to hyperlinks using link text
wherever it seems appropriate to do so.  If this problem with terminal
emulator capabilities resists solution for a long time, the style
guidelines for the Linux man-pages project might need to counsel use of
the `UR`/`UE` and `MT`/`ME` macros only like this.

.UR http://what.ever/
.UE

That is, with no link text at all, which the man(7) macro package will
degrade gracefully to an angle-brackted visible URL formatted as text on
all devices.

I'd hate for that to become part of any project's man page style guide,
however, because if we do get the OSC 8 terminal capability problem
fixed, I expect it would take many years to unwind the workaround in
dozens or hundreds of man pages.  Plus, the original contributors will
often have moved on in the meantime.  We have decades of experience with
crafting intellgible hyperlink text--unhelpful phrasing like "find an
example <a href="http://example.com">here</a>" is rarer now than it was
in 1999.  My view is that people should write high quality man pages,
groff(1) should do its best to render them, and if something goes wrong
after that point, attention should turn to the rendering device.

In practice most deployed systems have few users (often only one), and
those few users have strong terminal emulator preferences that are slow
to change.  Configuring a shell startup file as advised earlier, or
modifying (on Debian systems, at least) "/etc/groff/man.local" to force
the `U` register on or off as mentioned in my reply to Helge, should
produce desirable output.

Big distributors like Fedora and Debian, by contrast, tend to support
many different terminal emulators and there's no telling which their
users will pick.  They may be better advised to not patch groff 1.23.0
as Colin did, and to patch "/etc/groff/man.local" (or wherever they
install this file, whose location is determined by groff's "configure"
script) to say `.nr U 0`.

But I try not to make strident suggestions to package maintainers.  (If
a configuration is unquestionably correct for nearly all users, it
should be groff's default.)  I had that job myself for several years.
Package maintainers know their users better than I do as an upstream
developer.  I try to provide options and offer helpful advice.

https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/tmac/man.local?h=1.23.0#n5

(That conditional in groff 1.23.0 could have been written better--I
unwittingly laid a trap that Colin walked into: PDF hyperlinking support
was not yet fully armed and operational in 1.23.0, a problem the stock
configuration did not expose.  We got him pulled out,[1] and PDF
hyperlinking support has landed in the forthcoming groff 1.24.0.)

Regards,
Branden

[1] https://salsa.debian.org/debian/groff/-/merge_requests/6/diffs

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