From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mx.treblig.org (mx.treblig.org [46.235.229.95]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E6D5E18AE3 for ; Sun, 28 Dec 2025 02:23:52 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=46.235.229.95 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1766888636; cv=none; b=dYRukM4P42iJj//GDP3tSslow/NcU/z3ZLY5rHvxga4/LV9pnN0O3IZZjSl1CaCgIHzApDxdSie55gGToqERKxJY+UhBiwZ5SDnffnAoxGcv2fIjyk5rssBzaCOq7b89R0bnHgQ+I9D85EQH5I4jW9KALBftkBnxqB9bIclzVrk= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1766888636; c=relaxed/simple; bh=mjbq9GKj8puggTp89zCKu/PMelatFCxSwPFAbhCehFE=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=XAccCIUma69eN9YOfKk/CmqD8cC+8gL6KWcLKuI71RTMrxy/F/tKRiHSwt6dmuhGIFiXeKJ4fjZX4iLMImrAObrDWwF8tIp+DNHxDEhj9hNPYzDq6dr8zqAMJNWvo5InRjg1cSBSL6d5FgGsCpsGihn1oahCVw4ORQ82fV45vkg= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=treblig.org; spf=pass smtp.mailfrom=treblig.org; dkim=pass (2048-bit key) header.d=treblig.org header.i=@treblig.org header.b=enlKtteH; arc=none smtp.client-ip=46.235.229.95 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=treblig.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=treblig.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=treblig.org header.i=@treblig.org header.b="enlKtteH" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=treblig.org ; s=bytemarkmx; h=Content-Type:MIME-Version:Message-ID:Subject:From:Date:From :Subject; bh=1QixJu4CwTh2W418oM/lME7JsHG4GjdXDAVMaUEOz0s=; b=enlKtteHN/7Hl4xl uQeoaYzBF6mTVDbvSK/tW+bRvsnGO+TR9BLuc5m6SRpNhYKmKeorPpAIlSPq8MPy38D7gWyn5S5oK DcV7tB5DtionIQeEQJrNfGTeuKJjKTtiTpWRWR44tC/pyJR9Z0M7IOUmuyooCmDKMTY7FNw3Po0wZ /cZG7po04yetCrnxF7A8/M9QYrvQ7oD3ezGuO/yta5xNK44a/8EAvg6JnAHM3c2xHZJNsKZigaUKY zLsOfStSnj739csZJzijfdAkpQl+X3L7IrEqaT55mcOuLN1iD252qIPSMyD35wDDvfzKufvPcpgDx HQ5sW9gNlhklrYt3zA==; Received: from dg by mx.treblig.org with local (Exim 4.98.2) (envelope-from ) id 1vZftd-0000000BSwv-1Bh3; Sun, 28 Dec 2025 01:48:37 +0000 Date: Sun, 28 Dec 2025 01:48:37 +0000 From: "Dr. David Alan Gilbert" To: "Paul E. McKenney" Cc: Julia Lawall , Theodore Tso , Steven Rostedt , Sasha Levin , Gabriele Paoloni , Kate Stewart , Chuck Wolber , Dmitry Vyukov , Mark Rutland , Thomas Gleixner , Lorenzo Stoakes , Shuah Khan , Chris Mason , linux-kernel@vger.kernel.org Subject: Re: Follow-up on Linux-kernel code accessibility Message-ID: References: <89457d2d-153e-4274-b485-2ace983cec4f@paulmck-laptop> <20251224091158.6ab443cb@gandalf.local.home> <20251225150331.GB15088@macsyma.lan> <20251226114830.6bc7a3eb@gandalf.local.home> <20251226192217.GB67711@macsyma.local> <6915da9a-6cd7-c2a9-776d-963949a413c@inria.fr> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: X-Chocolate: 70 percent or better cocoa solids preferably X-Operating-System: Linux/6.12.48+deb13-amd64 (x86_64) X-Uptime: 01:44:13 up 62 days, 1:20, 2 users, load average: 0.00, 0.00, 0.00 User-Agent: Mutt/2.2.13 (2024-03-09) * Paul E. McKenney (paulmck@kernel.org) wrote: > On Sun, Dec 28, 2025 at 12:32:50AM +0100, Julia Lawall wrote: > > > > > > On Sat, 27 Dec 2025, Paul E. McKenney wrote: > > > > > On Sat, Dec 27, 2025 at 07:16:28AM +0100, Julia Lawall wrote: > > > > > > > > > > > > On Fri, 26 Dec 2025, Paul E. McKenney wrote: > > > > > > > > > On Fri, Dec 26, 2025 at 02:22:17PM -0500, Theodore Tso 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. > > > > > > > > > > > > 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. > > > > > > > > > > Here is how I group them: > > > > > > > > > > 1. RCU users in the Linux kernel. Largish group. Addressed by much > > > > > of the Documentation/RCU contents, the occasional LWN article, > > > > > blog posts, and by RCU experts in various subsystems. > > > > > > > > > > 2. RCU users in userspace. Modest group, but growing. LWN articles, > > > > > blog posts, an academic paper or three, and a number of people > > > > > who have implemented some form or another of RCU. > > > > > > > > > > 3. Userspace RCU implementations. Smallish group, but there are > > > > > quite a few implementations out there. I don't deliberately > > > > > target anything to this group, but it is quite possible that > > > > > some of the writings for the other groups have been helpful. > > > > > > > > > > 4. Linux-kernel RCU implementation. Small group, though a largish > > > > > one if we include all the people who have gotten at least one > > > > > patch accepted. Comments, Linux-kernel RCU Design Documents [1], > > > > > Documentation/RCU/Design, a few LWN articles, a few blog posts, > > > > > and the several regular developers and maintainers. > > > > > > > > > > And I would like to think that Section 9.5 of "Is Parallel Programming > > > > > Hard, And, If So, What Can You Do About It?" [2] has been helpful. > > > > > > > > > > What groups should I be adding? > > > > > > > > In the case of the scheduler, I observe some unexpected behavior, and then > > > > I have the feeling that I backtrack through the code coming from a > > > > direction that was not anticipated by the person who wrote the comments > > > > (sometimes inline comments, more likely the comments in the commit tht > > > > introduced the line I am wondering about). But I'm not sure how to place > > > > RCU. My impression is that it has a more monolithic implementation, and > > > > that I would only ever consider it to be a block box, not something I > > > > would debug my way into. But perhaps people felt that way about the > > > > scheduler functions I am looking at as well. Over time, there have surely > > > > been performance improvements in RCU as well. It seems hard to anticipate > > > > what information people will need. > > > > > > Although RCU does use heuristics, I would say that its operation adapts > > > less to dynamic conditions than does the scheduler. RCU is mostly an > > > observer of state, while the scheduler's job is mostly a controller > > > of state. > > > > > > > Maybe one could consider that division by a constant is sufficiently rare > > > > in the kernel that it should always be documented? > > > > > > If it is (for example) division by 10 in code that converts binary > > > integers to char, or code computing an average, I would not expect a > > > comment to be needed. > > > > > > But I do feel the need to ask what division you are referring to. ;-) > > > > j = (j + 2) / 3; > > "Divide by three rounding up." That's not *that* obvious, but ok, but then why 3? Then later there is: WRITE_ONCE(rcu_state.jiffies_kick_kthreads, jiffies + (j ? 3 * j : 2)); Which I assume is related - but then why the 2? Curiosly my local tame Qwen3 LLM explained the rounding up: > I see some code doing 'j = (j + 2) / 3' - what's it trying to do? The expression `j = (j + 2) / 3` is a clever way to **round up an integer division by 3** — that is, it computes the ceiling of `j / 3` for non-negative integers. Dave > > Thanx, Paul > > > > > julia > > > > > > > > > > > > > > > > > > > > > > Thanx, Paul > > > > > > > > > > [1] https://docs.google.com/document/d/1GCdQC8SDbb54W1shjEXqGZ0Rq8a6kIeYutdSIajfpLA/edit?pli=1&tab=t.0#heading=h.ytgz5i5df43s > > > > > > > > > > [2] https://www.kernel.org/pub/linux/kernel/people/paulmck/perfbook/perfbook.html > > > > > > > > > -- -----Open up your eyes, open up your mind, open up your code ------- / Dr. David Alan Gilbert | Running GNU/Linux | Happy \ \ dave @ treblig.org | | In Hex / \ _________________________|_____ http://www.treblig.org |_______/