1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
.\" $OpenBSD: km_alloc.9,v 1.8 2015/09/24 13:18:39 sobrado Exp $
.\" Copyright (c) 2011 Artur Grabowski <art@openbsd.org>
.\" All rights reserved.
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 24 2015 $
.Dt KM_ALLOC 9
.Os
.Sh NAME
.Nm km_alloc ,
.Nm km_free
.Nd kernel memory allocator
.Sh SYNOPSIS
.In sys/types.h
.In uvm/uvm_extern.h
.Ft void *
.Fn km_alloc "size_t sz" "const struct kmem_va_mode *kv" "const struct kmem_pa_mode *kp" "const struct kmem_dyn_mode *kd"
.Ft void
.Fn km_free "void *v" "size_t sz" "const struct kmem_va_mode *kv" "const struct kmem_pa_mode *kp"
.Sh DESCRIPTION
The
.Fn km_alloc
function allocates kernel virtual space optionally backed by physical pages.
The
.Fn km_free
function frees the space that was previously allocated by
.Fn km_alloc .
.Pp
The
.Fa sz
argument specifies the size of the allocation and must be a multiple
of
.Dv PAGE_SIZE .
The
.Fa kv
and
.Fa kp
arguments specify the type of virtual and physical memory to be allocated.
The
.Fa kd
argument specifies additional options for the allocation.
The arguments passed to
.Fn km_free
must match those that were used to obtain the space in
.Fn km_alloc .
.Pp
Typically a user will use certain predefined modes for memory allocation.
For virtual space the predefined modes are:
.Pp
.Bl -tag -width kv_intrsafe -offset 3n -compact
.It kv_any
Allocates the virtual space anywhere.
.It kv_intrsafe
Allocates the virtual space in the interrupt safe map.
.It kv_page
Allocates single pages.
.El
.Pp
For physical pages the predefined modes are:
.Pp
.Bl -tag -width kp_pageable -offset 3n -compact
.It kp_dirty
Maps dirty pages into the allocation.
.It kp_zero
Maps zeroed pages into the allocation.
.It kp_dma
Maps dma-accessible pages into the allocation.
.It kp_dma_zero
Maps zeroed dma-accessible pages into the allocation.
.It kp_pageable
Pages will be demand paged.
.It kp_none
Leaves the allocation unmapped.
.El
.Pp
The other parameters for allocation are:
.Pp
.Bl -tag -width kd_trylock -offset 3n -compact
.It kd_waitok
Sleeping for physical pages is allowed.
.It kd_nowait
Sleeping is not allowed.
.It kd_trylock
Fail if the allocator cannot obtain locks without waiting.
.El
.Pp
In case the predefined allocation modes are not sufficient, a custom allocation
mode can be created.
The structure controlling the virtual space allocation is:
.Bd -literal
struct kmem_va_mode {
struct vm_map **kv_map;
vsize_t kv_align;
int kv_wait;
int kv_singlepage;
};
.Ed
.Bl -tag -width kv_singlepage
.It kv_map
A pointer to the pointer to the uvm_map the space will be allocated from.
.It kv_align
Alignment constraint of the allocated space.
.It kv_wait
A flag indicating whether the allocator should wait for space to be freed if
the allocation cannot be satisfied.
.It kv_singlepage
A flag indicating if the allocations will always be for single pages.
.El
.Bd -literal
struct kmem_pa_mode {
struct uvm_constraint_range *kp_constraint;
struct uvm_object **kp_object;
paddr_t kp_align;
paddr_t kp_boundary;
int kp_nomem;
int kp_maxseg;
int kp_zero;
int kp_pageable;
};
.Ed
.Bl -tag -width kp_constraint
.It kp_constraint
A pointer to physical allocation constraints.
.It kp_object
A pointer to a pointer to a uvm_object if the pages should be backed by a
kernel object.
.It kp_align
Physical alignment of the first page in the allocation.
.It kp_boundary
Boundary that the physical addresses can't cross if the allocation is
contiguous.
.It kp_nomem
A flag that specifies that the allocation should not be backed by physical
pages.
.It kp_maxseg
Maximal amount of contiguous physical segments in the allocation.
.It kp_zero
A flag that specifies if the returned memory should be zeroed.
.It kp_pageable
A flag that specifies if the returned memory should be demand paged from the
backing object instead of being allocated up front.
.El
.Bd -literal
struct kmem_dyn_mode {
int kd_waitok;
int kd_trylock;
voff_t kd_prefer;
int *kd_slowdown;
};
.Ed
.Bl -tag -width kd_slowdown
.It kd_waitok
A flag that specifies if the allocator may sleep waiting for memory.
.It kd_trylock
A flag that specifies if the allocator should fail if it can't immediately
obtain a lock.
.It kd_prefer
An offset given to PMAP_PREFER to virtually align the allocated space.
.It kd_slowdown
A pointer to an integer that will be set to 1 if the internal single page
allocator needs the caller to back off to allow the allocator to catch up.
.El
.Sh RETURN VALUES
.Fn km_alloc
returns a kernel virtual address or
.Dv NULL
if the allocation cannot be satisfied.
.Sh SEE ALSO
.Xr malloc 9 ,
.Xr uvm 9
|
