382 lines
9.9 KiB
Groff
382 lines
9.9 KiB
Groff
.\" $NetBSD: malloc.9,v 1.35 2004/11/07 16:44:37 wiz Exp $
|
|
.\"
|
|
.\" 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, and by Jason R. Thorpe.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd November 7, 2004
|
|
.Dt MALLOC 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm malloc ,
|
|
.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
|
|
.In sys/malloc.h
|
|
.Ft void *
|
|
.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" "struct malloc_type *type"
|
|
.Fn FREE "void *addr" "struct malloc_type *type"
|
|
.Ft unsigned long
|
|
.Fn malloc_roundup "unsigned long size"
|
|
.Ft void
|
|
.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"
|
|
.In sys/mallocvar.h
|
|
.Fn MALLOC_DEFINE_LIMIT "type" "shortdesc" "longdesc" "limit"
|
|
.Fn MALLOC_DEFINE "type" "shortdesc" "longdesc"
|
|
.Fn MALLOC_DECLARE "type"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn malloc
|
|
function allocates uninitialized memory in kernel address space for an
|
|
object whose size is specified by
|
|
.Fa size .
|
|
.Fn malloc_roundup
|
|
returns the actual size of the allocation unit for the given value.
|
|
.Fn free
|
|
releases memory at address
|
|
.Fa addr
|
|
that was previously allocated by
|
|
.Fn malloc
|
|
for re-use.
|
|
Unlike
|
|
.Xr free 3 ,
|
|
.Fn free
|
|
does not accept an
|
|
.Fa addr
|
|
argument that is
|
|
.Dv NULL .
|
|
.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
|
|
.Bd -literal -offset indent
|
|
(space) = (cast)malloc((u_long)(size), type, flags)
|
|
.Ed
|
|
.Pp
|
|
and the
|
|
.Fn FREE
|
|
macro variant is equivalent to
|
|
.Bd -literal -offset indent
|
|
free((caddr_t)(addr), type)
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fn MALLOC
|
|
macro is intended to be used with a compile-time constant
|
|
.Fa size
|
|
so that the compiler can do constant folding.
|
|
In the comparison to
|
|
.Fn malloc
|
|
and
|
|
.Fn free
|
|
functions, the
|
|
.Fn MALLOC
|
|
and
|
|
.Fn FREE
|
|
macros may be faster, at the cost of increased code size.
|
|
There is no difference between the memory allocated with MALLOC and malloc.
|
|
i.e., no matter which MALLOC or malloc is used to allocate the memory,
|
|
either FREE or free can be used to free it.
|
|
.Pp
|
|
Unlike its standard C library counterpart
|
|
.Pq Xr malloc 3 ,
|
|
the kernel version takes two more arguments.
|
|
.Pp
|
|
The
|
|
.Fa flags
|
|
argument further qualifies
|
|
.Fn malloc
|
|
operational characteristics as follows:
|
|
.Bl -tag -offset indent -width M_CANFAIL
|
|
.It Dv M_NOWAIT
|
|
Causes
|
|
.Fn malloc
|
|
to return
|
|
.Dv NULL
|
|
if the request cannot be immediately fulfilled due to resource shortage.
|
|
If this flag is not set
|
|
(see
|
|
.Dv M_WAITOK ) ,
|
|
.Fn malloc
|
|
will never return
|
|
.Dv NULL .
|
|
.It Dv M_WAITOK
|
|
By default,
|
|
.Fn malloc
|
|
may call
|
|
.Xr tsleep 9
|
|
to wait for resources to be released by other processes, and this
|
|
flag represents this behaviour.
|
|
Note that
|
|
.Dv M_WAITOK
|
|
is conveniently defined to be 0, and hence may be or'ed into the
|
|
.Fa flags
|
|
argument to indicate that it's ok to wait for resources.
|
|
.It Dv M_ZERO
|
|
Causes the allocated memory to be set to all zeros.
|
|
.It Dv M_CANFAIL
|
|
Changes behaviour for
|
|
.Dv M_WAITOK
|
|
case - if the requested memory size is bigger than
|
|
.Fn malloc
|
|
can ever allocate, return failure, rather than calling
|
|
.Xr panic 9 .
|
|
This is different to M_NOWAIT, since
|
|
the call can still wait for resources.
|
|
.Pp
|
|
Rather than depending on
|
|
.Dv M_CANFAIL ,
|
|
kernel code should do proper bound checking itself.
|
|
This flag should only be used in cases where this is not feasible.
|
|
Since it can hide real kernel bugs, its usage is
|
|
.Em strongly discouraged .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fa type
|
|
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, enforce 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_DEVBUF
|
|
Device driver memory.
|
|
.It Dv M_DMAMAP
|
|
.Xr bus_dma 9
|
|
structures.
|
|
.It Dv M_FREE
|
|
Should be on free list.
|
|
.It Dv M_PCB
|
|
Protocol control block.
|
|
.It Dv M_SOFTINTR
|
|
Softinterrupt structures.
|
|
.It Dv M_TEMP
|
|
Misc temporary data buffers.
|
|
.El
|
|
.Pp
|
|
Other malloc types are defined by the corresponding subsystem; see the
|
|
documentation for that subsystem for information its available malloc
|
|
types.
|
|
.Pp
|
|
Statistics based on the
|
|
.Fa type
|
|
argument are maintained only if the kernel option
|
|
.Dv KMEMSTATS
|
|
is used when compiling the kernel
|
|
.Po
|
|
the default in current
|
|
.Nx
|
|
kernels
|
|
.Pc
|
|
and can be examined by using
|
|
.Sq vmstat -m .
|
|
.Sh RETURN VALUES
|
|
.Fn malloc
|
|
returns a kernel virtual address that is suitably aligned for storage of
|
|
any type of object.
|
|
.Sh DIAGNOSTICS
|
|
A kernel compiled with the
|
|
.Dv DIAGNOSTIC
|
|
configuration option attempts to detect memory corruption caused by
|
|
such things as writing outside the allocated area and imbalanced calls to the
|
|
.Fn malloc
|
|
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: out of space in kmem_map
|
|
.It
|
|
panic:
|
|
.Dq malloc: allocation too large
|
|
.It
|
|
panic:
|
|
.Dq malloc: wrong bucket
|
|
.It
|
|
panic:
|
|
.Dq malloc: lost data
|
|
.It
|
|
panic:
|
|
.Dq free: unaligned addr
|
|
.It
|
|
panic:
|
|
.Dq free: duplicated free
|
|
.It
|
|
panic:
|
|
.Dq free: multiple frees
|
|
.It
|
|
panic:
|
|
.Dq init: minbucket too small/struct freelist too big
|
|
.It
|
|
.Dq multiply freed item Aq addr
|
|
.It
|
|
.Dq Data modified on freelist: Aq data object description
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr vmstat 1
|