Re: [PATCH RFC] Documentation: RCU: Clarify comment about fanout

[Paul E. McKenney]

On Sat, Sep 22, 2018 at 04:10:51AM -0400, Joel Fernandes wrote:
> On Fri, Sep 21, 2018 at 9:14 PM Paul E. McKenney <paulmck@xxxxxxxxxxxxx> wrote:
> >
> > On Fri, Sep 21, 2018 at 06:31:53PM -0400, Joel Fernandes (Google) wrote:
> > > RCU Data-Structures document describes a trick to test RCU with small
> > > number of CPUs but with a larger tree. It wasn't immediately clear how
> > > the document arrived at 16 CPUs which also requires setting the
> > > FANOUT_LEAF to 2 instead of the default of 16. Clarify that.
> > >
> > > Signed-off-by: Joel Fernandes (Google) <joel@xxxxxxxxxxxxxxxxx>
> >
> > Good catch, applied, thank you!  You know, those two Kconfig options
> > are so closely linked in my mind that I doubt if I would ever have
> > noticed this issue.  So good show!
> 
> Thanks!
> 
> > I of course could not resist doing a bit of editing.  Could you please
> > check the following to make sure that I didn't mess something up?
> 
> Yes, the edit looks good and improved the changes ;-)

Whew!

> I have a few more as well, I'll send them out soon.

I do have on my list to update this document based on the changes in
-rcu, which among other things eliminate the rcu_dynticks structure
and  make it so there is only one rcu_state structure in a given
running system.

If you are crazy enough to want to make the corresponding changes,
I would welcome the patches (and would be happy to help with editing,
grammar, and soforth.  The potential advantage to you is familiarlzation
with the new version of the code.

This is not a small amount of work, so please give it some thought
before saying "yes".  (In contrast, I would of course understand and
respect an immediate "no".)

							Thanx, Paul

> thanks!
> 
>  - Joel
> 
> 
> >
> >                                                         Thanx, Paul
> >
> > ------------------------------------------------------------------------
> >
> > commit 9870c5b0f7b41a7b6085c20c22b320681800dabc
> > Author: Joel Fernandes (Google) <joel@xxxxxxxxxxxxxxxxx>
> > Date:   Fri Sep 21 18:31:53 2018 -0400
> >
> >     doc: Clarify RCU data-structure comment about rcu_tree fanout
> >
> >     RCU Data-Structures document describes a trick to test RCU with small
> >     number of CPUs but with a taller tree. It wasn't immediately clear how
> >     the document arrived at 16 CPUs which also requires setting the
> >     FANOUT_LEAF to 2 instead of the default of 16.  This commit therefore
> >     provides the needed clarification.
> >
> >     Signed-off-by: Joel Fernandes (Google) <joel@xxxxxxxxxxxxxxxxx>
> >     Signed-off-by: Paul E. McKenney <paulmck@xxxxxxxxxxxxx>
> >
> > diff --git a/Documentation/RCU/Design/Data-Structures/Data-Structures.html b/Documentation/RCU/Design/Data-Structures/Data-Structures.html
> > index 1d2051c0c3fc..476b1ac38e4c 100644
> > --- a/Documentation/RCU/Design/Data-Structures/Data-Structures.html
> > +++ b/Documentation/RCU/Design/Data-Structures/Data-Structures.html
> > @@ -127,9 +127,11 @@ CPUs, RCU would configure the <tt>rcu_node</tt> tree as follows:
> >  </p><p>RCU currently permits up to a four-level tree, which on a 64-bit system
> >  accommodates up to 4,194,304 CPUs, though only a mere 524,288 CPUs for
> >  32-bit systems.
> > -On the other hand, you can set <tt>CONFIG_RCU_FANOUT</tt> to be
> > -as small as 2 if you wish, which would permit only 16 CPUs, which
> > -is useful for testing.
> > +On the other hand, you can set both <tt>CONFIG_RCU_FANOUT</tt> and
> > +<tt>CONFIG_RCU_FANOUT_LEAF</tt> to be as small as 2, which would result
> > +in a 16-CPU test using a 4-level tree.
> > +This can be useful for testing large-system capabilities on small test
> > +machines.
> >
> >  </p><p>This multi-level combining tree allows us to get most of the
> >  performance and scalability
> >
>