Message-ID: <8c575ab1-d9bc-4af3-ac8d-724fdd6c1b19@paulmck-laptop>
Date: Mon, 12 Jan 2026 08:57:11 -0800
From: "Paul E. McKenney" <paulmck@...nel.org>
To: Julia Lawall <julia.lawall@...ia.fr>
Cc: Steven Rostedt <rostedt@...dmis.org>, Theodore Tso <tytso@....edu>,
	"Dr. David Alan Gilbert" <dave@...blig.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 Mon, Jan 12, 2026 at 08:05:54AM +0100, Julia Lawall wrote:
> 
> 
> On Sun, 11 Jan 2026, Paul E. McKenney wrote:
> 
> > On Sun, Jan 11, 2026 at 12:11:51PM -0500, Steven Rostedt wrote:
> > > On Sat, 10 Jan 2026 19:30:40 -0800
> > > "Theodore Tso" <tytso@....edu> wrote:
> > > >
> > > > Steven, you may disagree with this conclusion, but speaking
> > > > personally, everything that I've read on this thread strongly confirms
> > > > it.
> > >
> > > I'm not talking about someone with no knowledge about the kernel. If
> > > someone has a strong understanding of how an operating system works,
> > > and a general idea of the system, looking at the comments in the code
> > > should be enough for them to figure out the understanding of what is
> > > happening.
> > >
> > > I look at it as two levels. There's an architectural understanding
> > > (which is achieved via books and design documents and such) and then
> > > there's the implementation details. The implementation details should
> > > be expressed in comments, and actually avoided when possible from the
> > > design and architectural documentation. That's because the
> > > implementation can change, and does often.
> >
> > You seem to be assuming that the implementation can always be understood
> > independent of the architecture.  This would be a brave assumption that
> > has not been borne out by my experience.
> >
> > Or am I missing your point?
> 
> I think that the point is that people who understand the overall
> architecture still need help at some times with the implementation
> details.  And often the implementation details can help correct
> misunderstandings about the architecture.
> 
> At least that is my experience.

I agree completely, but in that case we are talking about RCU's
maintainers and developers, and for them a less point-focused approach
to internal documentation seems to work better.  Hence my looking to
walkthroughs to guide the generation of comments.

							Thanx, Paul

> julia
> 
> 
> 
> >
> > > > I am not sure that we can count on LLM's to provide reliable "active
> > > > software assistance", although a recent experiment, where I enabled
> > > > Gemini 3's "deep research" mode, and asked it the question, "How much
> > > > money do most software engineers need to retire?", resulted in a 15
> > > > page report[2], with footnotes, so you could verify whether or not the
> > > > LLM was halucinating or not --- and it was much better than I
> > > > expected.  I'm not sure I agree with all of it, but it's better than
> > > > many of the YouTube financial advice videos out there.  :-)
> > > >
> > > > [2] https://docs.google.com/document/d/1EDqC-qnHkEyEeewXFx4PuL4VtnC_LxPZ2CKlleB7QBc/edit?tab=t.0
> > >
> > > I fail to understand the analogy of using AI for financial security for
> > > retired software engineers and understanding an implementation of code
> > > by experience developers.
> > >
> > > If I hit a bug that leads me to RCU code, I would hope there's enough
> > > commenting for me to understand if the bug is with RCU or my usage of
> > > RCU.
> >
> > In this case, trawling through the RCU implementation itself would
> > not normally be the first choice.  I instead suggest starting
> > with the documentation of RCU's usage.  Documentation/RCU has a
> > lot of this, and there is also the 2024 edition of the RCU API:
> > https://lwn.net/Articles/988638.
> >
> > There are of course always exceptions, but this is after all the purpose
> > of RCU's usage documentation.
> >
> > > > Thta being said, there's a big difference between retirement planning
> > > > and trusting a LLM to be able to explain the finer points of say, an
> > > > I/O scheduler, the MM's OOM Killer hueristics, or RCU.  I suspect
> > > > there are no silver bullets here.
> > >
> > > There was a performance issue that Joel pointed out which lead to this
> > > one function I was looking at. But with the use of various constants
> > > that don't appear to be documented anywhere made it impossible for me
> > > to know if that code really was the performance issue or not. Sure I
> > > could simply ask Paul or Joel why is 3 so important here, but the fact
> > > I need to ask is a fail in my mind.
> >
> > Failure or not, in this particular case, again, please reach out to
> > Joel while CCing rcu@...r.kernel.org.  And again, the current state of
> > RCU commenting is somewhere between "notes to Paul" and sufficient for
> > those working closely with it.
> >
> > And again, I do not expect RCU's commenting to support context free
> > dives into random places in its code any time soon.
> >
> > > I have the same issue with the scheduler. There's parts of the
> > > scheduler that I worked on years ago, but the changes to it, I have no
> > > idea why it's doing what it is doing because there's no comments about
> > > it. The design is basically the same, but the implementation has
> > > changed. I'm going to be actively fixing that, as one of my OKRs is to
> > > comment the scheduler in more detail as to explain why functions do
> > > what they do.
> >
> > A few weeks back, I took the liberty of doing a quick scan through the
> > kernel for use of constants, and there are a *lot* of them.  The scheduler
> > and RCU are among the least of the problems.  And at least some of the
> > scheduler's use of constants look to be in code implementing digital
> > filters of one sort or another.  Such constants tend to be empirical in
> > nature, and the reason for the choice is usually "because this particular
> > value works better than the other choices".
> >
> > But I do applaud your going through the scheduler to improve comments.
> > Going through RCU with Boqun, Frederic, Joel, Neeraj, and Uladzislau
> > certainly greatly improved RCU's comments, inadequate though you
> > apparently consider them to be.  And so, as I mentioned earlier, I would
> > be happy to participate in another walkthrough.  ;-)
> >
> > 							Thanx, Paul
> >

Powered by blists - more mailing lists