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