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 for Android: free password hash cracker in your pocket

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

Message-ID: <20251224091158.6ab443cb@gandalf.local.home>
Date: Wed, 24 Dec 2025 09:11:58 -0500
From: Steven Rostedt <rostedt@...dmis.org>
To: "Paul E. McKenney" <paulmck@...nel.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 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.

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