diff options
author | Dag-Erling Smørgrav <des@FreeBSD.org> | 2001-01-27 19:13:08 +0000 |
---|---|---|
committer | Dag-Erling Smørgrav <des@FreeBSD.org> | 2001-01-27 19:13:08 +0000 |
commit | 0aa028ffe940314955c458a628fb175b6db09376 (patch) | |
tree | 794dcdef2e49a0e71fd361a4ccf833646ff1c103 /share/man/man9/zone.9 | |
parent | 5774351e81f02bef2afd3d0d9fe6776e1f22ddad (diff) | |
download | src-0aa028ffe940314955c458a628fb175b6db09376.tar.gz src-0aa028ffe940314955c458a628fb175b6db09376.zip |
Add a man page for the zone allocator.
Notes
Notes:
svn path=/head/; revision=71714
Diffstat (limited to 'share/man/man9/zone.9')
-rw-r--r-- | share/man/man9/zone.9 | 191 |
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 000000000000..2ac1aa27f051 --- /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 . |