Message-ID: <b6c33ada-5141-c999-d038-e815d21b978a@inria.fr>
Date: Sat, 27 Dec 2025 07:16:28 +0100 (CET)
From: Julia Lawall <julia.lawall@...ia.fr>
To: "Paul E. McKenney" <paulmck@...nel.org>
cc: Theodore Tso <tytso@....edu>, Steven Rostedt <rostedt@...dmis.org>, 
    Sasha Levin <sashal@...nel.org>, Gabriele Paoloni <gpaoloni@...hat.com>, 
    Kate Stewart <kstewart@...uxfoundation.org>, 
    Chuck Wolber <chuckwolber@...il.com>, Dmitry Vyukov <dvyukov@...gle.com>, 
    Mark Rutland <mark.rutland@....com>, Thomas Gleixner <tglx@...utronix.de>, 
    Lorenzo Stoakes <lorenzo.stoakes@...cle.com>, 
    Shuah Khan <skhan@...uxfoundation.org>, Chris Mason <clm@...a.com>, 
    linux-kernel@...r.kernel.org
Subject: Re: Follow-up on Linux-kernel code accessibility



On Fri, 26 Dec 2025, Paul E. McKenney wrote:

> On Fri, Dec 26, 2025 at 02:22:17PM -0500, Theodore Tso wrote:
> > On Fri, Dec 26, 2025 at 11:48:30AM -0500, Steven Rostedt wrote:
> > > Agreed, but knowing what the function is doing should give you some idea of
> > > how it is doing it.
> > >
> > >   "Loop doing repeated quiescent-state forcing until the grace period ends."
> > >
> > > Is the only description of "what the function is doing", but it gives you
> > > no clue to why it's using those magic numbers. There should be comments
> > > about how the magic numbers relate to the what.
> >
> > Sure, but rcu_gp_fqs_loop() is a static, internal function.  I agree
> > that better documentation would be usefui for people who want to
> > modify the internals of the RCU infrastructure, but it's not something
> > that should be in kernel documentation for newcomers to kernel
> > development.
> >
> > When we talk about making the kernel code more accessible, it's really
> > important to keep in mind that different audiences may have different
> > needs, and too much information can be just as confusing as too
> > little.  It seems likely that most newcomers aren't going to be
> > looking to make changes to important systems like RCU.
> >
> > That being said, even though most newcomers aren't probably going to
> > be making changes to file systems, as a file system maintainer I
> > admittedly to have a vested interest in making easier for
> > intermediate-level kernel developers who might take an interest to
> > ext4 development to have an easy path to do so.  So I get where Paul
> > is coming from.
> >
> > When we're talking about making the kernel code more accessible, we
> > need need to be very explicit about which target audiences we are
> > targetting, because the strategies might be different for different
> > readers.
>
> Here is how I group them:
>
> 1.	RCU users in the Linux kernel.	Largish group.	Addressed by much
> 	of the Documentation/RCU contents, the occasional LWN article,
> 	blog posts, and by RCU experts in various subsystems.
>
> 2.	RCU users in userspace.  Modest group, but growing.  LWN articles,
> 	blog posts, an academic paper or three, and a number of people
> 	who have implemented some form or another of RCU.
>
> 3.	Userspace RCU implementations.  Smallish group, but there are
> 	quite a few implementations out there.  I don't deliberately
> 	target anything to this group, but it is quite possible that
> 	some of the writings for the other groups have been helpful.
>
> 4.	Linux-kernel RCU implementation.  Small group, though a largish
> 	one if we include all the people who have gotten at least one
> 	patch accepted.  Comments, Linux-kernel RCU Design Documents [1],
> 	Documentation/RCU/Design, a few LWN articles, a few blog posts,
> 	and the several regular developers and maintainers.
>
> And I would like to think that Section 9.5 of "Is Parallel Programming
> Hard, And, If So, What Can You Do About It?" [2] has been helpful.
>
> What groups should I be adding?

In the case of the scheduler, I observe some unexpected behavior, and then
I have the feeling that I backtrack through the code coming from a
direction that was not anticipated by the person who wrote the comments
(sometimes inline comments, more likely the comments in the commit tht
introduced the line I am wondering about).  But I'm not sure how to place
RCU.  My impression is that it has a more monolithic implementation, and
that I would only ever consider it to be a block box, not something I
would debug my way into.  But perhaps people felt that way about the
scheduler functions I am looking at as well.  Over time, there have surely
been performance improvements in RCU as well.  It seems hard to anticipate
what information people will need.

Maybe one could consider that division by a constant is sufficiently rare
in the kernel that it should always be documented?

julia



>
> 							Thanx, Paul
>
> [1] https://docs.google.com/document/d/1GCdQC8SDbb54W1shjEXqGZ0Rq8a6kIeYutdSIajfpLA/edit?pli=1&tab=t.0#heading=h.ytgz5i5df43s
>
> [2] https://www.kernel.org/pub/linux/kernel/people/paulmck/perfbook/perfbook.html
>

Powered by blists - more mailing lists