Copy head@r302406 to stable/11 as part of the 11.0-RELEASE cycle.
Prune svn:mergeinfo from the new branch, as nothing has been merged
here.

Additional commits post-branch will follow.

Approved by: re (implicit)
Sponsored by: The FreeBSD Foundation

Fix a bunch of "sentence not on new line" warnings in section 9.

MFC after: 1 month

Document the locking context for the directly dispatched callouts.
Cross-reference timeout(9).

Sponsored by: The FreeBSD Foundation
MFC after: 1 week

Fix various mdoc issues and some EOL whitespace.

Found with: mandoc -Tlint

Grammar tweaks for locking.9

Reviewed by: jhb
Approved by: hrs (mentor)

mdoc: remove EOL whitespace.

Make a pass over this page to correct and clarify a few things as well as
some general word-smithing.
- Don't claim that adaptive mutexes have a timeout (they don't).
- Don't treat pool mutexes as a separate primitive in a few places.
- Describe sleepable read-mostly locks as a separate lock type and add
them to the various tables.
- Don't claim that sx locks are less efficient. That hasn't been true in
a few years now.
- Describe lockmanager locks next to sx locks since they are very similar
in terms of rules, etc., and so that all the lock primitives are
grouped together before the non-lock primitives.
- Similarly, move the section on Giant after the description of all the
non-lock primitives to preserve grouping.
- Condition variables work on several types of locks, not just mutexes.
- Add a bit of language to compare/contrast condition variables with
sleep/wakeup.
- Add a note about why pause(9) is unique.
- Add some language to define bounded vs unbounded sleeps and explain
why they are treated separately (bounded sleeps only need CPU time
to make forward progress).
- Don't state that using mtx_sleep() is a bad idea. It is in fact rather
necessary.
- Rework the interaction table a bit. First, it did not include really
include sleepable rmlocks and it left out lockmgr entirely. To get
things to fit, combine similar lock types into the same column / row,
and explicitly state what "sleep" means. The notes about recursion
and lock order were also a bit banal (lock order is always important,
not just in the few places annotated here), so remove them. In
particular, the lock order note would need to be on just about every
cell. If we want to document recursion I think a better approach
would be a separate table summarizing the recursion rules for each
lock as having too many notes clutters the table.
- Tweak the tables to use less indentation so everything still fits with
the added columns.
- Correct a few cells in the context mode table.
- Use mdoc markup instead of explicit markup in a few places.

Requested by: julian
MFC after: 2 weeks

Remove reference to removed !MPSAFE filesystem support

Remove contractions.

Remove a duplicated "thread".

Try clean up some of my original text and neaten a table.

MFC after: 1 week

Fix lock interaction table for rmlocks - by default they cannot sleep,
just like rwlocks.

MFC after: 1 week

Typo and mdoc(7) style fixes.

PR: 168117
Submitted by: Nobuyuki Koganemaru (kogane&jp!freebsd!org)
MFC after: 3 days

Remove duplicate words in mdoc(7) pages.

PR: 167810
Submitted by: Bryan Drewery {bryan!shatow%net} (hackers lounge)
Found with: textproc/igor
MFC after: 3 days

Fix typo from last commit.

Noticed by: brueffer

Remove unnecessary Xo/Xc.

Reviewed by: brueffer

Remove trailing whitespace per mdoc lint warning

Disussed with: gavin
No objection from: doc
Approved by: joel
MFC after: 3 days

Remove superfluous paragraph macro.

Xref BUS_SETUP_INTR(9) and locking(9).

rmlock(9) two additions and one change/fix:
- add rm_try_rlock().
- add RM_SLEEPABLE to use sx(9) as the back-end lock in order to sleep while
holding the write lock.
- change rm_noreadtoken to a cpu bitmask to indicate which CPUs need to go
through the lock/unlock in order to synchronize. As a side effect, this
also avoids IPI to CPUs without any readers during rm_wlock.

Discussed with: ups@, rwatson@ on arch@
Sponsored by: Isilon Systems, Inc.

s/ithread/interrupt thread/

Fix a bunch of typos and spelling mistakes.

Some rewording and language fixes.

PR: docs/136918, docs/134074
Submitted by: Ben Kaduk <kaduk at mit dot edu>, Haven Hash <havenster at gmail dot com>

Remove list of locking primitives, which is kind of redundant, move
information about witness(9) to the section about interactions, and
expand 'contexts' table.

Start sentences with a new line.

Submitted by: brueffer

Improve description for Giant and mention blocking inside interrupt threads.

Cosmetic fixes.

Add description of bounded sleep vs unbounded sleep (aka blocking). Move
rules into their own section.

Improve descriptions, remove turnstiles (since, from what I understand,
they are only used to implement other synchronization primitives), tweak
formatting.

Initial checkin for rmlock (read mostly lock) a multi reader single writer
lock optimized for almost exclusive reader access. (see also rmlock.9)

TODO:
Convert to per cpu variables linkerset as soon as it is available.
Optimize UP (single processor) case.

Corrections and clarifications

Approved by: re (bmah)

Remove duplicate xref and add missing commas.

PR: 113891
Submitted by: pluknet <pluknet@gmail.com>
Approved by: re (blanket)

Markup fixes.

Giant is special. How do I love thee? Let me count the ways?

errr, I mean "Enumerate how the giant lock differs from other locks"

Please let me know if I missed any. Or misrepresented any...

Reviewed by: ssouhlal@

- Remove an unneeded comma
- Remove a redundant .Xc
- Spell "Largely" as it should.

More corrections, this time from Wojciech Koszek

Spelling and whitespace fixes from Dunne Whitty

fix braino in markup.

More suggestions from pjd.

Some comments from pjd

Add locking.9
This is supposed to be a brief overview of the locking primatives.
It is not yet complete and contains many place-holders for information
I do not know.

The locking is getting so diverse that I've lost track of it all.
We need this page to keep outselves in sync with what the primitives do.

note.. not part of the build yet.