kernel/linux.git/Documentation/RCU/Design/Requirements/Requirements.html, branch master

docs: rcu: convert some articles from html to ReST

2019-10-29T09:48:12+00:00

There are 4 RCU articles that are written on html format. The way they are, they can't be part of the Linux Kernel documentation body nor share the styles and pdf output. So, convert them to ReST format. This way, make htmldocs and make pdfdocs will produce a documentation output that will be like the original ones, but will be part of the Linux Kernel documentation body. Part of the conversion was done with the help of pandoc, but the result had some broken things that had to be manually fixed. Following are manual changes Mauro made when doing the automatic conversion: Quoting from: https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/ > > At least the pandoc's version I used here has a bug: its conversion > > from html to ReST on those files only start after a tag - or > > when the first quiz table starts. I only discovered that adding a > > at the beginning of the file solve this book at the last > > conversions. > > > > So, for most html->ReST conversions, I manually converted the first > > part of the document, basically stripping html paragraph tags and > > by replacing highlights by the ReST syntax. > > > > Also, all the quiz tables seem to assume some javascript macro or > > css style that would be hiding the answer part until the mouse moves > > to it. Such macro/css was not there at the kernel tree. So, the quiz > > answers have the same color as the background, making them invisible. > > Even if we had such macro/css, this is not portable for pdf/LaTeX output > > (and I'm not sure if this would work with ePub). > > > > So, I ended by manually doing the table conversion. > > > > Finally, I double-checked if the conversions ended ok, addressing any > > issues that might have heppened. > > > > So, after both automatic conversion and manual fixes, I opened both the > > html files produced by Sphinx and the original ones and compared them > > line per line (except for the indexes, as Sphinx produces them > > automatically), in order to see if all information from the original > > files will be there on a format close to what we have on other ReST > > files, fixing any pending issues if any. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Paul E. McKenney

Revert docs from "treewide: Rename rcu_dereference_raw_notrace() to _check()"

2019-10-29T09:46:55+00:00

This reverts docs from commit 355e9972da81e803bbb825b76106ae9b358caf8e. Signed-off-by: Joel Fernandes (Google) [ paulmck: Added Joel's SoB per Stephen Rothwell feedback. ] [ paulmck: Joel approved via private email. ] Signed-off-by: Paul E. McKenney

Revert docs from "rcu: Restore barrier() to rcu_read_lock() and rcu_read_unlock()"

2019-10-29T09:43:50+00:00

This reverts docs from commit d6b9cd7dc8e041ee83cb1362fce59a3cdb1f2709. Signed-off-by: Joel Fernandes (Google) [ paulmck: Added Joel's SoB per Stephen Rothwell feedback. ] [ paulmck: Joel approved via private email. ] Signed-off-by: Paul E. McKenney

Merge branches 'consolidate.2019.08.01b', 'fixes.2019.08.12a', 'lists.2019.08.13a' and 'torture.2019.08.01b' into HEAD

2019-08-13T21:30:30+00:00

consolidate.2019.08.01b: Further consolidation cleanups fixes.2019.08.12a: Miscellaneous fixes lists.2019.08.13a: Optional lockdep arguments for RCU list macros torture.2019.08.01b: Torture-test updates

treewide: Rename rcu_dereference_raw_notrace() to _check()

2019-08-01T21:16:21+00:00

The rcu_dereference_raw_notrace() API name is confusing. It is equivalent to rcu_dereference_raw() except that it also does sparse pointer checking. There are only a few users of rcu_dereference_raw_notrace(). This patches renames all of them to be rcu_dereference_raw_check() with the "_check()" indicating sparse checking. Signed-off-by: Joel Fernandes (Google) [ paulmck: Fix checkpatch warnings about parentheses. ] Signed-off-by: Paul E. McKenney

rcu: Restore barrier() to rcu_read_lock() and rcu_read_unlock()

2019-08-01T21:05:51+00:00

Commit bb73c52bad36 ("rcu: Don't disable preemption for Tiny and Tree RCU readers") removed the barrier() calls from rcu_read_lock() and rcu_write_lock() in CONFIG_PREEMPT=n&&CONFIG_PREEMPT_COUNT=n kernels. Within RCU, this commit was OK, but it failed to account for things like get_user() that can pagefault and that can be reordered by the compiler. Lack of the barrier() calls in rcu_read_lock() and rcu_read_unlock() can cause these page faults to migrate into RCU read-side critical sections, which in CONFIG_PREEMPT=n kernels could result in too-short grace periods and arbitrary misbehavior. Please see commit 386afc91144b ("spinlocks and preemption points need to be at least compiler barriers") and Linus's commit 66be4e66a7f4 ("rcu: locking and unlocking need to always be at least barriers"), this last of which restores the barrier() call to both rcu_read_lock() and rcu_read_unlock(). This commit removes barrier() calls that are no longer needed given that the addition of them in Linus's commit noted above. The combination of this commit and Linus's commit effectively reverts commit bb73c52bad36 ("rcu: Don't disable preemption for Tiny and Tree RCU readers"). Reported-by: Herbert Xu Reported-by: Linus Torvalds Signed-off-by: Paul E. McKenney [ paulmck: Fix embarrassing typo located by Alan Stern. ]

doc: CPU-hotplug notifiers cannot invoke synchronize_srcu() or srcu_barrier()

2019-01-25T23:34:18+00:00

SRCU's synchronize_srcu() may not be invoked from CPU-hotplug notifiers, due to the fact that SRCU grace periods make use of timers and the possibility of timers being temporarily stranded on the outgoing CPU. This stranding of timers means that timers posted to the outgoing CPU will not fire until late in the CPU-hotplug process. The problem is that if a notifier is waiting on an SRCU grace period, that grace period is waiting on a timer, and that timer is stranded on the outgoing CPU, then the notifier will never be awakened, in other words, deadlock has occurred. This same situation of course also prohibits srcu_barrier() from being invoked from CPU-hotplug notifiers. This commit therefore updates the requirements to include this restriction. Signed-off-by: Paul E. McKenney

doc: RCU scheduler spinlock rcu_read_unlock() restriction remains

2018-11-12T16:56:25+00:00

Given RCU flavor consolidation, when rcu_read_unlock() is invoked with interrupts disabled, the reporting of the corresponding quiescent state is deferred until interrupts are re-enabled. There was therefore some hope that this would allow dropping the restriction against holding scheduler spinlocks across an rcu_read_unlock() without disabling interrupts across the entire corresponding RCU read-side critical section. Unfortunately, the need to quickly provide a quiescent state to expedited grace periods sometimes requires a call to raise_softirq() during rcu_read_unlock() execution. Because raise_softirq() can sometimes acquire the scheduler spinlocks, the restriction must remain in effect. This commit therefore updates the RCU requirements documentation accordingly. Signed-off-by: Paul E. McKenney

doc: Make listing in RCU perf/scale requirements use rcu_assign_pointer()

2018-11-12T16:56:25+00:00

The code listing under this section has a quick quiz that says line 19 uses rcu_access_pointer, but the code listing itself instead uses rcu_dereference(). This commit therefore makes the code listing match the quick quiz. Signed-off-by: Joel Fernandes (Google) Signed-off-by: Paul E. McKenney

doc: Remove obsolete (non-)requirement about disabling preemption

2018-11-12T16:56:25+00:00

The Requirements.html document says "Disabling Preemption Does Not Block Grace Periods". However this is no longer true with the RCU consolidation. This commit therefore removes the obsolete (non-)requirement entirely. Signed-off-by: Joel Fernandes (Google) Signed-off-by: Paul E. McKenney