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

MFcalloutng:
Dcoument the new functions added to condvar(9), sleep(9), sleepqueue(9)
KPIs. Also document recent changes in timeout(9) and eventtimers(4).

Remove trailing whitespace per mdoc lint warning

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

Permit Giant to be passed as the explicit interlock either to
msleep/mtx_sleep or the various cv_*wait*() routines. Currently, the
"unlock" behavior of PDROP and cv_wait_unlock() with Giant is not
permitted as it is will be confusing since Giant is fully unrecursed and
unlocked during a thread sleep.

This is handy for subsystems which wish to allow unlocked drivers to
continue to use Giant such as CAM, the new TTY layer, and the new USB
stack. CAM currently uses a hack that I told Scott to use because I
really didn't want to permit this behavior, and the TTY and USB patches
both have various patches to permit this.

MFC after: 2 weeks

bump date for 1.20

Add note about condvars not working with spin locks.

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

Rename the cv_*wait*() functions to _cv_*wait*() and change their second
argument from a mutex to a lock_object. Add cv_*wait*() wrapper macros
that accept either a mutex, rwlock, or sx lock as the second argument and
convert it to a lock_object and then call _cv_*wait*(). Basically, the
visible difference is that you can now use rwlocks and sx locks with
condition variables using the same API as with mutexes.

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.

Oof, it is not my day. Unswap the descriptions of EINTR and ERESTART.

Fix a typo in the last that claimed that only masked signals were caught.

Correct descriptions of EINTR and ERESTART errors. Masked signals don't
interrupt sleeps. Rather, unmasked signals interrupt restarts and can
either interrupt the system call by having it return EINTR in userland or
force the system call to be restarted.

- Document cv_wait_unlock(9).
- Don't claim that the mutex is atomically reacquired when a cv_wait
routine returns. There's nothing atomic or magical about the lock
reacquire. The only magic is that we atomically drop the lock by
placing the thread on the sleep queue before dropping the lock.

Xref rwlock(9).

Reviewed by: ru

Catch up to rev 1.52 of sys/kern/kern_condvar.c. cv_signal() and
cv_broadcast() no longer require that the interlock mutex be held when
called.

Reminded by: das

Spelling fixes.

- Document cv_broadcastpri().
- Remove references to cv_waitq_*() as they no longer exist.

Add mtx_pool(9) to the SEE ALSO section.

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

Update function definitions and required include files to reflect
the current state of the system.

Approved by: alfred

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.

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

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: use .Fa for function arguments, use .Vt for variable type.

Implement condition variables.