Re: [PATCH] RCU/torture.txt: remove section MODULE PARAMETERS

[Junchang Wang]

On Fri, Jan 4, 2019 at 1:03 AM Paul E. McKenney <paulmck@xxxxxxxxxxxxx> wrote:
>
> On Thu, Jan 03, 2019 at 10:24:51PM +0800, Junchang Wang wrote:
> > The supported module parameters are detailed in both RCU/torture.txt and
> > admin-guide/kernel-parameters.txt, and the latter is actively maintained.
> > So this patch removes section MODULE PARAMETERS in torture.txt and
> > adds a reference to the information in kernel-parameters.txt.
> >
> > Signed-off-by: Junchang Wang <junchangwang@xxxxxxxxx>
>
> Queued and pushed, thank you!
>
> I made some small updates, first capitalizing the word following the
> colon (":") in the subject line and second adding a search string
> for Documentation/admin-guide/kernel-parameters.txt.  Please see below
> and please let me know if I messed anything up.
>

Hi Paul,

Your updated version is definitely much better. Thanks a lot for
helping review the patch.


--Junchang

>                                                         Thanx, Paul
>
> ------------------------------------------------------------------------
>
> commit 150c2476dd32126505dc26f644fa8eb643630d9c
> Author: Junchang Wang <junchangwang@xxxxxxxxx>
> Date:   Thu Jan 3 22:24:51 2019 +0800
>
>     RCU/torture.txt: Remove section MODULE PARAMETERS
>
>     The supported module parameters are detailed in both RCU/torture.txt and
>     admin-guide/kernel-parameters.txt, and the latter is actively maintained.
>     So this patch removes section MODULE PARAMETERS in torture.txt and
>     adds a reference to the information in kernel-parameters.txt.
>
>     Signed-off-by: Junchang Wang <junchangwang@xxxxxxxxx>
>     Signed-off-by: Paul E. McKenney <paulmck@xxxxxxxxxxxxx>
>     [ paulmck: Add search string. ]
>
> diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt
> index 55918b54808b..a41a0384d20c 100644
> --- a/Documentation/RCU/torture.txt
> +++ b/Documentation/RCU/torture.txt
> @@ -10,173 +10,8 @@ status messages via printk(), which can be examined via the dmesg
>  command (perhaps grepping for "torture").  The test is started
>  when the module is loaded, and stops when the module is unloaded.
>
> -
> -MODULE PARAMETERS
> -
> -This module has the following parameters:
> -
> -fqs_duration   Duration (in microseconds) of artificially induced bursts
> -               of force_quiescent_state() invocations.  In RCU
> -               implementations having force_quiescent_state(), these
> -               bursts help force races between forcing a given grace
> -               period and that grace period ending on its own.
> -
> -fqs_holdoff    Holdoff time (in microseconds) between consecutive calls
> -               to force_quiescent_state() within a burst.
> -
> -fqs_stutter    Wait time (in seconds) between consecutive bursts
> -               of calls to force_quiescent_state().
> -
> -gp_normal      Make the fake writers use normal synchronous grace-period
> -               primitives.
> -
> -gp_exp         Make the fake writers use expedited synchronous grace-period
> -               primitives.  If both gp_normal and gp_exp are set, or
> -               if neither gp_normal nor gp_exp are set, then randomly
> -               choose the primitive so that about 50% are normal and
> -               50% expedited.  By default, neither are set, which
> -               gives best overall test coverage.
> -
> -irqreader      Says to invoke RCU readers from irq level.  This is currently
> -               done via timers.  Defaults to "1" for variants of RCU that
> -               permit this.  (Or, more accurately, variants of RCU that do
> -               -not- permit this know to ignore this variable.)
> -
> -n_barrier_cbs  If this is nonzero, RCU barrier testing will be conducted,
> -               in which case n_barrier_cbs specifies the number of
> -               RCU callbacks (and corresponding kthreads) to use for
> -               this testing.  The value cannot be negative.  If you
> -               specify this to be non-zero when torture_type indicates a
> -               synchronous RCU implementation (one for which a member of
> -               the synchronize_rcu() rather than the call_rcu() family is
> -               used -- see the documentation for torture_type below), an
> -               error will be reported and no testing will be carried out.
> -
> -nfakewriters   This is the number of RCU fake writer threads to run.  Fake
> -               writer threads repeatedly use the synchronous "wait for
> -               current readers" function of the interface selected by
> -               torture_type, with a delay between calls to allow for various
> -               different numbers of writers running in parallel.
> -               nfakewriters defaults to 4, which provides enough parallelism
> -               to trigger special cases caused by multiple writers, such as
> -               the synchronize_srcu() early return optimization.
> -
> -nreaders       This is the number of RCU reading threads supported.
> -               The default is twice the number of CPUs.  Why twice?
> -               To properly exercise RCU implementations with preemptible
> -               read-side critical sections.
> -
> -onoff_interval
> -               The number of seconds between each attempt to execute a
> -               randomly selected CPU-hotplug operation.  Defaults to
> -               zero, which disables CPU hotplugging.  In HOTPLUG_CPU=n
> -               kernels, rcutorture will silently refuse to do any
> -               CPU-hotplug operations regardless of what value is
> -               specified for onoff_interval.
> -
> -onoff_holdoff  The number of seconds to wait until starting CPU-hotplug
> -               operations.  This would normally only be used when
> -               rcutorture was built into the kernel and started
> -               automatically at boot time, in which case it is useful
> -               in order to avoid confusing boot-time code with CPUs
> -               coming and going.
> -
> -shuffle_interval
> -               The number of seconds to keep the test threads affinitied
> -               to a particular subset of the CPUs, defaults to 3 seconds.
> -               Used in conjunction with test_no_idle_hz.
> -
> -shutdown_secs  The number of seconds to run the test before terminating
> -               the test and powering off the system.  The default is
> -               zero, which disables test termination and system shutdown.
> -               This capability is useful for automated testing.
> -
> -stall_cpu      The number of seconds that a CPU should be stalled while
> -               within both an rcu_read_lock() and a preempt_disable().
> -               This stall happens only once per rcutorture run.
> -               If you need multiple stalls, use modprobe and rmmod to
> -               repeatedly run rcutorture.  The default for stall_cpu
> -               is zero, which prevents rcutorture from stalling a CPU.
> -
> -               Note that attempts to rmmod rcutorture while the stall
> -               is ongoing will hang, so be careful what value you
> -               choose for this module parameter!  In addition, too-large
> -               values for stall_cpu might well induce failures and
> -               warnings in other parts of the kernel.  You have been
> -               warned!
> -
> -stall_cpu_holdoff
> -               The number of seconds to wait after rcutorture starts
> -               before stalling a CPU.  Defaults to 10 seconds.
> -
> -stat_interval  The number of seconds between output of torture
> -               statistics (via printk()).  Regardless of the interval,
> -               statistics are printed when the module is unloaded.
> -               Setting the interval to zero causes the statistics to
> -               be printed -only- when the module is unloaded, and this
> -               is the default.
> -
> -stutter                The length of time to run the test before pausing for this
> -               same period of time.  Defaults to "stutter=5", so as
> -               to run and pause for (roughly) five-second intervals.
> -               Specifying "stutter=0" causes the test to run continuously
> -               without pausing, which is the old default behavior.
> -
> -test_boost     Whether or not to test the ability of RCU to do priority
> -               boosting.  Defaults to "test_boost=1", which performs
> -               RCU priority-inversion testing only if the selected
> -               RCU implementation supports priority boosting.  Specifying
> -               "test_boost=0" never performs RCU priority-inversion
> -               testing.  Specifying "test_boost=2" performs RCU
> -               priority-inversion testing even if the selected RCU
> -               implementation does not support RCU priority boosting,
> -               which can be used to test rcutorture's ability to
> -               carry out RCU priority-inversion testing.
> -
> -test_boost_interval
> -               The number of seconds in an RCU priority-inversion test
> -               cycle.  Defaults to "test_boost_interval=7".  It is
> -               usually wise for this value to be relatively prime to
> -               the value selected for "stutter".
> -
> -test_boost_duration
> -               The number of seconds to do RCU priority-inversion testing
> -               within any given "test_boost_interval".  Defaults to
> -               "test_boost_duration=4".
> -
> -test_no_idle_hz        Whether or not to test the ability of RCU to operate in
> -               a kernel that disables the scheduling-clock interrupt to
> -               idle CPUs.  Boolean parameter, "1" to test, "0" otherwise.
> -               Defaults to omitting this test.
> -
> -torture_type   The type of RCU to test, with string values as follows:
> -
> -               "rcu":  rcu_read_lock(), rcu_read_unlock() and call_rcu(),
> -                       along with expedited, synchronous, and polling
> -                       variants.
> -
> -               "rcu_bh": rcu_read_lock_bh(), rcu_read_unlock_bh(), and
> -                       call_rcu_bh(), along with expedited and synchronous
> -                       variants.
> -
> -               "rcu_busted": This tests an intentionally incorrect version
> -                       of RCU in order to help test rcutorture itself.
> -
> -               "srcu": srcu_read_lock(), srcu_read_unlock() and
> -                       call_srcu(), along with expedited and
> -                       synchronous variants.
> -
> -               "sched": preempt_disable(), preempt_enable(), and
> -                       call_rcu_sched(), along with expedited,
> -                       synchronous, and polling variants.
> -
> -               "tasks": voluntary context switch and call_rcu_tasks(),
> -                       along with expedited and synchronous variants.
> -
> -               Defaults to "rcu".
> -
> -verbose                Enable debug printk()s.  Default is disabled.
> -
> +Module parameters are prefixed by "rcutorture." in
> +Documentation/admin-guide/kernel-parameters.txt.
>
>  OUTPUT
>
>