Merge commit '9276b3991ba20d5a5660887ba81b0bc7bed25a0c'
[unleashed.git] / share / man / man9f / vmem_alloc.9f
blob07a65b3aaba0a3376964a6b65e7509ba92ed0905
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source.  A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright 2017, Richard Lowe.
13 .\"
14 .Dd Jan 18, 2017
15 .Dt VMEM_ALLOC 9F
16 .Os
17 .Sh NAME
18 .Nm vmem_alloc ,
19 .Nm vmem_xalloc ,
20 .Nm vmem_free ,
21 .Nm vmem_xfree
22 .Nd allocate and free segments from a vmem arena
23 .Sh SYNOPSIS
24 .In sys/vmem.h
25 .Ft void *
26 .Fo vmem_alloc
27 .Fa "vmem_t *vmp"
28 .Fa "size_t size"
29 .Fa "int vmflag"
30 .Fc
31 .Ft void *
32 .Fo vmem_xalloc
33 .Fa "vmem_t *vmp"
34 .Fa "size_t size"
35 .Fa "size_t align_arg"
36 .Fa "size_t phase"
37 .Fa "size_t nocross"
38 .Fa "void *minaddr"
39 .Fa "void *maxaddr"
40 .Fa "int vmflag"
41 .Fc
42 .Ft void
43 .Fo vmem_free
44 .Fa "vmem_t *vmp"
45 .Fa "void *vaddr"
46 .Fa "size_t size"
47 .Fc
48 .Ft void
49 .Fo vmem_xfree
50 .Fa "vmem_t *vmp"
51 .Fa "void *vaddr"
52 .Fa "size_t size"
53 .Fc
54 .Sh INTERFACE LEVEL
55 illumos DDI specific
56 .Sh PARAMETERS
57 .Bl -tag -width Ds
58 .It Fa vmp
59 The vmem arena from which to allocate or free.
60 .It Fa size
61 The size of the segment to allocate or free.
62 .It Fa vmflag
63 A bitmask of flags controlling the behaviour of the allocation.
64 There are two meaningful groups of flags.
65 .Dv VM_SLEEP
67 .Dv VM_NOSLEEP
68 must be specified, and indicate whether the allocation may block.
70 .Dv VM_SLEEP
71 allocation can never fail but may block indefinitely.
72 .Pp
73 The allocation policy may be specified by one of the following flags:
74 .Bl -tag -width Ds
75 .It Dv VM_BESTFIT
76 Take the segment from the smallest free segment that could satisfy this
77 allocation.
78 .It Dv VM_FIRSTFIT
79 Take the segment from the first free segment found that could satisfy this
80 allocation.
81 .It Dv VM_NEXTFIT
82 Take the segment from the segment after the one previously allocated.
83 This
84 provides sequential behaviour useful when allocating identifiers from a
85 .Dv VMC_IDENTIFIER
86 arena.
87 .It Dv VM_ENDALLOC
88 May be specified in combination with
89 .Dv VM_BESTFIT ,
90 .Dv VM_FIRSTFIT
91 or the default policy to indicate that the higher addresses should be
92 preferred.
93 .El
94 .Pp
95 The default (unnamed) allocation policy is
96 .Dq "instant fit" ,
97 an approximation of
98 .Dv VM_BESTFIT
99 in guaranteed constant time.
100 .It Fa align_arg
101 The minimum alignment of the allocation.
102 If 0, the allocated segment will be aligned as the arena's quantum.
103 .It Fa phase
104 The allocated segment must be
105 .Fa phase
106 bytes from the alignment boundary.
107 .It Fa nocross
108 The allocated segment may not straddle a
109 .Fa nocross
110 alignment boundary.
111 .It Fa minaddr
112 The minimum address at which the segment may be allocated.
113 .It Fa maxaddr
114 The maximum address which may be included in the segment.
115 .It Fa vaddr
116 The address of the segment which
117 .Fn vmem_free
119 .Fn vmem_xfree
120 should free.
122 .Sh DESCRIPTION
124 .Fn vmem_alloc
126 .Fn vmem_xalloc
127 functions allocate a segment of
128 .Fa size
129 length from the vmem arena
130 .Fa vmp .
133 .Fa vmflag
134 argument controls the behaviour of the allocation, as described in
135 .Sx PARAMETERS .
137 For allocations with complex requirements, such as those used for DMA
138 .Fn vmem_xalloc
139 takes additional arguments allowing those requirements to be expressed.
141 Segments allocated with
142 .Fn vmem_xalloc
143 must always be freed with
144 .Fn vmem_xfree ,
145 since these allocations are uncached.
146 .Sh CONTEXT
147 This function can be called from either user or kernel context.
148 If the
149 .Dv VM_NOSLEEP
150 flag is specified, it may also be called from interrupt context.
151 .Sh RETURN VALUES
152 Upon successful completion the
153 .Fn vmem_alloc
155 .Fn vmem_xalloc
156 functions return a pointer to the beginning of the allocated segment.
157 In the case of a
158 .Dv VMC_IDENTIFIER
159 arena, the address of this pointer is the meaningful component, not the value
160 to which it points.
162 On failure,
163 .Dv NULL
164 is returned.
165 When the
166 .Dv VM_SLEEP
167 flag is specified, these functions can never fail (but may block forever).
168 .Sh SEE ALSO
169 .Xr vmem 9 ,
170 .Xr vmem_contains 9F ,
171 .Xr vmem_create 9F