Add a man page for the zone allocator.

1 files changed, 191 insertions, 0 deletions

diff --git a/share/man/man9/zone.9 b/share/man/man9/zone.9
new file mode 100644
index 0000000..2ac1aa2
--- /dev/null
+++ b/share/man/man9/zone.9
@@ -0,0 +1,191 @@
+.\"-
+.\" 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
+.Nd Zone allocator
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <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"
+.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,
+so structures that will be managed by the zone allocator 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
+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
+.Fa 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
+.Fa 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.
+.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
+.Fa struct vm_zone ,
+or
+.Dv NULL
+if it was unable to
+.Fn malloc
+a
+.Fa 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 .