MFC r327674, r327796

Introduce mallocarray() in the kernel

Similar to calloc() the mallocarray() function checks for integer
overflows before allocating memory.
It does not zero memory, unless the M_ZERO flag is set.

Additionally, move the overflow check logic out to WOULD_OVERFLOW() for
consumers to have a common means of testing for overflowing allocations.
WOULD_OVERFLOW() should be a secondary check -- on 64-bit platforms, just
because an allocation won't overflow size_t does not mean it is a sane size
to request. Callers should be imposing reasonable allocation limits far,
far, below overflow.

Obtained from: OpenBSD

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 issues found by mandoc -Tlint.

MFC after: 1 week

Consistently enforce the restriction against calling malloc/free when in a
critical section.

uma_zalloc_arg()/uma_zalloc_free() may acquire a sleepable lock on the
zone. The malloc() family of functions may call uma_zalloc_arg() or
uma_zalloc_free().

The malloc(9) man page currently claims that free() will never sleep.
It also implies that the malloc() family of functions will not sleep
when called with M_NOWAIT. However, it is more correct to say that
these functions will not sleep indefinitely. Indeed, they may acquire
a sleepable lock. However, a developer may overlook this restriction
because the WITNESS check that catches attempts to call the malloc()
family of functions within a critical section is inconsistenly
applied.

This change clarifies the language of the malloc(9) man page to clarify
the restriction against calling the malloc() family of functions
while in a critical section or holding a spin lock. It also adds
KASSERTs at appropriate points to make the enforcement of this
restriction more consistent.

PR: 204633
Differential Revision: https://reviews.freebsd.org/D4197
Reviewed by: markj
Approved by: gnn (mentor)
Sponsored by: Juniper Networks

Misc mdoc fixes:

- Remove superfluous paragraph macros.
- Remove/fix empty or incorrect macros.
- Sort sections into conventional order.
- Terminate quoted strings properly.
- Remove EOL whitespace.

Remove notes about historical mbuf(9) allocator flags from documentation.

Sponsored by: Nginx, Inc.

Remove trailing whitespace.

M_USE_RESERVE is no longer deprecated. It is once again supported.

Reviewed by: kib

Put parenthesis around sizeof args.

Remove trailing whitespace per mdoc lint warning

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

update .Dd

document M_NODUMP flag

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

Obtained from: NetBSD

Retire the MALLOC and FREE macros. They are an abomination unto style(9).

MFC after: 3 months

s/M_TRYWAIT/M_WAIT/

Xref memguard(9)

Sort sections.

Spelling fixes.

Cross-reference contigmalloc(9).

Back out previous commit due to objections.

Document the change in M_WAITOK semantics.

mdoc(7): Use the new feature of the .In macro.

Rename the section 'locking considerations' into 'context'.
Change the wording in this section to get rid of references to mutexes
and talk about sleeping instead.

Discussed with: jhb@, ru@

Assorted mdoc(7), grammar, spelling, and punctuation fixes.

Approved by: re (blanket)

malloc(9) types can be used to identify multiple allocations.

PR: docs/38618
Approved by: des (mentor)

Forced commit to fill in the fields below for the last commit. Also
bump the date of the man page.

PR: docs/24797
Reviewed by: bde, jake, jhb

Explicitely document the locking requirements for the malloc interface.
While beeing here also correct the following:

- list missing macros in the header
- document MALLOC_DEFINE and MALLOC_DECLARE in the SYNOPSIS section
- document additional include requirements for MALLOC_DEFINE
- M_NOWAIT is not 0 anymore
- remove rotted diagnostic messages

Return bits which were removed in revision 1.28.

Requested by: imp

The .Fn function

Catch up to WAIT/NOWAIT cleanup.

Add required commas that were ommitted in the previous delta; the
SEE ALSO section's list of manual pages must be comma-separated.

Document lock order reversals possible when calling allocation functions
with vnode interlocks held.

Emphasize that users need to be careful with malloc flags versus mbuf
flags.

Remove stale portion in vnode.9 about v_tag. We don't have it anylonger.

Submitted by: Hiten Pandya <hiten@unixdaemons.com>

Caution programmers not to confuse M_DONTWAIT with M_NOWAIT. They
are not the same.

Suggested by: Hiten Pandya <hiten@unixdaemons.com>

Spelling: s/then/than/ where appropriate.

mdoc(7) police: fixed some wording, kill whitespace at EOL.

Add realloc() and reallocf(), and make free(NULL, ...) acceptable.

Reviewed by: alfred

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

Spelling fix: depreciated -> deprecated.

Remove refernces to M_ASLEEP/asleep/await.

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.

mdoc(7) police: Removed extraneous .No call. The .Nm macro in
mdocNG has been fixed to properly handle its arguments so this
was causing the extraneous (undesirable) space.

Prepare for mdoc(7)NG.

Introduce the M_ZERO flag to malloc(9)

Instead of:

foo = malloc(sizeof(foo), M_WAIT);
bzero(foo, sizeof(foo));

You can now (and please do) use:

foo = malloc(sizeof(foo), M_WAIT | M_ZERO);

In the future this will enable us to do idle-time pre-zeroing of
malloc-space.

Remove single-space hard sentence breaks. These degrade the quality
of the typeset output, tend to make diffs harder to read and provide
bad examples for new-comers to mdoc.

Bring kernel malloc documentation up to date, including the example.

PR: docs/10059

$Id$ -> $FreeBSD$

Add $Id$, to make it simpler for members of the translation teams to
track.

The $Id$ line is normally at the bottom of the main comment block in the
man page, separated from the rest of the manpage by an empty comment,
like so;

.\" $Id$
.\"

If the immediately preceding comment is a @(#) format ID marker than the
the $Id$ will line up underneath it with no intervening blank lines.
Otherwise, an additional blank line is inserted.

Approved by: bde

Fix some typos and do some minor mdoc cleanup.

Removed occurrences of consecutive repeated words (such as "the the").

M_AWAIT changed to M_ASLEEP

Documentation update for new M_AWAIT flag to kernel malloc, plus revamp
the descriptions of the flags and return value.

Fix argument reversal in example.
PR: 7138
Reviewed by: phk
Submitted by: Robert Watson <robert+freebsd@cyrus.watson.org>

Fix a few typos.

Fixed a missing #include in the synopsis.

Update malloc.9 to reflect new reality.

Add malloc(9) to document the kernel malloc() and free() routines.

Obtained from: NetBSD w/changes to reflect current FreeBSD headers
and diagnostic messages.