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