xref: /freebsd/share/man/man9/vmem.9 (revision e0c4386e7e71d93b0edc0c8fa156263fc4a8b0b6)
1.\"	$NetBSD: vmem.9,v 1.15 2013/01/29 22:02:17 wiz Exp $
2.\"
3.\" Copyright (c)2006 YAMAMOTO Takashi,
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25.\" SUCH DAMAGE.
26.\"
27.\" ------------------------------------------------------------
28.Dd May 17, 2019
29.Dt VMEM 9
30.Os
31.\" ------------------------------------------------------------
32.Sh NAME
33.Nm vmem
34.Nd general purpose resource allocator
35.\" ------------------------------------------------------------
36.Sh SYNOPSIS
37.In sys/vmem.h
38.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
39.Ft vmem_t *
40.Fn vmem_create \
41"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \
42"vmem_size_t qcache_max" "int flags"
43.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
44.Ft int
45.Fn vmem_add \
46"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "int flags"
47.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
48.Ft int
49.Fn vmem_xalloc \
50"vmem_t *vm" "const vmem_size_t size" "vmem_size_t align" \
51"const vmem_size_t phase" "const vmem_size_t nocross" \
52"const vmem_addr_t minaddr" "const vmem_addr_t maxaddr" "int flags" \
53"vmem_addr_t *addrp"
54.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
55.Ft void
56.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size"
57.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
58.Ft int
59.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "int flags" "vmem_addr_t *addrp"
60.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
61.Ft void
62.Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size"
63.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
64.Ft void
65.Fn vmem_destroy "vmem_t *vm"
66.\" ------------------------------------------------------------
67.Sh DESCRIPTION
68The
69.Nm
70is a general purpose resource allocator.
71Despite its name, it can be used for arbitrary resources
72other than virtual memory.
73.Pp
74.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
75.Fn vmem_create
76creates a new vmem arena.
77.Bl -tag -width qcache_max
78.It Fa name
79The string to describe the vmem.
80.It Fa base
81The start address of the initial span.
82Pass
83.Dv 0
84if no initial span is required.
85.It Fa size
86The size of the initial span.
87Pass
88.Dv 0
89if no initial span is required.
90.It Fa quantum
91The smallest unit of allocation.
92.It Fa qcache_max
93The largest size of allocations which can be served by quantum cache.
94It is merely a hint and can be ignored.
95.It Fa flags
96.Xr malloc 9
97wait flag.
98.El
99.Pp
100.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
101.Fn vmem_add
102adds a span of size
103.Fa size
104starting at
105.Fa addr
106to the arena.
107Returns
1080
109on success,
110.Dv ENOMEM
111on failure.
112.Fa flags
113is
114.Xr malloc 9
115wait flag.
116.Pp
117.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
118.Fn vmem_xalloc
119allocates a resource from the arena.
120.Bl -tag -width nocross
121.It Fa vm
122The arena which we allocate from.
123.It Fa size
124Specify the size of the allocation.
125.It Fa align
126If zero, don't care about the alignment of the allocation.
127Otherwise, request a resource segment starting at
128offset
129.Fa phase
130from an
131.Fa align
132aligned boundary.
133.It Fa phase
134See the above description of
135.Fa align .
136If
137.Fa align
138is zero,
139.Fa phase
140should be zero.
141Otherwise,
142.Fa phase
143should be smaller than
144.Fa align .
145.It Fa nocross
146Request a resource which doesn't cross
147.Fa nocross
148aligned boundary.
149.It Fa minaddr
150Specify the minimum address which can be allocated, or
151.Dv VMEM_ADDR_MIN
152if the caller does not care.
153.It Fa maxaddr
154Specify the maximum address which can be allocated, or
155.Dv VMEM_ADDR_MAX
156if the caller does not care.
157.It Fa flags
158A bitwise OR of an allocation strategy and a
159.Xr malloc 9
160wait flag.
161The allocation strategy is one of:
162.Bl -tag width indent
163.It Dv M_FIRSTFIT
164Prefer allocation performance.
165.It Dv M_BESTFIT
166Prefer space efficiency.
167.It Dv M_NEXTFIT
168Perform an address-ordered search for free addresses, beginning where
169the previous search ended.
170.El
171.It Fa addrp
172On success, if
173.Fa addrp
174is not
175.Dv NULL ,
176.Fn vmem_xalloc
177overwrites it with the start address of the allocated span.
178.El
179.Pp
180.\" ------------------------------------------------------------
181.Fn vmem_xfree
182frees resource allocated by
183.Fn vmem_xalloc
184to the arena.
185.Bl -tag -width addr
186.It Fa vm
187The arena which we free to.
188.It Fa addr
189The resource being freed.
190It must be the one returned by
191.Fn vmem_xalloc .
192Notably, it must not be the one from
193.Fn vmem_alloc .
194Otherwise, the behaviour is undefined.
195.It Fa size
196The size of the resource being freed.
197It must be the same as the
198.Fa size
199argument used for
200.Fn vmem_xalloc .
201.El
202.Pp
203.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
204.Fn vmem_alloc
205allocates a resource from the arena.
206.Bl -tag -width flags
207.It Fa vm
208The arena which we allocate from.
209.It Fa size
210Specify the size of the allocation.
211.It Fa flags
212A bitwise OR of an
213.Nm
214allocation strategy flag (see above) and a
215.Xr malloc 9
216sleep flag.
217.It Fa addrp
218On success, if
219.Fa addrp
220is not
221.Dv NULL ,
222.Fn vmem_alloc
223overwrites it with the start address of the allocated span.
224.El
225.Pp
226.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
227.Fn vmem_free
228frees resource allocated by
229.Fn vmem_alloc
230to the arena.
231.Bl -tag -width addr
232.It Fa vm
233The arena which we free to.
234.It Fa addr
235The resource being freed.
236It must be the one returned by
237.Fn vmem_alloc .
238Notably, it must not be the one from
239.Fn vmem_xalloc .
240Otherwise, the behaviour is undefined.
241.It Fa size
242The size of the resource being freed.
243It must be the same as the
244.Fa size
245argument used for
246.Fn vmem_alloc .
247.El
248.Pp
249.\" ------------------------------------------------------------
250.Fn vmem_destroy
251destroys a vmem arena.
252.Bl -tag -width vm
253.It Fa vm
254The vmem arena being destroyed.
255The caller should ensure that no one will use it anymore.
256.El
257.\" ------------------------------------------------------------
258.Sh RETURN VALUES
259.Fn vmem_create
260returns a pointer to the newly allocated vmem_t.
261Otherwise, it returns
262.Dv NULL .
263.Pp
264On success,
265.Fn vmem_xalloc
266and
267.Fn vmem_alloc
268return 0.
269Otherwise,
270.Dv ENOMEM
271is returned.
272.\" ------------------------------------------------------------
273.Sh CODE REFERENCES
274The
275.Nm
276subsystem is implemented within the file
277.Pa sys/kern/subr_vmem.c .
278.\" ------------------------------------------------------------
279.Sh SEE ALSO
280.Xr malloc 9
281.Rs
282.%A Jeff Bonwick
283.%A Jonathan Adams
284.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources"
285.%J "2001 USENIX Annual Technical Conference"
286.%D 2001
287.Re
288.\" ------------------------------------------------------------
289.Sh HISTORY
290The
291.Nm
292allocator was originally implemented in
293.Nx .
294It was introduced in
295.Fx 10.0 .
296.Sh AUTHORS
297.An -nosplit
298Original implementation of
299.Nm
300was written by
301.An "YAMAMOTO Takashi" .
302The
303.Fx
304port was made by
305.An "Jeff Roberson" .
306.Sh BUGS
307.Nm
308relies on
309.Xr malloc 9 ,
310so it cannot be used as early during system bootstrap.
311