diff options
-rw-r--r-- | share/man/man9/Makefile | 7 | ||||
-rw-r--r-- | share/man/man9/zone.9 | 191 |
2 files changed, 198 insertions, 0 deletions
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index cba8932..f9e4adc 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -49,6 +49,7 @@ MAN9+= device.9 device_add_child.9 device_delete_child.9 device_enable.9 \ VOP_ACLCHECK.9 VOP_GETACL.9 VOP_GETEXTATTR.9 VOP_SETACL.9 \ VOP_SETEXTATTR.9 acl.9 extattr.9 kobj.9 taskqueue.9 accept_filter.9 \ sbuf.9 \ + zone.9 \ sysctl_add_oid.9 sysctl_ctx_init.9 MLINKS+=MD5.9 MD5Init.9 MD5.9 MD5Transform.9 @@ -211,4 +212,10 @@ MLINKS+=sbuf.9 sbuf_data.9 MLINKS+=sbuf.9 sbuf_len.9 MLINKS+=sbuf.9 sbuf_delete.9 +MLINKS+=zone.9 zalloc.9 +MLINKS+=zone.9 zfree.9 +MLINKS+=zone.9 zinit.9 +MLINKS+=zone.9 zinitna.9 +MLINKS+=zone.9 zbootinit.9 + .include <bsd.prog.mk> 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 . |