xref: /freebsd/share/man/man9/vmem.9 (revision 4f4b548b1d21ae16955b09f9b717524167a7d97e) 
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.\" $FreeBSD$
28.\"
29.\" ------------------------------------------------------------
30.Dd May 17, 2019
31.Dt VMEM 9
32.Os
33.\" ------------------------------------------------------------
34.Sh NAME
35.Nm vmem
36.Nd general purpose resource allocator
37.\" ------------------------------------------------------------
38.Sh SYNOPSIS
39.In sys/vmem.h
40.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
41.Ft vmem_t *
42.Fn vmem_create \
43"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \
44"vmem_size_t qcache_max" "int flags"
45.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
46.Ft int
47.Fn vmem_add \
48"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "int flags"
49.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
50.Ft int
51.Fn vmem_xalloc \
52"vmem_t *vm" "const vmem_size_t size" "vmem_size_t align" \
53"const vmem_size_t phase" "const vmem_size_t nocross" \
54"const vmem_addr_t minaddr" "const vmem_addr_t maxaddr" "int flags" \
55"vmem_addr_t *addrp"
56.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
57.Ft void
58.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size"
59.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
60.Ft int
61.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "int flags" "vmem_addr_t *addrp"
62.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
63.Ft void
64.Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size"
65.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
66.Ft void
67.Fn vmem_destroy "vmem_t *vm"
68.\" ------------------------------------------------------------
69.Sh DESCRIPTION
70The
71.Nm
72is a general purpose resource allocator.
73Despite its name, it can be used for arbitrary resources
74other than virtual memory.
75.Pp
76.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
77.Fn vmem_create
78creates a new vmem arena.
79.Bl -tag -width qcache_max
80.It Fa name
81The string to describe the vmem.
82.It Fa base
83The start address of the initial span.
84Pass
85.Dv 0
86if no initial span is required.
87.It Fa size
88The size of the initial span.
89Pass
90.Dv 0
91if no initial span is required.
92.It Fa quantum
93The smallest unit of allocation.
94.It Fa qcache_max
95The largest size of allocations which can be served by quantum cache.
96It is merely a hint and can be ignored.
97.It Fa flags
98.Xr malloc 9
99wait flag.
100.El
101.Pp
102.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
103.Fn vmem_add
104adds a span of size
105.Fa size
106starting at
107.Fa addr
108to the arena.
109Returns
1100
111on success,
112.Dv ENOMEM
113on failure.
114.Fa flags
115is
116.Xr malloc 9
117wait flag.
118.Pp
119.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
120.Fn vmem_xalloc
121allocates a resource from the arena.
122.Bl -tag -width nocross
123.It Fa vm
124The arena which we allocate from.
125.It Fa size
126Specify the size of the allocation.
127.It Fa align
128If zero, don't care about the alignment of the allocation.
129Otherwise, request a resource segment starting at
130offset
131.Fa phase
132from an
133.Fa align
134aligned boundary.
135.It Fa phase
136See the above description of
137.Fa align .
138If
139.Fa align
140is zero,
141.Fa phase
142should be zero.
143Otherwise,
144.Fa phase
145should be smaller than
146.Fa align .
147.It Fa nocross
148Request a resource which doesn't cross
149.Fa nocross
150aligned boundary.
151.It Fa minaddr
152Specify the minimum address which can be allocated, or
153.Dv VMEM_ADDR_MIN
154if the caller does not care.
155.It Fa maxaddr
156Specify the maximum address which can be allocated, or
157.Dv VMEM_ADDR_MAX
158if the caller does not care.
159.It Fa flags
160A bitwise OR of an allocation strategy and a
161.Xr malloc 9
162wait flag.
163The allocation strategy is one of:
164.Bl -tag width indent
165.It Dv M_FIRSTFIT
166Prefer allocation performance.
167.It Dv M_BESTFIT
168Prefer space efficiency.
169.It Dv M_NEXTFIT
170Perform an address-ordered search for free addresses, beginning where
171the previous search ended.
172.El
173.It Fa addrp
174On success, if
175.Fa addrp
176is not
177.Dv NULL ,
178.Fn vmem_xalloc
179overwrites it with the start address of the allocated span.
180.El
181.Pp
182.\" ------------------------------------------------------------
183.Fn vmem_xfree
184frees resource allocated by
185.Fn vmem_xalloc
186to the arena.
187.Bl -tag -width addr
188.It Fa vm
189The arena which we free to.
190.It Fa addr
191The resource being freed.
192It must be the one returned by
193.Fn vmem_xalloc .
194Notably, it must not be the one from
195.Fn vmem_alloc .
196Otherwise, the behaviour is undefined.
197.It Fa size
198The size of the resource being freed.
199It must be the same as the
200.Fa size
201argument used for
202.Fn vmem_xalloc .
203.El
204.Pp
205.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
206.Fn vmem_alloc
207allocates a resource from the arena.
208.Bl -tag -width flags
209.It Fa vm
210The arena which we allocate from.
211.It Fa size
212Specify the size of the allocation.
213.It Fa flags
214A bitwise OR of an
215.Nm
216allocation strategy flag (see above) and a
217.Xr malloc 9
218sleep flag.
219.It Fa addrp
220On success, if
221.Fa addrp
222is not
223.Dv NULL ,
224.Fn vmem_alloc
225overwrites it with the start address of the allocated span.
226.El
227.Pp
228.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
229.Fn vmem_free
230frees resource allocated by
231.Fn vmem_alloc
232to the arena.
233.Bl -tag -width addr
234.It Fa vm
235The arena which we free to.
236.It Fa addr
237The resource being freed.
238It must be the one returned by
239.Fn vmem_alloc .
240Notably, it must not be the one from
241.Fn vmem_xalloc .
242Otherwise, the behaviour is undefined.
243.It Fa size
244The size of the resource being freed.
245It must be the same as the
246.Fa size
247argument used for
248.Fn vmem_alloc .
249.El
250.Pp
251.\" ------------------------------------------------------------
252.Fn vmem_destroy
253destroys a vmem arena.
254.Bl -tag -width vm
255.It Fa vm
256The vmem arena being destroyed.
257The caller should ensure that no one will use it anymore.
258.El
259.\" ------------------------------------------------------------
260.Sh RETURN VALUES
261.Fn vmem_create
262returns a pointer to the newly allocated vmem_t.
263Otherwise, it returns
264.Dv NULL .
265.Pp
266On success,
267.Fn vmem_xalloc
268and
269.Fn vmem_alloc
270return 0.
271Otherwise,
272.Dv ENOMEM
273is returned.
274.\" ------------------------------------------------------------
275.Sh CODE REFERENCES
276The
277.Nm
278subsystem is implemented within the file
279.Pa sys/kern/subr_vmem.c .
280.\" ------------------------------------------------------------
281.Sh SEE ALSO
282.Xr malloc 9
283.Rs
284.%A Jeff Bonwick
285.%A Jonathan Adams
286.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources"
287.%J "2001 USENIX Annual Technical Conference"
288.%D 2001
289.Re
290.\" ------------------------------------------------------------
291.Sh HISTORY
292The
293.Nm
294allocator was originally implemented in
295.Nx .
296It was introduced in
297.Fx 10.0 .
298.Sh AUTHORS
299.An -nosplit
300Original implementation of
301.Nm
302was written by
303.An "YAMAMOTO Takashi" .
304The
305.Fx
306port was made by
307.An "Jeff Roberson" .
308.Sh BUGS
309.Nm
310relies on
311.Xr malloc 9 ,
312so it cannot be used as early during system bootstrap.
313