Kernel Functions for Drivers kmemcachecreate(9F)
NAME
kmemcachecreate, kmemcachealloc, kmemcachefree,
kmemcachedestroy, kmemcachesetmove - kernel memory
cache allocator operations
SYNOPSIS
#include
#include
kmemcachet *kmemcachecreate(char *name, sizet bufsize,
sizet align, int (*constructor)(void *, void *, int),
void (*destructor)(void *, void *), void (*reclaim)(void *),
void *private, void *vmp, int cflags);
void kmemcachedestroy(kmemcachet *cp);
void *kmemcachealloc(kmemcachet *cp, int kmflag);
void kmemcachefree(kmemcachet *cp, void *obj);
void kmemcachesetmove(kmemcachet *cp, kmemcbrct (*move)(void *,
void *, sizet *, void *));
[Synopsis for callback functions:]
int (*constructor)(void *buf, void *userarg, int kmflags);
void (*destructor)(void *buf, void *userarg);
kmemcbrct (*move)(void *old, void *new, sizet bufsize,
void *userarg);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
The parameters for the kmemcache* functions are as fol-
lows:
name Descriptive name of a kstat(9S) structure of
class kmemcache. Names longer than 31 char-
acters are truncated.
SunOS 5.11 Last change: 24 Jun 2008 1
Kernel Functions for Drivers kmemcachecreate(9F)
bufsize Size of the objects it manages.
align Required object alignment.
constructor Pointer to an object constructor function.
Parameters are defined below.
destructor Pointer to an object destructor function.
Parameters are defined below.
reclaim Drivers should pass NUL.
private Pass-through argument for
constructor/destructor.
vmp Drivers should pass NUL.
cflags Drivers must pass 0.
kmflag Possible flags are:
KMSLEP Allow sleeping (blocking)
until memory is available.
KMNOSLEP Return NUL immediately if
memory is not available.
KMPUSHPAGE Allow the allocation to use
reserved memory.
obj Pointer to the object allocated by
kmemcachealloc().
move Pointer to an object relocation function.
Parameters are defined below.
SunOS 5.11 Last change: 24 Jun 2008 2
Kernel Functions for Drivers kmemcachecreate(9F)
The parameters for the callback constructor function are as
follows:
void *buf Pointer to the object to be constructed.
void *userarg The private parameter from the call to
kmemcachecreate(); it is typically a
pointer to the soft-state structure.
int kmflags Propagated kmflag values.
The parameters for the callback destructor function are as
follows:
void *buf Pointer to the object to be deconstructed.
void *userarg The private parameter from the call to
kmemcachecreate(); it is typically a
pointer to the soft-state structure.
The parameters for the callback move() function are as fol-
lows:
void *old Pointer to the object to be moved.
void *new Pointer to the object that serves as the
copy destination for the contents of the
old parameter.
sizet bufsize Size of the object to be moved.
void *userarg The private parameter from the call to
kmemcachecreate(); it is typically a
pointer to the soft-state structure.
DESCRIPTION
In many cases, the cost of initializing and destroying an
object exceeds the cost of allocating and freeing memory for
it. The functions described here address this condition.
SunOS 5.11 Last change: 24 Jun 2008 3
Kernel Functions for Drivers kmemcachecreate(9F)
Object caching is a technique for dealing with objects that
are:
o frequently allocated and freed, and
o have setup and initialization costs.
The idea is to allow the allocator and its clients to
cooperate to preserve the invariant portion of an object's
initial state, or constructed state, between uses, so it
does not have to be destroyed and re-created every time the
object is used. For example, an object containing a mutex
only needs to have mutexinit() applied once, the first time
the object is allocated. The object can then be freed and
reallocated many times without incurring the expense of
mutexdestroy() and mutexinit() each time. An object's
embedded locks, condition variables, reference counts, lists
of other objects, and read-only data all generally qualify
as constructed state. The essential requirement is that the
client must free the object (using kmemcachefree()) in its
constructed state. The allocator cannot enforce this, so
programming errors will lead to hard-to-find bugs.
A driver should call kmemcachecreate() at the time of
fini(9E) or attach(9E), and call the corresponding
kmemcachedestroy() at the time of fini(9E) or detach(9E).
kmemcachecreate() creates a cache of objects, each of size
bufsize bytes, aligned on an align boundary. Drivers not
requiring a specific alignment can pass 0. name identifies
the cache for statistics and debugging. constructor and des-
tructor convert plain memory into objects and back again;
constructor can fail if it needs to allocate memory but can-
not. private is a parameter passed to the constructor and
destructor callbacks to support parameterized caches (for
example, a pointer to an instance of the driver's soft-state
structure). To facilitate debugging, kmemcachecreate()
creates a kstat(9S) structure of class kmemcache and name
name. It returns an opaque pointer to the object cache.
kmemcachealloc() gets an object from the cache. The object
will be in its constructed state. kmflag has either KMSLEP
or KMNOSLEP set, indicating whether it is acceptable to
wait for memory if none is currently available.
A small pool of reserved memory is available to allow the
system to progress toward the goal of freeing additional
SunOS 5.11 Last change: 24 Jun 2008 4
Kernel Functions for Drivers kmemcachecreate(9F)
memory while in a low memory situation. The KMPUSHPAGE flag
enables use of this reserved memory pool on an allocation.
This flag can be used by drivers that implement strategy(9E)
on memory allocations associated with a single I/O opera-
tion. The driver guarantees that the I/O operation will com-
plete (or timeout) and, on completion, that the memory will
be returned. The KMPUSHPAGE flag should be used only in
kmemcachealloc() calls. All allocations from a given cache
should be consistent in their use of the flag. A driver that
adheres to these restrictions can guarantee progress in a
low memory situation without resorting to complex private
allocation and queuing schemes. If KMPUSHPAGE is specified,
KMSLEP can also be used without causing deadlock.
kmemcachefree() returns an object to the cache. The object
must be in its constructed state.
kmemcachedestroy() destroys the cache and releases all
associated resources. All allocated objects must have been
previously freed.
kmemcachesetmove() registers a function that the alloca-
tor may call to move objects from sparsely allocated pages
of memory so that the system can reclaim pages that are tied
up by the client. Since caching objects of the same size and
type already makes severe memory fragmentation unlikely,
there is generally no need to register such a function. The
idea is to make it possible to limit worst-case fragmenta-
tion in caches that exhibit a tendency to become highly
fragmented. Only clients that allocate a mix of long- and
short-lived objects from the same cache are prone to exhibit
this tendency, making them candidates for a move() callback.
The move() callback supplies the client with two addresses:
the allocated object that the allocator wants to move and a
buffer selected by the allocator for the client to use as
the copy destination. The new parameter is an allocated,
constructed object ready to receive the contents of the old
parameter. The bufsize parameter supplies the size of the
object, in case a single move function handles multiple
caches whose objects differ only in size. Finally, the
private parameter passed to the constructor and destructor
is also passed to the move() callback.
Only the client knows about its own data and when it is a
good time to move it. The client cooperates with the alloca-
tor to return unused memory to the system, and the allocator
SunOS 5.11 Last change: 24 Jun 2008 5
Kernel Functions for Drivers kmemcachecreate(9F)
accepts this help at the client's convenience. When asked to
move an object, the client can respond with any of the fol-
lowing:
typedef enum kmemcbrc {
KMEMCBRCYES,
KMEMCBRCNO,
KMEMCBRCLATER,
KMEMCBRCDONTNED,
KMEMCBRCDONTKNOW
} kmemcbrct;
The client must not explicitly free either of the objects
passed to the move() callback, since the allocator wants to
free them directly to the slab layer (bypassing the per-CPU
magazine layer). The response tells the allocator which of
the two object parameters to free:
KMEMCBRCYES The client moved the object; the
allocator frees the old parameter.
KMEMCBRCNO The client refused to move the
object; the allocator frees the new
parameter (the unused copy destina-
tion).
KMEMCBRCLATER The client is using the object and
cannot move it now; the allocator
frees the new parameter (the unused
copy destination). The client should
use KMEMCBRCLATER instead of
KMEMCBRCNO if the object is likely
to become movable soon.
KMEMCBRCDONTNED The client no longer needs the
object; the allocator frees both the
old and new parameters. This response
is the client's opportunity to be a
model citizen and give back as much
as it can.
KMEMCBRCDONTKNOW The client does not know about the
object because:
SunOS 5.11 Last change: 24 Jun 2008 6
Kernel Functions for Drivers kmemcachecreate(9F)
a) the client has just allocated
the object and has not yet put
it wherever it expects to find
known objects
b) the client has removed the
object from wherever it expects
to find known objects and is
about to free the object
c) the client has freed the object
In all of these cases above, the
allocator frees the new parameter
(the unused copy destination) and
searches for the old parameter in the
magazine layer. If the object is
found, it is removed from the maga-
zine layer and freed to the slab
layer so that it will no longer tie
up an entire page of memory.
Any object passed to the move() callback is guaranteed to
have been touched only by the allocator or by the client.
Because memory patterns applied by the allocator always set
at least one of the two lowest order bits, the bottom two
bits of any pointer member (other than char * or short *,
which may not be 8-byte aligned on all platforms) are avail-
able to the client for marking cached objects that the
client is about to free. This way, the client can recognize
known objects in the move() callback by the unmarked (valid)
pointer value.
If the client refuses to move an object with either
KMEMCBRCNO or KMEMCBRCLATER, and that object later
becomes movable, the client can notify the allocator by cal-
ling kmemcachemovenotify(). Alternatively, the client can
simply wait for the allocator to call back again with the
same object address. Responding KMEMCRBCNO even once or
responding KMEMCRBCLATER too many times for the same
object makes the allocator less likely to call back again
for that object.
[Synopsis for notification function:]
SunOS 5.11 Last change: 24 Jun 2008 7
Kernel Functions for Drivers kmemcachecreate(9F)
void kmemcachemovenotify(kmemcachet *cp, void *obj);
The parameters for the notification function are as follows:
cp Pointer to the object cache.
obj Pointer to the object that has become movable since
an earlier refusal to move it.
CONTEXT
Constructors can be invoked during any call to
kmemcachealloc(), and will run in that context. Similarly,
destructors can be invoked during any call to
kmemcachefree(), and can also be invoked during
kmemcachedestroy(). Therefore, the functions that a con-
structor or destructor invokes must be appropriate in that
context. Furthermore, the allocator may also call the con-
structor and destructor on objects still under its control
without client involvement.
kmemcachecreate() and kmemcachedestroy() must not be
called from interrupt context. kmemcachecreate() can also
block for available memory.
kmemcachealloc() can be called from interrupt context only
if the KMNOSLEP flag is set. It can be called from user or
kernel context with any valid flag.
kmemcachefree() can be called from user, kernel, or inter-
rupt context.
kmemcachesetmove() is called from the same context as
kmemcachecreate(), immediately after kmemcachecreate()
and before allocating any objects from the cache.
The registered move() callback is always invoked in the same
global callback thread dedicated for move requests, guaran-
teeing that no matter how many clients register a move()
function, the allocator never tries to move more than one
object at a time. Neither the allocator nor the client can
be assumed to know the object's whereabouts at the time of
the callback.
SunOS 5.11 Last change: 24 Jun 2008 8
Kernel Functions for Drivers kmemcachecreate(9F)
EXAMPLES
Example 1 Object Caching
Consider the following data structure:
struct foo {
kmutext foolock;
kcondvart foocv;
struct bar *foobarlist;
int foorefcnt;
};
Assume that a foo structure cannot be freed until there are
no outstanding references to it (foorefcnt == 0) and all of
its pending bar events (whatever they are) have completed
(foobarlist == NUL). The life cycle of a dynamically allo-
cated foo would be something like this:
foo = kmemalloc(sizeof (struct foo), KMSLEP);
mutexinit(&foo->foolock, ...);
cvinit(&foo->foocv, ...);
foo->foorefcnt = 0;
foo->foobarlist = NUL;
use foo;
ASERT(foo->foobarlist == NUL);
ASERT(foo->foorefcnt == 0);
cvdestroy(&foo->foocv);
mutexdestroy(&foo->foolock);
kmemfree(foo);
Notice that between each use of a foo object we perform a
sequence of operations that constitutes nothing but expen-
sive overhead. All of this overhead (that is, everything
other than use foo above) can be eliminated by object cach-
ing.
int
fooconstructor(void *buf, void *arg, int tags)
{
struct foo *foo = buf;
mutexinit(&foo->foolock, ...);
cvinit(&foo->foocv, ...);
foo->foorefcnt = 0;
foo->foobarlist = NUL;
SunOS 5.11 Last change: 24 Jun 2008 9
Kernel Functions for Drivers kmemcachecreate(9F)
return (0);
}
void
foodestructor(void *buf, void *arg)
{
struct foo *foo = buf;
ASERT(foo->foobarlist == NUL);
ASERT(foo->foorefcnt == 0);
cvdestroy(&foo->foocv);
mutexdestroy(&foo->foolock);
}
userarg = ddigetsoftstate(foosoftc, instance);
(void) snprintf(buf, KSTATSTRLEN, "foo%dcache",
ddigetinstance(dip));
foocache = kmemcachecreate(buf,
sizeof (struct foo), 0,
fooconstructor, foodestructor,
NUL, userarg, 0);
To allocate, use, and free a foo object:
foo = kmemcachealloc(foocache, KMSLEP);
use foo;
kmemcachefree(foocache, foo);
This makes foo allocation fast, because the allocator will
usually do nothing more than fetch an already-constructed
foo from the cache. fooconstructor and foodestructor will
be invoked only to populate and drain the cache, respec-
tively.
Example 2 Registering a Move Callback
To register a move() callback:
objectcache = kmemcachecreate(...);
kmemcachesetmove(objectcache, objectmove);
RETURN VALUES
If successful, the constructor function must return 0. If
KMNOSLEP is set and memory cannot be allocated without
SunOS 5.11 Last change: 24 Jun 2008 10
Kernel Functions for Drivers kmemcachecreate(9F)
sleeping, the constructor must return -1.
kmemcachecreate() returns a pointer to the allocated
cache.
If successful, kmemcachealloc() returns a pointer to the
allocated object. If KMNOSLEP is set and memory cannot be
allocated without sleeping, kmemcachealloc() returns NUL.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
SEE ALSO
condvar(9F), kmemalloc(9F), mutex(9F), kstat(9S)
Writing Device Drivers
The Slab Allocator: An Object-Caching Kernel Memory Alloca-
tor, Bonwick, J.; USENIX Summer 1994 Technical Conference
(1994).
Magazines and vmem: Extending the Slab Allocator to Many
CPUs and Arbitrary Resources, Bonwick, J. and Adams, J.;
USENIX 2001 Technical Conference (2001).
NOTES
The constructor must be immediately reversible by the des-
tructor, since the allocator may call the constructor and
destructor on objects still under its control at any time
without client involvement.
The constructor must respect the kmflags argument by for-
warding it to allocations made inside the constructor, and
must not ASERT anything about the given flags.
SunOS 5.11 Last change: 24 Jun 2008 11
Kernel Functions for Drivers kmemcachecreate(9F)
The user argument forwarded to the constructor must be fully
operational before it is passed to kmemcachecreate().
SunOS 5.11 Last change: 24 Jun 2008 12
|
