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
