10aa028ffSDag-Erling Smørgrav.\"- 20aa028ffSDag-Erling Smørgrav.\" Copyright (c) 2001 Dag-Erling Co�dan Sm�rgrav 30aa028ffSDag-Erling Smørgrav.\" All rights reserved. 40aa028ffSDag-Erling Smørgrav.\" 50aa028ffSDag-Erling Smørgrav.\" Redistribution and use in source and binary forms, with or without 60aa028ffSDag-Erling Smørgrav.\" modification, are permitted provided that the following conditions 70aa028ffSDag-Erling Smørgrav.\" are met: 80aa028ffSDag-Erling Smørgrav.\" 1. Redistributions of source code must retain the above copyright 90aa028ffSDag-Erling Smørgrav.\" notice, this list of conditions and the following disclaimer. 100aa028ffSDag-Erling Smørgrav.\" 2. Redistributions in binary form must reproduce the above copyright 110aa028ffSDag-Erling Smørgrav.\" notice, this list of conditions and the following disclaimer in the 120aa028ffSDag-Erling Smørgrav.\" documentation and/or other materials provided with the distribution. 130aa028ffSDag-Erling Smørgrav.\" 140aa028ffSDag-Erling Smørgrav.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 150aa028ffSDag-Erling Smørgrav.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 160aa028ffSDag-Erling Smørgrav.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 170aa028ffSDag-Erling Smørgrav.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 180aa028ffSDag-Erling Smørgrav.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 190aa028ffSDag-Erling Smørgrav.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 200aa028ffSDag-Erling Smørgrav.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 210aa028ffSDag-Erling Smørgrav.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 220aa028ffSDag-Erling Smørgrav.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 230aa028ffSDag-Erling Smørgrav.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 240aa028ffSDag-Erling Smørgrav.\" SUCH DAMAGE. 250aa028ffSDag-Erling Smørgrav.\" 260aa028ffSDag-Erling Smørgrav.\" $FreeBSD$ 270aa028ffSDag-Erling Smørgrav.\" 280aa028ffSDag-Erling Smørgrav.Dd January 27, 2001 290aa028ffSDag-Erling Smørgrav.Dt ZONE 9 300aa028ffSDag-Erling Smørgrav.Os 310aa028ffSDag-Erling Smørgrav.Sh NAME 320aa028ffSDag-Erling Smørgrav.Nm zbootinit , 330aa028ffSDag-Erling Smørgrav.Nm zinitna , 340aa028ffSDag-Erling Smørgrav.Nm zinit , 350aa028ffSDag-Erling Smørgrav.Nm zalloc , 362f7ac308SRuslan Ermilov.Nm zfree , 372f7ac308SRuslan Ermilov.Nm zdestroy 38f5fccbbcSDag-Erling Smørgrav.Nd zone allocator 390aa028ffSDag-Erling Smørgrav.Sh SYNOPSIS 4032eef9aeSRuslan Ermilov.In sys/param.h 41f16b3c0dSChad David.In sys/queue.h 4232eef9aeSRuslan Ermilov.In vm/vm_zone.h 430aa028ffSDag-Erling Smørgrav.Ft void 440aa028ffSDag-Erling Smørgrav.Fn zbootinit "vm_zone_t z" "char *name" "int size" "void *item" "int nitems" 450aa028ffSDag-Erling Smørgrav.Ft int 460aa028ffSDag-Erling Smørgrav.Fn zinitna "vm_zone_t z" "struct vm_object *obj" "char *name" "int size" "int nentries" "int flags" "int zalloc" 470aa028ffSDag-Erling Smørgrav.Ft vm_zone_t 480aa028ffSDag-Erling Smørgrav.Fn zinit "char *name" "int size" "int nentries" "int flags" "int zalloc" 490aa028ffSDag-Erling Smørgrav.Ft void * 500aa028ffSDag-Erling Smørgrav.Fn zalloc "vm_zone_t z" 510aa028ffSDag-Erling Smørgrav.Ft void 520aa028ffSDag-Erling Smørgrav.Fn zfree "vm_zone_t z" "void *item" 535ca0c84eSThomas Moestl.Ft void 545ca0c84eSThomas Moestl.Fn zdestroy "vm_zone_t z" 550aa028ffSDag-Erling Smørgrav.Sh DESCRIPTION 560aa028ffSDag-Erling SmørgravThe zone allocator provides an efficient interface for managing 570aa028ffSDag-Erling Smørgravdynamically-sized collections of items of similar size. 580aa028ffSDag-Erling SmørgravThe zone allocator can work with preallocated zones as well as with 590aa028ffSDag-Erling Smørgravruntime-allocated ones, and is therefore available much earlier in the 600aa028ffSDag-Erling Smørgravboot process than other memory management routines. 610aa028ffSDag-Erling Smørgrav.Pp 620aa028ffSDag-Erling SmørgravA zone is an extensible collection of items of identical size. 630aa028ffSDag-Erling SmørgravThe zone allocator keeps track of which items are in use and which 640aa028ffSDag-Erling Smørgravaren't, and provides functions for allocating items from the zone and 650aa028ffSDag-Erling Smørgravfor releasing them back (which makes them available for later use). 660aa028ffSDag-Erling Smørgrav.Pp 6790d83886SJulian ElischerThe zone allocator stores state information inside the items proper 6890d83886SJulian Elischerwhile they are not allocated, 6990d83886SJulian Elischerso structures that will be managed by the zone allocator 7090d83886SJulian Elischerand wish to use the type stable property of zones by leaving some fields 7190d83886SJulian Elischerpre-filled between allocations, must reserve 720aa028ffSDag-Erling Smørgravtwo pointers at the very beginning for internal use by the zone 730aa028ffSDag-Erling Smørgravallocator, as follows: 740aa028ffSDag-Erling Smørgrav.Bd -literal 750aa028ffSDag-Erling Smørgravstruct my_item { 760aa028ffSDag-Erling Smørgrav struct my_item *z_rsvd1; 770aa028ffSDag-Erling Smørgrav struct my_item *z_rsvd2; 780aa028ffSDag-Erling Smørgrav /* rest of structure */ 790aa028ffSDag-Erling Smørgrav}; 800aa028ffSDag-Erling Smørgrav.Ed 810aa028ffSDag-Erling Smørgrav.Pp 8290d83886SJulian ElischerAlternatively they should assume those entries corrupted 8390d83886SJulian Elischerafter each allocation. After the first allocation of an item, 8490d83886SJulian Elischerit will have been cleared to zeroes, however subsequent allocations 8590d83886SJulian Elischerwill retain the contents as of the last free, with the exception of the 8690d83886SJulian Elischerfields mentioned above. 8790d83886SJulian Elischer.Pp 880aa028ffSDag-Erling SmørgravZones are created in one of two fashions, depending how far along the 890aa028ffSDag-Erling Smørgravboot process is. 900aa028ffSDag-Erling Smørgrav.Pp 910aa028ffSDag-Erling SmørgravIf the VM system is fully initialized, a dynamically allocated zone can 920aa028ffSDag-Erling Smørgravbe created using 930aa028ffSDag-Erling Smørgrav.Fn zinit . 940aa028ffSDag-Erling SmørgravThe 950aa028ffSDag-Erling Smørgrav.Fa name 960aa028ffSDag-Erling Smørgravargument should be a pointer to a short, descriptive name for the 970aa028ffSDag-Erling Smørgravzone; it is used for statistics and debugging purposes. 980aa028ffSDag-Erling SmørgravThe 990aa028ffSDag-Erling Smørgrav.Fa size 1000aa028ffSDag-Erling Smørgravand 1010aa028ffSDag-Erling Smørgrav.Fa nentries 1020aa028ffSDag-Erling Smørgravare the size of the items held by the zone and the initial size (in 1030aa028ffSDag-Erling Smørgravitems) of the zone, respectively. 1040aa028ffSDag-Erling SmørgravThe 1050aa028ffSDag-Erling Smørgrav.Fa flags 1060aa028ffSDag-Erling Smørgravargument should be set to 1070aa028ffSDag-Erling Smørgrav.Dv ZONE_INTERRUPT 1080aa028ffSDag-Erling Smørgravif there is a chance that items may be allocated from the zone in 1090aa028ffSDag-Erling Smørgravinterrupt context; note that in this case, the zone will never grow 1100aa028ffSDag-Erling Smørgravlarger than 1110aa028ffSDag-Erling Smørgrav.Fa nentries 1120aa028ffSDag-Erling Smørgravitems. 1130aa028ffSDag-Erling SmørgravIn all other cases, 1140aa028ffSDag-Erling Smørgrav.Fa flags 1150aa028ffSDag-Erling Smørgravshould be set to 0. 1160aa028ffSDag-Erling SmørgravThe final argument, 1170aa028ffSDag-Erling Smørgrav.Fa zalloc , 1180aa028ffSDag-Erling Smørgravindicates the number of VM pages by which the zone should grow every 1190aa028ffSDag-Erling Smørgravtime it fills up. 1200aa028ffSDag-Erling Smørgrav.Pp 1210aa028ffSDag-Erling SmørgravIf the VM system is not yet fully initialized, the zone allocator 1220aa028ffSDag-Erling Smørgravcannot dynamically allocate VM pages from which to dole out items, so 1230aa028ffSDag-Erling Smørgravthe caller needs to provide a static pool of items. 1240aa028ffSDag-Erling SmørgravIn this case, the initialization is done in two stages: first, 1250aa028ffSDag-Erling Smørgrav.Fn zbootinit 1260aa028ffSDag-Erling Smørgravis called before first use of the zone; later, when the VM system is 1270aa028ffSDag-Erling Smørgravup, the initialization of the zone is completed by calling 1280aa028ffSDag-Erling Smørgrav.Fn zinitna . 1290aa028ffSDag-Erling Smørgrav.Pp 1300aa028ffSDag-Erling SmørgravThe first argument to 1310aa028ffSDag-Erling Smørgrav.Fn zbootinit 1320aa028ffSDag-Erling Smørgravis a pointer to a static 133f5fccbbcSDag-Erling Smørgrav.Vt "struct vm_zone" 1340aa028ffSDag-Erling Smørgravto initialize. 1350aa028ffSDag-Erling SmørgravThe second and third are the name of the zone and the size of the 1360aa028ffSDag-Erling Smørgravitems it will hold. 1370aa028ffSDag-Erling SmørgravThe fourth argument is a pointer to a static array of items from which 1380aa028ffSDag-Erling Smørgravthe zone allocator will draw until the zone is fully initialized. 1390aa028ffSDag-Erling SmørgravThe 1400aa028ffSDag-Erling Smørgrav.Fa nitems 1410aa028ffSDag-Erling Smørgravargument is the number of items in the array. 1420aa028ffSDag-Erling Smørgrav.Pp 1430aa028ffSDag-Erling SmørgravThe arguments to 1440aa028ffSDag-Erling Smørgrav.Fa zinitna 1450aa028ffSDag-Erling Smørgravare the same as for 1460aa028ffSDag-Erling Smørgrav.Fa zinit , 1470aa028ffSDag-Erling Smørgravwith the addition of a pointer to the zone to initialize, and a 1480aa028ffSDag-Erling Smørgravpointer to a 149f5fccbbcSDag-Erling Smørgrav.Vt "struct vm_object" 1500aa028ffSDag-Erling Smørgravfrom which to allocate pages in the 1510aa028ffSDag-Erling Smørgrav.Dv ZONE_INTERRUPT 1520aa028ffSDag-Erling Smørgravcase. 1530aa028ffSDag-Erling Smørgrav.Pp 1540aa028ffSDag-Erling SmørgravTo allocate an item from a zone, simply call 1550aa028ffSDag-Erling Smørgrav.Fn zalloc 1560aa028ffSDag-Erling Smørgravwith a pointer to that zone; it will return a pointer to an item, or 1570aa028ffSDag-Erling Smørgrav.Dv NULL 1580aa028ffSDag-Erling Smørgravin the rare case where all items in the zone are in use and the 1590aa028ffSDag-Erling Smørgravallocator is unable to grow the zone. 1600aa028ffSDag-Erling Smørgrav.Pp 1610aa028ffSDag-Erling SmørgravItems are released back to the zone from which they were allocated by 1620aa028ffSDag-Erling Smørgravcalling 1630aa028ffSDag-Erling Smørgrav.Fn zfree 1640aa028ffSDag-Erling Smørgravwith a pointer to the zone and a pointer to the item. 1655ca0c84eSThomas Moestl.Pp 1665ca0c84eSThomas MoestlZones created with 1675ca0c84eSThomas Moestl.Fn zinit 1685ca0c84eSThomas Moestlor 1695ca0c84eSThomas Moestl.Fn zinitna 1705ca0c84eSThomas Moestlcan be destroyed using 1715ca0c84eSThomas Moestl.Fn zdestroy , 1725ca0c84eSThomas Moestlfreeing all memory that was allocated for the zone. 1735ca0c84eSThomas MoestlAll items allocated from the zone with 1745ca0c84eSThomas Moestl.Fn zalloc 1755ca0c84eSThomas Moestlmust have been freed with 1765ca0c84eSThomas Moestl.Fn zfree 1775ca0c84eSThomas Moestlbefore. 1780aa028ffSDag-Erling Smørgrav.Sh RETURN VALUES 1790aa028ffSDag-Erling SmørgravThe 1800aa028ffSDag-Erling Smørgrav.Fn zinitna 1810aa028ffSDag-Erling Smørgravfunction returns 1 on success and 0 on failure; the only failure case 1820aa028ffSDag-Erling Smørgravis inability to preallocate address space for an interrupt-safe zone. 1830aa028ffSDag-Erling Smørgrav.Pp 1840aa028ffSDag-Erling SmørgravThe 1850aa028ffSDag-Erling Smørgrav.Fn zinit 1860aa028ffSDag-Erling Smørgravfunction returns a pointer to a fully initialized 187f5fccbbcSDag-Erling Smørgrav.Vt "struct vm_zone" , 1880aa028ffSDag-Erling Smørgravor 1890aa028ffSDag-Erling Smørgrav.Dv NULL 1900aa028ffSDag-Erling Smørgravif it was unable to 1910aa028ffSDag-Erling Smørgrav.Fn malloc 1920aa028ffSDag-Erling Smørgrava 193f5fccbbcSDag-Erling Smørgrav.Vt "struct vm_zone" 1940aa028ffSDag-Erling Smørgravor the 1950aa028ffSDag-Erling Smørgrav.Dv ZONE_INTERRUPT 1960aa028ffSDag-Erling Smørgravflag was specified and 1970aa028ffSDag-Erling Smørgrav.Fn zinitna 1980aa028ffSDag-Erling Smørgravfailed to preallocate address space. 1990aa028ffSDag-Erling Smørgrav.Pp 2000aa028ffSDag-Erling SmørgravThe 2010aa028ffSDag-Erling Smørgrav.Fn zalloc 2020aa028ffSDag-Erling Smørgravfunction returns a pointer to an item, or 2030aa028ffSDag-Erling Smørgrav.Dv NULL 2040aa028ffSDag-Erling Smørgravif the zone ran out of unused items and the allocator was unable to 2050aa028ffSDag-Erling Smørgravenlarge it. 2060aa028ffSDag-Erling Smørgrav.Sh SEE ALSO 2070aa028ffSDag-Erling Smørgrav.Xr malloc 9 2080aa028ffSDag-Erling Smørgrav.Sh HISTORY 2090aa028ffSDag-Erling SmørgravThe zone allocator first appeared in 2100aa028ffSDag-Erling Smørgrav.Fx 3.0 . 2110aa028ffSDag-Erling Smørgrav.Sh AUTHORS 2120aa028ffSDag-Erling Smørgrav.An -nosplit 2130aa028ffSDag-Erling SmørgravThe zone allocator was written by 2140aa028ffSDag-Erling Smørgrav.An John S. Dyson . 2150aa028ffSDag-Erling Smørgrav.Pp 2160aa028ffSDag-Erling SmørgravThis manual page was written by 2170aa028ffSDag-Erling Smørgrav.An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org . 218