1kmem_cache_create(9F)    Kernel Functions for Drivers    kmem_cache_create(9F)
2
3
4

NAME

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

SYNOPSIS

11       #include <sys/types.h>
12       #include <sys/kmem.h>
13
14       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
19
20       void kmem_cache_destroy(kmem_cache_t *cp);
21
22
23       void *kmem_cache_alloc(kmem_cache_t *cp, int kmflag);
24
25
26       void kmem_cache_free(kmem_cache_t *cp, void *obj);
27
28
29       void kmem_cache_set_move(kmem_cache_t *cp, kmem_cbrc_t (*move)(void *,
30            void *, size_t *, void *));
31
32
33        [Synopsis for callback functions:]
34
35
36       int (*constructor)(void *buf, void *user_arg, int kmflags);
37
38
39       void (*destructor)(void *buf, void *user_arg);
40
41
42       kmem_cbrc_t (*move)(void *old, void *new, size_t bufsize,
43            void *user_arg);
44
45

INTERFACE LEVEL

47       Solaris DDI specific (Solaris DDI)
48

PARAMETERS

50       The parameters for the kmem_cache_* functions are as follows:
51
52       name           Descriptive  name  of  a  kstat(9S)  structure  of class
53                      kmem_cache. Names longer than 31  characters  are  trun‐
54                      cated.
55
56
57       bufsize        Size of the objects it manages.
58
59
60       align          Required object alignment.
61
62
63       constructor    Pointer  to  an  object constructor function. Parameters
64                      are defined below.
65
66
67       destructor     Pointer to an object destructor function. Parameters are
68                      defined below.
69
70
71       reclaim        Drivers should pass NULL.
72
73
74       private        Pass-through argument for constructor/destructor.
75
76
77       vmp            Drivers should pass NULL.
78
79
80       cflags         Drivers must pass 0.
81
82
83       kmflag         Possible flags are:
84
85                      KM_SLEEP       Allow sleeping (blocking) until memory is
86                                     available.
87
88
89                      KM_NOSLEEP     Return NULL immediately if memory is  not
90                                     available.
91
92
93                      KM_PUSHPAGE    Allow the allocation to use reserved mem‐
94                                     ory.
95
96
97
98       obj            Pointer to the object allocated by kmem_cache_alloc().
99
100
101       move           Pointer to an object relocation function. Parameters are
102                      defined below.
103
104
105
106       The parameters for the callback constructor function are as follows:
107
108       void *buf         Pointer to the object to be constructed.
109
110
111       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
115
116       int kmflags       Propagated kmflag values.
117
118
119
120       The parameters for the callback destructor function are as follows:
121
122       void *buf         Pointer to the object to be deconstructed.
123
124
125       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
129
130
131       The parameters for the callback move() function are as follows:
132
133       void *old         Pointer to the object to be moved.
134
135
136       void *new         Pointer  to the object that serves as the copy desti‐
137                         nation for the contents of the old parameter.
138
139
140       size_t bufsize    Size of the object to be moved.
141
142
143       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
147

DESCRIPTION

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
153
154       Object caching is a technique for dealing with objects that are:
155
156           o      frequently allocated and freed, and
157
158           o      have setup and initialization costs.
159
160
161       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
175
176       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
180
181       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
193
194       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
199
200       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
215
216       kmem_cache_free() returns an object to the cache. The object must be in
217       its constructed state.
218
219
220       kmem_cache_destroy()  destroys  the  cache  and releases all associated
221       resources. All allocated objects must have been previously freed.
222
223
224       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
235
236       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
246
247       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
253         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
261
262
263
264       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
269       KMEM_CBRC_YES          The client moved the object; the allocator frees
270                              the old parameter.
271
272
273       KMEM_CBRC_NO           The client refused to move the object; the allo‐
274                              cator frees the new parameter (the  unused  copy
275                              destination).
276
277
278       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
284
285       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
290
291       KMEM_CBRC_DONT_KNOW    The  client  does  not  know  about  the  object
292                              because:
293
294                              a)    the  client  has just allocated the object
295                                    and has not yet put it wherever it expects
296                                    to find known objects
297
298
299                              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
303
304                              c)    the client has freed the object
305
306                              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
314
315
316       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
325
326       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
334       [Synopsis for notification function:]
335
336
337       void kmem_cache_move_notify(kmem_cache_t *cp, void *obj);
338
339
340
341       The parameters for the notification function are as follows:
342
343       cp     Pointer to the object cache.
344
345
346       obj    Pointer to the object that has become movable since  an  earlier
347              refusal to move it.
348
349

CONTEXT

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
359
360       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
364
365       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
369
370       kmem_cache_free()  can  be  called from user, kernel, or interrupt con‐
371       text.
372
373
374       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
378
379       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

EXAMPLES

387       Example 1 Object Caching
388
389
390       Consider the following data structure:
391
392
393         struct foo {
394             kmutex_t foo_lock;
395             kcondvar_t foo_cv;
396             struct bar *foo_barlist;
397             int foo_refcnt;
398             };
399
400
401
402       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
407
408         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
420
421
422       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
427
428         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
439         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
449         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
457
458
459       To allocate, use, and free a foo object:
460
461
462         foo = kmem_cache_alloc(foo_cache, KM_SLEEP);
463             use foo;
464         kmem_cache_free(foo_cache, foo);
465
466
467
468       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
473
474       Example 2 Registering a Move Callback
475
476
477       To register a move() callback:
478
479
480         object_cache = kmem_cache_create(...);
481         kmem_cache_set_move(object_cache, object_move);
482
483

RETURN VALUES

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
489
490       kmem_cache_create() returns a pointer to the allocated cache.
491
492
493       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

ATTRIBUTES

498       See attributes(5) for descriptions of the following attributes:
499
500
501
502
503       ┌─────────────────────────────┬─────────────────────────────┐
504       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
505       ├─────────────────────────────┼─────────────────────────────┤
506       │Interface Stability          │Committed                    │
507       └─────────────────────────────┴─────────────────────────────┘
508

SEE ALSO

510       condvar(9F), kmem_alloc(9F), mutex(9F), kstat(9S)
511
512
513       Writing Device Drivers
514
515
516       The Slab Allocator: An Object-Caching Kernel Memory Allocator, Bonwick,
517       J.; USENIX Summer 1994 Technical Conference (1994).
518
519
520       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

NOTES

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
529
530       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
534
535       The  user  argument  forwarded  to the constructor must be fully opera‐
536       tional before it is passed to kmem_cache_create().
537
538
539
540SunOS 5.11                        24 Jun 2008            kmem_cache_create(9F)
Impressum