Follow-up on Linux-kernel code accessibility

Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

Hello!

Just following up on some Linux Plumbers Conference discussions on the
accessibility of Linux-kernel code to people ranging from novices to
the developers and maintainers of the code in question.  I am adding
Lorenze on CC not because he was involved with these discussions (at
least as far as I know), but rather because I am using some of his work
in my follow-up analysis.

The Linux kernel's mm system weighs in at about 200KLoC, and Lorenzo
wrote a book on its design that weighs in at about 1300 pages, or
about 150 LoC/page.  This suggests that the Linux-kernel scheduler,
which weighs in at about 70KLoC and has similar heuristics/workload
challenges as does mm, would require a 430-page textbook to provide a
similar level of design detail.  By this methodology, RCU would require
"only" 190 pages, presumably substituting its unfamiliarity for sched's
and mm's deeply heuristic and workload-dependent nature.

Sadly, this data does not support the hypothesis that we can create
comments that will provide understanding to people taking random dives
into the Linux kernel's source code.  In contrast to code that is closely
associated with a specific type of mechanical device, Linux-kernel
code requires the reader to possess a great deal of abstract and global
conceptual/workload information.

This is not to say that the Linux kernel's internal documentation
(including its comments) cannot or should not be improved.
They clearly should.  It instead means that a necessary part of any
instant-understanding methodology for the Linux kernel include active
software assistance, for example, Anthropic's Claude LLM or IBM's (rather
older but less readily accessible) Analysis and Renovation Catalyst (ARC).
I am not denigrating other options, but rather restricting myself to
tools with which I have personal experience.

And one reason for continued but reasonable emphasis on internal
documentation, including comments, is that the aforementioned tools
ingest that documentation.  ;-)

Thoughts?

And in the meantime, happy holidays for those celebrating them!

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[David Laight]

On Thu, 18 Dec 2025 11:49:21 -0800
"Paul E. McKenney" <paulmck@kernel.org> wrote:

> Hello!
...
> The Linux kernel's mm system weighs in at about 200KLoC, and Lorenzo
> wrote a book on its design that weighs in at about 1300 pages, or
> about 150 LoC/page.

TL;DR :-)

	David

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Thu, Dec 18, 2025 at 10:09:21PM +0000, David Laight wrote:
> On Thu, 18 Dec 2025 11:49:21 -0800
> "Paul E. McKenney" <paulmck@kernel.org> wrote:
> 
> > Hello!
> ...
> > The Linux kernel's mm system weighs in at about 200KLoC, and Lorenzo
> > wrote a book on its design that weighs in at about 1300 pages, or
> > about 150 LoC/page.
> 
> TL;DR :-)

Well, there is the old saying "First, we must code.  Only then is there
incentive to think."  Perhaps as with thinking, also with reading?

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[Julia Lawall]

On Thu, 18 Dec 2025, Paul E. McKenney wrote:

> Hello!
>
> Just following up on some Linux Plumbers Conference discussions on the
> accessibility of Linux-kernel code to people ranging from novices to
> the developers and maintainers of the code in question.  I am adding
> Lorenze on CC not because he was involved with these discussions (at
> least as far as I know), but rather because I am using some of his work
> in my follow-up analysis.
>
> The Linux kernel's mm system weighs in at about 200KLoC, and Lorenzo
> wrote a book on its design that weighs in at about 1300 pages, or
> about 150 LoC/page.  This suggests that the Linux-kernel scheduler,
> which weighs in at about 70KLoC and has similar heuristics/workload
> challenges as does mm, would require a 430-page textbook to provide a
> similar level of design detail.  By this methodology, RCU would require
> "only" 190 pages, presumably substituting its unfamiliarity for sched's
> and mm's deeply heuristic and workload-dependent nature.
>
> Sadly, this data does not support the hypothesis that we can create
> comments that will provide understanding to people taking random dives
> into the Linux kernel's source code.  In contrast to code that is closely
> associated with a specific type of mechanical device, Linux-kernel
> code requires the reader to possess a great deal of abstract and global
> conceptual/workload information.
>
> This is not to say that the Linux kernel's internal documentation
> (including its comments) cannot or should not be improved.
> They clearly should.  It instead means that a necessary part of any
> instant-understanding methodology for the Linux kernel include active
> software assistance, for example, Anthropic's Claude LLM or IBM's (rather
> older but less readily accessible) Analysis and Renovation Catalyst (ARC).
> I am not denigrating other options, but rather restricting myself to
> tools with which I have personal experience.
>
> And one reason for continued but reasonable emphasis on internal
> documentation, including comments, is that the aforementioned tools
> ingest that documentation.  ;-)

Maybe we're not looking for an instant understanding methodology.  Rather
a machine checkable way to document the invariants that exist in the head
of the developer, and for some bounded amount of time in the head of the
person who has tried to reconstruct them.

There are different levels of specifications that one can write.  In Japan
Imentioned how for the enable-disable ftrace function, I enumerated all of
the permutations of the if tests, resulting in hundreds of lines of
specifications, but after two failed attempts, the third attempt yielded
both valid specifications and some insight into what the function was
doing.  This insight could potentially be used to make some higher level
specifications that would be even more concise than the current
English-language ones.  Maybe the low-level ones could be made
automatically in many cases, or regenerated automatically from some hints.
But the low-level ones may be needed to make the bridge between the code
and the high-level specification.

julia


>
> Thoughts?
>
> And in the meantime, happy holidays for those celebrating them!
>
> 							Thanx, Paul
>

Re: Follow-up on Linux-kernel code accessibility

[Theodore Tso]

On Fri, Dec 19, 2025 at 07:51:47AM +0100, Julia Lawall wrote:
> 
> Maybe we're not looking for an instant understanding methodology.  Rather
> a machine checkable way to document the invariants that exist in the head
> of the developer, and for some bounded amount of time in the head of the
> person who has tried to reconstruct them.

One of the things that I found really interesting with Chris Mason's
kernel review prompts is that it documents some of these invariants
which are not otherwise covered in the kernel documentation.  And
while Chris originally created those prompts for Anthropic's Claude
LLM, we've successfully used them with Gemini 2.5 and 3.

I wonder if we should consider folding them into the kernel sources,
so they can be updated alongside the kernel.  It might also mean that
as the invariants change, the documentation / prompts in an LTS kernel
and for the latest upstream kernel can be up to sync with the relevant
kernel versions.

> Maybe the low-level ones could be made
> automatically in many cases, or regenerated automatically from some hints.
> But the low-level ones may be needed to make the bridge between the code
> and the high-level specification.

Sasha's API specification framework patches might be something that's
worth considering in this context.  The thing that we need be careful
though, is that we might need to have a way of tagging kernel
functions in terms of the priority for the first set of high-level
interfaces for a newcomer to the kernel should look at first, and
those that might be less important, so that the newcomer won't get
overwhelmed with a vast number of low-level definitions.

Cheers,

							- Ted

Re: Follow-up on Linux-kernel code accessibility

[Sasha Levin]

On Fri, Dec 19, 2025 at 12:09:45PM -0500, Theodore Tso wrote:
>On Fri, Dec 19, 2025 at 07:51:47AM +0100, Julia Lawall wrote:
>> automatically in many cases, or regenerated automatically from some hints.
>> But the low-level ones may be needed to make the bridge between the code
>> and the high-level specification.
>
>Sasha's API specification framework patches might be something that's
>worth considering in this context.  The thing that we need be careful
>though, is that we might need to have a way of tagging kernel
>functions in terms of the priority for the first set of high-level
>interfaces for a newcomer to the kernel should look at first, and
>those that might be less important, so that the newcomer won't get
>overwhelmed with a vast number of low-level definitions.

I just sent a refreshed version earlier today
(https://lore.kernel.org/all/20251218204239.4159453-1-sashal@kernel.org/),
which also links to a branch that has over 100 LLM-generated syscall specs.

The nice thing about it is that we don't need to trust the LLM to do the right
thing: the spec is machine readable and we can generate testing based off of
it. Running something like LTP using those specs is pretty good at highlighting
issues - whether in the spec or the actual implementation.

I'd we weary to see complex specs in kernel-internal functions. Those often get
refactored and improved. Having complex speccing on them will make that work
much more difficult and complex.

-- 
Thanks,
Sasha

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Fri, 19 Dec 2025 12:59:42 -0500
Sasha Levin <sashal@kernel.org> wrote:

> I'd we weary to see complex specs in kernel-internal functions. Those often get
> refactored and improved. Having complex speccing on them will make that work
> much more difficult and complex.

I would argue that having a module describing a complex portion of the
kernel functions would be useful for not only helping to understand those
functions, but also possibly making it easier to see how they can be
improved upon.

This is one of the motivations I have for modeling the complex portions of
the tracing subsystem. I'm hoping that I can see better ways to perform
these tasks and possibly even improve its performance.

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Chris Mason]

On 12/19/25 12:09 PM, Theodore Tso wrote:
> On Fri, Dec 19, 2025 at 07:51:47AM +0100, Julia Lawall wrote:
>>
>> Maybe we're not looking for an instant understanding methodology.  Rather
>> a machine checkable way to document the invariants that exist in the head
>> of the developer, and for some bounded amount of time in the head of the
>> person who has tried to reconstruct them.
> 
> One of the things that I found really interesting with Chris Mason's
> kernel review prompts is that it documents some of these invariants
> which are not otherwise covered in the kernel documentation.  And
> while Chris originally created those prompts for Anthropic's Claude
> LLM, we've successfully used them with Gemini 2.5 and 3.
> 
> I wonder if we should consider folding them into the kernel sources,
> so they can be updated alongside the kernel.  It might also mean that
> as the invariants change, the documentation / prompts in an LTS kernel
> and for the latest upstream kernel can be up to sync with the relevant
> kernel versions.
> 

Yeah, I agree.  I think/hope these details from the prompts can end up
folded into the kernel docs.  As the prompts age, we're going to have
the equivalent of sprinkling ifdefs into them, and I think it's much
better if they just reference knowledge in the kernel.

I recently pushed out changes that remove most of the process and focus
more on kernel internals.  So hopefully over time we can get to
something that just documents kerneling in a way that is useful beyond
LLMs.

-chris

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Fri, Dec 19, 2025 at 07:51:47AM +0100, Julia Lawall wrote:
> Maybe we're not looking for an instant understanding methodology.  Rather
> a machine checkable way to document the invariants that exist in the head
> of the developer, and for some bounded amount of time in the head of the
> person who has tried to reconstruct them.

I like that goal.  Much easier to evaluate the results than for
improving learning, for one thing.

> There are different levels of specifications that one can write.  In Japan
> Imentioned how for the enable-disable ftrace function, I enumerated all of
> the permutations of the if tests, resulting in hundreds of lines of
> specifications, but after two failed attempts, the third attempt yielded
> both valid specifications and some insight into what the function was
> doing.  This insight could potentially be used to make some higher level
> specifications that would be even more concise than the current
> English-language ones.  Maybe the low-level ones could be made
> automatically in many cases, or regenerated automatically from some hints.
> But the low-level ones may be needed to make the bridge between the code
> and the high-level specification.

If it was easy, we would already be doing it?  ;-)

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Fri, Dec 19, 2025 at 01:28:12PM -0500, Steven Rostedt wrote:
> On Fri, 19 Dec 2025 12:59:42 -0500
> Sasha Levin <sashal@kernel.org> wrote:
> 
> > I'd we weary to see complex specs in kernel-internal functions. Those often get
> > refactored and improved. Having complex speccing on them will make that work
> > much more difficult and complex.
> 
> I would argue that having a module describing a complex portion of the
> kernel functions would be useful for not only helping to understand those
> functions, but also possibly making it easier to see how they can be
> improved upon.
> 
> This is one of the motivations I have for modeling the complex portions of
> the tracing subsystem. I'm hoping that I can see better ways to perform
> these tasks and possibly even improve its performance.

If there are 100,000 function-like things in the kernel, and we add 100
lines of comments to each, we will have expanded the kernel source by
some tens of percent.  Plus staleness and/or churn will likely be problems.

Yes, it helped you, and that is good.  But is this really the best way to
achieve that goal?  Better than human walkthroughs?  Than querying LLMs
that ingested the code?  Better than producing external documentation
at the design/code level?

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[Theodore Tso]

On Fri, Dec 19, 2025 at 04:05:33PM -0500, Chris Mason wrote:
> I recently pushed out changes that remove most of the process and focus
> more on kernel internals.  So hopefully over time we can get to
> something that just documents kerneling in a way that is useful beyond
> LLMs.

One of the things which I found really interesting, and it was a bit
of revelation to me, was how much we could have text that could be
useful *both* as a documentations for humans, as well as instructions
to LLM's.  So I think both are important/useful.

						- Ted

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Fri, 19 Dec 2025 16:36:33 -0800
"Paul E. McKenney" <paulmck@kernel.org> wrote:

> > This is one of the motivations I have for modeling the complex portions of
> > the tracing subsystem. I'm hoping that I can see better ways to perform
> > these tasks and possibly even improve its performance.  
> 
> If there are 100,000 function-like things in the kernel, and we add 100
> lines of comments to each, we will have expanded the kernel source by
> some tens of percent.  Plus staleness and/or churn will likely be problems.

I'm really only interested in the more subtle and complex functions. The
majority of those 100,000 functions do not need extra comments.

And I honestly don't care about increasing the source due to comments.
That's a good thing. I like going to a subsystem and seeing a lot of
comments in the code. I hate going to a subsystem where there's no
comments, thus you need to try to figure out the context from the code, and
when I had that, I usually got it wrong.

> 
> Yes, it helped you, and that is good.  But is this really the best way to
> achieve that goal?  Better than human walkthroughs?  Than querying LLMs
> that ingested the code?  Better than producing external documentation
> at the design/code level?

So far I've not been too happy with the results of LLMs describing code.
They tend to come up with the same mistakes I do when I try to figure out
what the author of the code was doing by looking only at the code without
any comments that came from said author.

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Mon, Dec 22, 2025 at 10:42:09AM -0500, Steven Rostedt wrote:
> On Fri, 19 Dec 2025 16:36:33 -0800
> "Paul E. McKenney" <paulmck@kernel.org> wrote:
> 
> > > This is one of the motivations I have for modeling the complex portions of
> > > the tracing subsystem. I'm hoping that I can see better ways to perform
> > > these tasks and possibly even improve its performance.  
> > 
> > If there are 100,000 function-like things in the kernel, and we add 100
> > lines of comments to each, we will have expanded the kernel source by
> > some tens of percent.  Plus staleness and/or churn will likely be problems.
> 
> I'm really only interested in the more subtle and complex functions. The
> majority of those 100,000 functions do not need extra comments.

Sigh.  "Subtle" and "Complex" are rather subjective, and given the
goals of one of the LPC MCs, others outside the community might decide
to weigh in.

> And I honestly don't care about increasing the source due to comments.
> That's a good thing. I like going to a subsystem and seeing a lot of
> comments in the code. I hate going to a subsystem where there's no
> comments, thus you need to try to figure out the context from the code, and
> when I had that, I usually got it wrong.

I do care.  After all, life got much better when (mostly) ineffective
"Only invoke this function with interrupts disabled" comments became
"lockdep_assert_irqs_disabled()" executable code.

So if we are going to add more explicit constraints in header comments,
we owe it to ourselves to see what can be made executable so that
normal testing has at least some chance of detecting violations of
these constraints.

> > Yes, it helped you, and that is good.  But is this really the best way to
> > achieve that goal?  Better than human walkthroughs?  Than querying LLMs
> > that ingested the code?  Better than producing external documentation
> > at the design/code level?
> 
> So far I've not been too happy with the results of LLMs describing code.
> They tend to come up with the same mistakes I do when I try to figure out
> what the author of the code was doing by looking only at the code without
> any comments that came from said author.

Fair enough.  I am not entirely satisfied with the LLMs myself.
Then again, I am also not entirely satisfied with the output of humans.
But so it goes.

What about walkthroughs?  Producing external documentation based on
the code?

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Tue, 23 Dec 2025 15:46:10 -0800
"Paul E. McKenney" <paulmck@kernel.org> wrote:

> > I'm really only interested in the more subtle and complex functions. The
> > majority of those 100,000 functions do not need extra comments.  
> 
> Sigh.  "Subtle" and "Complex" are rather subjective, and given the
> goals of one of the LPC MCs, others outside the community might decide
> to weigh in.

I only stated what I'm interested in. Others may have different ideas.

> 
> > And I honestly don't care about increasing the source due to comments.
> > That's a good thing. I like going to a subsystem and seeing a lot of
> > comments in the code. I hate going to a subsystem where there's no
> > comments, thus you need to try to figure out the context from the code, and
> > when I had that, I usually got it wrong.  
> 
> I do care.  After all, life got much better when (mostly) ineffective
> "Only invoke this function with interrupts disabled" comments became
> "lockdep_assert_irqs_disabled()" executable code.

Yes, constraints of a function do better with annotations like this. But
"Only invoke this function if interrupts are disabled" does nothing to
describe what the function is doing.

> 
> So if we are going to add more explicit constraints in header comments,
> we owe it to ourselves to see what can be made executable so that
> normal testing has at least some chance of detecting violations of
> these constraints.

I agree on constraints. But how a function works is different.


> What about walkthroughs?  Producing external documentation based on
> the code?

I'm not sure what you mean by "walkthroughs". AI can help give a general
idea on code, but it still needs the author of the code to verify it.

One place I recently found where I wish there was some more descriptions of
what the code is doing was here:

/*
 * Loop doing repeated quiescent-state forcing until the grace period ends.
 */
static noinline_for_stack void rcu_gp_fqs_loop(void)
{
	bool first_gp_fqs = true;
	int gf = 0;
	unsigned long j;
	int ret;
	struct rcu_node *rnp = rcu_get_root();

	j = READ_ONCE(jiffies_till_first_fqs);
	if (rcu_state.cbovld)
		gf = RCU_GP_FLAG_OVLD;
	ret = 0;
	for (;;) {
		if (rcu_state.cbovld) {
			j = (j + 2) / 3;
			if (j <= 0)
				j = 1;
		}
		if (!ret || time_before(jiffies + j, rcu_state.jiffies_force_qs)) {
			WRITE_ONCE(rcu_state.jiffies_force_qs, jiffies + j);
			/*
			 * jiffies_force_qs before RCU_GP_WAIT_FQS state
			 * update; required for stall checks.
			 */
			smp_wmb();
			WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
				   jiffies + (j ? 3 * j : 2));
		}

There's a bit of magical manipulation of "j" that I have no idea why it's
doing that. ;-)

I would love if Julia or Gabriele came up with some specification for that
function.

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Theodore Tso]

On Wed, Dec 24, 2025 at 09:11:58AM -0500, Steven Rostedt wrote:
> /*
>  * Loop doing repeated quiescent-state forcing until the grace period ends.
>  */
> static noinline_for_stack void rcu_gp_fqs_loop(void)
> {
> 	bool first_gp_fqs = true;
> 	int gf = 0;
> 	unsigned long j;
> 	int ret;
> 	struct rcu_node *rnp = rcu_get_root();
> 
> 	j = READ_ONCE(jiffies_till_first_fqs);
> 	if (rcu_state.cbovld)
> 		gf = RCU_GP_FLAG_OVLD;
> 	ret = 0;
> 	for (;;) {
> 		if (rcu_state.cbovld) {
> 			j = (j + 2) / 3;
> 			if (j <= 0)
> 				j = 1;
> 		}
> 		if (!ret || time_before(jiffies + j, rcu_state.jiffies_force_qs)) {
> 			WRITE_ONCE(rcu_state.jiffies_force_qs, jiffies + j);
> 			/*
> 			 * jiffies_force_qs before RCU_GP_WAIT_FQS state
> 			 * update; required for stall checks.
> 			 */
> 			smp_wmb();
> 			WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
> 				   jiffies + (j ? 3 * j : 2));
> 		}
> 
> There's a bit of magical manipulation of "j" that I have no idea why it's
> doing that. ;-)
> 
> I would love if Julia or Gabriele came up with some specification for that
> function.

I think we need to separate out two different things.  The first is
<<what>> the function is doing, and the other is <<how>> the function
is doing it.  The first is the specification, or the interface
contract.  The second is the implementation details that are important
if you need to modify the function, or want to verify its corrections.

I'm reminded of the ancient Unix documentation of how context
switching was implemented on a PDP-11, "You are not expected to
understand this".  But as long as you understood what it was doing,
the fact the magic wasn't described in the source code might be OK.
OTOH, it's what inspired the Lion's Commentary on the Unix Source
Code book.   :-)

						- Ted

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Wed, Dec 24, 2025 at 09:11:58AM -0500, Steven Rostedt wrote:
> On Tue, 23 Dec 2025 15:46:10 -0800
> "Paul E. McKenney" <paulmck@kernel.org> wrote:
> 
> > > I'm really only interested in the more subtle and complex functions. The
> > > majority of those 100,000 functions do not need extra comments.  
> > 
> > Sigh.  "Subtle" and "Complex" are rather subjective, and given the
> > goals of one of the LPC MCs, others outside the community might decide
> > to weigh in.
> 
> I only stated what I'm interested in. Others may have different ideas.
> 
> > 
> > > And I honestly don't care about increasing the source due to comments.
> > > That's a good thing. I like going to a subsystem and seeing a lot of
> > > comments in the code. I hate going to a subsystem where there's no
> > > comments, thus you need to try to figure out the context from the code, and
> > > when I had that, I usually got it wrong.  
> > 
> > I do care.  After all, life got much better when (mostly) ineffective
> > "Only invoke this function with interrupts disabled" comments became
> > "lockdep_assert_irqs_disabled()" executable code.
> 
> Yes, constraints of a function do better with annotations like this. But
> "Only invoke this function if interrupts are disabled" does nothing to
> describe what the function is doing.
> 
> > 
> > So if we are going to add more explicit constraints in header comments,
> > we owe it to ourselves to see what can be made executable so that
> > normal testing has at least some chance of detecting violations of
> > these constraints.
> 
> I agree on constraints. But how a function works is different.
> 
> 
> > What about walkthroughs?  Producing external documentation based on
> > the code?
> 
> I'm not sure what you mean by "walkthroughs". AI can help give a general
> idea on code, but it still needs the author of the code to verify it.

So let's kill two birds with one stone.  Let's arrange a walkthrough
of this code (starting from its calling function rcu_gp_kthread() some
time after the new year.  That will show you how a walkthrough works
(or at least one walkthrough method) and also answer your questions
about the variable "j".

> One place I recently found where I wish there was some more descriptions of
> what the code is doing was here:
> 
> /*
>  * Loop doing repeated quiescent-state forcing until the grace period ends.
>  */
> static noinline_for_stack void rcu_gp_fqs_loop(void)
> {
> 	bool first_gp_fqs = true;
> 	int gf = 0;
> 	unsigned long j;
> 	int ret;
> 	struct rcu_node *rnp = rcu_get_root();
> 
> 	j = READ_ONCE(jiffies_till_first_fqs);
> 	if (rcu_state.cbovld)
> 		gf = RCU_GP_FLAG_OVLD;
> 	ret = 0;
> 	for (;;) {
> 		if (rcu_state.cbovld) {
> 			j = (j + 2) / 3;
> 			if (j <= 0)
> 				j = 1;
> 		}
> 		if (!ret || time_before(jiffies + j, rcu_state.jiffies_force_qs)) {
> 			WRITE_ONCE(rcu_state.jiffies_force_qs, jiffies + j);
> 			/*
> 			 * jiffies_force_qs before RCU_GP_WAIT_FQS state
> 			 * update; required for stall checks.
> 			 */
> 			smp_wmb();
> 			WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
> 				   jiffies + (j ? 3 * j : 2));
> 		}
> 
> There's a bit of magical manipulation of "j" that I have no idea why it's
> doing that. ;-)

Back in the old days, I used to put inline comments on local variables,
but this practice did not spark joy in the Linux kernel community back
in the very early 2000s.

So another question for our walkthrough:  Should this practice be
introduced into the Linux kernel?

> I would love if Julia or Gabriele came up with some specification for that
> function.

Sounds like a worthy challenge to me!  Me, I would open it up to all
comers, but I was clearly willing to give Julia and Gabriele a one-day
head start, even if it was rather inconveniently timed.  ;-)

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Thu, Dec 25, 2025 at 10:03:31AM -0500, Theodore Tso wrote:
> On Wed, Dec 24, 2025 at 09:11:58AM -0500, Steven Rostedt wrote:
> > /*
> >  * Loop doing repeated quiescent-state forcing until the grace period ends.
> >  */
> > static noinline_for_stack void rcu_gp_fqs_loop(void)
> > {
> > 	bool first_gp_fqs = true;
> > 	int gf = 0;
> > 	unsigned long j;
> > 	int ret;
> > 	struct rcu_node *rnp = rcu_get_root();
> > 
> > 	j = READ_ONCE(jiffies_till_first_fqs);
> > 	if (rcu_state.cbovld)
> > 		gf = RCU_GP_FLAG_OVLD;
> > 	ret = 0;
> > 	for (;;) {
> > 		if (rcu_state.cbovld) {
> > 			j = (j + 2) / 3;
> > 			if (j <= 0)
> > 				j = 1;
> > 		}
> > 		if (!ret || time_before(jiffies + j, rcu_state.jiffies_force_qs)) {
> > 			WRITE_ONCE(rcu_state.jiffies_force_qs, jiffies + j);
> > 			/*
> > 			 * jiffies_force_qs before RCU_GP_WAIT_FQS state
> > 			 * update; required for stall checks.
> > 			 */
> > 			smp_wmb();
> > 			WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
> > 				   jiffies + (j ? 3 * j : 2));
> > 		}
> > 
> > There's a bit of magical manipulation of "j" that I have no idea why it's
> > doing that. ;-)
> > 
> > I would love if Julia or Gabriele came up with some specification for that
> > function.
> 
> I think we need to separate out two different things.  The first is
> <<what>> the function is doing, and the other is <<how>> the function
> is doing it.  The first is the specification, or the interface
> contract.  The second is the implementation details that are important
> if you need to modify the function, or want to verify its corrections.

Good point, and thank you!

> I'm reminded of the ancient Unix documentation of how context
> switching was implemented on a PDP-11, "You are not expected to
> understand this".  But as long as you understood what it was doing,
> the fact the magic wasn't described in the source code might be OK.
> OTOH, it's what inspired the Lion's Commentary on the Unix Source
> Code book.   :-)

Also a good point, but one of my goals is to move RCU further out of "You
are not expected to understand this" state.  And in that spirit, I will
further celebrate this day by offering up a big "THANK YOU!" to those who
have dug into RCU's implementation, and most especially the Big Five who
have dug deeply enough into it to have sent RCU pull requests to Linus!

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Thu, 25 Dec 2025 10:03:31 -0500
"Theodore Tso" <tytso@mit.edu> wrote:

> > There's a bit of magical manipulation of "j" that I have no idea why it's
> > doing that. ;-)
> > 
> > I would love if Julia or Gabriele came up with some specification for that
> > function.  
> 
> I think we need to separate out two different things.  The first is
> <<what>> the function is doing, and the other is <<how>> the function
> is doing it.  The first is the specification, or the interface
> contract.  The second is the implementation details that are important
> if you need to modify the function, or want to verify its corrections.

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.

As Julia said in one of our meetings, the "what a function is doing" should
describe enough so that if you gave that to two different developers they
would come up with similar code. Different implementations, but at least
they should have the same result.

> 
> I'm reminded of the ancient Unix documentation of how context
> switching was implemented on a PDP-11, "You are not expected to
> understand this".  But as long as you understood what it was doing,
> the fact the magic wasn't described in the source code might be OK.
> OTOH, it's what inspired the Lion's Commentary on the Unix Source
> Code book.   :-)

Reminds me of a saying I saw posted to a developer's desk back in 1992 at
Martin Marietta: "I don't document my code. If it was hard to write, it
should be hard to understand!" :-p

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Thu, 25 Dec 2025 10:18:20 -0800
"Paul E. McKenney" <paulmck@kernel.org> wrote:

> > I'm not sure what you mean by "walkthroughs". AI can help give a general
> > idea on code, but it still needs the author of the code to verify it.  
> 
> So let's kill two birds with one stone.  Let's arrange a walkthrough
> of this code (starting from its calling function rcu_gp_kthread() some
> time after the new year.  That will show you how a walkthrough works
> (or at least one walkthrough method) and also answer your questions
> about the variable "j".

Sure, I'll be up for that.


> > There's a bit of magical manipulation of "j" that I have no idea why it's
> > doing that. ;-)  
> 
> Back in the old days, I used to put inline comments on local variables,
> but this practice did not spark joy in the Linux kernel community back
> in the very early 2000s.

Matters how much comments that was I guess. And how useful they were.
Today, I believe people want comments. The kernel is much more complex
today then it was back in the early 2000s.

> 
> So another question for our walkthrough:  Should this practice be
> introduced into the Linux kernel?

I can't answer that until after the walkthrough ;-)

> 
> > I would love if Julia or Gabriele came up with some specification for that
> > function.  
> 
> Sounds like a worthy challenge to me!  Me, I would open it up to all
> comers, but I was clearly willing to give Julia and Gabriele a one-day
> head start, even if it was rather inconveniently timed.  ;-)

I'll let them speak for themselves.

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Fri, Dec 26, 2025 at 11:51:36AM -0500, Steven Rostedt wrote:
> On Thu, 25 Dec 2025 10:18:20 -0800
> "Paul E. McKenney" <paulmck@kernel.org> wrote:
> 
> > > I'm not sure what you mean by "walkthroughs". AI can help give a general
> > > idea on code, but it still needs the author of the code to verify it.  
> > 
> > So let's kill two birds with one stone.  Let's arrange a walkthrough
> > of this code (starting from its calling function rcu_gp_kthread() some
> > time after the new year.  That will show you how a walkthrough works
> > (or at least one walkthrough method) and also answer your questions
> > about the variable "j".
> 
> Sure, I'll be up for that.

Sounds good!  Any particularly good/bad times for you?

> > > There's a bit of magical manipulation of "j" that I have no idea why it's
> > > doing that. ;-)  
> > 
> > Back in the old days, I used to put inline comments on local variables,
> > but this practice did not spark joy in the Linux kernel community back
> > in the very early 2000s.
> 
> Matters how much comments that was I guess. And how useful they were.
> Today, I believe people want comments. The kernel is much more complex
> today then it was back in the early 2000s.

Here are three examples:

o	Comment restricted to the remainder of the line.

o	Comment restricted to the remainder of the line, but the
	initialization was moved to executable code to make more room.

o	Comment extends for multiple lines.

> > So another question for our walkthrough:  Should this practice be
> > introduced into the Linux kernel?
> 
> I can't answer that until after the walkthrough ;-)

Well, you *could* answer, but you just might not be all that confident
in your answer.  You could build confidence in the meantime by looking
at other examples and asking yourself whether such a comment would
be helpful.  ;-)

> > > I would love if Julia or Gabriele came up with some specification for that
> > > function.  
> > 
> > Sounds like a worthy challenge to me!  Me, I would open it up to all
> > comers, but I was clearly willing to give Julia and Gabriele a one-day
> > head start, even if it was rather inconveniently timed.  ;-)
> 
> I'll let them speak for themselves.

Fair enough!

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Fri, Dec 26, 2025 at 11:48:30AM -0500, Steven Rostedt wrote:
> On Thu, 25 Dec 2025 10:03:31 -0500
> "Theodore Tso" <tytso@mit.edu> wrote:
> 
> > > There's a bit of magical manipulation of "j" that I have no idea why it's
> > > doing that. ;-)
> > > 
> > > I would love if Julia or Gabriele came up with some specification for that
> > > function.  
> > 
> > I think we need to separate out two different things.  The first is
> > <<what>> the function is doing, and the other is <<how>> the function
> > is doing it.  The first is the specification, or the interface
> > contract.  The second is the implementation details that are important
> > if you need to modify the function, or want to verify its corrections.
> 
> 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.

Wait...  How can you be certain of this in advance of the walkthrough,
but at the same time be uncertain of the value (or lack thereof) of
per-local-variable inline comments?  ;-)

> As Julia said in one of our meetings, the "what a function is doing" should
> describe enough so that if you gave that to two different developers they
> would come up with similar code. Different implementations, but at least
> they should have the same result.

For many Linux-kernel subsystems, including RCU, I stand by my point
about background information, as exemplified by Lorenzo's 1300-page book
on mm, and by Mel Gorman's earlier 750-page book.  Similar material,
but nowhere near as complete, on RCU may be found in Documentation/RCU.

All that aside, I have no objection to improvements in header comments.
There were quite a few patches to comments that resulted from walking
other RCU maintainers through the code, after all.  The rcu_gp_fqs_loop()
header comment was not considered to be lacking for whatever reason,
but who knows?

							Thanx, Paul

> > I'm reminded of the ancient Unix documentation of how context
> > switching was implemented on a PDP-11, "You are not expected to
> > understand this".  But as long as you understood what it was doing,
> > the fact the magic wasn't described in the source code might be OK.
> > OTOH, it's what inspired the Lion's Commentary on the Unix Source
> > Code book.   :-)
> 
> Reminds me of a saying I saw posted to a developer's desk back in 1992 at
> Martin Marietta: "I don't document my code. If it was hard to write, it
> should be hard to understand!" :-p
> 
> -- Steve

Re: Follow-up on Linux-kernel code accessibility

[Theodore Tso]

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.

						- Ted

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Fri, 26 Dec 2025 14:22:17 -0500
"Theodore Tso" <tytso@mit.edu> 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.

This actually has nothing to do with newcomers. It's for other kernel
developers that would like to help review code in other subsystems. Greg is
always saying "if you want your code reviewed, review other people's code".

Some history on why I'm picking on this particular function. Joel Fernandes
recently posted an RFC about jiffies_till_first_fqs being off by 1.

  https://lore.kernel.org/all/1efce983-639b-430d-a613-03baef81c416@nvidia.com/

I wanted to understand what Joel was talking about and came to this
function which mostly sets that variable. That's when I said to myself "oh
there's gnomes laying out their magical numbers here to define this
variable". It's great that Joel appears to understand this, but without
digging much more into the entire RCU subsystem, it's hard for even other
kernel developers to know what's going on, let alone any kernel newbies.

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

But I'm not talking about newcomers. I'm talking about other kernel
developers (like myself) trying to wrap my head around this code.

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

Agreed. And at this moment, the target audience is people like myself and
Julia, who voiced her opinion at a Linux Plumbers meeting where she (like
myself) goes to another subsystem and has no idea about how things work,
and would have been pleased to see some comments describing what functions
intend to be doing.

This is also how I fell out of grace with Linus with eventfs as I didn't
have the tribal knowledge to know the "right" ways to do things when
creating that code. And I tried to know. I read lots of documentation. I
even talked with you about it at LSFMM. But a lot of VFS is still just
tribal knowledge.

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

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

Re: Follow-up on Linux-kernel code accessibility

[Julia Lawall]

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
>

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Sat, Dec 27, 2025 at 07:16:28AM +0100, Julia Lawall wrote:
> 
> 
> 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.

Although RCU does use heuristics, I would say that its operation adapts
less to dynamic conditions than does the scheduler.  RCU is mostly an
observer of state, while the scheduler's job is mostly a controller
of state.

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

If it is (for example) division by 10 in code that converts binary
integers to char, or code computing an average, I would not expect a
comment to be needed.

But I do feel the need to ask what division you are referring to.  ;-)

							Thanx, Paul

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

Re: Follow-up on Linux-kernel code accessibility

[Julia Lawall]

On Sat, 27 Dec 2025, Paul E. McKenney wrote:

> On Sat, Dec 27, 2025 at 07:16:28AM +0100, Julia Lawall wrote:
> >
> >
> > 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.
>
> Although RCU does use heuristics, I would say that its operation adapts
> less to dynamic conditions than does the scheduler.  RCU is mostly an
> observer of state, while the scheduler's job is mostly a controller
> of state.
>
> > Maybe one could consider that division by a constant is sufficiently rare
> > in the kernel that it should always be documented?
>
> If it is (for example) division by 10 in code that converts binary
> integers to char, or code computing an average, I would not expect a
> comment to be needed.
>
> But I do feel the need to ask what division you are referring to.  ;-)

j = (j + 2) / 3;

>
> 							Thanx, Paul
>
> > 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
> > >
>

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Sun, Dec 28, 2025 at 12:32:50AM +0100, Julia Lawall wrote:
> 
> 
> On Sat, 27 Dec 2025, Paul E. McKenney wrote:
> 
> > On Sat, Dec 27, 2025 at 07:16:28AM +0100, Julia Lawall wrote:
> > >
> > >
> > > 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.
> >
> > Although RCU does use heuristics, I would say that its operation adapts
> > less to dynamic conditions than does the scheduler.  RCU is mostly an
> > observer of state, while the scheduler's job is mostly a controller
> > of state.
> >
> > > Maybe one could consider that division by a constant is sufficiently rare
> > > in the kernel that it should always be documented?
> >
> > If it is (for example) division by 10 in code that converts binary
> > integers to char, or code computing an average, I would not expect a
> > comment to be needed.
> >
> > But I do feel the need to ask what division you are referring to.  ;-)
> 
> j = (j + 2) / 3;

"Divide by three rounding up."


							Thanx, Paul

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

Re: Follow-up on Linux-kernel code accessibility

[Dr. David Alan Gilbert]

* Paul E. McKenney (paulmck@kernel.org) wrote:
> On Sun, Dec 28, 2025 at 12:32:50AM +0100, Julia Lawall wrote:
> > 
> > 
> > On Sat, 27 Dec 2025, Paul E. McKenney wrote:
> > 
> > > On Sat, Dec 27, 2025 at 07:16:28AM +0100, Julia Lawall wrote:
> > > >
> > > >
> > > > 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.
> > >
> > > Although RCU does use heuristics, I would say that its operation adapts
> > > less to dynamic conditions than does the scheduler.  RCU is mostly an
> > > observer of state, while the scheduler's job is mostly a controller
> > > of state.
> > >
> > > > Maybe one could consider that division by a constant is sufficiently rare
> > > > in the kernel that it should always be documented?
> > >
> > > If it is (for example) division by 10 in code that converts binary
> > > integers to char, or code computing an average, I would not expect a
> > > comment to be needed.
> > >
> > > But I do feel the need to ask what division you are referring to.  ;-)
> > 
> > j = (j + 2) / 3;
> 
> "Divide by three rounding up."

That's not *that* obvious, but ok, but then why 3?

Then later there is:
         WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
                   jiffies + (j ? 3 * j : 2));

Which I assume is related - but then why the 2?

Curiosly my local tame Qwen3 LLM explained the rounding up:

> I see some code doing 'j = (j + 2) / 3'  - what's it trying to do?
The expression `j = (j + 2) / 3` is a clever way to **round up an
integer division by 3** — that is, it computes the ceiling of `j / 3`
for non-negative integers.

Dave

> 
> 							Thanx, Paul
> 
> > > > 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
> > > > >
> > >
> 
-- 
 -----Open up your eyes, open up your mind, open up your code -------   
/ Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
\        dave @ treblig.org |                               | In Hex /
 \ _________________________|_____ http://www.treblig.org   |_______/

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Sun, Dec 28, 2025 at 01:48:37AM +0000, Dr. David Alan Gilbert wrote:
> * Paul E. McKenney (paulmck@kernel.org) wrote:
> > On Sun, Dec 28, 2025 at 12:32:50AM +0100, Julia Lawall wrote:
> > > 
> > > 
> > > On Sat, 27 Dec 2025, Paul E. McKenney wrote:
> > > 
> > > > On Sat, Dec 27, 2025 at 07:16:28AM +0100, Julia Lawall wrote:
> > > > >
> > > > >
> > > > > 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.
> > > >
> > > > Although RCU does use heuristics, I would say that its operation adapts
> > > > less to dynamic conditions than does the scheduler.  RCU is mostly an
> > > > observer of state, while the scheduler's job is mostly a controller
> > > > of state.
> > > >
> > > > > Maybe one could consider that division by a constant is sufficiently rare
> > > > > in the kernel that it should always be documented?
> > > >
> > > > If it is (for example) division by 10 in code that converts binary
> > > > integers to char, or code computing an average, I would not expect a
> > > > comment to be needed.
> > > >
> > > > But I do feel the need to ask what division you are referring to.  ;-)
> > > 
> > > j = (j + 2) / 3;
> > 
> > "Divide by three rounding up."
> 
> That's not *that* obvious, but ok, but then why 3?
> 
> Then later there is:
>          WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
>                    jiffies + (j ? 3 * j : 2));
> 
> Which I assume is related - but then why the 2?

Would the two of you (Julia and Dave) like to join in with Steve and
myself walking through this function and its caller?

> Curiosly my local tame Qwen3 LLM explained the rounding up:
> 
> > I see some code doing 'j = (j + 2) / 3'  - what's it trying to do?
> The expression `j = (j + 2) / 3` is a clever way to **round up an
> integer division by 3** — that is, it computes the ceiling of `j / 3`
> for non-negative integers.

Good to see!

							Thanx, Paul

> Dave
> 
> > 
> > 							Thanx, Paul
> > 
> > > > > 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
> > > > > >
> > > >
> > 
> -- 
>  -----Open up your eyes, open up your mind, open up your code -------   
> / Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
> \        dave @ treblig.org |                               | In Hex /
>  \ _________________________|_____ http://www.treblig.org   |_______/

Re: Follow-up on Linux-kernel code accessibility

[Julia Lawall]

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



On Sat, 27 Dec 2025, Paul E. McKenney wrote:

> On Sun, Dec 28, 2025 at 01:48:37AM +0000, Dr. David Alan Gilbert wrote:
> > * Paul E. McKenney (paulmck@kernel.org) wrote:
> > > On Sun, Dec 28, 2025 at 12:32:50AM +0100, Julia Lawall wrote:
> > > >
> > > >
> > > > On Sat, 27 Dec 2025, Paul E. McKenney wrote:
> > > >
> > > > > On Sat, Dec 27, 2025 at 07:16:28AM +0100, Julia Lawall wrote:
> > > > > >
> > > > > >
> > > > > > 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.
> > > > >
> > > > > Although RCU does use heuristics, I would say that its operation adapts
> > > > > less to dynamic conditions than does the scheduler.  RCU is mostly an
> > > > > observer of state, while the scheduler's job is mostly a controller
> > > > > of state.
> > > > >
> > > > > > Maybe one could consider that division by a constant is sufficiently rare
> > > > > > in the kernel that it should always be documented?
> > > > >
> > > > > If it is (for example) division by 10 in code that converts binary
> > > > > integers to char, or code computing an average, I would not expect a
> > > > > comment to be needed.
> > > > >
> > > > > But I do feel the need to ask what division you are referring to.  ;-)
> > > >
> > > > j = (j + 2) / 3;
> > >
> > > "Divide by three rounding up."
> >
> > That's not *that* obvious, but ok, but then why 3?
> >
> > Then later there is:
> >          WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
> >                    jiffies + (j ? 3 * j : 2));
> >
> > Which I assume is related - but then why the 2?
>
> Would the two of you (Julia and Dave) like to join in with Steve and
> myself walking through this function and its caller?

Sure.  The question was indeed why divide by 3.

julia

>
> > Curiosly my local tame Qwen3 LLM explained the rounding up:
> >
> > > I see some code doing 'j = (j + 2) / 3'  - what's it trying to do?
> > The expression `j = (j + 2) / 3` is a clever way to **round up an
> > integer division by 3** — that is, it computes the ceiling of `j / 3`
> > for non-negative integers.
>
> Good to see!
>
> 							Thanx, Paul
>
> > Dave
> >
> > >
> > > 							Thanx, Paul
> > >
> > > > > > 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
> > > > > > >
> > > > >
> > >
> > --
> >  -----Open up your eyes, open up your mind, open up your code -------
> > / Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \
> > \        dave @ treblig.org |                               | In Hex /
> >  \ _________________________|_____ http://www.treblig.org   |_______/
>

Re: Follow-up on Linux-kernel code accessibility

[Dr. David Alan Gilbert]

* Paul E. McKenney (paulmck@kernel.org) wrote:

<snip>

> > > > 
> > > > j = (j + 2) / 3;
> > > 
> > > "Divide by three rounding up."
> > 
> > That's not *that* obvious, but ok, but then why 3?
> > 
> > Then later there is:
> >          WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
> >                    jiffies + (j ? 3 * j : 2));
> > 
> > Which I assume is related - but then why the 2?
> 
> Would the two of you (Julia and Dave) like to join in with Steve and
> myself walking through this function and its caller?

Not sure what you mean join in; not really set up for a call etc at the
moment, but happy to continue a mail chain.

But, if we're talking about the understandability of these few lines,
it looks like this could be something like:


   // We have 3 ..... for the case when ...
   const unsigned long something = 3;
....
   j = DIV_ROUND_UP(j, something);

which would seem to make it more readable with very little effort.

(Hmm, since j is unsigned long why do we have a test of:
    if  (j <= 0) 
      j = 1
)

Dave

> > Curiosly my local tame Qwen3 LLM explained the rounding up:
> > 
> > > I see some code doing 'j = (j + 2) / 3'  - what's it trying to do?
> > The expression `j = (j + 2) / 3` is a clever way to **round up an
> > integer division by 3** — that is, it computes the ceiling of `j / 3`
> > for non-negative integers.
> 
> Good to see!
> 
> 							Thanx, Paul
> 
> > Dave
> > 
> > > 
> > > 							Thanx, Paul
> > > 
> > > > > > 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
> > > > > > >
> > > > >
> > > 
> > -- 
> >  -----Open up your eyes, open up your mind, open up your code -------   
> > / Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
> > \        dave @ treblig.org |                               | In Hex /
> >  \ _________________________|_____ http://www.treblig.org   |_______/
-- 
 -----Open up your eyes, open up your mind, open up your code -------   
/ Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
\        dave @ treblig.org |                               | In Hex /
 \ _________________________|_____ http://www.treblig.org   |_______/

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Sun, Dec 28, 2025 at 12:46:01PM +0000, Dr. David Alan Gilbert wrote:
> * Paul E. McKenney (paulmck@kernel.org) wrote:
> 
> <snip>
> 
> > > > > 
> > > > > j = (j + 2) / 3;
> > > > 
> > > > "Divide by three rounding up."
> > > 
> > > That's not *that* obvious, but ok, but then why 3?
> > > 
> > > Then later there is:
> > >          WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
> > >                    jiffies + (j ? 3 * j : 2));
> > > 
> > > Which I assume is related - but then why the 2?
> > 
> > Would the two of you (Julia and Dave) like to join in with Steve and
> > myself walking through this function and its caller?
> 
> Not sure what you mean join in; not really set up for a call etc at the
> moment, but happy to continue a mail chain.

Fair enough.  This question is to be addressed in that walkthrough.
I will hold off discussions of this particular line of code and of this
function until then.  After all, part of the point is to demonstrate
walkthroughs, and answering the question beforehand would prevent this.

In the meantime, please feel free to change your focus to some other
line of code in some unrelated function and I will be happy to continue
*that* discussion via email.

							Thanx, Paul

> But, if we're talking about the understandability of these few lines,
> it looks like this could be something like:
> 
> 
>    // We have 3 ..... for the case when ...
>    const unsigned long something = 3;
> ....
>    j = DIV_ROUND_UP(j, something);
> 
> which would seem to make it more readable with very little effort.
> 
> (Hmm, since j is unsigned long why do we have a test of:
>     if  (j <= 0) 
>       j = 1
> )
> 
> Dave
> 
> > > Curiosly my local tame Qwen3 LLM explained the rounding up:
> > > 
> > > > I see some code doing 'j = (j + 2) / 3'  - what's it trying to do?
> > > The expression `j = (j + 2) / 3` is a clever way to **round up an
> > > integer division by 3** — that is, it computes the ceiling of `j / 3`
> > > for non-negative integers.
> > 
> > Good to see!
> > 
> > 							Thanx, Paul
> > 
> > > Dave
> > > 
> > > > 
> > > > 							Thanx, Paul
> > > > 
> > > > > > > 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
> > > > > > > >
> > > > > >
> > > > 
> > > -- 
> > >  -----Open up your eyes, open up your mind, open up your code -------   
> > > / Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
> > > \        dave @ treblig.org |                               | In Hex /
> > >  \ _________________________|_____ http://www.treblig.org   |_______/
> -- 
>  -----Open up your eyes, open up your mind, open up your code -------   
> / Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
> \        dave @ treblig.org |                               | In Hex /
>  \ _________________________|_____ http://www.treblig.org   |_______/

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Sun, 28 Dec 2025 10:36:39 +0100 (CET)
Julia Lawall <julia.lawall@inria.fr> wrote:

> > > > > j = (j + 2) / 3;  
> > > >
> > > > "Divide by three rounding up."  

That's as useful as:

	/* Add one to X */
	x++;

> > >
> > > That's not *that* obvious, but ok, but then why 3?
> > >

Bingo! You win a cigar! :-)

I know that was a round up (and yes, as David pointed out, we have macros
for that too). The question is why are you dividing it by 3? I don't see
anything in that function which suggests the reason for needing to divide j
by 3.

If the comments you were adding in the past was things like "Divide by
three rounding up" then yeah, I can see why people would say you have too
many comments. The comments are not to be discussing what is being done,
but why is it being done.

			WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
				   jiffies + (j ? 3 * j : 2));


Why the: (j ? 3 * j : 2) ?

Why is 3 so magical?

			/*
			 * j is the Father, Son and Holy Ghost.
			 * But only one may be active at a time.
			 * They each take a third. Father is first,
			 * Son is second, and Holy Ghost is third.
			 */
			j = (j + 2) / 3;

			/*
			 * j may not be zero, as that would lead to
			 * damnation. 
			 */
			if (j <= 0)
				j = 1;

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Mon, Dec 29, 2025 at 10:40:05AM -0500, Steven Rostedt wrote:
> On Sun, 28 Dec 2025 10:36:39 +0100 (CET)
> Julia Lawall <julia.lawall@inria.fr> wrote:
> 
> > > > > > j = (j + 2) / 3;  
> > > > >
> > > > > "Divide by three rounding up."  
> 
> That's as useful as:
> 
> 	/* Add one to X */
> 	x++;
> 
> > > >
> > > > That's not *that* obvious, but ok, but then why 3?
> > > >
> 
> Bingo! You win a cigar! :-)
> 
> I know that was a round up (and yes, as David pointed out, we have macros
> for that too). The question is why are you dividing it by 3? I don't see
> anything in that function which suggests the reason for needing to divide j
> by 3.
> 
> If the comments you were adding in the past was things like "Divide by
> three rounding up" then yeah, I can see why people would say you have too
> many comments. The comments are not to be discussing what is being done,
> but why is it being done.
> 
> 			WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
> 				   jiffies + (j ? 3 * j : 2));
> 
> 
> Why the: (j ? 3 * j : 2) ?
> 
> Why is 3 so magical?
> 
> 			/*
> 			 * j is the Father, Son and Holy Ghost.
> 			 * But only one may be active at a time.
> 			 * They each take a third. Father is first,
> 			 * Son is second, and Holy Ghost is third.
> 			 */
> 			j = (j + 2) / 3;
> 
> 			/*
> 			 * j may not be zero, as that would lead to
> 			 * damnation. 
> 			 */
> 			if (j <= 0)
> 				j = 1;

I would of course nack that comment, amusing though it might be to track
others' reactions to it over time.  ;-)

So you are now unwilling to do a walkthrough?  That would be unfortunate.

If your view is that I should just answer the question so that
everyone can get on with life, please keep in mind that there are some
tens of thousands of other lines of code in Linux-kernel RCU.  It is
therefore only reasonable that I insist upon a more organized approach.
In addition, as noted earlier [1], you guys are members of one of the
smaller audiences that need my assistance.  Plus you were on CC for the
patch that added this line.  ;-)

On the other hand, if your view is instead that because the three of
you don't immediately grok this line of code, I should be willing to
take hundreds of lines of LLM-generated comments for each and every
non-trivial RCU function (for some TBD definition of "non-trivial"),
sorry, but no, that does not follow.

							Thanx, Paul

[1] https://lore.kernel.org/all/fe8c7e28-b5fe-4411-b27c-b2efd89a74c7@paulmck-laptop/

Re: Follow-up on Linux-kernel code accessibility

[Dr. David Alan Gilbert]

* Paul E. McKenney (paulmck@kernel.org) wrote:
> On Mon, Dec 29, 2025 at 10:40:05AM -0500, Steven Rostedt wrote:
> > On Sun, 28 Dec 2025 10:36:39 +0100 (CET)
> > Julia Lawall <julia.lawall@inria.fr> wrote:
> > 
> > > > > > > j = (j + 2) / 3;  
> > > > > >
> > > > > > "Divide by three rounding up."  
> > 
> > That's as useful as:
> > 
> > 	/* Add one to X */
> > 	x++;
> > 
> > > > >
> > > > > That's not *that* obvious, but ok, but then why 3?
> > > > >
> > 
> > Bingo! You win a cigar! :-)
> > 
> > I know that was a round up (and yes, as David pointed out, we have macros
> > for that too). The question is why are you dividing it by 3? I don't see
> > anything in that function which suggests the reason for needing to divide j
> > by 3.
> > 
> > If the comments you were adding in the past was things like "Divide by
> > three rounding up" then yeah, I can see why people would say you have too
> > many comments. The comments are not to be discussing what is being done,
> > but why is it being done.
> > 
> > 			WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
> > 				   jiffies + (j ? 3 * j : 2));
> > 
> > 
> > Why the: (j ? 3 * j : 2) ?
> > 
> > Why is 3 so magical?
> > 
> > 			/*
> > 			 * j is the Father, Son and Holy Ghost.
> > 			 * But only one may be active at a time.
> > 			 * They each take a third. Father is first,
> > 			 * Son is second, and Holy Ghost is third.
> > 			 */
> > 			j = (j + 2) / 3;
> > 
> > 			/*
> > 			 * j may not be zero, as that would lead to
> > 			 * damnation. 
> > 			 */
> > 			if (j <= 0)
> > 				j = 1;
> 
> I would of course nack that comment, amusing though it might be to track
> others' reactions to it over time.  ;-)
> 
> So you are now unwilling to do a walkthrough?  That would be unfortunate.
> 
> If your view is that I should just answer the question so that
> everyone can get on with life, please keep in mind that there are some
> tens of thousands of other lines of code in Linux-kernel RCU.  It is
> therefore only reasonable that I insist upon a more organized approach.

I'm actually not interested in the answer to what the magical 3 is *;
I just think this piece of code is a nice example of code that has
poor accessibility - both for human and AI - although frankly the
humans might find it harder.

My point of my previous response was that I don't think this is an
example of something that needs clever extra stuff for some of the
accessibility issues; just the basics of not using magic constants
and making sure clever tricks are either commented or use
appropriate named functions.  That's just basic good style!

> In addition, as noted earlier [1], you guys are members of one of the
> smaller audiences that need my assistance.  Plus you were on CC for the
> patch that added this line.  ;-)
> 
> On the other hand, if your view is instead that because the three of
> you don't immediately grok this line of code, I should be willing to
> take hundreds of lines of LLM-generated comments for each and every
> non-trivial RCU function (for some TBD definition of "non-trivial"),
> sorry, but no, that does not follow.

That indeed would be terrible; but a few clear basic comments around
clever stuff would be great.

Dave
(* It's obviously for Huey, Dewey, and Louie)
> 							Thanx, Paul
> 
> [1] https://lore.kernel.org/all/fe8c7e28-b5fe-4411-b27c-b2efd89a74c7@paulmck-laptop/
-- 
 -----Open up your eyes, open up your mind, open up your code -------   
/ Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
\        dave @ treblig.org |                               | In Hex /
 \ _________________________|_____ http://www.treblig.org   |_______/

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Mon, Dec 29, 2025 at 05:02:04PM +0000, Dr. David Alan Gilbert wrote:
> * Paul E. McKenney (paulmck@kernel.org) wrote:
> > On Mon, Dec 29, 2025 at 10:40:05AM -0500, Steven Rostedt wrote:
> > > On Sun, 28 Dec 2025 10:36:39 +0100 (CET)
> > > Julia Lawall <julia.lawall@inria.fr> wrote:
> > > 
> > > > > > > > j = (j + 2) / 3;  
> > > > > > >
> > > > > > > "Divide by three rounding up."  
> > > 
> > > That's as useful as:
> > > 
> > > 	/* Add one to X */
> > > 	x++;
> > > 
> > > > > >
> > > > > > That's not *that* obvious, but ok, but then why 3?
> > > > > >
> > > 
> > > Bingo! You win a cigar! :-)
> > > 
> > > I know that was a round up (and yes, as David pointed out, we have macros
> > > for that too). The question is why are you dividing it by 3? I don't see
> > > anything in that function which suggests the reason for needing to divide j
> > > by 3.
> > > 
> > > If the comments you were adding in the past was things like "Divide by
> > > three rounding up" then yeah, I can see why people would say you have too
> > > many comments. The comments are not to be discussing what is being done,
> > > but why is it being done.
> > > 
> > > 			WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
> > > 				   jiffies + (j ? 3 * j : 2));
> > > 
> > > 
> > > Why the: (j ? 3 * j : 2) ?
> > > 
> > > Why is 3 so magical?
> > > 
> > > 			/*
> > > 			 * j is the Father, Son and Holy Ghost.
> > > 			 * But only one may be active at a time.
> > > 			 * They each take a third. Father is first,
> > > 			 * Son is second, and Holy Ghost is third.
> > > 			 */
> > > 			j = (j + 2) / 3;
> > > 
> > > 			/*
> > > 			 * j may not be zero, as that would lead to
> > > 			 * damnation. 
> > > 			 */
> > > 			if (j <= 0)
> > > 				j = 1;
> > 
> > I would of course nack that comment, amusing though it might be to track
> > others' reactions to it over time.  ;-)
> > 
> > So you are now unwilling to do a walkthrough?  That would be unfortunate.
> > 
> > If your view is that I should just answer the question so that
> > everyone can get on with life, please keep in mind that there are some
> > tens of thousands of other lines of code in Linux-kernel RCU.  It is
> > therefore only reasonable that I insist upon a more organized approach.
> 
> I'm actually not interested in the answer to what the magical 3 is *;
> I just think this piece of code is a nice example of code that has
> poor accessibility - both for human and AI - although frankly the
> humans might find it harder.
> 
> My point of my previous response was that I don't think this is an
> example of something that needs clever extra stuff for some of the
> accessibility issues; just the basics of not using magic constants
> and making sure clever tricks are either commented or use
> appropriate named functions.  That's just basic good style!

I am *not* arguing against adding a commment.  I am instead arguing for
an organized approach, for example, guided by the following:

1.	What lines should be commented?

2.	What level of detail should be provided?

3.	What prerequisites should be assumed for those diving into
	Linux-kernel RCU code?

If we instead do random drive-by comment additions at random times
throughout kernel/rcu, all we will accomplish is making a bigger mess.

> > In addition, as noted earlier [1], you guys are members of one of the
> > smaller audiences that need my assistance.  Plus you were on CC for the
> > patch that added this line.  ;-)
> > 
> > On the other hand, if your view is instead that because the three of
> > you don't immediately grok this line of code, I should be willing to
> > take hundreds of lines of LLM-generated comments for each and every
> > non-trivial RCU function (for some TBD definition of "non-trivial"),
> > sorry, but no, that does not follow.
> 
> That indeed would be terrible; but a few clear basic comments around
> clever stuff would be great.

I appreciate the compliment, but this line is not particularly clever.
It just gets its job done.

Glad you agree on the "terrible" part, but this is exactly one of the
things that was being seriously proposed at LPC.  And not just for RCU,
but for the entire kernel.

> Dave
> (* It's obviously for Huey, Dewey, and Louie)

Ah, Pascal!  I remember it well, having worked on two projects that used
Pascal code in production.  I was quite happy to transition to 1980s
C code.  ;-)

							Thanx, Paul

> > [1] https://lore.kernel.org/all/fe8c7e28-b5fe-4411-b27c-b2efd89a74c7@paulmck-laptop/
> -- 
>  -----Open up your eyes, open up your mind, open up your code -------   
> / Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
> \        dave @ treblig.org |                               | In Hex /
>  \ _________________________|_____ http://www.treblig.org   |_______/

Re: Follow-up on Linux-kernel code accessibility

[Dr. David Alan Gilbert]

* Paul E. McKenney (paulmck@kernel.org) wrote:
> On Mon, Dec 29, 2025 at 05:02:04PM +0000, Dr. David Alan Gilbert wrote:
> > * Paul E. McKenney (paulmck@kernel.org) wrote:
> > > On Mon, Dec 29, 2025 at 10:40:05AM -0500, Steven Rostedt wrote:
> > > > On Sun, 28 Dec 2025 10:36:39 +0100 (CET)
> > > > Julia Lawall <julia.lawall@inria.fr> wrote:
> > > > 
> > > > > > > > > j = (j + 2) / 3;  
> > > > > > > >
> > > > > > > > "Divide by three rounding up."  
> > > > 
> > > > That's as useful as:
> > > > 
> > > > 	/* Add one to X */
> > > > 	x++;
> > > > 
> > > > > > >
> > > > > > > That's not *that* obvious, but ok, but then why 3?
> > > > > > >
> > > > 
> > > > Bingo! You win a cigar! :-)
> > > > 
> > > > I know that was a round up (and yes, as David pointed out, we have macros
> > > > for that too). The question is why are you dividing it by 3? I don't see
> > > > anything in that function which suggests the reason for needing to divide j
> > > > by 3.
> > > > 
> > > > If the comments you were adding in the past was things like "Divide by
> > > > three rounding up" then yeah, I can see why people would say you have too
> > > > many comments. The comments are not to be discussing what is being done,
> > > > but why is it being done.
> > > > 
> > > > 			WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
> > > > 				   jiffies + (j ? 3 * j : 2));
> > > > 
> > > > 
> > > > Why the: (j ? 3 * j : 2) ?
> > > > 
> > > > Why is 3 so magical?
> > > > 
> > > > 			/*
> > > > 			 * j is the Father, Son and Holy Ghost.
> > > > 			 * But only one may be active at a time.
> > > > 			 * They each take a third. Father is first,
> > > > 			 * Son is second, and Holy Ghost is third.
> > > > 			 */
> > > > 			j = (j + 2) / 3;
> > > > 
> > > > 			/*
> > > > 			 * j may not be zero, as that would lead to
> > > > 			 * damnation. 
> > > > 			 */
> > > > 			if (j <= 0)
> > > > 				j = 1;
> > > 
> > > I would of course nack that comment, amusing though it might be to track
> > > others' reactions to it over time.  ;-)
> > > 
> > > So you are now unwilling to do a walkthrough?  That would be unfortunate.
> > > 
> > > If your view is that I should just answer the question so that
> > > everyone can get on with life, please keep in mind that there are some
> > > tens of thousands of other lines of code in Linux-kernel RCU.  It is
> > > therefore only reasonable that I insist upon a more organized approach.
> > 
> > I'm actually not interested in the answer to what the magical 3 is *;
> > I just think this piece of code is a nice example of code that has
> > poor accessibility - both for human and AI - although frankly the
> > humans might find it harder.
> > 
> > My point of my previous response was that I don't think this is an
> > example of something that needs clever extra stuff for some of the
> > accessibility issues; just the basics of not using magic constants
> > and making sure clever tricks are either commented or use
> > appropriate named functions.  That's just basic good style!
> 
> I am *not* arguing against adding a commment.  I am instead arguing for
> an organized approach, for example, guided by the following:
> 
> 1.	What lines should be commented?

IMHO thinking in 'lines' is wrong; if this was a /3 in something where
the 3 was obvious (say in an x/y/z set or in a handle_triangle function)
it wouldn't need anything.
This loop is apparently doing something clever in moving ahead a few
jiffies, but no one knows why it's working in 3s or why that other ?: line
Steve mentioned chose to use the :2 in that set of 3.

> 2.	What level of detail should be provided?

Enough to point people at better documentation for hard stuff,
but commented enough that you don't have to go looking at the docs
all the time.

> 3.	What prerequisites should be assumed for those diving into
> 	Linux-kernel RCU code?

IMHO all code should be 'readable' - no magic constants is a standard
readability thing in any project.

But, it might depend on why they're diving in - did it show up in
a profile when they were working on something else?  Did their compiler
break on it?   Do they have a backtrace from somewhere including it?
Or do they actually feel like improving RCU.
If they actually want to improve RCU then sure the prerequisities
involve reading every reasonable piece of RCU docs; but in the other
cases?  Don't make it too hard.

> If we instead do random drive-by comment additions at random times
> throughout kernel/rcu, all we will accomplish is making a bigger mess.

Well, cleaning up bits people find hard to understand isn't that bad an idea
as long as they really do make it easier.

> > > In addition, as noted earlier [1], you guys are members of one of the
> > > smaller audiences that need my assistance.  Plus you were on CC for the
> > > patch that added this line.  ;-)
> > > 
> > > On the other hand, if your view is instead that because the three of
> > > you don't immediately grok this line of code, I should be willing to
> > > take hundreds of lines of LLM-generated comments for each and every
> > > non-trivial RCU function (for some TBD definition of "non-trivial"),
> > > sorry, but no, that does not follow.
> > 
> > That indeed would be terrible; but a few clear basic comments around
> > clever stuff would be great.
> 
> I appreciate the compliment, but this line is not particularly clever.
> It just gets its job done.

If the job it was trying to get done was clear then that might be OK;
it's not!

These things aren't individual lines either; think of it more cumulative;
you've for some reason landed in needing to look at the RCU code:
  a) It's the RCU code, so everyone knows it's magic
  b) You're looking at a magic 3 constant
  c) With some clever rounding trick
  d) On the descriptively named variable 'j'
  e) many other variables in the function have most vowels missing.

If it was only one of those then you can take a deep breath and poke
your way through it before having to ask; but the combination
makes the learning curve crazy.

> Glad you agree on the "terrible" part, but this is exactly one of the
> things that was being seriously proposed at LPC.  And not just for RCU,
> but for the entire kernel.
> 
> > Dave
> > (* It's obviously for Huey, Dewey, and Louie)
> 
> Ah, Pascal!  I remember it well, having worked on two projects that used
> Pascal code in production.  I was quite happy to transition to 1980s
> C code.  ;-)

The transition was Wirth it.

Dave

> 							Thanx, Paul
> 
> > > [1] https://lore.kernel.org/all/fe8c7e28-b5fe-4411-b27c-b2efd89a74c7@paulmck-laptop/
> > -- 
> >  -----Open up your eyes, open up your mind, open up your code -------   
> > / Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
> > \        dave @ treblig.org |                               | In Hex /
> >  \ _________________________|_____ http://www.treblig.org   |_______/
-- 
 -----Open up your eyes, open up your mind, open up your code -------   
/ Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
\        dave @ treblig.org |                               | In Hex /
 \ _________________________|_____ http://www.treblig.org   |_______/

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Mon, Dec 29, 2025 at 06:10:41PM +0000, Dr. David Alan Gilbert wrote:
> * Paul E. McKenney (paulmck@kernel.org) wrote:
> > On Mon, Dec 29, 2025 at 05:02:04PM +0000, Dr. David Alan Gilbert wrote:
> > > * Paul E. McKenney (paulmck@kernel.org) wrote:
> > > > On Mon, Dec 29, 2025 at 10:40:05AM -0500, Steven Rostedt wrote:
> > > > > On Sun, 28 Dec 2025 10:36:39 +0100 (CET)
> > > > > Julia Lawall <julia.lawall@inria.fr> wrote:
> > > > > 
> > > > > > > > > > j = (j + 2) / 3;  
> > > > > > > > >
> > > > > > > > > "Divide by three rounding up."  
> > > > > 
> > > > > That's as useful as:
> > > > > 
> > > > > 	/* Add one to X */
> > > > > 	x++;
> > > > > 
> > > > > > > >
> > > > > > > > That's not *that* obvious, but ok, but then why 3?
> > > > > > > >
> > > > > 
> > > > > Bingo! You win a cigar! :-)
> > > > > 
> > > > > I know that was a round up (and yes, as David pointed out, we have macros
> > > > > for that too). The question is why are you dividing it by 3? I don't see
> > > > > anything in that function which suggests the reason for needing to divide j
> > > > > by 3.
> > > > > 
> > > > > If the comments you were adding in the past was things like "Divide by
> > > > > three rounding up" then yeah, I can see why people would say you have too
> > > > > many comments. The comments are not to be discussing what is being done,
> > > > > but why is it being done.
> > > > > 
> > > > > 			WRITE_ONCE(rcu_state.jiffies_kick_kthreads,
> > > > > 				   jiffies + (j ? 3 * j : 2));
> > > > > 
> > > > > 
> > > > > Why the: (j ? 3 * j : 2) ?
> > > > > 
> > > > > Why is 3 so magical?
> > > > > 
> > > > > 			/*
> > > > > 			 * j is the Father, Son and Holy Ghost.
> > > > > 			 * But only one may be active at a time.
> > > > > 			 * They each take a third. Father is first,
> > > > > 			 * Son is second, and Holy Ghost is third.
> > > > > 			 */
> > > > > 			j = (j + 2) / 3;
> > > > > 
> > > > > 			/*
> > > > > 			 * j may not be zero, as that would lead to
> > > > > 			 * damnation. 
> > > > > 			 */
> > > > > 			if (j <= 0)
> > > > > 				j = 1;
> > > > 
> > > > I would of course nack that comment, amusing though it might be to track
> > > > others' reactions to it over time.  ;-)
> > > > 
> > > > So you are now unwilling to do a walkthrough?  That would be unfortunate.
> > > > 
> > > > If your view is that I should just answer the question so that
> > > > everyone can get on with life, please keep in mind that there are some
> > > > tens of thousands of other lines of code in Linux-kernel RCU.  It is
> > > > therefore only reasonable that I insist upon a more organized approach.
> > > 
> > > I'm actually not interested in the answer to what the magical 3 is *;
> > > I just think this piece of code is a nice example of code that has
> > > poor accessibility - both for human and AI - although frankly the
> > > humans might find it harder.
> > > 
> > > My point of my previous response was that I don't think this is an
> > > example of something that needs clever extra stuff for some of the
> > > accessibility issues; just the basics of not using magic constants
> > > and making sure clever tricks are either commented or use
> > > appropriate named functions.  That's just basic good style!
> > 
> > I am *not* arguing against adding a commment.  I am instead arguing for
> > an organized approach, for example, guided by the following:
> > 
> > 1.	What lines should be commented?
> 
> IMHO thinking in 'lines' is wrong; if this was a /3 in something where
> the 3 was obvious (say in an x/y/z set or in a handle_triangle function)
> it wouldn't need anything.
> This loop is apparently doing something clever in moving ahead a few
> jiffies, but no one knows why it's working in 3s or why that other ?: line
> Steve mentioned chose to use the :2 in that set of 3.

Well, you guys pointed to this line, and not to some other code construct,
so it is on you guys to un-wrong your own thinking.  ;-)

The point here is that there are a lot of uncommented lines of code in
Linux-kernel RCU.  There are no doubt also lines that are commented,
but whose comments are not sufficiently clear to some target audience
or another.  Which should receive additional comments and why?  Of those
that should receive additional comments, what is the priority ordering
for actually doing that work?

> > 2.	What level of detail should be provided?
> 
> Enough to point people at better documentation for hard stuff,
> but commented enough that you don't have to go looking at the docs
> all the time.

Experience indicates that this line of code does not appear to qualify
as the hard stuff in the context of the Linux-kernel RCU implementation.

> > 3.	What prerequisites should be assumed for those diving into
> > 	Linux-kernel RCU code?
> 
> IMHO all code should be 'readable' - no magic constants is a standard
> readability thing in any project.

What is your basis for stating that this particular constant qualifies
as magic?

> But, it might depend on why they're diving in - did it show up in
> a profile when they were working on something else?  Did their compiler
> break on it?   Do they have a backtrace from somewhere including it?

Show up in a profile?  Unlikely.  Compiler break on it?  Who knows, but
this line is just simple arithmetic.  Appear in a backtrace?  Not likely
unless the compiler broke on it.

> Or do they actually feel like improving RCU.
> If they actually want to improve RCU then sure the prerequisities
> involve reading every reasonable piece of RCU docs; but in the other
> cases?  Don't make it too hard.

I only get 24 hours in each day, my friend.  Experience has shown that
there are way more people struggling with code using RCU than with code
implementing RCU, so the former get priority.  I could hit you with a
Spock quote from a certain movie, if you would like.  ;-)

And as noted earlier in this thread, the mm subtree just got a 1300-page
textbook to explain its workings.  If the 150LoC per textbook page
translation holds, that suggests somewhere around 100-200 pages of
textbook for the RCU implementation.  So yes, significant learning curve.

And yes, I have burned more time on this than would be consumed by just
proposing a comment.  That would be because you guys are straining on
a gnat while swallowing huge numbers of camels.  We fix the camels
first, and that requires some way of identifying them.  Plus it is
entirely possible that an accurate comment describing this line would
make things *less* clear for our poor unprepared developer who is diving
into this code.

> > If we instead do random drive-by comment additions at random times
> > throughout kernel/rcu, all we will accomplish is making a bigger mess.
> 
> Well, cleaning up bits people find hard to understand isn't that bad an idea
> as long as they really do make it easier.

Fair enough, but from what I can see, you guys are just piling onto
a randomly selected (and rarely executed) piece of code without any
regard to whether any added comment would actually help anyone.  I am
willing to put up with this if (and only if) Steve actually does the
walkthrough.  ;-)

But as long as you are here, what is your opinion on adding inline
comments to local variables?

> > > > In addition, as noted earlier [1], you guys are members of one of the
> > > > smaller audiences that need my assistance.  Plus you were on CC for the
> > > > patch that added this line.  ;-)
> > > > 
> > > > On the other hand, if your view is instead that because the three of
> > > > you don't immediately grok this line of code, I should be willing to
> > > > take hundreds of lines of LLM-generated comments for each and every
> > > > non-trivial RCU function (for some TBD definition of "non-trivial"),
> > > > sorry, but no, that does not follow.
> > > 
> > > That indeed would be terrible; but a few clear basic comments around
> > > clever stuff would be great.
> > 
> > I appreciate the compliment, but this line is not particularly clever.
> > It just gets its job done.
> 
> If the job it was trying to get done was clear then that might be OK;
> it's not!
> 
> These things aren't individual lines either; think of it more cumulative;
> you've for some reason landed in needing to look at the RCU code:
>   a) It's the RCU code, so everyone knows it's magic
>   b) You're looking at a magic 3 constant
>   c) With some clever rounding trick
>   d) On the descriptively named variable 'j'
>   e) many other variables in the function have most vowels missing.
> 
> If it was only one of those then you can take a deep breath and poke
> your way through it before having to ask; but the combination
> makes the learning curve crazy.

My points 1, 2, and 3 above still stand.  ;-)

> > Glad you agree on the "terrible" part, but this is exactly one of the
> > things that was being seriously proposed at LPC.  And not just for RCU,
> > but for the entire kernel.
> > 
> > > Dave
> > > (* It's obviously for Huey, Dewey, and Louie)
> > 
> > Ah, Pascal!  I remember it well, having worked on two projects that used
> > Pascal code in production.  I was quite happy to transition to 1980s
> > C code.  ;-)
> 
> The transition was Wirth it.

;-) ;-) ;-)

							Thanx, Paul

> Dave
> > 
> > > > [1] https://lore.kernel.org/all/fe8c7e28-b5fe-4411-b27c-b2efd89a74c7@paulmck-laptop/
> > > -- 
> > >  -----Open up your eyes, open up your mind, open up your code -------   
> > > / Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
> > > \        dave @ treblig.org |                               | In Hex /
> > >  \ _________________________|_____ http://www.treblig.org   |_______/
> -- 
>  -----Open up your eyes, open up your mind, open up your code -------   
> / Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
> \        dave @ treblig.org |                               | In Hex /
>  \ _________________________|_____ http://www.treblig.org   |_______/

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Mon, 29 Dec 2025 10:59:12 -0800
"Paul E. McKenney" <paulmck@kernel.org> wrote:

> > > 1.	What lines should be commented?  
> > 
> > IMHO thinking in 'lines' is wrong; if this was a /3 in something where
> > the 3 was obvious (say in an x/y/z set or in a handle_triangle function)
> > it wouldn't need anything.
> > This loop is apparently doing something clever in moving ahead a few
> > jiffies, but no one knows why it's working in 3s or why that other ?: line
> > Steve mentioned chose to use the :2 in that set of 3.  
> 
> Well, you guys pointed to this line, and not to some other code construct,
> so it is on you guys to un-wrong your own thinking.  ;-)

Specifically, it was me that pointed it out.

> 
> The point here is that there are a lot of uncommented lines of code in
> Linux-kernel RCU.  There are no doubt also lines that are commented,
> but whose comments are not sufficiently clear to some target audience
> or another.  Which should receive additional comments and why?  Of those
> that should receive additional comments, what is the priority ordering
> for actually doing that work?

The point is that there should be no magic numbers without some comments to
why they are magical. I pointed this code out because it is a real life
example. I saw Joel's RFC about jiffies_till_first_fqs being off by one and
wanted to investigate. It brought me to this code. Once I saw that the
variable that Joel specified had some unknown division by 3, I gave up on
looking at it.

I don't expect to have to call for a meeting with the developers to do a
walkthrough of their code every time I see there's an issue with their
code. I hardly doubt that anyone would be up to that (besides you).

You have yet to even say why "3" is of value here. And it appears I'll only
find out about this magically 3 when we go through a walk through. Why is
it so secretive?

If it requires a walkthrough to understand why you used 3, then damn, it
should most definitely have a comment about it.

The target audience of comments should be anyone interested in how that
code functions. (AKA any kernel developer). Why does this have to be so
difficult?


> 
> > > 2.	What level of detail should be provided?  
> > 
> > Enough to point people at better documentation for hard stuff,
> > but commented enough that you don't have to go looking at the docs
> > all the time.  
> 
> Experience indicates that this line of code does not appear to qualify
> as the hard stuff in the context of the Linux-kernel RCU implementation.

What code is not the "hard stuff". Why the division of 3? Details matter,
especially when it comes to constants in code.

> 
> > > 3.	What prerequisites should be assumed for those diving into
> > > 	Linux-kernel RCU code?  
> > 
> > IMHO all code should be 'readable' - no magic constants is a standard
> > readability thing in any project.  
> 
> What is your basis for stating that this particular constant qualifies
> as magic?

  ALL CONSTANTS ARE MAGIC!

This is something I learned in CS-101. No constants without comments. In
fact, I try to replace all constants with enums or macros, so that they
have meaning. Right now, "3" has no meaning. I used the example of "Father,
Son and Holy Ghost" to show that it could mean anything!


> 
> > But, it might depend on why they're diving in - did it show up in
> > a profile when they were working on something else?  Did their compiler
> > break on it?   Do they have a backtrace from somewhere including it?  
> 
> Show up in a profile?  Unlikely.  Compiler break on it?  Who knows, but
> this line is just simple arithmetic.  Appear in a backtrace?  Not likely
> unless the compiler broke on it.

You're missing the point! It is not about the arithmetic. If you think the
arithmetic is the problem than we are having a major miscommunication here.

The problem is why did you choose "3". Why not "4" or "5" or "42"???

There's nothing there that says "3" is needed. Why divide at all? Why not
just add 1?

The arithmetic is not the issue, it's why you picked this particular
arithmetic to begin with.


> 
> > Or do they actually feel like improving RCU.
> > If they actually want to improve RCU then sure the prerequisities
> > involve reading every reasonable piece of RCU docs; but in the other
> > cases?  Don't make it too hard.  
> 
> I only get 24 hours in each day, my friend.  Experience has shown that
> there are way more people struggling with code using RCU than with code
> implementing RCU, so the former get priority.  I could hit you with a
> Spock quote from a certain movie, if you would like.  ;-)
> 
> And as noted earlier in this thread, the mm subtree just got a 1300-page
> textbook to explain its workings.  If the 150LoC per textbook page
> translation holds, that suggests somewhere around 100-200 pages of
> textbook for the RCU implementation.  So yes, significant learning curve.

That's for general design for a deep dive. Great for people who are going
to architect and make big changes if needed. But for those just trying to
understand why a function exists, it's way too much of a big hammer.

> 
> And yes, I have burned more time on this than would be consumed by just
> proposing a comment.  That would be because you guys are straining on
> a gnat while swallowing huge numbers of camels.  We fix the camels
> first, and that requires some way of identifying them.  Plus it is
> entirely possible that an accurate comment describing this line would
> make things *less* clear for our poor unprepared developer who is diving
> into this code.

I think we are talking way past each other and this is why it's not moving
forward.

> 
> > > If we instead do random drive-by comment additions at random times
> > > throughout kernel/rcu, all we will accomplish is making a bigger mess.  
> > 
> > Well, cleaning up bits people find hard to understand isn't that bad an idea
> > as long as they really do make it easier.  
> 
> Fair enough, but from what I can see, you guys are just piling onto
> a randomly selected (and rarely executed) piece of code without any
> regard to whether any added comment would actually help anyone.  I am
> willing to put up with this if (and only if) Steve actually does the
> walkthrough.  ;-)

I picked this random code because it was an example of something that I hit
very recently. And doing a walkthrough is fine, but what is the purpose of
this walkthrough? So I can understand the issue that Joel is dealing with?

> 
> But as long as you are here, what is your opinion on adding inline
> comments to local variables?

Not sure what you mean by that. Names of variables should be self
descriptive, but how they are used should be commented (if it's not totally
obvious).

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Dr. David Alan Gilbert]

* Steven Rostedt (rostedt@goodmis.org) wrote:

> There's nothing there that says "3" is needed. Why divide at all? Why not
> just add 1?

Now while Paul obviously doesn't want to tell us, I decided I should
do what someone who actually cared would do, and looked at the git history,
To my surprise, I see I made a mistake - the three magic constants
in this function were all added separately, and the two uses of '3'
are not necessarily the same.

8c7c4829a8 - from 2016 
  rcu: Awaken grace-period kthread if too long since FQS

  says it's a crude hack but doesn't mention why it chose 3 in the commit
  message; among other stuff it adds:

+                               WRITE_ONCE(rsp->jiffies_kick_kthreads,
+                                          jiffies + 3 * j);

9cf422a8 - from 2018
  rcu: Accommodate zero jiffies_till_first_fqs and kthread kicking

  replaces that:
-                                  jiffies + 3 * j);
+                                  jiffies + (j ? 3 * j : 2));

  to stop using too much cpu and says 'at least two jiffies'

fb77dcc - from 2022
  rcu: Decrease FQS scan wait time in case of callback overloading

  introduces the:
  j = (j + 2) / 3;
and commit message says:
    This commit therefore divides the normal time between rescans by three,
    rounding up.  Thus a small system running at HZ=1000 that is suffering
    from callback overload will wait only one jiffy instead of the normal
    three between rescans.

So that one does have a commit message explanation at least; although
I'm not sure I know where the 'normal three' comes from - but I guess
that's followable eventually.

But heck, this is making it hard to find them.

Dave

-- 
 -----Open up your eyes, open up your mind, open up your code -------   
/ Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
\        dave @ treblig.org |                               | In Hex /
 \ _________________________|_____ http://www.treblig.org   |_______/

Re: Follow-up on Linux-kernel code accessibility

[Theodore Tso]

On Mon, Dec 29, 2025 at 10:59:12AM -0800, Paul E. McKenney wrote:
> > Or do they actually feel like improving RCU.
> > If they actually want to improve RCU then sure the prerequisities
> > involve reading every reasonable piece of RCU docs; but in the other
> > cases?  Don't make it too hard.
> 
> I only get 24 hours in each day, my friend.  Experience has shown that
> there are way more people struggling with code using RCU than with code
> implementing RCU, so the former get priority.  I could hit you with a
> Spock quote from a certain movie, if you would like.  ;-)

,.. and that's why I was recalling the comment, "You are not expected
to understand this" and asking the question of which audience are we
trying to make the code more accessible for, at least first.

Yes, it would be good if there were more than one person who can
understand the details of the code and who can maintain it, so we
don't have teh bus factor == 1 problem.  But the fact remains that are
many parts of the kernel that I will freely admit that I have no
*clue* how it work, and that's OK.  I'm sure if I spent a few weeks
deeply meditating on the code, I could eventually figure it out ---
but I don't have that kind of spare time.  Nor am I someone who is
going to insist on a lot of documentation of internal details, since I
happen to believe, like you, that accessibility to *users* of RCU is
more important that people who are curious about the internal details
about why we are dividing by 3, and not 4 (and 5 is right out) :-)

     	     	 	     	    	  - Ted

P.S.  If someone wants to spend time being the John Lions for RCU,
great!  But that should be someone's passion project, and not
necessarily highest priority for the community at large.

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Mon, 29 Dec 2025 18:50:10 -0500
"Theodore Tso" <tytso@mit.edu> wrote:

> Yes, it would be good if there were more than one person who can
> understand the details of the code and who can maintain it, so we
> don't have teh bus factor == 1 problem.  But the fact remains that are
> many parts of the kernel that I will freely admit that I have no
> *clue* how it work, and that's OK.  I'm sure if I spent a few weeks
> deeply meditating on the code, I could eventually figure it out ---
> but I don't have that kind of spare time.  Nor am I someone who is
> going to insist on a lot of documentation of internal details, since I
> happen to believe, like you, that accessibility to *users* of RCU is
> more important that people who are curious about the internal details
> about why we are dividing by 3, and not 4 (and 5 is right out) :-)

Do we care about reviewers? I keep hearing at every maintainer's summit and
what not that we don't have enough reviewers. Well if it takes weeks to sit
down and gork at code to be able to have a quality review, then yeah, we
are not going to have any reviewers. RCU is one of the core infrastructures
of the kernel. If it is wrong, then bad things can happen. I would think we
would want as many people as possible to be able to understand how it works.

I'm listed as one of the RCU reviewers because I spent a lot of time a few
years back trying very hard to understand all the code. But things have
changed a lot since I did that and when I go back now, I have no clue to how
the simplest things work there anymore and I give up.

I am Cc'd on a lot of the RCU code, and start looking at it when I can, but
it usually comes in batches of 10-40 patches at a time. I can look at 10, but
when it gets more than that, I simply don't have the time anymore to keep up.

I guess I should just remove my name as a reviewer.

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Mon, 29 Dec 2025 19:19:23 -0500
Steven Rostedt <rostedt@goodmis.org> wrote:

> I'm listed as one of the RCU reviewers because I spent a lot of time a few
> years back trying very hard to understand all the code. But things have
> changed a lot since I did that and when I go back now, I have no clue to how
> the simplest things work there anymore and I give up.

Although I will say that Paul did a terrific job when it came to RCU in the
Documentation directory. I should take some time out and read his RCU
handbook again to refresh my memory of all things RCU.

  https://docs.kernel.org/RCU/index.html

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Lorenzo Stoakes]

Sorry been on leave!

Sorry to fork the thread but going to take me a while to catch up with it.

On Thu, Dec 18, 2025 at 11:49:21AM -0800, Paul E. McKenney wrote:
> Hello!
>
> Just following up on some Linux Plumbers Conference discussions on the
> accessibility of Linux-kernel code to people ranging from novices to
> the developers and maintainers of the code in question.  I am adding
> Lorenze on CC not because he was involved with these discussions (at
> least as far as I know), but rather because I am using some of his work
> in my follow-up analysis.
>
> The Linux kernel's mm system weighs in at about 200KLoC, and Lorenzo
> wrote a book on its design that weighs in at about 1300 pages, or
> about 150 LoC/page.  This suggests that the Linux-kernel scheduler,
> which weighs in at about 70KLoC and has similar heuristics/workload
> challenges as does mm, would require a 430-page textbook to provide a
> similar level of design detail.  By this methodology, RCU would require
> "only" 190 pages, presumably substituting its unfamiliarity for sched's
> and mm's deeply heuristic and workload-dependent nature.

Well - keep in mind my book explicitly and intentionally excludes a _great
deal_ of topics (simply because I didn't have the time or capacity to cover
more), and even when exploring the code, I made liberal use of 'X is out of
scope' here to a. make it readable without being distracted constantly, and
b. again for time/capacity reasons.

And of course, I focused on only one architecture for anything
arch-specific (x86-64) with similar excuses^Wreasoning so there's that as a
multiplier too.

Overall I suspect what I cover is really only 10% of mm, as well or not
otherwise as I did.

So I'd x10 the LoC there ;)

>
> Sadly, this data does not support the hypothesis that we can create
> comments that will provide understanding to people taking random dives
> into the Linux kernel's source code.  In contrast to code that is closely
> associated with a specific type of mechanical device, Linux-kernel
> code requires the reader to possess a great deal of abstract and global
> conceptual/workload information.
>
> This is not to say that the Linux kernel's internal documentation
> (including its comments) cannot or should not be improved.
> They clearly should.  It instead means that a necessary part of any
> instant-understanding methodology for the Linux kernel include active
> software assistance, for example, Anthropic's Claude LLM or IBM's (rather
> older but less readily accessible) Analysis and Renovation Catalyst (ARC).
> I am not denigrating other options, but rather restricting myself to
> tools with which I have personal experience.

In my view AI is useful in the hands of an expert who can determine when it
tells the truth or not.

So you have a catch-22 there that's unresolvable by such tooling in my
opinion, and developers relying on that from the start are likely to not
have the right mental muscles exercised in my opinion.

I think there's definitely a place for AI, but I feel like this is not
it. And I think we'd do people a disservice by suggesting it.

A big idea in my book is to get people familiar with the concepts and the
code presented together so they can end up reading the code and
understanding it on the basis of the book having tied the two together and
shown 'hey it's not so bad you can extract meaning from this!'

That way, they can take the inevitably out of date contents and update to
the latest kernel with the skills developed (and of course many of the
concepts will remain valid).

>
> And one reason for continued but reasonable emphasis on internal
> documentation, including comments, is that the aforementioned tools
> ingest that documentation.  ;-)
>
> Thoughts?
>
> And in the meantime, happy holidays for those celebrating them!
>
> 							Thanx, Paul

Cheers, Lorenzo

Re: Follow-up on Linux-kernel code accessibility

[Lorenzo Stoakes]

On Fri, Dec 19, 2025 at 04:05:33PM -0500, Chris Mason wrote:
> On 12/19/25 12:09 PM, Theodore Tso wrote:
> > On Fri, Dec 19, 2025 at 07:51:47AM +0100, Julia Lawall wrote:
> >>
> >> Maybe we're not looking for an instant understanding methodology.  Rather
> >> a machine checkable way to document the invariants that exist in the head
> >> of the developer, and for some bounded amount of time in the head of the
> >> person who has tried to reconstruct them.
> >
> > One of the things that I found really interesting with Chris Mason's
> > kernel review prompts is that it documents some of these invariants
> > which are not otherwise covered in the kernel documentation.  And
> > while Chris originally created those prompts for Anthropic's Claude
> > LLM, we've successfully used them with Gemini 2.5 and 3.
> >
> > I wonder if we should consider folding them into the kernel sources,
> > so they can be updated alongside the kernel.  It might also mean that
> > as the invariants change, the documentation / prompts in an LTS kernel
> > and for the latest upstream kernel can be up to sync with the relevant
> > kernel versions.
> >
>
> Yeah, I agree.  I think/hope these details from the prompts can end up
> folded into the kernel docs.  As the prompts age, we're going to have
> the equivalent of sprinkling ifdefs into them, and I think it's much
> better if they just reference knowledge in the kernel.
>
> I recently pushed out changes that remove most of the process and focus
> more on kernel internals.  So hopefully over time we can get to
> something that just documents kerneling in a way that is useful beyond
> LLMs.
>
> -chris
>

I think we have to be super cautious about ensuring that any such output is
correct.

To me the system is assistant-to-an-expert.

Adding a bunch of invariant details including very subtle (or otherwise)
bugs is worse than having no such documentation.

I say this with a far more broad and open-minded impression of AI tooling
in relation to review and the kernel in general by the way - I'm just
keeping things real here.

Maybe the answer is we need a R-b for any such output from maintainers with
appropriate expertise.

Thanks for the work you're doing on review by the way Chris! Is promising
:)

Cheers, Lorenzo

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Mon, Dec 29, 2025 at 03:35:17PM -0500, Steven Rostedt wrote:
> On Mon, 29 Dec 2025 10:59:12 -0800
> "Paul E. McKenney" <paulmck@kernel.org> wrote:
> 
> > > > 1.	What lines should be commented?  
> > > 
> > > IMHO thinking in 'lines' is wrong; if this was a /3 in something where
> > > the 3 was obvious (say in an x/y/z set or in a handle_triangle function)
> > > it wouldn't need anything.
> > > This loop is apparently doing something clever in moving ahead a few
> > > jiffies, but no one knows why it's working in 3s or why that other ?: line
> > > Steve mentioned chose to use the :2 in that set of 3.  
> > 
> > Well, you guys pointed to this line, and not to some other code construct,
> > so it is on you guys to un-wrong your own thinking.  ;-)
> 
> Specifically, it was me that pointed it out.

Fair enough, so I will let you continue that discussion with Dave.

> > The point here is that there are a lot of uncommented lines of code in
> > Linux-kernel RCU.  There are no doubt also lines that are commented,
> > but whose comments are not sufficiently clear to some target audience
> > or another.  Which should receive additional comments and why?  Of those
> > that should receive additional comments, what is the priority ordering
> > for actually doing that work?
> 
> The point is that there should be no magic numbers without some comments to
> why they are magical. I pointed this code out because it is a real life
> example. I saw Joel's RFC about jiffies_till_first_fqs being off by one and
> wanted to investigate. It brought me to this code. Once I saw that the
> variable that Joel specified had some unknown division by 3, I gave up on
> looking at it.
> 
> I don't expect to have to call for a meeting with the developers to do a
> walkthrough of their code every time I see there's an issue with their
> code. I hardly doubt that anyone would be up to that (besides you).

The Linux-kernel RCU internal documentation is not (yet) intended to
support random entry points.  Plus the context of this email thread is
not a bug report, but rather the question of general accessibilty raised
at Plumbers.  Which I am still having difficulty believing is not really
about auto-creating certification documents from Linux-kernel comments.

Had you instead sent me a separate email asking about this constant,
I would likely have just answered.  I would imagine that Joel would have
done the same in response to your asking him.

> You have yet to even say why "3" is of value here. And it appears I'll only
> find out about this magically 3 when we go through a walk through. Why is
> it so secretive?
> 
> If it requires a walkthrough to understand why you used 3, then damn, it
> should most definitely have a comment about it.

The point of the walkthrough is not to answer that specific question,
but instead to upgrade the documentation of the function containing that
line.  Please keep in mind that I never have had the experience of being
taught about RCU in general, let alone any particular implementation.
Listening to the questions that come up during a walkthrough helps me
figure out what needs to be commented.

And we did walk through that particular function some time back,
but it was apparently overshadowed by the complexity of the related
rcu_gp_init(), rcu_gp_cleanup(), rcu_watching_snap_save(), and
rcu_watching_snap_recheck() functions.  So we did not add much (or maybe
any) in the way of added comments.

Hence my suggestion of a walkthrough.  But if you don't want to do that,
not a problem.  We will get to it at some point, just as we will get to
other functions in need of better comments at some point.

> The target audience of comments should be anyone interested in how that
> code functions. (AKA any kernel developer). Why does this have to be so
> difficult?

Because it is inherently difficult!!!

Please recall that your initial ask was that we comment Linux-kernel RCU
to provide any needed guidance for any kernel developer (plus others
wanted to include non-developers) parachuting anywhere into the code.
Especially for something like Linux-kernel RCU, that is still in
grand-challenge territory.

Don't get me wrong, I am all for that as an aspiration, but it cannot
be a realistic goal at this time.

> > > > 2.	What level of detail should be provided?  
> > > 
> > > Enough to point people at better documentation for hard stuff,
> > > but commented enough that you don't have to go looking at the docs
> > > all the time.  
> > 
> > Experience indicates that this line of code does not appear to qualify
> > as the hard stuff in the context of the Linux-kernel RCU implementation.
> 
> What code is not the "hard stuff". Why the division of 3? Details matter,
> especially when it comes to constants in code.

Our experience walking through this code was that it was in fact not
the hard stuff.

And this constant is but one of a huge number of details of various types.
Next time, someone will dive into some other part of the code for some
other reason and have some other difficulty.

> > > > 3.	What prerequisites should be assumed for those diving into
> > > > 	Linux-kernel RCU code?  
> > > 
> > > IMHO all code should be 'readable' - no magic constants is a standard
> > > readability thing in any project.  
> > 
> > What is your basis for stating that this particular constant qualifies
> > as magic?
> 
>   ALL CONSTANTS ARE MAGIC!
> 
> This is something I learned in CS-101. No constants without comments. In
> fact, I try to replace all constants with enums or macros, so that they
> have meaning. Right now, "3" has no meaning. I used the example of "Father,
> Son and Holy Ghost" to show that it could mean anything!

Sure, we could create a long list of commenting requirements in the
style of Strunk's and White's "The Elements of Style", starting with "No
constants without comments".  We would end up with a mess.  There would be
disconnected comments providing details that made no sense taken together.
Similarly, I would recommend something like Joseph M. Willams's "Style:
Towards Clarity and Grace" over Strunk's and White's list of rules.

I am sorry to disappoint you, but the only way I know to get coherent
comments for Linux-kernel RCU is to have some people walk through the
code so that I can learn what is needed.

I can of course walk through the code and see what *I* need, but that
might or might not be all that helpful to others.

> > > But, it might depend on why they're diving in - did it show up in
> > > a profile when they were working on something else?  Did their compiler
> > > break on it?   Do they have a backtrace from somewhere including it?  
> > 
> > Show up in a profile?  Unlikely.  Compiler break on it?  Who knows, but
> > this line is just simple arithmetic.  Appear in a backtrace?  Not likely
> > unless the compiler broke on it.
> 
> You're missing the point! It is not about the arithmetic. If you think the
> arithmetic is the problem than we are having a major miscommunication here.
> 
> The problem is why did you choose "3". Why not "4" or "5" or "42"???
> 
> There's nothing there that says "3" is needed. Why divide at all? Why not
> just add 1?
> 
> The arithmetic is not the issue, it's why you picked this particular
> arithmetic to begin with.

No, the problem with this function is *not* "why did Paul choose 3?".
The problem is instead making that function's purpose and operation
clear to people going through the code.  At present, the people going
through RCU code need considerable background or some serious time and
stubbornness.  This will get better over time, but I have no wand to wave,
whether for RCU or for any of the other obscure portions of the kernel.

> > > Or do they actually feel like improving RCU.
> > > If they actually want to improve RCU then sure the prerequisities
> > > involve reading every reasonable piece of RCU docs; but in the other
> > > cases?  Don't make it too hard.  
> > 
> > I only get 24 hours in each day, my friend.  Experience has shown that
> > there are way more people struggling with code using RCU than with code
> > implementing RCU, so the former get priority.  I could hit you with a
> > Spock quote from a certain movie, if you would like.  ;-)
> > 
> > And as noted earlier in this thread, the mm subtree just got a 1300-page
> > textbook to explain its workings.  If the 150LoC per textbook page
> > translation holds, that suggests somewhere around 100-200 pages of
> > textbook for the RCU implementation.  So yes, significant learning curve.
> 
> That's for general design for a deep dive. Great for people who are going
> to architect and make big changes if needed. But for those just trying to
> understand why a function exists, it's way too much of a big hammer.

On what evidence do you base this claim?

We are after all still working to get the internal documentation to the
point where it serves the people making big changes.  Need to walk
before running, after all.

> > And yes, I have burned more time on this than would be consumed by just
> > proposing a comment.  That would be because you guys are straining on
> > a gnat while swallowing huge numbers of camels.  We fix the camels
> > first, and that requires some way of identifying them.  Plus it is
> > entirely possible that an accurate comment describing this line would
> > make things *less* clear for our poor unprepared developer who is diving
> > into this code.
> 
> I think we are talking way past each other and this is why it's not moving
> forward.

No argument with the "talking way past each other"!  ;-)

> > > > If we instead do random drive-by comment additions at random times
> > > > throughout kernel/rcu, all we will accomplish is making a bigger mess.  
> > > 
> > > Well, cleaning up bits people find hard to understand isn't that bad an idea
> > > as long as they really do make it easier.  
> > 
> > Fair enough, but from what I can see, you guys are just piling onto
> > a randomly selected (and rarely executed) piece of code without any
> > regard to whether any added comment would actually help anyone.  I am
> > willing to put up with this if (and only if) Steve actually does the
> > walkthrough.  ;-)
> 
> I picked this random code because it was an example of something that I hit
> very recently. And doing a walkthrough is fine, but what is the purpose of
> this walkthrough? So I can understand the issue that Joel is dealing with?

OK, if this still matters (as opposed to your above statement about having
given up), please first ask Joel CCing rcu@vger.kernel.org.  If that
goes sideways, I will see it and will help on this specific question.

> > But as long as you are here, what is your opinion on adding inline
> > comments to local variables?
> 
> Not sure what you mean by that. Names of variables should be self
> descriptive, but how they are used should be commented (if it's not totally
> obvious).

I did not fallow that, but I mean something this:

	int self_descriptive; // Additional self_descriptive details.

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Mon, Dec 29, 2025 at 10:05:15PM +0000, Dr. David Alan Gilbert wrote:
> * Steven Rostedt (rostedt@goodmis.org) wrote:
> 
> > There's nothing there that says "3" is needed. Why divide at all? Why not
> > just add 1?
> 
> Now while Paul obviously doesn't want to tell us, I decided I should
> do what someone who actually cared would do, and looked at the git history,
> To my surprise, I see I made a mistake - the three magic constants
> in this function were all added separately, and the two uses of '3'
> are not necessarily the same.
> 
> 8c7c4829a8 - from 2016 
>   rcu: Awaken grace-period kthread if too long since FQS
> 
>   says it's a crude hack but doesn't mention why it chose 3 in the commit
>   message; among other stuff it adds:
> 
> +                               WRITE_ONCE(rsp->jiffies_kick_kthreads,
> +                                          jiffies + 3 * j);
> 
> 9cf422a8 - from 2018
>   rcu: Accommodate zero jiffies_till_first_fqs and kthread kicking
> 
>   replaces that:
> -                                  jiffies + 3 * j);
> +                                  jiffies + (j ? 3 * j : 2));
> 
>   to stop using too much cpu and says 'at least two jiffies'
> 
> fb77dcc - from 2022
>   rcu: Decrease FQS scan wait time in case of callback overloading
> 
>   introduces the:
>   j = (j + 2) / 3;
> and commit message says:
>     This commit therefore divides the normal time between rescans by three,
>     rounding up.  Thus a small system running at HZ=1000 that is suffering
>     from callback overload will wait only one jiffy instead of the normal
>     three between rescans.
> 
> So that one does have a commit message explanation at least; although
> I'm not sure I know where the 'normal three' comes from - but I guess
> that's followable eventually.
> 
> But heck, this is making it hard to find them.

I do appreciate your digging in and looking in at least the git-history
direction!

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Tue, Jan 06, 2026 at 06:05:28PM +0000, Lorenzo Stoakes wrote:
> Sorry been on leave!

No problem!  At least one of us has priorities straight.  ;-)

> Sorry to fork the thread but going to take me a while to catch up with it.
> 
> On Thu, Dec 18, 2025 at 11:49:21AM -0800, Paul E. McKenney wrote:
> > Hello!
> >
> > Just following up on some Linux Plumbers Conference discussions on the
> > accessibility of Linux-kernel code to people ranging from novices to
> > the developers and maintainers of the code in question.  I am adding
> > Lorenze on CC not because he was involved with these discussions (at
> > least as far as I know), but rather because I am using some of his work
> > in my follow-up analysis.
> >
> > The Linux kernel's mm system weighs in at about 200KLoC, and Lorenzo
> > wrote a book on its design that weighs in at about 1300 pages, or
> > about 150 LoC/page.  This suggests that the Linux-kernel scheduler,
> > which weighs in at about 70KLoC and has similar heuristics/workload
> > challenges as does mm, would require a 430-page textbook to provide a
> > similar level of design detail.  By this methodology, RCU would require
> > "only" 190 pages, presumably substituting its unfamiliarity for sched's
> > and mm's deeply heuristic and workload-dependent nature.
> 
> Well - keep in mind my book explicitly and intentionally excludes a _great
> deal_ of topics (simply because I didn't have the time or capacity to cover
> more), and even when exploring the code, I made liberal use of 'X is out of
> scope' here to a. make it readable without being distracted constantly, and
> b. again for time/capacity reasons.
> 
> And of course, I focused on only one architecture for anything
> arch-specific (x86-64) with similar excuses^Wreasoning so there's that as a
> multiplier too.
> 
> Overall I suspect what I cover is really only 10% of mm, as well or not
> otherwise as I did.
> 
> So I'd x10 the LoC there ;)

Fair enough.  And if you have covered 10% of mm, you are probably ahead
of the coverage of Documntation/RCU/Design.  ;-)

> > Sadly, this data does not support the hypothesis that we can create
> > comments that will provide understanding to people taking random dives
> > into the Linux kernel's source code.  In contrast to code that is closely
> > associated with a specific type of mechanical device, Linux-kernel
> > code requires the reader to possess a great deal of abstract and global
> > conceptual/workload information.
> >
> > This is not to say that the Linux kernel's internal documentation
> > (including its comments) cannot or should not be improved.
> > They clearly should.  It instead means that a necessary part of any
> > instant-understanding methodology for the Linux kernel include active
> > software assistance, for example, Anthropic's Claude LLM or IBM's (rather
> > older but less readily accessible) Analysis and Renovation Catalyst (ARC).
> > I am not denigrating other options, but rather restricting myself to
> > tools with which I have personal experience.
> 
> In my view AI is useful in the hands of an expert who can determine when it
> tells the truth or not.
> 
> So you have a catch-22 there that's unresolvable by such tooling in my
> opinion, and developers relying on that from the start are likely to not
> have the right mental muscles exercised in my opinion.
> 
> I think there's definitely a place for AI, but I feel like this is not
> it. And I think we'd do people a disservice by suggesting it.

Is AI really worse than a randomly selected human-generated comment in
the Linux kernel?  Especially one of the older comments?  I agree that
the best possible human-generated comment will likely beat the current
crop of LLMs, but we are definitely not oversupplied with anything
resembling best possible comments here.  ;-)

> A big idea in my book is to get people familiar with the concepts and the
> code presented together so they can end up reading the code and
> understanding it on the basis of the book having tied the two together and
> shown 'hey it's not so bad you can extract meaning from this!'
> 
> That way, they can take the inevitably out of date contents and update to
> the latest kernel with the skills developed (and of course many of the
> concepts will remain valid).

Makes sense to me!

							Thanx, Paul

> > And one reason for continued but reasonable emphasis on internal
> > documentation, including comments, is that the aforementioned tools
> > ingest that documentation.  ;-)
> >
> > Thoughts?
> >
> > And in the meantime, happy holidays for those celebrating them!
> >
> > 							Thanx, Paul
> 
> Cheers, Lorenzo

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Mon, Dec 29, 2025 at 06:50:10PM -0500, Theodore Tso wrote:
> On Mon, Dec 29, 2025 at 10:59:12AM -0800, Paul E. McKenney wrote:
> > > Or do they actually feel like improving RCU.
> > > If they actually want to improve RCU then sure the prerequisities
> > > involve reading every reasonable piece of RCU docs; but in the other
> > > cases?  Don't make it too hard.
> > 
> > I only get 24 hours in each day, my friend.  Experience has shown that
> > there are way more people struggling with code using RCU than with code
> > implementing RCU, so the former get priority.  I could hit you with a
> > Spock quote from a certain movie, if you would like.  ;-)
> 
> ,.. and that's why I was recalling the comment, "You are not expected
> to understand this" and asking the question of which audience are we
> trying to make the code more accessible for, at least first.
> 
> Yes, it would be good if there were more than one person who can
> understand the details of the code and who can maintain it, so we
> don't have teh bus factor == 1 problem.  But the fact remains that are
> many parts of the kernel that I will freely admit that I have no
> *clue* how it work, and that's OK.  I'm sure if I spent a few weeks
> deeply meditating on the code, I could eventually figure it out ---
> but I don't have that kind of spare time.  Nor am I someone who is
> going to insist on a lot of documentation of internal details, since I
> happen to believe, like you, that accessibility to *users* of RCU is
> more important that people who are curious about the internal details
> about why we are dividing by 3, and not 4 (and 5 is right out) :-)

We are making good (if slow) progress on Linux-kernel RCU's bus number.
For but one example, I have sent only the one RCU pull request to Linus
this year (v6.18).  Uladzislau Rezki sent v6.14, Boqun Feng v6.15, Joel
Fernandes v6.16, Neeraj Upadhyay v6.17, and Frederic Weisbecker v6.19.

Things are not yet perfect, but I would say that the bus number of
all parts of the RCU implementation itself is greater than two, with
substantial portions having a much higher bus number.   This was in
part due to our having done a line-by-line walkthrough of the code,
which did result in some greatly improved comments, in case you were
wondering why I am insisting on walkthroughs for changes to comments.

And there are even some parts or RCU that have been written primarily
by someone other than me.

Much of the RCU test code, especially the rcutorture scripting under
tools, might still be at a bus number of 1, but that is a work in
progress.  Plus this scripting should be easier for an RCU newbie to
pick up.  To me, it seemed the highest priorities were:  (1) Increasing
the bus number of the actual RCU implementation and (2) Getting Linus
used to taking pull requests from not-me.  The next step`is getting the
RCU proteges more comfortable curating RCU patches.

>      	     	 	     	    	  - Ted
> 
> P.S.  If someone wants to spend time being the John Lions for RCU,
> great!  But that should be someone's passion project, and not
> necessarily highest priority for the community at large.

I tried, I really did, and not once but twice.

The first time was in the first edition of "Is Parallel Programming Hard,
And, If So, What Can You Do About it?".  This was of course stupid due to
version skew between the book and the kernel.  The second time was partly
successful, and you can see the results in Documentation/RCU/Design.
Both times I was under the mistaken impression that the RCU implementation
would not be changing much going forward.  I have since learned to ignore
that false feeling of completion.  ;-)

On the other hand, some substantial updates to this documentation were
more recently done by not-me, so maybe there is hope longer term.

Part of the problem is of course that I have not had the experience of
having been taught RCU.  I guess from that viewpoint, the real surprise
is that so many people are successfully using it.

In the meantime, I have continued on user documentation, with which I have
more than three decades of experience, getting RCU into the C++ standard,
helping Mathieu with userspace RCU (but this is mostly his baby by now),
and so on.  Current projects include an entry-level userspace RCU doc
for newbies and helping someone get an RCU implementation into libstdc++.

And these efforts really do add up.  For example, one of my children's
old high-school classmates recently started using RCU in userspace with
no help from me, just from the available documentation.

So there is significant reason for hope  ;-)

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Thu, 8 Jan 2026 17:34:14 -0800
"Paul E. McKenney" <paulmck@kernel.org> wrote:

> Had you instead sent me a separate email asking about this constant,
> I would likely have just answered.  I would imagine that Joel would have
> done the same in response to your asking him.

OK so this is part of the contention here. This thread turned slightly away
from the original topic and moved towards the importance of commenting
code, at least for me. But if you were still discussing this as a
requirement document of some kind, then the comment on the "3" is out of
scope.

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

On Fri, Jan 09, 2026 at 09:58:58AM -0500, Steven Rostedt wrote:
> On Thu, 8 Jan 2026 17:34:14 -0800
> "Paul E. McKenney" <paulmck@kernel.org> wrote:
> 
> > Had you instead sent me a separate email asking about this constant,
> > I would likely have just answered.  I would imagine that Joel would have
> > done the same in response to your asking him.
> 
> OK so this is part of the contention here. This thread turned slightly away
> from the original topic and moved towards the importance of commenting
> code, at least for me. But if you were still discussing this as a
> requirement document of some kind, then the comment on the "3" is out of
> scope.

Thank you!

And I should re-emphasize that I really would like to see things that
add more robustness to the Linux kernel, including things that allow
it to be used in more demanding application areas.

I just want those things to be maintainable.  Easy for me to say,
I know!  ;-)

							Thanx, Paul

Re: Follow-up on Linux-kernel code accessibility

[Theodore Tso]

On Fri, Jan 09, 2026 at 09:58:58AM -0500, Steven Rostedt wrote:
> 
> OK so this is part of the contention here. This thread turned slightly away
> from the original topic and moved towards the importance of commenting
> code, at least for me. But if you were still discussing this as a
> requirement document of some kind, then the comment on the "3" is out of
> scope.

Looking at the original context of of the first message[1] in this
thread, the thesis statement of Paul's message was that commenting
code was *not* a viable way of enabling who want to do "random dives"
into kernel code to understand it.

[1] https://lore.kernel.org/r/90d56d30-232d-4930-ad9f-5aebade7cdf2@paulmck-laptop

Quoting from that first message:

    "The Linux kernel's mm system weighs in at about 200KLoC, and Lorenzo
    wrote a book on its design that weighs in at about 1300 pages, or
    about 150 LoC/page.  This suggests that the Linux-kernel scheduler,
    which weighs in at about 70KLoC and has similar heuristics/workload
    challenges as does mm, would require a 430-page textbook to provide a
    similar level of design detail.  By this methodology, RCU would require
    "only" 190 pages, presumably substituting its unfamiliarity for sched's
    and mm's deeply heuristic and workload-dependent nature.

    Sadly, this data does not support the hypothesis that we can create
    comments that will provide understanding to people taking random dives
    into the Linux kernel's source code.  In contrast to code that is closely
    associated with a specific type of mechanical device, Linux-kernel
    code requires the reader to possess a great deal of abstract and global
    conceptual/workload information."

Steven, you may disagree with this conclusion, but speaking
personally, everything that I've read on this thread strongly confirms
it.

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

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.

Cheers,

						- Ted

Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Sat, 10 Jan 2026 19:30:40 -0800
"Theodore Tso" <tytso@mit.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.

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

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

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.

-- Steve

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

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@mit.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 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@vger.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

Re: Follow-up on Linux-kernel code accessibility

[Julia Lawall]

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


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

Re: Follow-up on Linux-kernel code accessibility

[Paul E. McKenney]

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@mit.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@vger.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
> >

Re: Follow-up on Linux-kernel code accessibility

[Chris Mason]

On 1/6/26 1:08 PM, Lorenzo Stoakes wrote:
> On Fri, Dec 19, 2025 at 04:05:33PM -0500, Chris Mason wrote:
>> On 12/19/25 12:09 PM, Theodore Tso wrote:
>>> On Fri, Dec 19, 2025 at 07:51:47AM +0100, Julia Lawall wrote:
>>>>
>>>> Maybe we're not looking for an instant understanding methodology.  Rather
>>>> a machine checkable way to document the invariants that exist in the head
>>>> of the developer, and for some bounded amount of time in the head of the
>>>> person who has tried to reconstruct them.
>>>
>>> One of the things that I found really interesting with Chris Mason's
>>> kernel review prompts is that it documents some of these invariants
>>> which are not otherwise covered in the kernel documentation.  And
>>> while Chris originally created those prompts for Anthropic's Claude
>>> LLM, we've successfully used them with Gemini 2.5 and 3.
>>>
>>> I wonder if we should consider folding them into the kernel sources,
>>> so they can be updated alongside the kernel.  It might also mean that
>>> as the invariants change, the documentation / prompts in an LTS kernel
>>> and for the latest upstream kernel can be up to sync with the relevant
>>> kernel versions.
>>>
>>
>> Yeah, I agree.  I think/hope these details from the prompts can end up
>> folded into the kernel docs.  As the prompts age, we're going to have
>> the equivalent of sprinkling ifdefs into them, and I think it's much
>> better if they just reference knowledge in the kernel.
>>
>> I recently pushed out changes that remove most of the process and focus
>> more on kernel internals.  So hopefully over time we can get to
>> something that just documents kerneling in a way that is useful beyond
>> LLMs.
>>
>> -chris
>>
> 
> I think we have to be super cautious about ensuring that any such output is
> correct.
> 
> To me the system is assistant-to-an-expert.
> 
> Adding a bunch of invariant details including very subtle (or otherwise)
> bugs is worse than having no such documentation.
> 
> I say this with a far more broad and open-minded impression of AI tooling
> in relation to review and the kernel in general by the way - I'm just
> keeping things real here.
> 
> Maybe the answer is we need a R-b for any such output from maintainers with
> appropriate expertise.

I agree with all of the above, and my goal for the prompts was always to
have the subsystem specific prompts owned by the subsystem itself.  If a
particular subsystem isn't interested, I'd either limit it to obviously
correct details or just not run reviews against those commits.

We're not quite there yet, but both scheduler.md and nfs.md were
contributed by respective maintainers, and the bpf and block details
were reviewed when they went in.

LLMs end up consuming these docs the same way people do, so all the
debates about where to put documentation (inline comments? doc files?)
apply the same way.  I think the review automation is a good excuse to
talk about this for individual subsystems, and hopefully the automated
reviews can help subsystems keep whatever documentation scheme they
choose up to date.

> 
> Thanks for the work you're doing on review by the way Chris! Is promising
> :)

Thanks!  I'm doing another MM run this week, so you'll soon have a
chance to give feedback ;)

-chris