Re: Follow-up on Linux-kernel code accessibility

["Theodore Tso" <tytso@mit.edu>]

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