| @@ -1,275 +1,275 @@ | | | @@ -1,275 +1,275 @@ |
1 | .\" $NetBSD: kmem.9,v 1.11 2010/12/02 12:54:13 wiz Exp $ | | 1 | .\" $NetBSD: kmem.9,v 1.12 2011/01/08 18:07:14 jym Exp $ |
2 | .\" | | 2 | .\" |
3 | .\" Copyright (c)2006 YAMAMOTO Takashi, | | 3 | .\" Copyright (c)2006 YAMAMOTO Takashi, |
4 | .\" All rights reserved. | | 4 | .\" All rights reserved. |
5 | .\" | | 5 | .\" |
6 | .\" Redistribution and use in source and binary forms, with or without | | 6 | .\" Redistribution and use in source and binary forms, with or without |
7 | .\" modification, are permitted provided that the following conditions | | 7 | .\" modification, are permitted provided that the following conditions |
8 | .\" are met: | | 8 | .\" are met: |
9 | .\" 1. Redistributions of source code must retain the above copyright | | 9 | .\" 1. Redistributions of source code must retain the above copyright |
10 | .\" notice, this list of conditions and the following disclaimer. | | 10 | .\" notice, this list of conditions and the following disclaimer. |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 11 | .\" 2. Redistributions in binary form must reproduce the above copyright |
12 | .\" notice, this list of conditions and the following disclaimer in the | | 12 | .\" notice, this list of conditions and the following disclaimer in the |
13 | .\" documentation and/or other materials provided with the distribution. | | 13 | .\" documentation and/or other materials provided with the distribution. |
14 | .\" | | 14 | .\" |
15 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | | 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 | | 16 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
17 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | | 17 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
18 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | | 18 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
19 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | | 19 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
20 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | | 20 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
21 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | | 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 | | 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 | | 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 | | 24 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
25 | .\" SUCH DAMAGE. | | 25 | .\" SUCH DAMAGE. |
26 | .\" | | 26 | .\" |
27 | .\" ------------------------------------------------------------ | | 27 | .\" ------------------------------------------------------------ |
28 | .Dd May 16, 2010 | | 28 | .Dd May 16, 2010 |
29 | .Dt KMEM 9 | | 29 | .Dt KMEM 9 |
30 | .Os | | 30 | .Os |
31 | .\" ------------------------------------------------------------ | | 31 | .\" ------------------------------------------------------------ |
32 | .Sh NAME | | 32 | .Sh NAME |
33 | .Nm kmem | | 33 | .Nm kmem |
34 | .Nd kernel wired memory allocator | | 34 | .Nd kernel wired memory allocator |
35 | .\" ------------------------------------------------------------ | | 35 | .\" ------------------------------------------------------------ |
36 | .Sh SYNOPSIS | | 36 | .Sh SYNOPSIS |
37 | .In sys/kmem.h | | 37 | .In sys/kmem.h |
38 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | | 38 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
39 | .Ft void * | | 39 | .Ft void * |
40 | .Fn kmem_alloc \ | | 40 | .Fn kmem_alloc \ |
41 | "size_t size" "km_flag_t kmflags" | | 41 | "size_t size" "km_flag_t kmflags" |
42 | .Ft void * | | 42 | .Ft void * |
43 | .Fn kmem_zalloc \ | | 43 | .Fn kmem_zalloc \ |
44 | "size_t size" "km_flag_t kmflags" | | 44 | "size_t size" "km_flag_t kmflags" |
45 | .Ft void | | 45 | .Ft void |
46 | .Fn kmem_free \ | | 46 | .Fn kmem_free \ |
47 | "void *p" "size_t size" | | 47 | "void *p" "size_t size" |
48 | .Ft char * | | 48 | .Ft char * |
49 | .Fn kmem_asprintf \ | | 49 | .Fn kmem_asprintf \ |
50 | "const char *fmt" "..." | | 50 | "const char *fmt" "..." |
51 | .\" ------------------------------------------------------------ | | 51 | .\" ------------------------------------------------------------ |
52 | .Pp | | 52 | .Pp |
53 | .Cd "options DEBUG" | | 53 | .Cd "options DEBUG" |
54 | .Sh DESCRIPTION | | 54 | .Sh DESCRIPTION |
55 | .Fn kmem_alloc | | 55 | .Fn kmem_alloc |
56 | allocates kernel wired memory. | | 56 | allocates kernel wired memory. |
57 | It takes the following arguments. | | 57 | It takes the following arguments. |
58 | .Bl -tag -width kmflags | | 58 | .Bl -tag -width kmflags |
59 | .It Fa size | | 59 | .It Fa size |
60 | Specify the size of allocation in bytes. | | 60 | Specify the size of allocation in bytes. |
61 | .It Fa kmflags | | 61 | .It Fa kmflags |
62 | Either of the following: | | 62 | Either of the following: |
63 | .Bl -tag -width KM_NOSLEEP | | 63 | .Bl -tag -width KM_NOSLEEP |
64 | .It KM_SLEEP | | 64 | .It KM_SLEEP |
65 | If the allocation cannot be satisfied immediately, sleep until enough | | 65 | If the allocation cannot be satisfied immediately, sleep until enough |
66 | memory is available. | | 66 | memory is available. |
67 | .It KM_NOSLEEP | | 67 | .It KM_NOSLEEP |
68 | Don't sleep. | | 68 | Don't sleep. |
69 | Immediately return | | 69 | Immediately return |
70 | .Dv NULL | | 70 | .Dv NULL |
71 | if there is not enough memory available. | | 71 | if there is not enough memory available. |
72 | It should only be used when failure to allocate will not have harmful, | | 72 | It should only be used when failure to allocate will not have harmful, |
73 | user-visible effects. | | 73 | user-visible effects. |
74 | .Pp | | 74 | .Pp |
75 | .Bf -symbolic | | 75 | .Bf -symbolic |
76 | Use of | | 76 | Use of |
77 | .Dv KM_NOSLEEP | | 77 | .Dv KM_NOSLEEP |
78 | is strongly discouraged as it can create transient, hard to debug failures | | 78 | is strongly discouraged as it can create transient, hard to debug failures |
79 | that occur when the system is under memory pressure. | | 79 | that occur when the system is under memory pressure. |
80 | .Ef | | 80 | .Ef |
81 | .Pp | | 81 | .Pp |
82 | In situations where it is not possible to sleep, for example because locks | | 82 | In situations where it is not possible to sleep, for example because locks |
83 | are held by the caller, the code path should be restructured to allow the | | 83 | are held by the caller, the code path should be restructured to allow the |
84 | allocation to be made in another place. | | 84 | allocation to be made in another place. |
85 | .El | | 85 | .El |
86 | .El | | 86 | .El |
87 | .Pp | | 87 | .Pp |
88 | The contents of allocated memory are uninitialized. | | 88 | The contents of allocated memory are uninitialized. |
89 | .Pp | | 89 | .Pp |
90 | Unlike Solaris, kmem_alloc(0, flags) is illegal. | | 90 | Unlike Solaris, kmem_alloc(0, flags) is illegal. |
91 | .Pp | | 91 | .Pp |
92 | .\" ------------------------------------------------------------ | | 92 | .\" ------------------------------------------------------------ |
93 | .Fn kmem_zalloc | | 93 | .Fn kmem_zalloc |
94 | is the equivalent of | | 94 | is the equivalent of |
95 | .Fn kmem_alloc , | | 95 | .Fn kmem_alloc , |
96 | except that it initializes the memory to zero. | | 96 | except that it initializes the memory to zero. |
97 | .Pp | | 97 | .Pp |
98 | .\" ------------------------------------------------------------ | | 98 | .\" ------------------------------------------------------------ |
99 | .Fn kmem_asprintf | | 99 | .Fn kmem_asprintf |
100 | functions as the well known | | 100 | functions as the well known |
101 | .Fn asprintf | | 101 | .Fn asprintf |
102 | function, but allocates memory using | | 102 | function, but allocates memory using |
103 | .Fn kmem_alloc . | | 103 | .Fn kmem_alloc . |
104 | This routine can sleep during allocation. | | 104 | This routine can sleep during allocation. |
105 | The size of the allocated area is the length of the returned character string, plus one (for the NUL terminator). | | 105 | The size of the allocated area is the length of the returned character string, plus one (for the NUL terminator). |
106 | This must be taken into consideration when freeing the returned area with | | 106 | This must be taken into consideration when freeing the returned area with |
107 | .Fn kmem_free . | | 107 | .Fn kmem_free . |
108 | .Pp | | 108 | .Pp |
109 | .\" ------------------------------------------------------------ | | 109 | .\" ------------------------------------------------------------ |
110 | .Fn kmem_free | | 110 | .Fn kmem_free |
111 | frees kernel wired memory allocated by | | 111 | frees kernel wired memory allocated by |
112 | .Fn kmem_alloc | | 112 | .Fn kmem_alloc |
113 | or | | 113 | or |
114 | .Fn kmem_zalloc | | 114 | .Fn kmem_zalloc |
115 | so that it can be used for other purposes. | | 115 | so that it can be used for other purposes. |
116 | It takes the following arguments. | | 116 | It takes the following arguments. |
117 | .Bl -tag -width kmflags | | 117 | .Bl -tag -width kmflags |
118 | .It Fa p | | 118 | .It Fa p |
119 | The pointer to the memory being freed. | | 119 | The pointer to the memory being freed. |
120 | It must be the one returned by | | 120 | It must be the one returned by |
121 | .Fn kmem_alloc | | 121 | .Fn kmem_alloc |
122 | or | | 122 | or |
123 | .Fn kmem_zalloc . | | 123 | .Fn kmem_zalloc . |
124 | .It Fa size | | 124 | .It Fa size |
125 | The size of the memory being freed, in bytes. | | 125 | The size of the memory being freed, in bytes. |
126 | It must be the same as the | | 126 | It must be the same as the |
127 | .Fa size | | 127 | .Fa size |
128 | argument used for | | 128 | argument used for |
129 | .Fn kmem_alloc | | 129 | .Fn kmem_alloc |
130 | or | | 130 | or |
131 | .Fn kmem_zalloc | | 131 | .Fn kmem_zalloc |
132 | when the memory was allocated. | | 132 | when the memory was allocated. |
133 | .El | | 133 | .El |
134 | .Pp | | 134 | .Pp |
135 | Freeing | | 135 | Freeing |
136 | .Dv NULL | | 136 | .Dv NULL |
137 | is illegal. | | 137 | is illegal. |
138 | .\" ------------------------------------------------------------ | | 138 | .\" ------------------------------------------------------------ |
139 | .Sh NOTES | | 139 | .Sh NOTES |
140 | Making | | 140 | Making |
141 | .Dv KM_SLEEP | | 141 | .Dv KM_SLEEP |
142 | allocations while holding mutexes or reader/writer locks is discouraged, as the | | 142 | allocations while holding mutexes or reader/writer locks is discouraged, as the |
143 | caller can sleep for an unbounded amount of time in order to satisfy the | | 143 | caller can sleep for an unbounded amount of time in order to satisfy the |
144 | allocation. | | 144 | allocation. |
145 | This can in turn block other threads that wish to acquire locks held by the | | 145 | This can in turn block other threads that wish to acquire locks held by the |
146 | caller. | | 146 | caller. |
147 | It should be noted that | | 147 | It should be noted that |
148 | .Fn kmem_free | | 148 | .Fn kmem_free |
149 | may also block. | | 149 | may also block. |
150 | .Pp | | 150 | .Pp |
151 | For some locks this is permissible or even unavoidable. | | 151 | For some locks this is permissible or even unavoidable. |
152 | For others, particularly locks that may be taken from soft interrupt context, | | 152 | For others, particularly locks that may be taken from soft interrupt context, |
153 | it is a serious problem. | | 153 | it is a serious problem. |
154 | As a general rule it is better not to allow this type of situation to develop. | | 154 | As a general rule it is better not to allow this type of situation to develop. |
155 | One way to circumvent the problem is to make allocations speculative and part | | 155 | One way to circumvent the problem is to make allocations speculative and part |
156 | of a retryable sequence. | | 156 | of a retryable sequence. |
157 | For example: | | 157 | For example: |
158 | .Bd -literal | | 158 | .Bd -literal |
159 | retry: | | 159 | retry: |
160 | /* speculative unlocked check */ | | 160 | /* speculative unlocked check */ |
161 | if (need to allocate) { | | 161 | if (need to allocate) { |
162 | new_item = kmem_alloc(sizeof(*new_item), KM_SLEEP); | | 162 | new_item = kmem_alloc(sizeof(*new_item), KM_SLEEP); |
163 | } else { | | 163 | } else { |
164 | new_item = NULL; | | 164 | new_item = NULL; |
165 | } | | 165 | } |
166 | mutex_enter(lock); | | 166 | mutex_enter(lock); |
167 | /* check while holding lock for true status */ | | 167 | /* check while holding lock for true status */ |
168 | if (need to allocate) { | | 168 | if (need to allocate) { |
169 | if (new_item == NULL) { | | 169 | if (new_item == NULL) { |
170 | mutex_exit(lock); | | 170 | mutex_exit(lock); |
171 | goto retry; | | 171 | goto retry; |
172 | } | | 172 | } |
173 | consume(new_item); | | 173 | consume(new_item); |
174 | new_item = NULL; | | 174 | new_item = NULL; |
175 | } | | 175 | } |
176 | mutex_exit(lock); | | 176 | mutex_exit(lock); |
177 | if (new_item != NULL) { | | 177 | if (new_item != NULL) { |
178 | /* did not use it after all */ | | 178 | /* did not use it after all */ |
179 | kmem_free(new_item, sizeof(*new_item)); | | 179 | kmem_free(new_item, sizeof(*new_item)); |
180 | } | | 180 | } |
181 | .Ed | | 181 | .Ed |
182 | .\" ------------------------------------------------------------ | | 182 | .\" ------------------------------------------------------------ |
183 | .Sh OPTIONS | | 183 | .Sh OPTIONS |
184 | Kernels compiled with the | | 184 | Kernels compiled with the |
185 | .Dv DEBUG | | 185 | .Dv DEBUG |
186 | option perform CPU intensive sanity checks on kmem operations, | | 186 | option perform CPU intensive sanity checks on kmem operations, |
187 | and include the | | 187 | and include the |
188 | .Dv kmguard | | 188 | .Dv kmguard |
189 | facility which can be enabled at runtime. | | 189 | facility which can be enabled at runtime. |
190 | .Pp | | 190 | .Pp |
191 | .Dv kmguard | | 191 | .Dv kmguard |
192 | adds additional, very high overhead runtime verification to kmem operations. | | 192 | adds additional, very high overhead runtime verification to kmem operations. |
193 | To enable it, boot the system with the | | 193 | To enable it, boot the system with the |
194 | .Fl d | | 194 | .Fl d |
195 | option, which causes the debugger to be entered early during the kernel | | 195 | option, which causes the debugger to be entered early during the kernel |
196 | boot process. | | 196 | boot process. |
197 | Issue commands such as the following: | | 197 | Issue commands such as the following: |
198 | .Bd -literal | | 198 | .Bd -literal |
199 | db\*[Gt] w kmem_guard_depth 0t30000 | | 199 | db\*[Gt] w kmem_guard_depth 0t30000 |
200 | db\*[Gt] c | | 200 | db\*[Gt] c |
201 | .Ed | | 201 | .Ed |
202 | .Pp | | 202 | .Pp |
203 | This instructs | | 203 | This instructs |
204 | .Dv kmguard | | 204 | .Dv kmguard |
205 | to queue up to 60000 (30000*2) pages of unmapped KVA to catch | | 205 | to queue up to 60000 (30000*2) pages of unmapped KVA to catch |
206 | use-after-free type errors. | | 206 | use-after-free type errors. |
207 | When | | 207 | When |
208 | .Fn kmem_free | | 208 | .Fn kmem_free |
209 | is called, memory backing a freed item is unmapped and the kernel VA | | 209 | is called, memory backing a freed item is unmapped and the kernel VA |
210 | space pushed onto a FIFO. | | 210 | space pushed onto a FIFO. |
211 | The VA space will not be reused until another 30k items have been freed. | | 211 | The VA space will not be reused until another 30k items have been freed. |
212 | Until reused the kernel will catch invalid accesses and panic with a page fault. | | 212 | Until reused the kernel will catch invalid accesses and panic with a page fault. |
213 | Limitations: | | 213 | Limitations: |
214 | .Bl -bullet | | 214 | .Bl -bullet |
215 | .It | | 215 | .It |
216 | It has a severe impact on performance. | | 216 | It has a severe impact on performance. |
217 | .It | | 217 | .It |
218 | It is best used on a 64-bit machine with lots of RAM. | | 218 | It is best used on a 64-bit machine with lots of RAM. |
219 | .It | | 219 | .It |
220 | Allocations larger than PAGE_SIZE bypass the | | 220 | Allocations larger than PAGE_SIZE bypass the |
221 | .Dv kmguard | | 221 | .Dv kmguard |
222 | facility. | | 222 | facility. |
223 | .El | | 223 | .El |
224 | .Pp | | 224 | .Pp |
225 | kmguard tries to catch the following types of bugs: | | 225 | kmguard tries to catch the following types of bugs: |
226 | .Bl -bullet | | 226 | .Bl -bullet |
227 | .It | | 227 | .It |
228 | Overflow at time of occurrence, by means of a guard page. | | 228 | Overflow at time of occurrence, by means of a guard page. |
229 | .It | | 229 | .It |
230 | Underflow at | | 230 | Underflow at |
231 | .Fn kmem_free , | | 231 | .Fn kmem_free , |
232 | by using a canary value. | | 232 | by using a canary value. |
233 | .It | | 233 | .It |
234 | Invalid pointer or size passed, at | | 234 | Invalid pointer or size passed, at |
235 | .Fn kmem_free . | | 235 | .Fn kmem_free . |
236 | .El | | 236 | .El |
237 | .Sh RETURN VALUES | | 237 | .Sh RETURN VALUES |
238 | On success, | | 238 | On success, |
239 | .Fn kmem_alloc | | 239 | .Fn kmem_alloc |
240 | and | | 240 | and |
241 | .Fn kmem_zalloc | | 241 | .Fn kmem_zalloc |
242 | return a pointer to allocated memory. | | 242 | return a pointer to allocated memory. |
243 | Otherwise, | | 243 | Otherwise, |
244 | .Dv NULL | | 244 | .Dv NULL |
245 | is returned. | | 245 | is returned. |
246 | .\" ------------------------------------------------------------ | | 246 | .\" ------------------------------------------------------------ |
247 | .Sh CODE REFERENCES | | 247 | .Sh CODE REFERENCES |
248 | The | | 248 | The |
249 | .Nm | | 249 | .Nm |
250 | subsystem is implemented within the file | | 250 | subsystem is implemented within the file |
251 | .Pa sys/kern/subr_kmem.c . | | 251 | .Pa sys/kern/subr_kmem.c . |
252 | .\" ------------------------------------------------------------ | | 252 | .\" ------------------------------------------------------------ |
253 | .Sh SEE ALSO | | 253 | .Sh SEE ALSO |
254 | .Xr intro 9 , | | 254 | .Xr intro 9 , |
255 | .Xr memoryallocators 9 , | | 255 | .Xr memoryallocators 9 , |
256 | .Xr percpu 9 , | | 256 | .Xr percpu 9 , |
257 | .Xr pool_cache 9 | | 257 | .Xr pool_cache 9 |
258 | .\" ------------------------------------------------------------ | | 258 | .\" ------------------------------------------------------------ |
259 | .Sh CAVEATS | | 259 | .Sh CAVEATS |
260 | Neither | | 260 | Neither |
261 | .Fn kmem_alloc | | 261 | .Fn kmem_alloc |
262 | nor | | 262 | nor |
263 | .Fn kmem_free | | 263 | .Fn kmem_free |
264 | can be used from interrupt context, from a soft interrupt, or from | | 264 | can be used from interrupt context, from a soft interrupt, or from |
265 | a callout. | | 265 | a callout. |
266 | Use | | 266 | Use |
267 | .Xr pool_cache 9 | | 267 | .Xr pool_cache 9 |
268 | in these situations. | | 268 | in these situations. |
269 | .\" ------------------------------------------------------------ | | 269 | .\" ------------------------------------------------------------ |
270 | .Sh SECURITY CONSIDERATION | | 270 | .Sh SECURITY CONSIDERATIONS |
271 | As the memory allocated by | | 271 | As the memory allocated by |
272 | .Fn kmem_alloc | | 272 | .Fn kmem_alloc |
273 | is uninitialized, it can contain security-sensitive data left by its | | 273 | is uninitialized, it can contain security-sensitive data left by its |
274 | previous user. | | 274 | previous user. |
275 | It is the caller's responsibility not to expose it to the world. | | 275 | It is the caller's responsibility not to expose it to the world. |