From a90ae59dd6d24053d1b7be5936275362f7645085 Mon Sep 17 00:00:00 2001
From: harti <harti@FreeBSD.org>
Date: Wed, 9 Apr 2003 08:27:32 +0000
Subject: 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
---
 share/man/man9/malloc.9 | 136 ++++++++++++++++++++++++------------------------
 1 file changed, 67 insertions(+), 69 deletions(-)

(limited to 'share')

diff --git a/share/man/man9/malloc.9 b/share/man/man9/malloc.9
index b22852c..be40a64 100644
--- a/share/man/man9/malloc.9
+++ b/share/man/man9/malloc.9
@@ -43,7 +43,11 @@
 .Nm malloc ,
 .Nm MALLOC ,
 .Nm free ,
-.Nm FREE
+.Nm FREE ,
+.Nm realloc ,
+.Nm reallocf ,
+.Nm MALLOC_DEFINE ,
+.Nm MALLOC_DECLARE
 .Nd kernel memory management routines
 .Sh SYNOPSIS
 .In sys/types.h
@@ -58,6 +62,11 @@
 .Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
 .Ft void *
 .Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
+.Fn MALLOC_DECLARE "type"
+.In sys/param.h
+.In sys/malloc.h
+.In sys/kernel.h
+.Fn MALLOC_DEFINE "type" "shortdesc" "longdesc"
 .Sh DESCRIPTION
 The
 .Fn malloc
@@ -147,44 +156,22 @@ and
 to return
 .Dv NULL
 if the request cannot be immediately fulfilled due to resource shortage.
-Otherwise, the current process may be put to sleep to wait for
-resources to be released by other processes.
-If this flag is set,
-.Fn malloc
-will return
-.Dv NULL
-rather than block.
 Note that
 .Dv M_NOWAIT
-is defined to be 0, meaning that blocking operation is the default.
-Also note that
-.Dv M_NOWAIT
 is required when running in an interrupt context.
-.Pp
-Programmers should be careful not to confuse
-.Dv M_NOWAIT ,
-the
-.Fn malloc
-flag, with
-.Dv M_DONTWAIT ,
-an
-.Xr mbuf 9
-allocation flag, which is not a valid argument to
-.Fn malloc .
 .It Dv M_WAITOK
-Indicates that it is Ok to wait for resources.  It is unconveniently
-defined as 0 so care should be taken never to compare against this value
-directly or try to AND it as a flag.  The default operation is to block
-until the memory allocation succeeds.
+Indicates that it is ok to wait for resources.  
+If the request cannot be immediately fulfilled the current process is put
+to sleep to wait for resources to be released by other processes.
 The
 .Fn malloc ,
 .Fn realloc ,
 and
 .Fn reallocf
-functions can only return
+functions cannot return
 .Dv NULL
 if
-.Dv M_NOWAIT
+.Dv M_WAITOK
 is specified.
 .It Dv M_USE_RESERVE
 Indicates that the system can dig into its reserve in order to obtain the
@@ -194,6 +181,12 @@ slowly being removed from the kernel, and so should not be used with any new
 programming.
 .El
 .Pp
+Exactly one of either
+.Dv M_WAITOK
+or
+.Dv M_NOWAIT
+must be specified.
+.Pp
 The
 .Fa type
 argument is used to perform statistics on memory usage, and for
@@ -203,9 +196,9 @@ The statistics can be examined by
 .Pp
 A
 .Fa type
-is defined using the
-.Va malloc_type_t
-typedef via the
+is defined using
+.Va struct malloc_type
+via the
 .Fn MALLOC_DECLARE
 and
 .Fn MALLOC_DEFINE
@@ -225,6 +218,15 @@ MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
 MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);
 
 .Ed
+.Pp
+In order to use
+.Fn MALLOC_DEFINE
+one must include
+.Aq sys/param.h
+(instead of
+.Aq sys/types.h )
+and
+.Aq sys/kernel.h .
 .Sh RETURN VALUES
 The
 .Fn malloc ,
@@ -244,14 +246,42 @@ For larger requests, one or more pages is allocated.
 While it should not be relied upon, this information may be useful for
 optimizing the efficiency of memory use.
 .Pp
-Malloc flags documented above should
-.Em NOT
-be used with
+Programmers should be careful not to confuse the malloc flags
+.Dv M_NOWAIT
+and
+.Dv M_WAITOK
+with the
 .Xr mbuf 9
-routines as it will cause undesired results.
+flags
+.Dv M_DONTWAIT
+and
+.Dv M_TRYWAIT .
+.Sh LOCKING CONSIDERATIONS
+.Fn malloc ,
+.Fn realloc
+and
+.Fn reallocf
+may not be called from fast interrupts handlers.
+When called from threaded interrupts
+.Ar flag
+must contain
+.Dv M_NOWAIT .
+.Pp
+.Fn malloc ,
+.Fn realloc
+and
+.Fn reallocf
+must not be called with
+.Dv M_WAITOK
+while a mutex other than Giant is held.
+Giant may or may not be held when
+.Fn free
+is called.
 .Pp
 Any calls to
 .Fn malloc
+(even with
+.Dv M_NOWAIT )
 or
 .Fn free
 when holding a
@@ -263,7 +293,7 @@ interwining of VM Objects and Vnodes.
 .Xr vnode 9
 .Sh DIAGNOSTICS
 A kernel compiled with the
-.Dv DIAGNOSTIC
+.Dv INVARIANTS
 configuration option attempts to detect memory corruption caused by
 such things as writing outside the allocated area and imbalanced calls to the
 .Fn malloc
@@ -271,36 +301,4 @@ and
 .Fn free
 functions.
 Failing consistency checks will cause a panic or a system console
-message:
-.Bl -bullet -offset indent -compact
-.Pp
-.It
-panic:
-.Dq malloc: bogus type
-.It
-panic:
-.Dq malloc: allocation too large
-.It
-panic:
-.Dq malloc: wrong bucket
-.It
-panic:
-.Dq malloc: lost data
-.It
-panic:
-.Dq free: address 0x%x out of range
-.It
-panic:
-.Dq free: type %d out of range
-.It
-panic:
-.Dq free: unaligned addr Aq description of object
-.It
-panic:
-.Dq free: item modified
-.It
-panic:
-.Dq free: multiple free[s]
-.It
-.Dq Data modified on freelist: Aq description of object
-.El
+message.
-- 
cgit v1.1