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

1 files changed, 8 insertions, 1 deletions

diff --git a/share/man/man9/malloc.9 b/share/man/man9/malloc.9
index a2978af..eec2c86 100644
--- a/share/man/man9/malloc.9
+++ b/share/man/man9/malloc.9
@@ -29,7 +29,7 @@
 .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
 .\" $FreeBSD$
 .\"
-.Dd January 16, 2014
+.Dd November 19, 2015
 .Dt MALLOC 9
 .Os
 .Sh NAME
@@ -227,6 +227,13 @@ may sleep when called with
 .Dv M_WAITOK .
 .Fn free
 never sleeps.
+However,
+.Fn malloc ,
+.Fn realloc,
+.Fn reallocf
+and
+.Fn free
+may not be called in a critical section or while holding a spin lock.
 .Pp
 Any calls to
 .Fn malloc