Re: [PATCH RFC 0/5] rcu doc updates for whatisRCU and checklist

From: "Theodore Y. Ts'o" <tytso@mit.edu>
To: "Joel Fernandes (Google)" <joel@joelfernandes.org>
Cc: linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>,
	Josh Triplett <josh@joshtriplett.org>,
	Lai Jiangshan <jiangshanlai@gmail.com>,
	linux-doc@vger.kernel.org,
	Mathieu Desnoyers <mathieu.desnoyers@efficios.com>,
	"Paul E. McKenney" <paulmck@linux.ibm.com>,
	Steven Rostedt <rostedt@goodmis.org>,
	pantin@google.com
Subject: Re: [PATCH RFC 0/5] rcu doc updates for whatisRCU and checklist
Date: Fri, 5 Oct 2018 19:46:28 -0400	[thread overview]
Message-ID: <20181005234628.GB2548@thunk.org> (raw)
In-Reply-To: <20181005231815.170433-1-joel@joelfernandes.org>

On Fri, Oct 05, 2018 at 04:18:09PM -0700, Joel Fernandes (Google) wrote:
> 
> Here are this week's rcu doc updates based on combing through whatisRCU and
> checklists. Hopefully you agree with them. I left several old _bh and _sched
> API references as is, since I don't think its a good idea to remove them till
> the APIs themselves are removed, however I did remove several of them as well
> (like in the first patch in this series) since I feel its better to "encourage"
> new users not to use the old API.

Hi Joel,

As it so happens, I just recently wrote my first RCU patch[1] (file
systems, especially on-disk data structures, generally tend not to be
good candidates for RCU semantics).

[1] http://patchwork.ozlabs.org/patch/979779/

So if you are working on improving RCU documentation, I thought I
would give two comments on the RCU docs from the perspective of a
developer trying to use RCU for the first time.

* whatisRCU is great, but one the example in Section 3 uses
  rcu_dereference_protected() without explaining it.  Given that using
  that function seems to be considered best practice, maybe a few more
  words there would be in order?  That function isn't mentioned in
  rcu.txt either, BTW.

* lockdep.txt *does* explain what rcu_dereference_protected() does,
  but it doesn't really describe lockdep_is_held().  You can mostly
  figure it out from context, but it wasn't obvious to me what locks
  it could be used against, and in the case of a rw_semaphore, whether
  it applied to shared as well as exclusive locks.  That's a lockdep
  abstraction, and not a RCU abstraction, but lockdep isn't
  particularly well documented, so I ended up spending 20-30 minutes
  or so looking at the lockdep implementation before I was sure it
  actually worked the way I thought it was going to.

Anyway, I was going to put submitting a patch to improve whatisRCU on
my (vastly over-long) TODO list, but when I saw your patch set, I
couldn't resist trying to see if I could fob it off on you.  If you
don't think that's fair (and it probably isn't really), just let me
know, and I'll put it back on my todo list.  :-)

Cheers,

					- Ted