NAME¶
osd
,
osd_register
,
osd_deregister
,
osd_set
,
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_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
().
Functions¶
The
osd_register
() function registers a
type/slot identifier pair with the
osd
framework for use with a new data type. The function may sleep and therefore
cannot be called from a non-sleepable context. The
type argument specifies which high-level type
grouping from
<sys/osd.h>
the slot identifier should be allocated under. The
destructor argument specifies an optional
osd_destructor_t function pointer that will be called for objects of the type
being registered which are later destroyed by the
osd_del
() function. NULL may be passed if
no destructor is required. The
methods
argument specifies an optional array of osd_method_t function pointers which
can be later invoked by the
osd_call
()
function. NULL may be passed if no methods are required. The
methods argument is currently only useful
with the OSD_JAIL type identifier.
The
osd_deregister
() function deregisters a
previously registered type/slot identifier pair. The function may sleep and
therefore cannot be called from a non-sleepable context. The
type argument specifies which high-level type
grouping from
<sys/osd.h>
the slot identifier is allocated under. The
slot argument specifies the slot identifier
which is being deregistered and should be the value that was returned by
osd_register
() when the data type was
registered.
The
osd_set
() function associates a data
object pointer with a kernel data structure's
struct osd member. The
type argument specifies which high-level type
grouping from
<sys/osd.h>
the slot identifier is allocated under. The
osd argument is a pointer to the kernel data
structure's
struct osd which will have the
value pointer associated with it. The
slot argument specifies the slot identifier
to assign the
value pointer to. The
value argument points to a data object to
associate with
osd.
The
osd_get
() function returns the data
pointer associated with a kernel data structure's
struct osd member from the specified
type/slot identifier pair. The
type argument
specifies which high-level type grouping from
<sys/osd.h>
the slot identifier is allocated under. The
osd argument is a pointer to the kernel data
structure's
struct osd to retrieve the data
pointer from. The
slot argument specifies the
slot identifier to retrieve the data pointer from.
The
osd_del
() function removes the data
pointer associated with a kernel data structure's
struct osd member from the specified
type/slot identifier pair. The
type argument
specifies which high-level type grouping from
<sys/osd.h>
the slot identifier is allocated under. The
osd argument is a pointer to the kernel data
structure's
struct osd to remove the data
pointer from. The
slot argument specifies the
slot identifier to remove the data pointer from. If an osd_destructor_t
function pointer was specified at registration time, the destructor function
will be called and passed the data pointer for the type/slot identifier pair
which is being deleted.
The
osd_call
() function calls the specified
osd_method_t function pointer for all currently registered slots of a given
type on the specified
obj and
data pointers. The function may sleep and
therefore cannot be called from a non-sleepable context. The
type argument specifies which high-level type
grouping from
<sys/osd.h>
to call the method for. The
method argument
specifies the index into the osd_method_t array that was passed to
osd_register
(). The
obj and
data
arguments are passed to the method function pointer of each slot.
The
osd_exit
() function removes all data
object pointers from all currently registered slots for a given type for the
specified kernel data structure's
struct osd
member. The
type argument specifies which
high-level type grouping from
<sys/osd.h>
to remove data pointers from. The
osd
argument is a pointer to the kernel data structure's
struct osd to remove all data object pointers
for all currently registered slots from.
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.
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.
Locking¶
osd
internally uses a mix of
mutex(9),
rmlock(9)
and
sx(9) locks to protect its internal data
structures and state.
Responsibility for synchronising access to a kernel data structure's
struct osd member is left to the subsystem
that uses the data structure and calls the
osd
API.
osd_get
() only acquires an
rmlock in read mode, therefore making it safe to
use in the majority of contexts within the kernel including most fast paths.
RETURN VALUES¶
osd_register
() returns the slot identifier
for the newly registered data type.
osd_set
() returns zero on success or ENOMEM
if the specified type/slot identifier pair triggered an internal
realloc(9) which failed.
osd_get
() returns the data pointer for the
specified type/slot identifier pair, or NULL if the slot has not been
initialised yet.
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⟩.