1.\"- 2.\" Copyright (c) 2001 Dag-Erling Co�dan Sm�rgrav 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD: src/share/man/man9/zone.9,v 1.9.2.4 2002/05/02 20:01:29 asmodai Exp $ 27.\" $DragonFly: src/share/man/man9/zone.9,v 1.3 2003/10/15 15:36:44 hmp Exp $ 28.\" 29.Dd January 27, 2001 30.Dt ZONE 9 31.Os 32.Sh NAME 33.Nm zbootinit , 34.Nm zinitna , 35.Nm zinit , 36.Nm zalloc , 37.Nm zfree , 38.Nd zone allocator 39.Sh SYNOPSIS 40.In sys/param.h 41.In sys/queue.h 42.In vm/vm_zone.h 43.Ft void 44.Fn zbootinit "vm_zone_t z" "char *name" "int size" "void *item" "int nitems" 45.Ft int 46.Fn zinitna "vm_zone_t z" "struct vm_object *obj" "char *name" "int size" "int nentries" "int flags" "int zalloc" 47.Ft vm_zone_t 48.Fn zinit "char *name" "int size" "int nentries" "int flags" "int zalloc" 49.Ft void * 50.Fn zalloc "vm_zone_t z" 51.Ft void 52.Fn zfree "vm_zone_t z" "void *item" 53.Sh DESCRIPTION 54The zone allocator provides an efficient interface for managing 55dynamically-sized collections of items of similar size. 56The zone allocator can work with preallocated zones as well as with 57runtime-allocated ones, and is therefore available much earlier in the 58boot process than other memory management routines. 59.Pp 60A zone is an extensible collection of items of identical size. 61The zone allocator keeps track of which items are in use and which 62are not, and provides functions for allocating items from the zone and 63for releasing them back (which makes them available for later use). 64.Pp 65The zone allocator stores state information inside the items proper 66while they are not allocated, 67so structures that will be managed by the zone allocator 68and wish to use the type stable property of zones by leaving some fields 69pre-filled between allocations, must reserve 70two pointers at the very beginning for internal use by the zone 71allocator, as follows: 72.Bd -literal 73struct my_item { 74 struct my_item *z_rsvd1; 75 struct my_item *z_rsvd2; 76 /* rest of structure */ 77}; 78.Ed 79.Pp 80Alternatively they should assume those entries corrupted 81after each allocation. 82After the first allocation of an item, 83it will have been cleared to zeroes, however subsequent allocations 84will retain the contents as of the last free, with the exception of the 85fields mentioned above. 86.Pp 87Zones are created in one of two fashions, depending how far along the 88boot process is. 89.Pp 90If the VM system is fully initialized, a dynamically allocated zone can 91be created using 92.Fn zinit . 93The 94.Fa name 95argument should be a pointer to a short, descriptive name for the 96zone; it is used for statistics and debugging purposes. 97The 98.Fa size 99and 100.Fa nentries 101are the size of the items held by the zone and the initial size (in 102items) of the zone, respectively. 103The 104.Fa flags 105argument should be set to 106.Dv ZONE_INTERRUPT 107if there is a chance that items may be allocated from the zone in 108interrupt context; note that in this case, the zone will never grow 109larger than 110.Fa nentries 111items. 112In all other cases, 113.Fa flags 114should be set to 0. 115The final argument, 116.Fa zalloc , 117indicates the number of VM pages by which the zone should grow every 118time it fills up. 119.Pp 120If the VM system is not yet fully initialized, the zone allocator 121cannot dynamically allocate VM pages from which to dole out items, so 122the caller needs to provide a static pool of items. 123In this case, the initialization is done in two stages: first, 124.Fn zbootinit 125is called before first use of the zone; later, when the VM system is 126up, the initialization of the zone is completed by calling 127.Fn zinitna . 128.Pp 129The first argument to 130.Fn zbootinit 131is a pointer to a static 132.Vt "struct vm_zone" 133to initialize. 134The second and third are the name of the zone and the size of the 135items it will hold. 136The fourth argument is a pointer to a static array of items from which 137the zone allocator will draw until the zone is fully initialized. 138The 139.Fa nitems 140argument is the number of items in the array. 141.Pp 142The arguments to 143.Fa zinitna 144are the same as for 145.Fa zinit , 146with the addition of a pointer to the zone to initialize, and a 147pointer to a 148.Vt "struct vm_object" 149from which to allocate pages in the 150.Dv ZONE_INTERRUPT 151case. 152.Pp 153To allocate an item from a zone, simply call 154.Fn zalloc 155with a pointer to that zone; it will return a pointer to an item, or 156.Dv NULL 157in the rare case where all items in the zone are in use and the 158allocator is unable to grow the zone. 159The 160.Fn zalloc 161and 162.Fn zfree 163functions are interrupt and SMP safe. 164.Pp 165Items are released back to the zone from which they were allocated by 166calling 167.Fn zfree 168with a pointer to the zone and a pointer to the item. 169.Sh RETURN VALUES 170The 171.Fn zinitna 172function returns 1 on success and 0 on failure; the only failure case 173is inability to preallocate address space for an interrupt-safe zone. 174.Pp 175The 176.Fn zinit 177function returns a pointer to a fully initialized 178.Vt "struct vm_zone" , 179or 180.Dv NULL 181if it was unable to 182.Fn malloc 183a 184.Vt "struct vm_zone" 185or the 186.Dv ZONE_INTERRUPT 187flag was specified and 188.Fn zinitna 189failed to preallocate address space. 190.Pp 191The 192.Fn zalloc 193function returns a pointer to an item, or 194.Dv NULL 195if the zone ran out of unused items and the allocator was unable to 196enlarge it. 197.Sh SEE ALSO 198.Xr malloc 9 199.Sh HISTORY 200The zone allocator first appeared in 201.Fx 3.0 . 202.Sh AUTHORS 203.An -nosplit 204The zone allocator was written by 205.An John S. Dyson . 206.Pp 207This manual page was written by 208.An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org . 209