219 lines
6.6 KiB
Groff
219 lines
6.6 KiB
Groff
.\"-
|
|
.\" Copyright (c) 2001 Dag-Erling Coïdan Smørgrav
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd January 27, 2001
|
|
.Dt ZONE 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm zbootinit ,
|
|
.Nm zinitna ,
|
|
.Nm zinit ,
|
|
.Nm zalloc ,
|
|
.Nm zfree ,
|
|
.Nm zdestroy
|
|
.Nd zone allocator
|
|
.Sh SYNOPSIS
|
|
.In sys/param.h
|
|
.In sys/queue.h
|
|
.In vm/vm_zone.h
|
|
.Ft void
|
|
.Fn zbootinit "vm_zone_t z" "char *name" "int size" "void *item" "int nitems"
|
|
.Ft int
|
|
.Fn zinitna "vm_zone_t z" "struct vm_object *obj" "char *name" "int size" "int nentries" "int flags" "int zalloc"
|
|
.Ft vm_zone_t
|
|
.Fn zinit "char *name" "int size" "int nentries" "int flags" "int zalloc"
|
|
.Ft void *
|
|
.Fn zalloc "vm_zone_t z"
|
|
.Ft void
|
|
.Fn zfree "vm_zone_t z" "void *item"
|
|
.Ft void
|
|
.Fn zdestroy "vm_zone_t z"
|
|
.Sh DESCRIPTION
|
|
The zone allocator provides an efficient interface for managing
|
|
dynamically-sized collections of items of similar size.
|
|
The zone allocator can work with preallocated zones as well as with
|
|
runtime-allocated ones, and is therefore available much earlier in the
|
|
boot process than other memory management routines.
|
|
.Pp
|
|
A zone is an extensible collection of items of identical size.
|
|
The zone allocator keeps track of which items are in use and which
|
|
aren't, and provides functions for allocating items from the zone and
|
|
for releasing them back (which makes them available for later use).
|
|
.Pp
|
|
The zone allocator stores state information inside the items proper
|
|
while they are not allocated,
|
|
so structures that will be managed by the zone allocator
|
|
and wish to use the type stable property of zones by leaving some fields
|
|
pre-filled between allocations, must reserve
|
|
two pointers at the very beginning for internal use by the zone
|
|
allocator, as follows:
|
|
.Bd -literal
|
|
struct my_item {
|
|
struct my_item *z_rsvd1;
|
|
struct my_item *z_rsvd2;
|
|
/* rest of structure */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
Alternatively they should assume those entries corrupted
|
|
after each allocation.
|
|
After the first allocation of an item,
|
|
it will have been cleared to zeroes, however subsequent allocations
|
|
will retain the contents as of the last free, with the exception of the
|
|
fields mentioned above.
|
|
.Pp
|
|
Zones are created in one of two fashions, depending how far along the
|
|
boot process is.
|
|
.Pp
|
|
If the VM system is fully initialized, a dynamically allocated zone can
|
|
be created using
|
|
.Fn zinit .
|
|
The
|
|
.Fa name
|
|
argument should be a pointer to a short, descriptive name for the
|
|
zone; it is used for statistics and debugging purposes.
|
|
The
|
|
.Fa size
|
|
and
|
|
.Fa nentries
|
|
are the size of the items held by the zone and the initial size (in
|
|
items) of the zone, respectively.
|
|
The
|
|
.Fa flags
|
|
argument should be set to
|
|
.Dv ZONE_INTERRUPT
|
|
if there is a chance that items may be allocated from the zone in
|
|
interrupt context; note that in this case, the zone will never grow
|
|
larger than
|
|
.Fa nentries
|
|
items.
|
|
In all other cases,
|
|
.Fa flags
|
|
should be set to 0.
|
|
The final argument,
|
|
.Fa zalloc ,
|
|
indicates the number of VM pages by which the zone should grow every
|
|
time it fills up.
|
|
.Pp
|
|
If the VM system is not yet fully initialized, the zone allocator
|
|
cannot dynamically allocate VM pages from which to dole out items, so
|
|
the caller needs to provide a static pool of items.
|
|
In this case, the initialization is done in two stages: first,
|
|
.Fn zbootinit
|
|
is called before first use of the zone; later, when the VM system is
|
|
up, the initialization of the zone is completed by calling
|
|
.Fn zinitna .
|
|
.Pp
|
|
The first argument to
|
|
.Fn zbootinit
|
|
is a pointer to a static
|
|
.Vt "struct vm_zone"
|
|
to initialize.
|
|
The second and third are the name of the zone and the size of the
|
|
items it will hold.
|
|
The fourth argument is a pointer to a static array of items from which
|
|
the zone allocator will draw until the zone is fully initialized.
|
|
The
|
|
.Fa nitems
|
|
argument is the number of items in the array.
|
|
.Pp
|
|
The arguments to
|
|
.Fa zinitna
|
|
are the same as for
|
|
.Fa zinit ,
|
|
with the addition of a pointer to the zone to initialize, and a
|
|
pointer to a
|
|
.Vt "struct vm_object"
|
|
from which to allocate pages in the
|
|
.Dv ZONE_INTERRUPT
|
|
case.
|
|
.Pp
|
|
To allocate an item from a zone, simply call
|
|
.Fn zalloc
|
|
with a pointer to that zone; it will return a pointer to an item, or
|
|
.Dv NULL
|
|
in the rare case where all items in the zone are in use and the
|
|
allocator is unable to grow the zone.
|
|
.Pp
|
|
Items are released back to the zone from which they were allocated by
|
|
calling
|
|
.Fn zfree
|
|
with a pointer to the zone and a pointer to the item.
|
|
.Pp
|
|
Zones created with
|
|
.Fn zinit
|
|
or
|
|
.Fn zinitna
|
|
can be destroyed using
|
|
.Fn zdestroy ,
|
|
freeing all memory that was allocated for the zone.
|
|
All items allocated from the zone with
|
|
.Fn zalloc
|
|
must have been freed with
|
|
.Fn zfree
|
|
before.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn zinitna
|
|
function returns 1 on success and 0 on failure; the only failure case
|
|
is inability to preallocate address space for an interrupt-safe zone.
|
|
.Pp
|
|
The
|
|
.Fn zinit
|
|
function returns a pointer to a fully initialized
|
|
.Vt "struct vm_zone" ,
|
|
or
|
|
.Dv NULL
|
|
if it was unable to
|
|
.Fn malloc
|
|
a
|
|
.Vt "struct vm_zone"
|
|
or the
|
|
.Dv ZONE_INTERRUPT
|
|
flag was specified and
|
|
.Fn zinitna
|
|
failed to preallocate address space.
|
|
.Pp
|
|
The
|
|
.Fn zalloc
|
|
function returns a pointer to an item, or
|
|
.Dv NULL
|
|
if the zone ran out of unused items and the allocator was unable to
|
|
enlarge it.
|
|
.Sh SEE ALSO
|
|
.Xr malloc 9
|
|
.Sh HISTORY
|
|
The zone allocator first appeared in
|
|
.Fx 3.0 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The zone allocator was written by
|
|
.An John S. Dyson .
|
|
.Pp
|
|
This manual page was written by
|
|
.An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org .
|