NAME¶

osd, osd_register, osd_deregister, osd_set, osd_reserve, osd_set_reserved, osd_free_reserved, osd_get, osd_del, osd_call, osd_exit — Object Specific Data

SYNOPSIS¶

#include <sys/osd.h>

typedef void
(*osd_destructor_t)(void *value);

typedef int
(*osd_method_t)(void *obj, void *data);

int
osd_register(u_int type, osd_destructor_t destructor, osd_method_t *methods);

void
osd_deregister(u_int type, u_int slot);

int
osd_set(u_int type, struct osd *osd, u_int slot, void *value);

void **
osd_reserve(u_int slot);

int
osd_set_reserved(u_int type, struct osd *osd, u_int slot, void **rsv, void *value);

void
osd_free_reserved(void **rsv);

void *
osd_get(u_int type, struct osd *osd, u_int slot);

void
osd_del(u_int type, struct osd *osd, u_int slot);

int
osd_call(u_int type, u_int method, void *obj, void *data);

void
osd_exit(u_int type, struct osd *osd);

DESCRIPTION¶

The osd framework provides a mechanism to dynamically associate arbitrary data at run-time with any kernel data structure which has been suitably modified for use with osd. The one-off modification required involves embedding a struct osd inside the kernel data structure.

An additional benefit is that after the initial change to a structure is made, all subsequent use of osd with the structure involves no changes to the structure's layout. By extension, if the data structure is part of the ABI, osd provides a way of extending the structure in an ABI preserving manner.

The details of the embedded struct osd are not relevant to consumers of the osd framework and should not be manipulated directly.

Data associated with a structure is referenced by the osd framework using a type/slot identifier pair. Types are statically defined in <sys/osd.h> and provide a high-level grouping for slots to be registered under. Slot identifiers are dynamically assigned by the framework when a data type is registered using osd_register() and remains valid until a corresponding call to osd_deregister().

IMPLEMENTATION NOTES¶

osd uses a two dimensional matrix (array of arrays) as the data structure to manage the external data associated with a kernel data structure's struct osd member. The type identifier is used as the index into the outer array, and the slot identifier is used as the index into the inner array. To set or retrieve a data pointer for a given type/slot identifier pair, osd_set() and osd_get() perform the equivalent of array[type][slot], which is both constant time and fast.

If osd_set() is called on a struct osd for the first time, the array for storing data pointers is dynamically allocated using malloc(9) with M_NOWAIT to a size appropriate for the slot identifier being set. If a subsequent call to osd_set() attempts to set a slot identifier which is numerically larger than the slot used in the previous osd_set() call, realloc(9) is used to grow the array to the appropriate size such that the slot identifier can be used. To maximise the efficiency of any code which calls osd_set() sequentially on a number of different slot identifiers (e.g., during an initialisation phase) one should loop through the slot identifiers in descending order from highest to lowest. This will result in only a single malloc(9) call to create an array of the largest slot size and all subsequent calls to osd_set() will proceed without any realloc(9) calls.

It is possible for osd_set() to fail to allocate this array. To ensure that such allocation succeeds, osd_reserve() may be called (in a non-blocking context), and it will pre-allocate the memory via malloc(9) with M_WAITOK. Then this pre-allocated memory is passed to osd_set_reserved(), which will use it if necessary or otherwise discard it. The memory may also be explicitly discarded by calling osd_free_reserved(). As this method always allocates memory whether or not it is ultimately needed, it should be used only rarely, such as in the unlikely event that osd_set() fails.

The osd API is geared towards slot identifiers storing pointers to the same underlying data structure type for a given osd type identifier. This is not a requirement, and khelp(9) for example stores completely different data types in slots under the OSD_KHELP type identifier.

RETURN VALUES¶

osd_register() returns the slot identifier for the newly registered data type.

osd_set() and osd_set_reserved() return zero on success or ENOMEM if the specified type/slot identifier pair triggered an internal realloc(9) which failed (osd_set_reserved() will always succeed when rsv is non-NULL).

osd_get() returns the data pointer for the specified type/slot identifier pair, or NULL if the slot has not been initialised yet.

osd_reserve() returns a pointer suitable for passing to osd_set_reserved() or osd_free_reserved().

osd_call() returns zero if no method is run or the method for each slot runs successfully. If a method for a slot returns non-zero, osd_call() terminates prematurely and returns the method's error to the caller.

SEE ALSO¶

khelp(9)

HISTORY¶

The Object Specific Data (OSD) facility first appeared in FreeBSD 8.0.

AUTHORS¶

The osd facility was written by Pawel Jakub Dawidek <pjd@FreeBSD.org>.

This manual page was written by Lawrence Stewart <lstewart@FreeBSD.org>.