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