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: <20251226192217.GB67711@macsyma.local>
Date: Fri, 26 Dec 2025 14:22:17 -0500
From: "Theodore Tso" <tytso@....edu>
To: Steven Rostedt <rostedt@...dmis.org>
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, 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.

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.

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.

						- Ted