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>.