Re: [PATCH 15/19] srcu: Create an SRCU-fast-updown API

[Akira Yokosawa <akiyks@gmail.com>]

Hi Paul,

Minor nitpicks in kernel-doc comment of srcu_read_lock_fast_updown().

On Sun,  2 Nov 2025 13:44:32 -0800, Paul E. McKenney wrote:
> This commit creates an SRCU-fast-updown API, including
> DEFINE_SRCU_FAST_UPDOWN(), DEFINE_STATIC_SRCU_FAST_UPDOWN(),
> __init_srcu_struct_fast_updown(), init_srcu_struct_fast_updown(),
> srcu_read_lock_fast_updown(), srcu_read_unlock_fast_updown(),
> __srcu_read_lock_fast_updown(), and __srcu_read_unlock_fast_updown().
> 
> These are initially identical to their SRCU-fast counterparts, but both
> SRCU-fast and SRCU-fast-updown will be optimized in different directions
> by later commits.  SRCU-fast will lack any sort of srcu_down_read() and
> srcu_up_read() APIs, which will enable extremely efficient NMI safety.
> For its part, SRCU-fast-updown will not be NMI safe, which will enable
> reasonably efficient implementations of srcu_down_read_fast() and
> srcu_up_read_fast().
> 
> Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
> Cc: Andrii Nakryiko <andrii@kernel.org>
> Cc: Alexei Starovoitov <ast@kernel.org>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Cc: <bpf@vger.kernel.org>
> ---
>  include/linux/srcu.h     | 77 +++++++++++++++++++++++++++++++++++++---
>  include/linux/srcutiny.h | 16 +++++++++
>  include/linux/srcutree.h | 55 ++++++++++++++++++++++++++--
>  kernel/rcu/srcutree.c    | 39 +++++++++++++++++---
>  4 files changed, 176 insertions(+), 11 deletions(-)
> 
> diff --git a/include/linux/srcu.h b/include/linux/srcu.h
> index 1dd6812aabe7..1fbf475eae5e 100644
> --- a/include/linux/srcu.h
> +++ b/include/linux/srcu.h

[...]

> @@ -305,6 +315,46 @@ static inline struct srcu_ctr __percpu *srcu_read_lock_fast(struct srcu_struct *
>  	return retval;
>  }
>  
> +/**
> + * srcu_read_lock_fast_updown - register a new reader for an SRCU-fast-updown structure.
> + * @ssp: srcu_struct in which to register the new reader.
> + *
> + * Enter an SRCU read-side critical section, but for a light-weight
> + * smp_mb()-free reader.  See srcu_read_lock() for more information.
> + * This function is compatible with srcu_down_read_fast(), but is not
> + * NMI-safe.
> + *
> + * For srcu_read_lock_fast_updown() to be used on an srcu_struct
> + * structure, that structure must have been defined using either
> + * DEFINE_SRCU_FAST_UPDOWN() or DEFINE_STATIC_SRCU_FAST_UPDOWN() on the one
> + * hand or initialized with init_srcu_struct_fast_updown() on the other.
> + * Such an srcu_struct structure cannot be passed to any non-fast-updown
> + * variant of srcu_read_{,un}lock() or srcu_{down,up}_read().  In kernels
> + * built with CONFIG_PROVE_RCU=y, () will complain bitterly if you ignore
> + * this * restriction.

Probably,

 * built with CONFIG_PROVE_RCU=y, __srcu_check_read_flavor() will complain
 * bitterly if you ignore this restriction.

??

> + *
> + * Grace-period auto-expediting is disabled for SRCU-fast-updown
> + * srcu_struct structures because SRCU-fast-updown expedited grace periods
> + * invoke synchronize_rcu_expedited(), IPIs and all.  If you need expedited
> + * SRCU-fast-updown grace periods, use synchronize_srcu_expedited().
> + *
> + * The srcu_read_lock_fast_updown() function can be invoked only from
> + those contexts where RCU is watching, that is, from contexts where
> + it would be legal to invoke rcu_read_lock().  Otherwise, lockdep will
> + complain.

kernel-doc (script) complains:

Warning: include/linux/srcu.h:341 bad line:  those contexts where RCU is watching, that is, from contexts where
Warning: include/linux/srcu.h:342 bad line:  it would be legal to invoke rcu_read_lock().  Otherwise, lockdep will
Warning: include/linux/srcu.h:343 bad line:  complain.

Leading "* "s are missing.

        Thanks, Akira

> + */
> +static inline struct srcu_ctr __percpu *srcu_read_lock_fast_updown(struct srcu_struct *ssp)
> +__acquires(ssp)
> +{
> +	struct srcu_ctr __percpu *retval;
> +
> +	RCU_LOCKDEP_WARN(!rcu_is_watching(), "RCU must be watching srcu_read_lock_fast_updown().");
> +	srcu_check_read_flavor(ssp, SRCU_READ_FLAVOR_FAST_UPDOWN);
> +	retval = __srcu_read_lock_fast_updown(ssp);
> +	rcu_try_lock_acquire(&ssp->dep_map);
> +	return retval;
> +}
> +
>  /*
>   * Used by tracing, cannot be traced and cannot call lockdep.
>   * See srcu_read_lock_fast() for more information.
[...]