Message-ID: <fe8c7e28-b5fe-4411-b27c-b2efd89a74c7@paulmck-laptop>
Date: Fri, 26 Dec 2025 17:04:56 -0800
From: "Paul E. McKenney" <paulmck@...nel.org>
To: Theodore Tso <tytso@....edu>
Cc: Steven Rostedt <rostedt@...dmis.org>, Sasha Levin <sashal@...nel.org>,
	Julia Lawall <julia.lawall@...ia.fr>,
	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, 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?

							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