xref: /dragonfly/share/man/man9/zone.9 (revision 16777b6b) 
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.2 2003/06/17 04:37:01 dillon 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.Nm zalloci ,
39.Nm zfreei ,
40.Nd zone allocator
41.Sh SYNOPSIS
42.In sys/param.h
43.In sys/queue.h
44.In vm/vm_zone.h
45.Ft void
46.Fn zbootinit "vm_zone_t z" "char *name" "int size" "void *item" "int nitems"
47.Ft int
48.Fn zinitna "vm_zone_t z" "struct vm_object *obj" "char *name" "int size" "int nentries" "int flags" "int zalloc"
49.Ft vm_zone_t
50.Fn zinit "char *name" "int size" "int nentries" "int flags" "int zalloc"
51.Ft void *
52.Fn zalloc "vm_zone_t z"
53.Ft void
54.Fn zfree "vm_zone_t z" "void *item"
55.Ft void *
56.Fn zalloci "vm_zone_t z"
57.Ft void
58.Fn zfreei "vm_zone_t z" "void *item"
59.Sh DESCRIPTION
60The zone allocator provides an efficient interface for managing
61dynamically-sized collections of items of similar size.
62The zone allocator can work with preallocated zones as well as with
63runtime-allocated ones, and is therefore available much earlier in the
64boot process than other memory management routines.
65.Pp
66A zone is an extensible collection of items of identical size.
67The zone allocator keeps track of which items are in use and which
68are not, and provides functions for allocating items from the zone and
69for releasing them back (which makes them available for later use).
70.Pp
71The zone allocator stores state information inside the items proper
72while they are not allocated,
73so structures that will be managed by the zone allocator
74and wish to use the type stable property of zones by leaving some fields
75pre-filled between allocations, must reserve
76two pointers at the very beginning for internal use by the zone
77allocator, as follows:
78.Bd -literal
79struct my_item {
80        struct my_item  *z_rsvd1;
81        struct my_item  *z_rsvd2;
82        /* rest of structure */
83};
84.Ed
85.Pp
86Alternatively they should assume those entries corrupted
87after each allocation.
88After the first allocation of an item,
89it will have been cleared to zeroes, however subsequent allocations
90will retain the contents as of the last free, with the exception of the
91fields mentioned above.
92.Pp
93Zones are created in one of two fashions, depending how far along the
94boot process is.
95.Pp
96If the VM system is fully initialized, a dynamically allocated zone can
97be created using
98.Fn zinit .
99The
100.Fa name
101argument should be a pointer to a short, descriptive name for the
102zone; it is used for statistics and debugging purposes.
103The
104.Fa size
105and
106.Fa nentries
107are the size of the items held by the zone and the initial size (in
108items) of the zone, respectively.
109The
110.Fa flags
111argument should be set to
112.Dv ZONE_INTERRUPT
113if there is a chance that items may be allocated from the zone in
114interrupt context; note that in this case, the zone will never grow
115larger than
116.Fa nentries
117items.
118In all other cases,
119.Fa flags
120should be set to 0.
121The final argument,
122.Fa zalloc ,
123indicates the number of VM pages by which the zone should grow every
124time it fills up.
125.Pp
126If the VM system is not yet fully initialized, the zone allocator
127cannot dynamically allocate VM pages from which to dole out items, so
128the caller needs to provide a static pool of items.
129In this case, the initialization is done in two stages: first,
130.Fn zbootinit
131is called before first use of the zone; later, when the VM system is
132up, the initialization of the zone is completed by calling
133.Fn zinitna .
134.Pp
135The first argument to
136.Fn zbootinit
137is a pointer to a static
138.Vt "struct vm_zone"
139to initialize.
140The second and third are the name of the zone and the size of the
141items it will hold.
142The fourth argument is a pointer to a static array of items from which
143the zone allocator will draw until the zone is fully initialized.
144The
145.Fa nitems
146argument is the number of items in the array.
147.Pp
148The arguments to
149.Fa zinitna
150are the same as for
151.Fa zinit ,
152with the addition of a pointer to the zone to initialize, and a
153pointer to a
154.Vt "struct vm_object"
155from which to allocate pages in the
156.Dv ZONE_INTERRUPT
157case.
158.Pp
159To allocate an item from a zone, simply call
160.Fn zalloc
161with a pointer to that zone; it will return a pointer to an item, or
162.Dv NULL
163in the rare case where all items in the zone are in use and the
164allocator is unable to grow the zone.
165Note that
166.Fn zalloc
167is not interrupt safe.
168For an interrupt safe allocation use
169.Fn zalloci ,
170which has the same semantics as
171.Fn zalloc .
172.Pp
173Items are released back to the zone from which they were allocated by
174calling
175.Fn zfree
176with a pointer to the zone and a pointer to the item.
177Use the corresponding
178.Fn zfreei
179function if the allocation was done using
180.Fn zalloci .
181.Sh RETURN VALUES
182The
183.Fn zinitna
184function returns 1 on success and 0 on failure; the only failure case
185is inability to preallocate address space for an interrupt-safe zone.
186.Pp
187The
188.Fn zinit
189function returns a pointer to a fully initialized
190.Vt "struct vm_zone" ,
191or
192.Dv NULL
193if it was unable to
194.Fn malloc
195a
196.Vt "struct vm_zone"
197or the
198.Dv ZONE_INTERRUPT
199flag was specified and
200.Fn zinitna
201failed to preallocate address space.
202.Pp
203The
204.Fn zalloc
205function returns a pointer to an item, or
206.Dv NULL
207if the zone ran out of unused items and the allocator was unable to
208enlarge it.
209.Sh SEE ALSO
210.Xr malloc 9
211.Sh HISTORY
212The zone allocator first appeared in
213.Fx 3.0 .
214.Sh AUTHORS
215.An -nosplit
216The zone allocator was written by
217.An John S. Dyson .
218.Pp
219This manual page was written by
220.An Dag-Erling Co\(:idan Sm\(/orgrav Aq des@FreeBSD.org .
221