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] [thread-next>] [day] [month] [year] [list]

Message-ID: <20251226153502.62c11798@gandalf.local.home>
Date: Fri, 26 Dec 2025 15:35:02 -0500
From: Steven Rostedt <rostedt@...dmis.org>
To: "Theodore Tso" <tytso@....edu>
Cc: "Paul E. McKenney" <paulmck@...nel.org>, Sasha Levin
 <sashal@...nel.org>, 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 Fri, 26 Dec 2025 14:22:17 -0500
"Theodore Tso" <tytso@....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