linux/Documentation/locking, branch v5.8

Merge tag 'docs-5.8' of git://git.lwn.net/linux

2020-06-01T22:45:27Z

Pull documentation updates from Jonathan Corbet: "A fair amount of stuff this time around, dominated by yet another massive set from Mauro toward the completion of the RST conversion. I *really* hope we are getting close to the end of this. Meanwhile, those patches reach pretty far afield to update document references around the tree; there should be no actual code changes there. There will be, alas, more of the usual trivial merge conflicts. Beyond that we have more translations, improvements to the sphinx scripting, a number of additions to the sysctl documentation, and lots of fixes" * tag 'docs-5.8' of git://git.lwn.net/linux: (130 commits) Documentation: fixes to the maintainer-entry-profile template zswap: docs/vm: Fix typo accept_threshold_percent in zswap.rst tracing: Fix events.rst section numbering docs: acpi: fix old http link and improve document format docs: filesystems: add info about efivars content Documentation: LSM: Correct the basic LSM description mailmap: change email for Ricardo Ribalda docs: sysctl/kernel: document unaligned controls Documentation: admin-guide: update bug-hunting.rst docs: sysctl/kernel: document ngroups_max nvdimm: fixes to maintainter-entry-profile Documentation/features: Correct RISC-V kprobes support entry Documentation/features: Refresh the arch support status files Revert "docs: sysctl/kernel: document ngroups_max" docs: move locking-specific documents to locking/ docs: move digsig docs to the security book docs: move the kref doc into the core-api book docs: add IRQ documentation at the core-api book docs: debugging-via-ohci1394.txt: add it to the core-api book docs: fix references for ipmi.rst file ...

locking: Introduce local_lock()

2020-05-28T08:31:09Z

preempt_disable() and local_irq_disable/save() are in principle per CPU big kernel locks. This has several downsides: - The protection scope is unknown - Violation of protection rules is hard to detect by instrumentation - For PREEMPT_RT such sections, unless in low level critical code, can violate the preemptability constraints. To address this PREEMPT_RT introduced the concept of local_locks which are strictly per CPU. The lock operations map to preempt_disable(), local_irq_disable/save() and the enabling counterparts on non RT enabled kernels. If lockdep is enabled local locks gain a lock map which tracks the usage context. This will catch cases where an area is protected by preempt_disable() but the access also happens from interrupt context. local locks have identified quite a few such issues over the years, the most recent example is: b7d5dc21072cd ("random: add a spinlock_t to struct batched_entropy") Aside of the lockdep coverage this also improves code readability as it precisely annotates the protection scope. PREEMPT_RT substitutes these local locks with 'sleeping' spinlocks to protect such sections while maintaining preemtability and CPU locality. local locks can replace: - preempt_enable()/disable() pairs - local_irq_disable/enable() pairs - local_irq_save/restore() pairs They are also used to replace code which implicitly disables preemption like: - get_cpu()/put_cpu() - get_cpu_var()/put_cpu_var() with PREEMPT_RT friendly constructs. Signed-off-by: Thomas Gleixner Signed-off-by: Sebastian Andrzej Siewior Signed-off-by: Ingo Molnar Acked-by: Peter Zijlstra Link: https://lore.kernel.org/r/20200527201119.1692513-2-bigeasy@linutronix.de

docs: move locking-specific documents to locking/

2020-05-15T18:05:07Z

Several files under Documentation/*.txt describe some type of locking API. Move them to locking/ subdir and add to the locking/index.rst index file. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/dd833a10bbd0b2c1461d78913f5ec28a7e27f00b.1588345503.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

doc:locking: remove info about old behavior of locktorture

2020-05-05T15:55:58Z

It is not useful to know what was the default at some point in the past: remove the information. Signed-off-by: Federico Vaga Link: https://lore.kernel.org/r/20200426211429.29133-1-federico.vaga@vaga.pv.it Signed-off-by: Jonathan Corbet

Documentation/locking/locktypes: Minor copy editor fixes

2020-03-28T11:47:34Z

Minor editorial fixes: - remove 'enabled' from PREEMPT_RT enabled kernels for consistency - add some periods for consistency - add "'" for possessive CPU's - spell out interrupts [ tglx: Picked up Paul's suggestions ] Signed-off-by: Randy Dunlap Signed-off-by: Thomas Gleixner Reviewed-by: Paul E. McKenney Link: https://lkml.kernel.org/r/ac615f36-0b44-408d-aeab-d76e4241add4@infradead.org

Documentation/locking/locktypes: Further clarifications and wordsmithing

2020-03-28T11:47:34Z

The documentation of rw_semaphores is wrong as it claims that the non-owner reader release is not supported by RT. That's just history biased memory distortion. Split the 'Owner semantics' section up and add separate sections for semaphore and rw_semaphore to reflect reality. Aside of that the following updates are done: - Add pseudo code to document the spinlock state preserving mechanism on PREEMPT_RT - Wordsmith the bitspinlock and lock nesting sections Co-developed-by: Paul McKenney Signed-off-by: Paul McKenney Signed-off-by: Thomas Gleixner Acked-by: Sebastian Andrzej Siewior Link: https://lkml.kernel.org/r/87wo78y5yy.fsf@nanos.tec.linutronix.de

Documentation: Add lock ordering and nesting documentation

2020-03-21T15:00:23Z

The kernel provides a variety of locking primitives. The nesting of these lock types and the implications of them on RT enabled kernels is nowhere documented. Add initial documentation. Signed-off-by: Thomas Gleixner Signed-off-by: Peter Zijlstra (Intel) Link: https://lkml.kernel.org/r/20200321113242.026561244@linutronix.de

docs/locking: Fix outdated section names

2020-02-05T17:21:12Z

Commit 2e4f5382d12a ("locking/doc: Rename LOCK/UNLOCK to ACQUIRE/RELEASE") has not appied to 'spinlock.rst'. This commit updates the doc for the change. Signed-off-by: SeongJae Park Link: https://lore.kernel.org/r/20200131205237.29535-2-sj38.park@gmail.com Signed-off-by: Jonathan Corbet

doc:locking: fix locktorture parameter description

2019-12-19T18:04:29Z

The description was talking about two default values: I removed the wrong one. Signed-off-by: Federico Vaga Link: https://lore.kernel.org/r/20191201121941.6971-1-federico.vaga@vaga.pv.it Signed-off-by: Jonathan Corbet

doc:lock: remove reference to clever use of read-write lock

2019-09-14T07:53:27Z

Remove the clever example about read-write lock because this type of lock is not recommended anymore (according to the very same document). So there is no reason to teach clever things that people should not do. Signed-off-by: Federico Vaga Acked-by: Will Deacon Signed-off-by: Jonathan Corbet