On Mon, Dec 10, 2018 at 12:48:43AM +0900, Akira Yokosawa wrote: > On 2018/12/02 07:27:09 -0800, Paul E. McKenney wrote: > > On Mon, Dec 03, 2018 at 12:11:20AM +0900, Akira Yokosawa wrote: > >> Paul, > >> > >> IIUC, your work on RCU API consolidation seems to affect Section 9.5.4, > >> especially Table 9.3. > >> > >> I'm not sure, but one idea would be to keep Table 9.3 for future > >> reference and add a new one representing consolidated set of API. > >> > >> Just a reminder. > > > > And a timely one! Please see attached for a possible LWN article. > > Though the LWN editors might quite rightly decide that a third > > RCU API article is one too many, in which case I will blog it. > > > > But either way, thoughts? > > Hi Paul, > > I took a while to skim through the article. > > My first thought was "Wow, the big API table has grown too big to > view in a single window of the browser!". Indeed, and that is not necessarily a good thing, is it now? ;-) But in the next version, I will be able to drop the RCU-bh and RCU-sched columns, which might make it fit once more. > For perfbook, it would be quite hard to shrink it in an A4 page. For perfbook, we should omit the RCU-bh and RCU-sched columns to start with, but with a citation of the LWN article. Jon Corbet indicated some interest, so maybe it will actually appear! > On read-side APIs, I could not get what "the RCU-bh and RCU-sched > read-side APIs may now be used with the vanilla RCU update-side APIs" > really means. Are they also consolidated in their implementation, > but kept for code readability and for static analysis? No and yes. For example, rcu_read_lock_sched() is stll preempt_disable() without any rcu_read_lock(), but a plain old synchronize_rcu() will wait for both. As you say, I am currently keeping them for code readability and static analysis, but might converge them later, depending on how things go. > I looked through LWN articles of RCU kernel APIs and see that > current Section 9.5.4 has not updated so much since the first > version in 2008 (https://lwn.net/Articles/264090/). > > Do you have plan to reflect all the updates mentioned in the followup > articles in 2010, 2014, as well this one in this section? I plan a heavy edit and reorganization of Section 9.5. It is old and is in pretty bad shape. Probably not quite as profound a change as for the old memory-ordering section, but lots of update. I have a printout that I have been taking to the gym with me, and it is very heavily marked up. ;-) I also plan to add a locking and an RCU section to the memory-ordering chapter. Alan Stern's RCU semantics are incredibly elegant! > Yes, documentation in linux/Documentation/RCU/ looks already ready for > v4.21/5.0 to reflect the update-side consolidation. Thanks mostly to Joel Fernandes, by the way. ;-) > So I don't think perfbook needs to cover all of the flavors/APIs. > Just referencing the kernel Documents and LWN articles for the complete > view should be good enough, I suppose. Agreed! > I'll keep posting if I find something to feedback. Looking forward to seeing whatever feedback you might have! Thanx, Paul
