Re: Follow-up on Linux-kernel code accessibility

[Steven Rostedt]

On Tue, 23 Dec 2025 15:46:10 -0800
"Paul E. McKenney" <paulmck@xxxxxxxxxx> 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