[src/trunk]: src/share/man/man9 Update for extensibe malloc types.

[thorpej <thorpej%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/889db9191ef5
branches:  trunk
changeset: 542537:889db9191ef5
user:      thorpej <thorpej%NetBSD.org@localhost>
date:      Sat Feb 01 06:27:23 2003 +0000

description:
Update for extensibe malloc types.

diffstat:

 share/man/man9/Makefile |   12 +-
 share/man/man9/malloc.9 |  442 +++++++++++++++++------------------------------
 2 files changed, 171 insertions(+), 283 deletions(-)

diffs (truncated from 542 to 300 lines):

diff -r 6b1f256f4a83 -r 889db9191ef5 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Sat Feb 01 06:26:30 2003 +0000
+++ b/share/man/man9/Makefile   Sat Feb 01 06:27:23 2003 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.134 2003/01/11 22:45:41 lha Exp $
+#       $NetBSD: Makefile,v 1.135 2003/02/01 06:27:23 thorpej Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -239,8 +239,11 @@
        lock.9 lockstatus.9 lock.9 lockmgr_printinfo.9 \
        lock.9 spinlockinit.9 lock.9 spinlockmgr.9
 MLINKS+=ltsleep.9 wakeup.9 ltsleep.9 tsleep.9
-MLINKS+=malloc.9 free.9 malloc.9 malloc_roundup.9
-MLINKS+=malloc.9 MALLOC.9 malloc.9 FREE.9
+MLINKS+=malloc.9 MALLOC.9 malloc.9 realloc.9 malloc.9 free.9 malloc.9 FREE.9
+MLINKS+=malloc.9 malloc_roundup.9 malloc.9 malloc_type_attach.9
+MLINKS+=malloc.9 malloc_type_detach.9 malloc.9 malloc_type_setlimit.9
+MLINKS+=malloc.9 MALLOC_DEFINE_LIMIT.9 malloc.9 MALLOC_DEFINE.9
+MLINKS+=malloc.9 MALLOC_DECLARE.9
 MLINKS+=mbuf.9 m_get.9 mbuf.9 m_getclr.9 mbuf.9 m_gethdr.9 mbuf.9 m_devget.9 \
        mbuf.9 m_copym.9 mbuf.9 m_copypacket.9 mbuf.9 m_copydata.9 \
        mbuf.9 m_copyback.9 mbuf.9 m_cat.9 mbuf.9 m_dup.9 mbuf.9 m_prepend.9 \
@@ -579,6 +582,3 @@
 
 .include <bsd.man.mk>
 .include <bsd.subdir.mk>
-
-
-
diff -r 6b1f256f4a83 -r 889db9191ef5 share/man/man9/malloc.9
--- a/share/man/man9/malloc.9   Sat Feb 01 06:26:30 2003 +0000
+++ b/share/man/man9/malloc.9   Sat Feb 01 06:27:23 2003 +0000
@@ -1,10 +1,10 @@
-.\"    $NetBSD: malloc.9,v 1.27 2003/01/17 08:11:49 itojun Exp $
+.\"    $NetBSD: malloc.9,v 1.28 2003/02/01 06:27:23 thorpej Exp $
 .\"
-.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
+.\" Copyright (c) 1996, 2003 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to The NetBSD Foundation
-.\" by Paul Kranenburg.
+.\" by Paul Kranenburg, and by Jason R. Thorpe.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -34,22 +34,47 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd December 4, 2001
+.Dd January 31, 2003
 .Dt MALLOC 9
 .Os
 .Sh NAME
 .Nm malloc ,
-.Nm free
-.Nd kernel memory allocator
+.Nm MALLOC ,
+.Nm realloc ,
+.Nm free ,
+.Nm FREE ,
+.Nm malloc_roundup ,
+.Nm malloc_type_attach ,
+.Nm malloc_type_detach ,
+.Nm malloc_type_setlimit ,
+.Nm MALLOC_DEFINE_LIMIT ,
+.Nm MALLOC_DEFINE ,
+.Nm MALLOC_DECLARE
+.Nd general-purpose kernel memory allocator
 .Sh SYNOPSIS
+.Fd #include \*[Lt]sys/malloc.h\*[Gt]
 .Ft void *
-.Fn malloc "unsigned long size" "int type" "int flags"
-.Fn MALLOC "space" "cast" "unsigned long size" "int type" "int flags"
+.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
+.Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type *type" \
+    "int flags"
+.Ft void *
+.Fn realloc "void *addr" "unsigned long newsize" "struct malloc_type *type" \
+    "int flags"
+.Ft void
+.Fn free "void *addr" "int type"
+.Fn FREE "void *addr" "int type"
 .Ft unsigned long
 .Fn malloc_roundup "unsigned long size"
 .Ft void
-.Fn free "void *addr" "int type"
-.Fn FREE "void *addr" "int type"
+.Fn malloc_type_attach "struct malloc_type *type"
+.Ft void
+.Fn malloc_type_detach "struct malloc_type *type"
+.Ft void
+.Fn malloc_type_setlimit "struct malloc_type *type" "unsigned long limit"
+.Fd #include \*[Lt]sys/mallocvar.h\*[Gt]
+.Fn MALLOC_DEFINE_LIMIT "type" "shortdesc" "longdesc" "limit"
+.Fn MALLOC_DEFINE "type" "shortdesc" "longdesc"
+.Fn MALLOC_DECLARE "type"
 .Sh DESCRIPTION
 The
 .Fn malloc
@@ -64,6 +89,38 @@
 that was previously allocated by
 .Fn malloc
 for re-use.
+.Pp
+The
+.Fn realloc
+function changes the size of the previously allocated memory referenced
+by
+.Fa addr
+to
+.Fa size
+and returns a pointer to the
+.Pq possibly moved
+object.  The memory contents are unchanged up to the lesser of the new
+and old sizes.
+If the new size is larger, the newly allocated memory is
+uninitialized.
+If the requested memory cannot be allocated,
+.Dv NULL
+is returned and the memory referenced by
+.Fa addr
+is unchanged.
+If
+.Fa addr
+is
+.Dv NULL ,
+then
+.Fn realloc
+behaves exactly as
+.Fn malloc .
+If the new size is 0, then
+.Fn realloc
+behaves exactly as
+.Fn free .
+.Pp
 The
 .Fn MALLOC
 macro variant is functionally equivalent to
@@ -80,9 +137,15 @@
 .Pp
 The
 .Fn MALLOC
-is intended to be used with a compile-time constant
+macro is intended to be used with a compile-time constant
 .Fa size
 so that the compiler can do constant folding.
+The
+.Fn MALLOC
+and
+.Fn FREE
+macros may be faster for some fixed-size allocations, at the cost of
+increased code size.
 .Pp
 Unlike its standard C library counterpart
 .Pq Xr malloc 3 ,
@@ -110,7 +173,7 @@
 By default,
 .Fn malloc
 may call
-.Xr sleep 9
+.Xr tsleep 9
 to wait for resources to be released by other processes, and this
 flag represents this behaviour.
 Note that
@@ -140,284 +203,109 @@
 .Pp
 The
 .Fa type
-argument broadly identifies the kernel subsystem for which the allocated
-memory was needed, and is commonly used to maintain statistics about
-kernel memory usage.
-The following types are currently defined:
+argument describes the subsystem and/or use within a subsystem for which
+the allocated memory was needed, and is commonly used to maintain statistics
+about kernel memory usage and, optionally, inforce limits on this usage for
+certain memory types.
+.Pp
+In addition to some built-in generic types defined by the kernel
+memory allocator, subsystems may define their own types.
+.Pp
+The
+.Fn MALLOC_DEFINE_LIMIT
+macro defines a malloc type named
+.Fa type
+with the short description
+.Fa shortdesc ,
+which must be a constant string; this description will be used for
+kernel memory statistics reporting.
+The
+.Fa longdesc
+argument, also a constant string, is intended as way to place a
+comment in the actual type definition, and is not currently stored
+in the type structure.
+The
+.Fa limit
+argument specifies the maximum amount of memory, in bytes, that this
+malloc type can consume.
+.Pp
+The
+.Fn MALLOC_DEFINE
+macro is equivalent to the
+.Fn MALLOC_DEFINE_LIMIT
+macro with a
+.Fa limit
+argument of 0.
+If kernel memory statistics are being gathered, the system will
+choose a reasonable default limit for the malloc type.
+.Pp
+The
+.Fn MALLOC_DECLARE
+macro is intended for use in header files which are included by
+code which needs to use the malloc type, providing the necessary
+extern declaration.
+.Pp
+Code which includes
+\*[Lt]sys/malloc.h\*[Gt]
+does not need to include
+\*[Lt]sys/mallocvar.h\*[Gt]
+to get these macro definitions.
+The
+\*[Lt]sys/mallocvar.h\*[Gt]
+header file is intended for other header files which need to use the
+.Fn MALLOC_DECLARE
+macro.
+.Pp
+The
+.Fn malloc_type_attach
+function attaches the malloc type
+.Fa type
+to the kernel memory allocator.
+This is intended for use by LKMs; malloc types included in modules
+statically-linked into the kernel are automatically registered with
+the kernel memory allocator.
+.Pp
+The
+.Fn malloc_type_detach
+function detaches the malloc type
+.Fa type
+previously attached with
+.Fn malloc_type_attach .
+.Pp
+The
+.Fn malloc_type_setlimit
+function sets the memory limit of the malloc type
+.Fa type
+to
+.Fa limit
+bytes.
+The type must already be registered with the kernel memory allocator.
+.Pp
+The following generic malloc types are currently defined:
 .Pp
 .Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact
-.It Dv M_FREE
-Should be on free list.
-.It Dv M_MBUF
-Mbuf memory.
 .It Dv M_DEVBUF
 Device driver memory.
-.It Dv M_SOCKET
-Socket structure.
-.It Dv M_PCB
-Protocol control block.
-.It Dv M_RTABLE
-Routing tables.
-.It Dv M_HTABLE
-IMP host tables.
-.It Dv M_FTABLE
-Fragment reassembly header.
-.It Dv M_ZOMBIE
-Zombie proc status
-.It Dv M_IFADDR
-Interface address.
-.It Dv M_SOOPTS
-Socket options.
-.It Dv M_SONAME
-Socket name.
-.It Dv M_NAMEI
-Namei path name buffer.
-.It Dv M_GPROF
-Kernel profiling buffer.
-.It Dv M_IOCTLOPS
-Ioctl data buffer.
-.It Dv M_MAPMEM
-Mapped memory descriptors.
-.It Dv M_CRED
-Credentials.
-.It Dv M_PGRP
-Process group header.
-.It Dv M_SESSION
-Session header.
-.It Dv M_IOV
-Large iov's.
-.It Dv M_MOUNT
-Vfs mount struct.
-.It Dv M_FHANDLE
-Network file handle.