2 .\" Copyright (c) 2010-2011 The FreeBSD Foundation
3 .\" All rights reserved.
5 .\" This documentation was written at the Centre for Advanced Internet
6 .\" Architectures, Swinburne University of Technology, Melbourne, Australia by
7 .\" David Hayes and Lawrence Stewart under sponsorship from the FreeBSD
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
23 .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
39 .Nm khelp_destroy_osd ,
43 .Nm khelp_remove_hhook ,
44 .Nm KHELP_DECLARE_MOD ,
45 .Nm KHELP_DECLARE_MOD_UMA
46 .Nd Kernel Helper Framework
49 .In sys/module_khelp.h
50 .Fn "int khelp_init_osd" "uint32_t classes" "struct osd *hosd"
51 .Fn "int khelp_destroy_osd" "struct osd *hosd"
52 .Fn "int32_t khelp_get_id" "char *hname"
53 .Fn "void * khelp_get_osd" "struct osd *hosd" "int32_t id"
54 .Fn "int khelp_add_hhook" "struct hookinfo *hki" "uint32_t flags"
55 .Fn "int khelp_remove_hhook" "struct hookinfo *hki"
56 .Fn KHELP_DECLARE_MOD "hname" "hdata" "hhooks" "version"
57 .Fn KHELP_DECLARE_MOD_UMA "hname" "hdata" "hhooks" "version" "ctor" "dtor"
60 provides a framework for managing
62 modules, which indirectly use the
64 KPI to register their hook functions with hook points of interest within the
66 Khelp modules aim to provide a structured way to dynamically extend the kernel
67 at runtime in an ABI preserving manner.
68 Depending on the subsystem providing hook points, a
70 module may be able to associate per-object data for maintaining relevant state
76 frameworks are tightly integrated and anyone interested in
80 manual page thoroughly.
81 .Ss Information for Khelp Module Implementors
83 modules are represented within the
87 which has the following members:
88 .Bd -literal -offset indent
90 int (*mod_init) (void);
91 int (*mod_destroy) (void);
92 #define HELPER_NAME_MAXLEN 16
93 char h_name[HELPER_NAME_MAXLEN];
95 struct hookinfo *h_hooks;
99 volatile uint32_t h_refcount;
101 TAILQ_ENTRY(helper) h_next;
105 Modules must instantiate a
107 but are only required to set the
109 field, and may optionally set the
114 fields where required.
115 The framework takes care of all other fields and modules should refrain from
117 Using the C99 designated initialiser feature to set fields is encouraged.
121 function will be run by the
123 framework prior to completing the registration process.
124 Returning a non-zero value from the
126 function will abort the registration process and fail to load the module.
129 function will be run by the
131 framework during the deregistration process, after the module has been
135 The return value is currently ignored.
138 classes are defined in
140 Valid flags are defined in
141 .In sys/module_khelp.h .
142 The HELPER_NEEDS_OSD flag should be set in the
146 module requires persistent per-object data storage.
147 There is no programmatic way (yet) to check if a
149 class provides the ability for
151 modules to associate persistent per-object data, so a manual check is required.
154 .Fn KHELP_DECLARE_MOD
156 .Fn KHELP_DECLARE_MOD_UMA
157 macros provide convenient wrappers around the
159 macro, and are used to register a
164 .Fn KHELP_DECLARE_MOD_UMA
165 should only be used by modules which require the use of persistent per-object
166 storage i.e. modules which set the HELPER_NEEDS_OSD flag in their
167 .Vt struct helper Ns 's
171 The first four arguments common to both macros are as follows.
174 argument specifies the unique
179 It should be no longer than HELPER_NAME_MAXLEN-1 characters in length.
182 argument is a pointer to the module's
186 argument points to a static array of
189 The array should contain a
193 point the module wishes to hook, even when using the same hook function multiple
199 argument specifies a version number for the module which will be passed to
200 .Xr MODULE_VERSION 9 .
202 .Fn KHELP_DECLARE_MOD_UMA
203 macro takes the additional
207 arguments, which specify optional
209 constructor and destructor functions.
210 NULL should be passed where the functionality is not required.
214 function returns the numeric identifier for the
221 function is used to obtain the per-object data pointer for a specified
226 argument is a pointer to the underlying subsystem object's
228 This is provided by the
230 framework when calling into a
232 module's hook function.
235 argument specifies the numeric identifier for the
237 module to extract the data pointer from
242 is obtained using the
249 .Fn khelp_remove_hhook
252 module to dynamically hook/unhook
257 argument specifies a pointer to a
259 which encapsulates the required information about the
261 point and hook function being manipulated.
262 The HHOOK_WAITOK flag may be passed in via the
268 is allowed to sleep waiting for memory to become available.
269 .Ss Integrating Khelp Into a Kernel Subsystem
270 Most of the work required to allow
272 modules to do useful things relates to defining and instantiating suitable
276 modules to hook into.
277 The only additional decision a subsystem needs to make is whether it wants to
280 modules to associate persistent per-object data.
281 Providing support for persistent data storage can allow
283 modules to perform more complex functionality which may be desirable.
284 Subsystems which want to allow Khelp modules to associate
285 persistent per-object data with one of the subsystem's data structures need to
286 make the following two key changes:
291 pointer in the structure definition for the object.
296 .Fn khelp_destroy_osd
297 to the subsystem code paths which are responsible for respectively initialising
298 and destroying the object.
303 function initialises the per-object data storage for all currently loaded
305 modules of appropriate classes which have set the HELPER_NEEDS_OSD flag in their
310 argument specifies a bitmask of
312 classes which this subsystem associates with.
315 module matches any of the classes in the bitmask, that module will be associated
319 argument specifies the pointer to the object's
321 which will be used to provide the persistent storage for use by
326 .Fn khelp_destroy_osd
327 function frees all memory that was associated with an object's
329 by a previous call to
333 argument specifies the pointer to the object's
335 which will be purged in preparation for destruction.
336 .Sh IMPLEMENTATION NOTES
338 modules are protected from being prematurely unloaded by a reference count.
339 The count is incremented each time a subsystem calls
341 causing persistent storage to be allocated for the module, and decremented for
342 each corresponding call to
343 .Fn khelp_destroy_osd .
344 Only when a module's reference count has dropped to zero can the module be
349 function returns zero if no errors occurred.
350 It returns ENOMEM if a
352 module which requires per-object storage fails to allocate the necessary memory.
355 .Fn khelp_destroy_osd
356 function only returns zero to indicate that no errors occurred.
360 function returns the unique numeric identifier for the registered
364 It return -1 if no module with the specified name is currently registered.
368 function returns the pointer to the
370 module's persistent object storage memory.
371 If the module identified by
373 does not have persistent object storage registered with the object's
380 function returns zero if no errors occurred.
381 It returns ENOENT if it could not find the requested
386 failed to allocate memory.
387 It returns EEXIST if attempting to register the same hook function more than
393 .Fn khelp_remove_hhook
394 function returns zero if no errors occurred.
395 It returns ENOENT if it could not find the requested
399 A well commented example Khelp module can be found at:
400 .Pa /usr/share/examples/kld/khelp/h_example.c
402 The Enhanced Round Trip Time (ERTT)
405 module provides a more complex example of what is possible.
411 Development and testing of this software were made possible in part by grants
412 from the FreeBSD Foundation and Cisco University Research Program Fund at
413 Community Foundation Silicon Valley.
417 kernel helper framework first appeared in
422 framework was first released in 2010 by Lawrence Stewart whilst studying at
423 Swinburne University of Technology's Centre for Advanced Internet Architectures,
424 Melbourne, Australia.
425 More details are available at:
427 http://caia.swin.edu.au/urp/newtcp/
432 framework was written by
433 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .
435 This manual page was written by
436 .An David Hayes Aq Mt david.hayes@ieee.org
438 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .