Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Tue, 18 Jul 2023 11:12:10 -0700
From:   "Paul E. McKenney" <paulmck@kernel.org>
To:     Joel Fernandes <joel@joelfernandes.org>
Cc:     rcu@vger.kernel.org, linux-kernel@vger.kernel.org,
        kernel-team@meta.com, rostedt@goodmis.org,
        Masami Hiramatsu <mhiramat@kernel.org>
Subject: Re: [PATCH rcu 2/6] rcu: Clarify rcu_is_watching() kernel-doc comment
Message-ID: <2e404769-67af-4240-b572-bd0808503486@paulmck-laptop>
Reply-To: paulmck@kernel.org
References: <6127192c-da9b-4599-9738-6e8f92e6c75c@paulmck-laptop>
 <20230717180317.1097590-2-paulmck@kernel.org>
 <a11d5ce7-5ee3-fbf7-9adb-4cfc805c6bb7@joelfernandes.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <a11d5ce7-5ee3-fbf7-9adb-4cfc805c6bb7@joelfernandes.org>
Precedence: bulk

On Tue, Jul 18, 2023 at 08:52:30AM -0400, Joel Fernandes wrote:
> Hi Paul,
> 
> On 7/17/23 14:03, Paul E. McKenney wrote:
> > Make it clear that this function always returns either true or false
> > without other planned failure modes.
> > 
> > Reported-by: Masami Hiramatsu <mhiramat@kernel.org>
> > Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
> > ---
> >   kernel/rcu/tree.c | 12 ++++++++----
> >   1 file changed, 8 insertions(+), 4 deletions(-)
> > 
> > diff --git a/kernel/rcu/tree.c b/kernel/rcu/tree.c
> > index 1449cb69a0e0..fae9b4e29c93 100644
> > --- a/kernel/rcu/tree.c
> > +++ b/kernel/rcu/tree.c
> > @@ -679,10 +679,14 @@ static void rcu_disable_urgency_upon_qs(struct rcu_data *rdp)
> >   /**
> >    * rcu_is_watching - see if RCU thinks that the current CPU is not idle
> 
> Would it be better to modify the 'not idle' to 'not idle from an RCU
> viewpoint'? This matches the comments in ct_nmi_enter() as well.

We have the "if RCU thinks that" earlier.

But maybe something like this?

 * rcu_is_watching - RCU read-side critical sections permitted on current CPU?

> >    *
> > - * Return true if RCU is watching the running CPU, which means that this
> > - * CPU can safely enter RCU read-side critical sections.  In other words,
> > - * if the current CPU is not in its idle loop or is in an interrupt or
> > - * NMI handler, return true.
> > + * Return @true if RCU is watching the running CPU and @false otherwise.
> > + * An @true return means that this CPU can safely enter RCU read-side
> > + * critical sections.
> > + *
> > + * More specifically, if the current CPU is not deep within its idle
> > + * loop, return @true.  Note that rcu_is_watching() will return @true if
> > + * invoked from an interrupt or NMI handler, even if that interrupt or
> > + * NMI interrupted the CPU while it was deep within its idle loop.
> 
> But it is more than the idle loop, for ex. NOHZ_FULL CPUs with single task
> running could be idle from RCU's viewpoint? Could that be clarified more?

Perhaps something like this?

 * Although calls to rcu_is_watching() from most parts of the kernel
 * will return @true, there are important exceptions.  For example, if the
 * current CPU is deep within its idle loop, in kernel entry/exit code,
 * or offline, rcu_is_watching() will return @false.

(Where nohz_full CPUs are covered by kernel entry/exit code.)

							Thanx, Paul

> thanks,
> 
>  - Joel
> 
> 
> >    *
> >    * Make notrace because it can be called by the internal functions of
> >    * ftrace, and making this notrace removes unnecessary recursion calls.
>