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

Message-ID: <823f79bc-12f0-445b-b7f3-49bce8b2b7b1@linux.dev>
Date: Fri, 5 Dec 2025 22:22:00 +0800
From: Kunwu Chan <kunwu.chan@...ux.dev>
To: paulmck@...nel.org
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 10/30/25 07:46, Paul E. McKenney wrote:
> 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".

Hi Paul,

Thank you for the feedback! I reviewed 
Documentation/process/coding-style.rst and
found the guidance on #endif comments (section 19), but I didn't find 
explicit
guidance on the #else comment format. I wasn't aware of the specific 
convention
used in the RCU codebase for #else and #endif directives. I understand 
now that
this format helps readers quickly identify which conditional branch 
they're in
without having to search backwards for the matching #if.

I'll prepare a V2 patch that restores the original #else and #endif 
comment format
while keeping the new explanatory comments about RCU_FANOUT and 
RCU_FANOUT_LEAF.

>
>>   #define RCU_FANOUT_1	      (RCU_FANOUT_LEAF)
>>   #define RCU_FANOUT_2	      (RCU_FANOUT_1 * RCU_FANOUT)
>> -- 
>> 2.25.1
>>
-- 
Thanks,
        Kunwu Chan.