Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
OSD(9)                 FreeBSD Kernel Developer's Manual                OSD(9)

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

FreeBSD 11.0-PRERELEASE         January 5, 2011        FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | IMPLEMENTATION NOTES | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=osd&sektion=9&manpath=FreeBSD+9.0-RELEASE>

home | help