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
66 or
67 .Dv VM_NOSLEEP
68 must be specified, and indicate whether the allocation may block. A
69 .Dv VM_SLEEP
70 allocation can never fail but may block indefinitely.
71 .Pp
72 The allocation policy may be specified by one of the following flags:
73 .Bl -tag -width Ds
74 .It Dv VM_BESTFIT
75 Take the segment from the smallest free segment that could satisfy this allocation
76 .It Dv VM_FIRSTFIT
77 Take the segment from the first free segment found that could satisfy this
78 allocation.
79 .It Dv VM_NEXTFIT
80 Take the segment from the segment after the one previously allocated. This
81 provides sequential behaviour useful when allocating identifiers from a
82 .Dv VMC_IDENTIFIER
83 arena.
84 .It Dv VM_ENDALLOC
85 May be specified in combination with
86 .Dv VM_BESTFIT ,
87 .Dv VM_FIRSTFIT
88 or the default policy to indicate that the higher addresses should be
89 preferred.
90 .El
91 .Pp
92 The default (un\-named) allocation policy is
93 .Dq instant fit
94 an approximation of
95 .Dv VM_BESTFIT
96 in guaranteed constant time.
97 .It Fa align_arg
98 The minimum alignment of the allocation. If
99 .Ql 0
100 the allocated segment will be aligned as the arena's quantum.
101 .It Fa phase
102 The allocated segment must be
103 .Fa phase
104 bytes from the alignment boundary.
105 .It Fa nocross
106 The allocated segment may not straddle a
107 .Fa nocross
108 alignment boundary.
109 .It Fa minaddr
110 The minimum address at which the segment may be allocated.
111 .It Fa maxaddr
112 The maximum address which may be included in the segment.
113 .It Fa vaddr
114 The address of the segment which
115 .Fn vmem_free
116 or
117 .Fn vmem_xfree
118 should free.
119 .El
120 .Sh DESCRIPTION
121 The
122 .Fn vmem_alloc
123 and
124 .Fn vmem_xalloc
125 functions allocate a segment of
126 .Fa size
127 length from the vmem arena
128 .Fa vmp .
129 .Pp
130 The
131 .Fa vmflag
132 argument controls the behaviour of the allocation. As described in
133 .Sx PARAMETERS
134 .Pp
135 For allocations with complex requirements, such as those used for DMA
136 .Fn vmem_xalloc
137 takes additional arguments allowing those requirements to be expressed.
138 .Pp
139 Segments allocated with
140 .Fn vmem_xalloc
141 must always be freed with
142 .Fn vmem_xfree ,
143 since these allocations are uncached.
144 .Sh CONTEXT
145 This function can be called from either user or kernel context.
146 If the
147 .Dv VM_NOSLEEP
148 flag is specified, it may also be called from interrupt context.
149 .Sh RETURN VALUES
150 Upon successful completion the
151 .Fn vmem_alloc
152 and
153 .Fn vmem_xalloc
154 functions return a pointer to the beginning of the allocated segment. In the
155 case of a
156 .Dv VMC_IDENTIFIER
157 arena, the address of this pointer is the meaningful component, not the value
158 to which it points.
159 .Pp
160 On failure,
161 .Dv NULL
162 is returned.
163 When the
164 .Dv VM_SLEEP
165 flag is specified, these functions can never fail (but may block forever).
166 .Sh SEE ALSO
167 .Xr vmem 9 ,
168 .Xr vmem_create 9F
|
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
66 or
67 .Dv VM_NOSLEEP
68 must be specified, and indicate whether the allocation may block. A
69 .Dv VM_SLEEP
70 allocation can never fail but may block indefinitely.
71 .Pp
72 The allocation policy may be specified by one of the following flags:
73 .Bl -tag -width Ds
74 .It Dv VM_BESTFIT
75 Take the segment from the smallest free segment that could satisfy this allocation.
76 .It Dv VM_FIRSTFIT
77 Take the segment from the first free segment found that could satisfy this
78 allocation.
79 .It Dv VM_NEXTFIT
80 Take the segment from the segment after the one previously allocated. This
81 provides sequential behaviour useful when allocating identifiers from a
82 .Dv VMC_IDENTIFIER
83 arena.
84 .It Dv VM_ENDALLOC
85 May be specified in combination with
86 .Dv VM_BESTFIT ,
87 .Dv VM_FIRSTFIT
88 or the default policy to indicate that the higher addresses should be
89 preferred.
90 .El
91 .Pp
92 The default (unnamed) allocation policy is
93 .Dq "instant fit" ,
94 an approximation of
95 .Dv VM_BESTFIT
96 in guaranteed constant time.
97 .It Fa align_arg
98 The minimum alignment of the allocation. If 0,
99 the allocated segment will be aligned as the arena's quantum.
100 .It Fa phase
101 The allocated segment must be
102 .Fa phase
103 bytes from the alignment boundary.
104 .It Fa nocross
105 The allocated segment may not straddle a
106 .Fa nocross
107 alignment boundary.
108 .It Fa minaddr
109 The minimum address at which the segment may be allocated.
110 .It Fa maxaddr
111 The maximum address which may be included in the segment.
112 .It Fa vaddr
113 The address of the segment which
114 .Fn vmem_free
115 or
116 .Fn vmem_xfree
117 should free.
118 .El
119 .Sh DESCRIPTION
120 The
121 .Fn vmem_alloc
122 and
123 .Fn vmem_xalloc
124 functions allocate a segment of
125 .Fa size
126 length from the vmem arena
127 .Fa vmp .
128 .Pp
129 The
130 .Fa vmflag
131 argument controls the behaviour of the allocation, as described in
132 .Sx PARAMETERS .
133 .Pp
134 For allocations with complex requirements, such as those used for DMA
135 .Fn vmem_xalloc
136 takes additional arguments allowing those requirements to be expressed.
137 .Pp
138 Segments allocated with
139 .Fn vmem_xalloc
140 must always be freed with
141 .Fn vmem_xfree ,
142 since these allocations are uncached.
143 .Sh CONTEXT
144 This function can be called from either user or kernel context.
145 If the
146 .Dv VM_NOSLEEP
147 flag is specified, it may also be called from interrupt context.
148 .Sh RETURN VALUES
149 Upon successful completion the
150 .Fn vmem_alloc
151 and
152 .Fn vmem_xalloc
153 functions return a pointer to the beginning of the allocated segment. In the
154 case of a
155 .Dv VMC_IDENTIFIER
156 arena, the address of this pointer is the meaningful component, not the value
157 to which it points.
158 .Pp
159 On failure,
160 .Dv NULL
161 is returned.
162 When the
163 .Dv VM_SLEEP
164 flag is specified, these functions can never fail (but may block forever).
165 .Sh SEE ALSO
166 .Xr vmem 9 ,
167 .Xr vmem_contains 9F ,
168 .Xr vmem_create 9F
|