linux-kernel - Re: [PATCH] rcu: Improve comments for RCU_FANOUT and RCU_FANOUT

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

Message-ID: <f2ca1650-0bbc-48fb-a6d9-6c4313325a1a@paulmck-laptop>
Date: Wed, 29 Oct 2025 16:46:51 -0700
From: "Paul E. McKenney" <paulmck@...nel.org>
To: Kunwu Chan <kunwu.chan@...ux.dev>
Cc: frederic@...nel.org, neeraj.upadhyay@...nel.org, joelagnelf@...dia.com,
	josh@...htriplett.org, boqun.feng@...il.com, urezki@...il.com,
	rostedt@...dmis.org, mathieu.desnoyers@...icios.com,
	jiangshanlai@...il.com, qiang.zhang@...ux.dev, rcu@...r.kernel.org,
	linux-kernel@...r.kernel.org, Kunwu Chan <chentao@...inos.cn>
Subject: Re: [PATCH] rcu: Improve comments for RCU_FANOUT and RCU_FANOUT_LEAF

On Thu, Oct 23, 2025 at 11:27:42AM +0800, Kunwu Chan wrote:
> From: Kunwu Chan <chentao@...inos.cn>
> 
> The original comments introduced in commit 05c5df31afd1
> ("rcu: Make RCU able to tolerate undefined CONFIG_RCU_FANOUT"),
> contained confusing annotations.
> 
> Specifically, the #else and #endif comments did not clearly reflect
> their corresponding condition blocks, hampering readability.
> 
> Fixes condition branch comments. And adds explicit explanations of
> the overall purpose:
> defining middle/leaf fan-out parameters, their relation to Kconfig,
> and how they shape the RCU hierarchy based on CPU count.
> 
> Make the hierarchical configuration logic of the RCU easier to understand.
> 
> Signed-off-by: Kunwu Chan <chentao@...inos.cn>

Thank you for posting this!  Please see below for some comments.

							Thanx, Paul

> ---
>  include/linux/rcu_node_tree.h | 16 ++++++++++++----
>  1 file changed, 12 insertions(+), 4 deletions(-)
> 
> diff --git a/include/linux/rcu_node_tree.h b/include/linux/rcu_node_tree.h
> index 78feb8ba7358..b03c0ce91dec 100644
> --- a/include/linux/rcu_node_tree.h
> +++ b/include/linux/rcu_node_tree.h
> @@ -25,26 +25,34 @@
>  /*
>   * Define shape of hierarchy based on NR_CPUS, CONFIG_RCU_FANOUT, and
>   * CONFIG_RCU_FANOUT_LEAF.
> + * - RCU_FANOUT: Controls fan-out of middle levels in the RCU hierarchy.
> + * - RCU_FANOUT_LEAF: Controls fan-out of the leaf level (directly managing CPUs).
> + *
> + * These parameters are determined by Kconfig options if configured; otherwise,
> + * they use sensible defaults based on system architecture (for RCU_FANOUT)
> + * or a fixed default (for RCU_FANOUT_LEAF).

I have no objections to this change if at least one of my fellow
maintainers is willing to speak up for it and none of the others object
to it.

>   * In theory, it should be possible to add more levels straightforwardly.
>   * In practice, this did work well going from three levels to four.
>   * Of course, your mileage may vary.
>   */
>  
> +/* Define RCU_FANOUT: middle-level fan-out parameter */
>  #ifdef CONFIG_RCU_FANOUT
>  #define RCU_FANOUT CONFIG_RCU_FANOUT
> -#else /* #ifdef CONFIG_RCU_FANOUT */
> +#else /* #ifndef CONFIG_RCU_FANOUT */
>  # ifdef CONFIG_64BIT
>  # define RCU_FANOUT 64
>  # else
>  # define RCU_FANOUT 32
>  # endif
> -#endif /* #else #ifdef CONFIG_RCU_FANOUT */
> +#endif
>  
> +/* Define RCU_FANOUT_LEAF: leaf-level fan-out parameter (manages CPUs directly) */
>  #ifdef CONFIG_RCU_FANOUT_LEAF
>  #define RCU_FANOUT_LEAF CONFIG_RCU_FANOUT_LEAF
> -#else /* #ifdef CONFIG_RCU_FANOUT_LEAF */
> +#else /* #ifndef CONFIG_RCU_FANOUT_LEAF */
>  #define RCU_FANOUT_LEAF 16
> -#endif /* #else #ifdef CONFIG_RCU_FANOUT_LEAF */
> +#endif

But these much stay as they are.  The #else echos the "#if" condition, and
the #endif contains "#else" followed by the "#if" condition.  This means
that you can tell where you are without having to find the matching "#if"
and without having to figure out whether there is an intervening "#else".

>  #define RCU_FANOUT_1	      (RCU_FANOUT_LEAF)
>  #define RCU_FANOUT_2	      (RCU_FANOUT_1 * RCU_FANOUT)
> -- 
> 2.25.1
>