linux-kernel - Re: Follow-up on Linux-kernel code accessibility

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <e9eb1ddd-4cf2-41f8-953c-5a49ed2cdc7f@paulmck-laptop>
Date: Thu, 25 Dec 2025 10:18:20 -0800
From: "Paul E. McKenney" <paulmck@...nel.org>
To: Steven Rostedt <rostedt@...dmis.org>
Cc: Sasha Levin <sashal@...nel.org>, Theodore Tso <tytso@....edu>,
	Julia Lawall <julia.lawall@...ia.fr>,
	Gabriele Paoloni <gpaoloni@...hat.com>,
	Kate Stewart <kstewart@...uxfoundation.org>,
	Chuck Wolber <chuckwolber@...il.com>,
	Dmitry Vyukov <dvyukov@...gle.com>,
	Mark Rutland <mark.rutland@....com>,
	Thomas Gleixner <tglx@...utronix.de>,
	Lorenzo Stoakes <lorenzo.stoakes@...cle.com>,
	Shuah Khan <skhan@...uxfoundation.org>, Chris Mason <clm@...a.com>,
	linux-kernel@...r.kernel.org
Subject: Re: Follow-up on Linux-kernel code accessibility

On 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@...nel.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