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

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

MFC r233648:
Remove trailing whitespace per mdoc lint warning

Approved by: cperciva (implicit)

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

Approved by: re (implicit)

mdoc: drop redundant .Pp and .LP calls

They have no effect when coming in pairs, or before .Bl/.Bd

Spelling fixes.

The NetBSD Foundation has granted permission to remove clause 3 and 4 from
their software.

Obtained from: NetBSD

add callout_schedule; besides being useful it also improves
compatibility with other systems

Reviewed by: ed, battlez

- Document newly added callout_init_rw function

Requested by: attilio
Reviewed by: attilio

- Use .fn to markup untimeout in two places it was missing.
- Reword a confusing sentence.

PR: docs/89810
Submitted by: Marius Nuennerich marius dot nuennerich at gmx dot net
MFC after: 3 days

-mdoc sweep.

Make callout_reset() return a non-zero value if a pending callout
was rescheduled. If there was no pending callout, then return 0.

Reviewed by: iedowse, cperciva

Assorted markup fixes and minor wordsmithing.

Approved by: re

Add a mechanism for associating a mutex with a callout when the
callout is first initialised, using a new function callout_init_mtx().
The callout system will acquire this mutex before calling the callout
function and release it on return.

In addition, the callout system uses the mutex to avoid most of the
complications and race conditions inherent in asynchronous timer
facilities, so mutex-protected callouts have much simpler semantics.
As long as the mutex is held when invoking callout_stop() or
callout_reset(), then these functions will guarantee that the callout
will be stopped, even if softclock() had already begun to process
the callout.

Existing Giant-locked callouts will automatically pick up the new
race-free semantics. This should close a number of race conditions
in the USB code and probably other areas of the kernel too.

There should be no change in behaviour for "MP-safe" callouts; these
still need to use the techniques mentioned in timeout(9) to avoid
race conditions.

Fixed whitespace at EOL and double word.
Uncompact enumaration to make it look better.

Attempt to describe the race conditions that must be considered
when using the callout subsystem. Show how the callout_pending(),
callout_active() and callout_deactivate() macros can be used to
achieve simpler race-free callout semantics in many situations.

Document callout_pending() macro.

MFC after: 1 week

Assorted markup, spelling, and grammar fixes.

mdoc(7) police:

* correctly place parenthisized sentences
* remove hard sentence breaks
* use .Vt instead of .Fn

Introduce a callout_drain() function. This acts in the same manner as
callout_stop(), except that if the callout being stopped is currently
in progress, it blocks attempts to reset the callout and waits until the
callout is completed before it returns.

This makes it possible to clean up callout-using code safely, e.g.,
without potentially freeing memory which is still being used by a callout.

Reviewed by: mux, gallatin, rwatson, jhb

Looks like I misread the callout code. We do not seem to hold the
callout lock while the callout is happening. So the serialization
that I thought was happening isn't. Therefore, remove the part of the
bugs that says this. Leave in the other bug as it is very hard to
work around (impossible?).

Fix various typos.

Also note that timeout/untimeout are considered to be the old interface and
the callout interface should be used insetad.

Submitted by: bde (first two) and wollman (third)

Document the implications of the callout_stop() returning 0 if the
callout has finished or is in progress. Also document that the
locking of the callout code for FreeBSD 5 has eliminated the 'or is in
progress' clause as a possibility and that such elimination is an
accident of the implementation and shouldn't be relied upon.

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

- callout_stop() now returns an integer value instead of void so
describe it.
- Add a return values section.

mdoc(7) police: s/BSD/.Bx/ where appropriate.

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 HISTORY info from the .Os call.

Document the mpsafe argument to callout_init().

PR: 24529
Submitted by: harti brandt <brandt@fokus.gmd.de>
Reviewed by: jlemon

Prepare for mdoc(7)NG.

Use Fx macro wherever possible.

Mention more functions in the headers so whatis(1) can find them, and
create links to functions so added found.

Fixed some bugs (one serious one: timeouts were claimed to be executed at
spl0) and some bitrot (the not-so-new callout_init/stop/reset functions
were not mentioned; the callout_activate/deactivate/pending macros are
still not mentioned).

Submitted by: mostly by jlemon

$Id$ -> $FreeBSD$

Fixed synopsis again. Too much was blown away by splatting a NetBSD-
based version over the top of the FreeBSD version in rev.1.6.

Updated timeout.9 man page describing the new callout interface. This
man page was based on the NetBSD version.

Fixed #include and/or prototype bugs in synopsis.

Fixed synopsis (wrong #includes and superfluous parentheses in typedef).

Nuked the confusing timeout_func_t typedef. It will go away in <systm.h>
later.

Revert $FreeBSD$ back to $Id$

Make the long-awaited change from $Id$ to $FreeBSD$

This will make a number of things easier in the future, as well as (finally!)
avoiding the Id-smashing problem which has plagued developers for so long.

Boy, I'm glad we're not using sup anymore. This update would have been
insane otherwise.

Describe timeout() and untimeout().