2 .\" Copyright (c) 2010 Lawrence Stewart <lstewart@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions, and the following disclaimer,
10 .\" without modification, immediately at the beginning of the file.
11 .\" 2. The name of the author may not be used to endorse or promote products
12 .\" derived from this software without specific prior written permission.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
18 .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
40 .Nd Object Specific Data
44 .Fn "\*(lp*osd_destructor_t\*(rp" "void *value"
46 .Fn "\*(lp*osd_method_t\*(rp" "void *obj" "void *data"
50 .Fa "osd_destructor_t destructor"
51 .Fa "osd_method_t *methods"
92 framework provides a mechanism to dynamically associate arbitrary data at
93 run-time with any kernel data structure which has been suitably modified for use
96 The one-off modification required involves embedding a
98 inside the kernel data structure.
100 An additional benefit is that after the initial change to a structure is made,
101 all subsequent use of
103 with the structure involves no changes to the structure's layout.
104 By extension, if the data structure is part of the ABI,
106 provides a way of extending the structure in an ABI preserving manner.
108 The details of the embedded
110 are not relevant to consumers of the
112 framework and should not be manipulated directly.
114 Data associated with a structure is referenced by the
116 framework using a type/slot identifier pair.
117 Types are statically defined in
119 and provide a high-level grouping for slots to be registered under.
120 Slot identifiers are dynamically assigned by the framework when a data type is
123 and remains valid until a corresponding call to
128 function registers a type/slot identifier pair with the
130 framework for use with a new data type.
131 The function may sleep and therefore cannot be called from a non-sleepable
135 argument specifies which high-level type grouping from
137 the slot identifier should be allocated under.
140 argument specifies an optional osd_destructor_t function pointer that will be
141 called for objects of the type being registered which are later destroyed by the
144 NULL may be passed if no destructor is required.
147 argument specifies an optional array of osd_method_t function pointers which
148 can be later invoked by the
151 NULL may be passed if no methods are required.
154 argument is currently only useful with the OSD_JAIL type identifier.
158 function deregisters a previously registered type/slot identifier pair.
159 The function may sleep and therefore cannot be called from a non-sleepable
163 argument specifies which high-level type grouping from
165 the slot identifier is allocated under.
168 argument specifies the slot identifier which is being deregistered and should be
169 the value that was returned by
171 when the data type was registered.
175 function associates a data object pointer with a kernel data structure's
180 argument specifies which high-level type grouping from
182 the slot identifier is allocated under.
185 argument is a pointer to the kernel data structure's
189 pointer associated with it.
192 argument specifies the slot identifier to assign the
197 argument points to a data object to associate with
202 function returns the data pointer associated with a kernel data structure's
204 member from the specified type/slot identifier pair.
207 argument specifies which high-level type grouping from
209 the slot identifier is allocated under.
212 argument is a pointer to the kernel data structure's
214 to retrieve the data pointer from.
217 argument specifies the slot identifier to retrieve the data pointer from.
221 function removes the data pointer associated with a kernel data structure's
223 member from the specified type/slot identifier pair.
226 argument specifies which high-level type grouping from
228 the slot identifier is allocated under.
231 argument is a pointer to the kernel data structure's
233 to remove the data pointer from.
236 argument specifies the slot identifier to remove the data pointer from.
237 If an osd_destructor_t function pointer was specified at registration time, the
238 destructor function will be called and passed the data pointer for the type/slot
239 identifier pair which is being deleted.
243 function calls the specified osd_method_t function pointer for all
244 currently registered slots of a given type on the specified
249 The function may sleep and therefore cannot be called from a non-sleepable
253 argument specifies which high-level type grouping from
255 to call the method for.
258 argument specifies the index into the osd_method_t array that was passed to
264 arguments are passed to the method function pointer of each slot.
268 function removes all data object pointers from all currently registered slots
269 for a given type for the specified kernel data structure's
274 argument specifies which high-level type grouping from
276 to remove data pointers from.
279 argument is a pointer to the kernel data structure's
281 to remove all data object pointers for all currently registered slots from.
282 .Sh IMPLEMENTATION NOTES
284 uses a two dimensional matrix (array of arrays) as the data structure to manage
285 the external data associated with a kernel data structure's
288 The type identifier is used as the index into the outer array, and the slot
289 identifier is used as the index into the inner array. To set or retrieve a data
290 pointer for a given type/slot identifier pair,
294 perform the equivalent of array[type][slot], which is both constant time and
301 for the first time, the array for storing data pointers is dynamically allocated
304 with M_NOWAIT to a size appropriate for the slot identifier being set.
305 If a subsequent call to
307 attempts to set a slot identifier which is numerically larger than the slot used
312 is used to grow the array to the appropriate size such that the slot identifier
314 To maximise the efficiency of any code which calls
316 sequentially on a number of different slot identifiers (e.g. during an
317 initialisation phase) one should loop through the slot identifiers in descending
318 order from highest to lowest.
319 This will result in only a single
321 call to create an array of the largest slot size and all subsequent calls to
323 will proceed without any
329 API is geared towards slot identifiers storing pointers to the same underlying
330 data structure type for a given
333 This is not a requirement, and
335 for example stores completely different data types in slots under the OSD_KHELP
339 internally uses a mix of
344 locks to protect its internal data structures and state.
346 Responsibility for synchronising access to a kernel data structure's
348 member is left to the subsystem that uses the data structure and calls the
355 in read mode, therefore making it safe to use in the majority of contexts within
356 the kernel including most fast paths.
359 returns the slot identifier for the newly registered data type.
362 returns zero on success or ENOMEM if the specified type/slot identifier pair
363 triggered an internal
368 returns the data pointer for the specified type/slot identifier pair, or NULL if
369 the slot has not been initialised yet.
372 returns zero if no method is run or the method for each slot runs successfully.
373 If a method for a slot returns non-zero,
375 terminates prematurely and returns the method's error to the caller.
380 Object Specific Data (OSD) facility first appeared in
386 facility was written by
387 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
389 This manual page was written by
390 .An Lawrence Stewart Aq lstewart@FreeBSD.org .