Copy stable/9 to releng/9.3 as part of the 9.3-RELEASE cycle.

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

Copy head to stable/9 as part of 9.0-RELEASE release cycle.

Approved by: re (implicit)

Reverse the logic for ADAPTIVE_SX option and enable it by default.
Introduce for this operation the reverse NO_ADAPTIVE_SX option.
The flag SX_ADAPTIVESPIN to be passed to sx_init_flags(9) gets suppressed
and the new flag, offering the reversed logic, SX_NOADAPTIVE is added.

Additively implements adaptive spininning for sx held in shared mode.
The spinning limit can be handled through sysctls in order to be tuned
while the code doesn't reach the release, after which time they should
be dropped probabilly.

This change has made been necessary by recent benchmarks where it does
improve concurrency of workloads in presence of high contention
(ie. ZFS).

KPI breakage is documented by __FreeBSD_version bumping, manpage and
UPDATING updates.

Requested by: jeff, kmacy
Reviewed by: jeff
Tested by: pho

Bump .Dd for previous revision.

Update sx(9) lock manpage in order to add missing prototypes for function
sx_slock_sig() and sx_xlock_sig() and their respective explanation.

Rename the macros for assertion flags passed to sx_assert() from SX_* to
SA_* to match mutexes and rwlocks. The old flags still exist for
backwards compatiblity.

Requested by: attilio

Document sx_xholder().

Document SX_RECURSE flag.

Optimize sx locks to use simple atomic operations for the common cases of
obtaining and releasing shared and exclusive locks. The algorithms for
manipulating the lock cookie are very similar to that rwlocks. This patch
also adds support for exclusive locks using the same algorithm as mutexes.

A new sx_init_flags() function has been added so that optional flags can be
specified to alter a given locks behavior. The flags include SX_DUPOK,
SX_NOWITNESS, SX_NOPROFILE, and SX_QUITE which are all identical in nature
to the similar flags for mutexes.

Adaptive spinning on select locks may be enabled by enabling the
ADAPTIVE_SX kernel option. Only locks initialized with the SX_ADAPTIVESPIN
flag via sx_init_flags() will adaptively spin.

The common cases for sx_slock(), sx_sunlock(), sx_xlock(), and sx_xunlock()
are now performed inline in non-debug kernels. As a result, <sys/sx.h> now
requires <sys/lock.h> to be included prior to <sys/sx.h>.

The new kernel option SX_NOINLINE can be used to disable the aforementioned
inlining in non-debug kernels.

The size of struct sx has changed, so the kernel ABI is probably greatly
disturbed.

MFC after: 1 month
Submitted by: attilio
Tested by: kris, pjd

Add some cross references to locking.9 from related pages.

Allow threads to atomically release rw and sx locks while waiting for an
event. Locking primitives that support this (mtx, rw, and sx) now each
include their own foo_sleep() routine.
- Rename msleep() to _sleep() and change it's 'struct mtx' object to a
'struct lock_object' pointer. _sleep() uses the recently added
lc_unlock() and lc_lock() function pointers for the lock class of the
specified lock to release the lock while the thread is suspended.
- Add wrappers around _sleep() for mutexes (mtx_sleep()), rw locks
(rw_sleep()), and sx locks (sx_sleep()). msleep() still exists and
is now identical to mtx_sleep(), but it is deprecated.
- Rename SLEEPQ_MSLEEP to SLEEPQ_SLEEP.
- Rewrite much of sleep.9 to not be msleep(9) centric.
- Flesh out the 'RETURN VALUES' section in sleep.9 and add an 'ERRORS'
section.
- Add __nonnull(1) to _sleep() and msleep_spin() so that the compiler will
warn if you try to pass a NULL wait channel. The functions already have
a KASSERT to that effect.

- Sort functions in the order that rwlock(9) and mutex(9) use.
- Markup sx_unlock() as a function rather than saying it is a macro.
The macro part is an implementation detail, and all the other sx_*lock()
functions are actually macros, too.
- Use the same style as rwlock(9) and mutex(9) to markup sx_assert() and
SX_SYSINIT() with respect to headers and kernel options.
- Add a missing MLINK.

Document sx_xlocked(9).

Submitted by: ssouhlal

Trim a couple of xrefs.

Xref rwlock(9).

Reviewed by: ru

Scheduled mdoc(7) sweep.

Make an attempt at explaining why sx(9) locks cannot be safely obtained
after acquiring a mutex(9).

PR: docs/75571
Submitted by: darrenr
Explanation by: jhb

Document that sx_unlock() exists as a macro.
Remove redundant include file, <sys/kernel.h>, and clean up the function
list at the top with the addition of a "Sx utility macro" section.

Assorted markup, spelling, and grammar fixes.

- Clarify ambiguous statement about not being able to both slock and xlock
a single lock at the same time.
- Avoid using "own" to refer to holding either a shared or exclusive lock
as it is only really correct for exclusive locks.
- Reword the sentence about sleep-ability to read easier.

Requested by: truckman (1)

Document new 'what' value for sx_assert(9).

PS. There is a inconsistency in this manual page, because in
non-WITNESS case sx_assert(9) does not panics, it only prints
the warning. I haven't fixed this, because jhb@ is planing to
replace those printf()s with panic()s.

Reviewed by: jhb
Approved by: jhb, scottl (mentor)

Add "options INVARIANTS" and "options INVARIANT_SUPPORT" to the
synopsis, with supporting text in the body of the manual page.

Add a cross-reference to panic(9) for completeness.

Reviewed by: ru (synopsis changes)

Make this manual page reflect the sources better.

- A #include of <sys/mutex.h> is no longer needed to use sx(9) (since
2001/05/01).
- Use of the SX_SYSINIT() macro requires inclusion of '<sys/kernel.h>'

Improve continuity of text.

Get rid of duplicates.

Document the fact that one is allowed to sleep while holding an sx lock.

Discussed with: jhb@

mdoc(7) police: lint.

mdoc police: turn .PP back into .Pp

Update the .Fn line for SX_SYSINIT to include the parameter types.

- Add notes about SX_SYSINIT and MTX_SYSINIT in order to document the
recent additions of these macros.
- Add in a MLINK to create SX_SYSINIT.9 and MTX_SYSINIT.9.

Add mtx_pool(9) to the SEE ALSO section.

Submitted by: Garrett Rooney <rooneg@electricjellyfish.net>

mdoc(7) police: WITNESS is a #define, mark it as such.

mdoc(7) police: cosmetique.

Document sx_assert(9).

Fixed wrong include in synopsis.

mdoc(7) police: Use the new .In macro for #include statements.

Common Mike adds see alsos from all of the synchronization
man pages to their brethren.

mdoc(7) police: bump document date.

Add missing commas.

Add sx_try_upgrade() and sx_downgrade().

Submitted by: Alexander Kabaev <ak03@gte.com>

Spell "FreeBSD" with "F" and "BSD" in uppercase.

Document sx_try_[sx]lock().

Removed whitespace at end-of-line; no content changes. I simply did
cd src/share; find man[1-9] -type f|xargs perl -pi -e 's/[ \t]+$//'

BTW, what editors are the culprits? I'm using vim and it shows
me whitespace at EOL in troff files with a thick blue block...

Reviewed by: Silence from cvs diff -b
MFC after: 7 days

mdoc(7) police: removed final dot from the .Nd call.

- Both <sys/sx.h> and <sys/mutex.h> depend on <sys/types.h> and
<sys/lock.h>.
- <sys/sx.h> depends on <sys/mutex.h>.

Implement shared/exclusive locks.

Reviewed by: bmilekic, jake, jhb