xref: /freebsd/share/man/man9/zone.9 (revision f16b3c0de48d0b845357e7cca843f645bc3117e3)
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