1kmem_cache_create(9F) Kernel Functions for Drivers kmem_cache_create(9F)
2
6 kmem_cache_create, kmem_cache_alloc, kmem_cache_free,
7 kmem_cache_destroy, kmem_cache_set_move - kernel memory cache allocator
8 operations
9
11 #include <sys/types.h>
12 #include <sys/kmem.h>
13 kmem_cache_t *kmem_cache_create(char *name, size_t bufsize,
15 size_t align, int (*constructor)(void *, void *, int),
16 void (*destructor)(void *, void *), void (*reclaim)(void *),
17 void *private, void *vmp, int cflags);
18 void kmem_cache_destroy(kmem_cache_t *cp);
21 void *kmem_cache_alloc(kmem_cache_t *cp, int kmflag);
24 void kmem_cache_free(kmem_cache_t *cp, void *obj);
27 void kmem_cache_set_move(kmem_cache_t *cp, kmem_cbrc_t (*move)(void *,
30 void *, size_t *, void *));
31 [Synopsis for callback functions:]
34 int (*constructor)(void *buf, void *user_arg, int kmflags);
37 void (*destructor)(void *buf, void *user_arg);
40 kmem_cbrc_t (*move)(void *old, void *new, size_t bufsize,
43 void *user_arg);
44
47 Solaris DDI specific (Solaris DDI)
48
50 The parameters for the kmem_cache_* functions are as follows:
51 name Descriptive name of a kstat(9S) structure of class
53 kmem_cache. Names longer than 31 characters are trun‐
54 cated.
55 bufsize Size of the objects it manages.
58 align Required object alignment.
61 constructor Pointer to an object constructor function. Parameters
64 are defined below.
65 destructor Pointer to an object destructor function. Parameters are
68 defined below.
69 reclaim Drivers should pass NULL.
72 private Pass-through argument for constructor/destructor.
75 vmp Drivers should pass NULL.
78 cflags Drivers must pass 0.
81 kmflag Possible flags are:
84 KM_SLEEP Allow sleeping (blocking) until memory is
86 available.
87 KM_NOSLEEP Return NULL immediately if memory is not
90 available.
91 KM_PUSHPAGE Allow the allocation to use reserved mem‐
94 ory.
95 obj Pointer to the object allocated by kmem_cache_alloc().
99 move Pointer to an object relocation function. Parameters are
102 defined below.
103 The parameters for the callback constructor function are as follows:
107 void *buf Pointer to the object to be constructed.
109 void *user_arg The private parameter from the call to
112 kmem_cache_create(); it is typically a pointer to the
113 soft-state structure.
114 int kmflags Propagated kmflag values.
117 The parameters for the callback destructor function are as follows:
121 void *buf Pointer to the object to be deconstructed.
123 void *user_arg The private parameter from the call to
126 kmem_cache_create(); it is typically a pointer to the
127 soft-state structure.
128 The parameters for the callback move() function are as follows:
132 void *old Pointer to the object to be moved.
134 void *new Pointer to the object that serves as the copy desti‐
137 nation for the contents of the old parameter.
138 size_t bufsize Size of the object to be moved.
141 void *user_arg The private parameter from the call to
144 kmem_cache_create(); it is typically a pointer to the
145 soft-state structure.
146
149 In many cases, the cost of initializing and destroying an object
150 exceeds the cost of allocating and freeing memory for it. The functions
151 described here address this condition.
152 Object caching is a technique for dealing with objects that are:
155 o frequently allocated and freed, and
157 o have setup and initialization costs.
159 The idea is to allow the allocator and its clients to cooperate to pre‐
162 serve the invariant portion of an object's initial state, or con‐
163 structed state, between uses, so it does not have to be destroyed and
164 re-created every time the object is used. For example, an object con‐
165 taining a mutex only needs to have mutex_init() applied once, the first
166 time the object is allocated. The object can then be freed and reallo‐
167 cated many times without incurring the expense of mutex_destroy() and
168 mutex_init() each time. An object's embedded locks, condition vari‐
169 ables, reference counts, lists of other objects, and read-only data all
170 generally qualify as constructed state. The essential requirement is
171 that the client must free the object (using kmem_cache_free()) in its
172 constructed state. The allocator cannot enforce this, so programming
173 errors will lead to hard-to-find bugs.
174 A driver should call kmem_cache_create() at the time of _fini(9E) or
177 attach(9E), and call the corresponding kmem_cache_destroy() at the time
178 of _fini(9E) or detach(9E).
179 kmem_cache_create() creates a cache of objects, each of size bufsize
182 bytes, aligned on an align boundary. Drivers not requiring a specific
183 alignment can pass 0. name identifies the cache for statistics and
184 debugging. constructor and destructor convert plain memory into objects
185 and back again; constructor can fail if it needs to allocate memory but
186 cannot. private is a parameter passed to the constructor and destructor
187 callbacks to support parameterized caches (for example, a pointer to an
188 instance of the driver's soft-state structure). To facilitate debug‐
189 ging, kmem_cache_create() creates a kstat(9S) structure of class
190 kmem_cache and name name. It returns an opaque pointer to the object
191 cache.
192 kmem_cache_alloc() gets an object from the cache. The object will be in
195 its constructed state. kmflag has either KM_SLEEP or KM_NOSLEEP set,
196 indicating whether it is acceptable to wait for memory if none is cur‐
197 rently available.
198 A small pool of reserved memory is available to allow the system to
201 progress toward the goal of freeing additional memory while in a low
202 memory situation. The KM_PUSHPAGE flag enables use of this reserved
203 memory pool on an allocation. This flag can be used by drivers that
204 implement strategy(9E) on memory allocations associated with a single
205 I/O operation. The driver guarantees that the I/O operation will com‐
206 plete (or timeout) and, on completion, that the memory will be
207 returned. The KM_PUSHPAGE flag should be used only in
208 kmem_cache_alloc() calls. All allocations from a given cache should be
209 consistent in their use of the flag. A driver that adheres to these
210 restrictions can guarantee progress in a low memory situation without
211 resorting to complex private allocation and queuing schemes. If
212 KM_PUSHPAGE is specified, KM_SLEEP can also be used without causing
213 deadlock.
214 kmem_cache_free() returns an object to the cache. The object must be in
217 its constructed state.
218 kmem_cache_destroy() destroys the cache and releases all associated
221 resources. All allocated objects must have been previously freed.
222 kmem_cache_set_move() registers a function that the allocator may call
225 to move objects from sparsely allocated pages of memory so that the
226 system can reclaim pages that are tied up by the client. Since caching
227 objects of the same size and type already makes severe memory fragmen‐
228 tation unlikely, there is generally no need to register such a func‐
229 tion. The idea is to make it possible to limit worst-case fragmentation
230 in caches that exhibit a tendency to become highly fragmented. Only
231 clients that allocate a mix of long- and short-lived objects from the
232 same cache are prone to exhibit this tendency, making them candidates
233 for a move() callback.
234 The move() callback supplies the client with two addresses: the allo‐
237 cated object that the allocator wants to move and a buffer selected by
238 the allocator for the client to use as the copy destination. The new
239 parameter is an allocated, constructed object ready to receive the con‐
240 tents of the old parameter. The bufsize parameter supplies the size of
241 the object, in case a single move function handles multiple caches
242 whose objects differ only in size. Finally, the private parameter
243 passed to the constructor and destructor is also passed to the move()
244 callback.
245 Only the client knows about its own data and when it is a good time to
248 move it. The client cooperates with the allocator to return unused mem‐
249 ory to the system, and the allocator accepts this help at the client's
250 convenience. When asked to move an object, the client can respond with
251 any of the following:
252 typedef enum kmem_cbrc {
254 KMEM_CBRC_YES,
255 KMEM_CBRC_NO,
256 KMEM_CBRC_LATER,
257 KMEM_CBRC_DONT_NEED,
258 KMEM_CBRC_DONT_KNOW
259 } kmem_cbrc_t;
260 The client must not explicitly free either of the objects passed to the
265 move() callback, since the allocator wants to free them directly to the
266 slab layer (bypassing the per-CPU magazine layer). The response tells
267 the allocator which of the two object parameters to free:
268 KMEM_CBRC_YES The client moved the object; the allocator frees
270 the old parameter.
271 KMEM_CBRC_NO The client refused to move the object; the allo‐
274 cator frees the new parameter (the unused copy
275 destination).
276 KMEM_CBRC_LATER The client is using the object and cannot move
279 it now; the allocator frees the new parameter
280 (the unused copy destination). The client should
281 use KMEM_CBRC_LATER instead of KMEM_CBRC_NO if
282 the object is likely to become movable soon.
283 KMEM_CBRC_DONT_NEED The client no longer needs the object; the allo‐
286 cator frees both the old and new parameters.
287 This response is the client's opportunity to be
288 a model citizen and give back as much as it can.
289 KMEM_CBRC_DONT_KNOW The client does not know about the object
292 because:
293 a) the client has just allocated the object
295 and has not yet put it wherever it expects
296 to find known objects
297 b) the client has removed the object from
300 wherever it expects to find known objects
301 and is about to free the object
302 c) the client has freed the object
305 In all of these cases above, the allocator frees
307 the new parameter (the unused copy destination)
308 and searches for the old parameter in the maga‐
309 zine layer. If the object is found, it is
310 removed from the magazine layer and freed to the
311 slab layer so that it will no longer tie up an
312 entire page of memory.
313 Any object passed to the move() callback is guaranteed to have been
317 touched only by the allocator or by the client. Because memory patterns
318 applied by the allocator always set at least one of the two lowest
319 order bits, the bottom two bits of any pointer member (other than char
320 * or short *, which may not be 8-byte aligned on all platforms) are
321 available to the client for marking cached objects that the client is
322 about to free. This way, the client can recognize known objects in the
323 move() callback by the unmarked (valid) pointer value.
324 If the client refuses to move an object with either KMEM_CBRC_NO or
327 KMEM_CBRC_LATER, and that object later becomes movable, the client can
328 notify the allocator by calling kmem_cache_move_notify(). Alterna‐
329 tively, the client can simply wait for the allocator to call back again
330 with the same object address. Responding KMEM_CRBC_NO even once or
331 responding KMEM_CRBC_LATER too many times for the same object makes the
332 allocator less likely to call back again for that object.
333 [Synopsis for notification function:]
335 void kmem_cache_move_notify(kmem_cache_t *cp, void *obj);
338 The parameters for the notification function are as follows:
342 cp Pointer to the object cache.
344 obj Pointer to the object that has become movable since an earlier
347 refusal to move it.
348
351 Constructors can be invoked during any call to kmem_cache_alloc(), and
352 will run in that context. Similarly, destructors can be invoked during
353 any call to kmem_cache_free(), and can also be invoked during
354 kmem_cache_destroy(). Therefore, the functions that a constructor or
355 destructor invokes must be appropriate in that context. Furthermore,
356 the allocator may also call the constructor and destructor on objects
357 still under its control without client involvement.
358 kmem_cache_create() and kmem_cache_destroy() must not be called from
361 interrupt context. kmem_cache_create() can also block for available
362 memory.
363 kmem_cache_alloc() can be called from interrupt context only if the
366 KM_NOSLEEP flag is set. It can be called from user or kernel context
367 with any valid flag.
368 kmem_cache_free() can be called from user, kernel, or interrupt con‐
371 text.
372 kmem_cache_set_move() is called from the same context as
375 kmem_cache_create(), immediately after kmem_cache_create() and before
376 allocating any objects from the cache.
377 The registered move() callback is always invoked in the same global
380 callback thread dedicated for move requests, guaranteeing that no mat‐
381 ter how many clients register a move() function, the allocator never
382 tries to move more than one object at a time. Neither the allocator nor
383 the client can be assumed to know the object's whereabouts at the time
384 of the callback.
385
387 Example 1 Object Caching
388 Consider the following data structure:
391 struct foo {
394 kmutex_t foo_lock;
395 kcondvar_t foo_cv;
396 struct bar *foo_barlist;
397 int foo_refcnt;
398 };
399 Assume that a foo structure cannot be freed until there are no out‐
403 standing references to it (foo_refcnt == 0) and all of its pending bar
404 events (whatever they are) have completed (foo_barlist == NULL). The
405 life cycle of a dynamically allocated foo would be something like this:
406 foo = kmem_alloc(sizeof (struct foo), KM_SLEEP);
409 mutex_init(&foo->foo_lock, ...);
410 cv_init(&foo->foo_cv, ...);
411 foo->foo_refcnt = 0;
412 foo->foo_barlist = NULL;
413 use foo;
414 ASSERT(foo->foo_barlist == NULL);
415 ASSERT(foo->foo_refcnt == 0);
416 cv_destroy(&foo->foo_cv);
417 mutex_destroy(&foo->foo_lock);
418 kmem_free(foo);
419 Notice that between each use of a foo object we perform a sequence of
423 operations that constitutes nothing but expensive overhead. All of this
424 overhead (that is, everything other than use foo above) can be elimi‐
425 nated by object caching.
426 int
429 foo_constructor(void *buf, void *arg, int tags)
430 {
431 struct foo *foo = buf;
432 mutex_init(&foo->foo_lock, ...);
433 cv_init(&foo->foo_cv, ...);
434 foo->foo_refcnt = 0;
435 foo->foo_barlist = NULL;
436 return (0);
437 }
438 void
440 foo_destructor(void *buf, void *arg)
441 {
442 struct foo *foo = buf;
443 ASSERT(foo->foo_barlist == NULL);
444 ASSERT(foo->foo_refcnt == 0);
445 cv_destroy(&foo->foo_cv);
446 mutex_destroy(&foo->foo_lock);
447 }
448 user_arg = ddi_get_soft_state(foo_softc, instance);
450 (void) snprintf(buf, KSTAT_STRLEN, "foo%d_cache",
451 ddi_get_instance(dip));
452 foo_cache = kmem_cache_create(buf,
453 sizeof (struct foo), 0,
454 foo_constructor, foo_destructor,
455 NULL, user_arg, 0);
456 To allocate, use, and free a foo object:
460 foo = kmem_cache_alloc(foo_cache, KM_SLEEP);
463 use foo;
464 kmem_cache_free(foo_cache, foo);
465 This makes foo allocation fast, because the allocator will usually do
469 nothing more than fetch an already-constructed foo from the cache.
470 foo_constructor and foo_destructor will be invoked only to populate and
471 drain the cache, respectively.
472 Example 2 Registering a Move Callback
475 To register a move() callback:
478 object_cache = kmem_cache_create(...);
481 kmem_cache_set_move(object_cache, object_move);
482
485 If successful, the constructor function must return 0. If KM_NOSLEEP is
486 set and memory cannot be allocated without sleeping, the constructor
487 must return -1.
488 kmem_cache_create() returns a pointer to the allocated cache.
491 If successful, kmem_cache_alloc() returns a pointer to the allocated
494 object. If KM_NOSLEEP is set and memory cannot be allocated without
495 sleeping, kmem_cache_alloc() returns NULL.
496
498 See attributes(5) for descriptions of the following attributes:
499 ┌─────────────────────────────┬─────────────────────────────┐
504 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
505 ├─────────────────────────────┼─────────────────────────────┤
506 │Interface Stability │Committed │
507 └─────────────────────────────┴─────────────────────────────┘
508
510 condvar(9F), kmem_alloc(9F), mutex(9F), kstat(9S)
511 Writing Device Drivers
514 The Slab Allocator: An Object-Caching Kernel Memory Allocator, Bonwick,
517 J.; USENIX Summer 1994 Technical Conference (1994).
518 Magazines and vmem: Extending the Slab Allocator to Many CPUs and Arbi‐
521 trary Resources, Bonwick, J. and Adams, J.; USENIX 2001 Technical Con‐
522 ference (2001).
523
525 The constructor must be immediately reversible by the destructor, since
526 the allocator may call the constructor and destructor on objects still
527 under its control at any time without client involvement.
528 The constructor must respect the kmflags argument by forwarding it to
531 allocations made inside the constructor, and must not ASSERT anything
532 about the given flags.
533 The user argument forwarded to the constructor must be fully opera‐
536 tional before it is passed to kmem_cache_create().
537SunOS 5.11 24 Jun 2008 kmem_cache_create(9F)