share/man/man9/khelp.9

   1 .\"
   2 .\" Copyright (c) 2010-2011 The FreeBSD Foundation
   3 .\" All rights reserved.
   4 .\"
   5 .\" This documentation was written at the Centre for Advanced Internet
   6 .\" Architectures, Swinburne University, Melbourne, Australia by David Hayes and
   7 .\" Lawrence Stewart under sponsorship from the FreeBSD Foundation.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
  22 .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd February 15, 2011
  33 .Dt khelp 9
  34 .Os
  35 .Sh NAME
  36 .Nm khelp ,
  37 .Nm khelp_init_osd ,
  38 .Nm khelp_destroy_osd ,
  39 .Nm khelp_get_id ,
  40 .Nm khelp_get_osd ,
  41 .Nm khelp_add_hhook ,
  42 .Nm khelp_remove_hhook ,
  43 .Nm KHELP_DECLARE_MOD ,
  44 .Nm KHELP_DECLARE_MOD_UMA
  45 .Nd Kernel Helper Framework
  46 .Sh SYNOPSIS
  47 .In sys/khelp.h
  48 .In sys/module_khelp.h
  49 .Fn "int khelp_init_osd" "uint32_t classes" "struct osd *hosd"
  50 .Fn "int khelp_destroy_osd" "struct osd *hosd"
  51 .Fn "int32_t khelp_get_id" "char *hname"
  52 .Fn "void * khelp_get_osd" "struct osd *hosd" "int32_t id"
  53 .Fn "int khelp_add_hhook" "struct hookinfo *hki" "uint32_t flags"
  54 .Fn "int khelp_remove_hhook" "struct hookinfo *hki"
  55 .Fn KHELP_DECLARE_MOD "hname" "hdata" "hhooks" "version"
  56 .Fn KHELP_DECLARE_MOD_UMA "hname" "hdata" "hhooks" "version" "ctor" "dtor"
  57 .Sh DESCRIPTION
  58 .Nm
  59 provides a framework for managing
  60 .Nm
  61 modules, which indirectly use the
  62 .Xr hhook 9
  63 KPI to register their hook functions with hook points of interest within the
  64 kernel.
  65 Khelp modules aim to provide a structured way to dynamically extend the kernel
  66 at runtime in an ABI preserving manner.
  67 Depending on the subsystem providing hook points, a
  68 .Nm
  69 module may be able to associate per-object data for maintaining relevant state
  70 between hook calls.
  71 The
  72 .Xr hhook 9
  73 and
  74 .Nm
  75 frameworks are tightly integrated and anyone interested in
  76 .Nm
  77 should also read the
  78 .Xr hhook 9
  79 manual page thoroughly.
  80 .Ss Information for Khelp Module Implementors
  81 .Nm
  82 modules are represented within the
  83 .Nm
  84 framework by a
  85 .Vt struct helper
  86 which has the following members:
  87 .Bd -literal -offset indent
  88 struct helper {
  89         int (*mod_init) (void);
  90         int (*mod_destroy) (void);
  91 #define HELPER_NAME_MAXLEN 16
  92         char                    h_name[HELPER_NAME_MAXLEN];
  93         uma_zone_t              h_zone;
  94         struct hookinfo         *h_hooks;
  95         uint32_t                h_nhooks;
  96         uint32_t                h_classes;
  97         int32_t                 h_id;
  98         volatile uint32_t       h_refcount;
  99         uint16_t                h_flags;
 100         TAILQ_ENTRY(helper)     h_next;
 101 };
 102 .Ed
 103 .Pp
 104 Modules must instantiate a
 105 .Vt struct helper ,
 106 but are only required to set the
 107 .Va h_classes
 108 field, and may optionally set the
 109 .Va h_flags ,
 110 .Va mod_init
 111 and
 112 .Va mod_destroy
 113 fields where required.
 114 The framework takes care of all other fields and modules should refrain from
 115 manipulating them.
 116 Using the C99 designated initialiser feature to set fields is encouraged.
 117 .Pp
 118 If specified, the
 119 .Va mod_init
 120 function will be run by the
 121 .Nm
 122 framework prior to completing the registration process.
 123 Returning a non-zero value from the
 124 .Va mod_init
 125 function will abort the registration process and fail to load the module.
 126 If specified, the
 127 .Va mod_destroy
 128 function will be run by the
 129 .Nm
 130 framework during the deregistration process, after the module has been
 131 deregistered by the
 132 .Nm
 133 framework.
 134 The return value is currently ignored.
 135 Valid
 136 .Nm
 137 classes are defined in
 138 .In sys/khelp.h .
 139 Valid flags are defined in
 140 .In sys/module_khelp.h .
 141 The HELPER_NEEDS_OSD flag should be set in the
 142 .Va h_flags
 143 field if the
 144 .Nm
 145 module requires persistent per-object data storage.
 146 There is no programmatic way (yet) to check if a
 147 .Nm
 148 class provides the ability for
 149 .Nm
 150 modules to associate persistent per-object data, so a manual check is required.
 151 .Pp
 152 The
 153 .Fn KHELP_DECLARE_MOD
 154 and
 155 .Fn KHELP_DECLARE_MOD_UMA
 156 macros provide convenient wrappers around the
 157 .Xr DECLARE_MODULE 9
 158 macro, and are used to register a
 159 .Nm
 160 module with the
 161 .Nm
 162 framework.
 163 .Fn KHELP_DECLARE_MOD_UMA
 164 should only be used by modules which require the use of persistent per-object
 165 storage i.e. modules which set the HELPER_NEEDS_OSD flag in their
 166 .Vt struct helper Ns 's
 167 .Va h_flags
 168 field.
 169 .Pp
 170 The first four arguments common to both macros are as follows.
 171 The
 172 .Fa hname
 173 argument specifies the unique
 174 .Xr ascii 7
 175 name for the
 176 .Nm
 177 module.
 178 It should be no longer than HELPER_NAME_MAXLEN-1 characters in length.
 179 The
 180 .Fa hdata
 181 argument is a pointer to the module's
 182 .Vt struct helper .
 183 The
 184 .Fa hhooks
 185 argument points to a static array of
 186 .Vt struct hookinfo
 187 structures.
 188 The array should contain a
 189 .Vt struct hookinfo
 190 for each
 191 .Xr hhook 9
 192 point the module wishes to hook, even when using the same hook function multiple
 193 times for different
 194 .Xr hhook 9
 195 points.
 196 The
 197 .Fa version
 198 argument specifies a version number for the module which will be passed to
 199 .Xr MODULE_VERSION 9 .
 200 The
 201 .Fn KHELP_DECLARE_MOD_UMA
 202 macro takes the additional
 203 .Fa ctor
 204 and
 205 .Fa dtor
 206 arguments, which specify optional
 207 .Xr uma 9
 208 constructor and destructor functions.
 209 NULL should be passed where the functionality is not required.
 210 .Pp
 211 The
 212 .Fn khelp_get_id
 213 function returns the numeric identifier for the
 214 .Nm
 215 module with name
 216 .Fa hname .
 217 .Pp
 218 The
 219 .Fn khelp_get_osd
 220 function is used to obtain the per-object data pointer for a specified
 221 .Nm
 222 module.
 223 The
 224 .Fa hosd
 225 argument is a pointer to the underlying subsystem object's
 226 .Vt struct osd .
 227 This is provided by the
 228 .Xr hhook 9
 229 framework when calling into a
 230 .Nm
 231 module's hook function.
 232 The
 233 .Fa id
 234 argument specifies the numeric identifier for the
 235 .Nm
 236 module to extract the data pointer from
 237 .Fa hosd
 238 for.
 239 The
 240 .Fa id
 241 is obtained using the
 242 .Fn khelp_get_id
 243 function.
 244 .Pp
 245 The
 246 .Fn khelp_add_hhook
 247 and
 248 .Fn khelp_remove_hhook
 249 functions allow a
 250 .Nm
 251 module to dynamically hook/unhook
 252 .Xr hhook 9
 253 points at run time.
 254 The
 255 .Fa hki
 256 argument specifies a pointer to a
 257 .Vt struct hookinfo
 258 which encapsulates the required information about the
 259 .Xr hhook 9
 260 point and hook function being manipulated.
 261 The HHOOK_WAITOK flag may be passed in via the
 262 .Fa flags
 263 argument of
 264 .Fn khelp_add_hhook
 265 if
 266 .Xr malloc 9
 267 is allowed to sleep waiting for memory to become available.
 268 .Ss Integrating Khelp Into a Kernel Subsystem
 269 Most of the work required to allow
 270 .Nm
 271 modules to do useful things relates to defining and instantiating suitable
 272 .Xr hhook 9
 273 points for
 274 .Nm
 275 modules to hook into.
 276 The only additional decision a subsystem needs to make is whether it wants to
 277 allow
 278 .Nm
 279 modules to associate persistent per-object data.
 280 Providing support for persistent data storage can allow
 281 .Nm
 282 modules to perform more complex functionality which may be desirable.
 283 Subsystems which want to allow Khelp modules to associate
 284 persistent per-object data with one of the subsystem's data structures need to
 285 make the following two key changes:
 286 .Bl -bullet
 287 .It
 288 Embed a
 289 .Vt struct osd
 290 pointer in the structure definition for the object.
 291 .It
 292 Add calls to
 293 .Fn khelp_init_osd
 294 and
 295 .Fn khelp_destroy_osd
 296 to the subsystem code paths which are responsible for respectively initialising
 297 and destroying the object.
 298 .El
 299 .Pp
 300 The
 301 .Fn khelp_init_osd
 302 function initialises the per-object data storage for all currently loaded
 303 .Nm
 304 modules of appropriate classes which have set the HELPER_NEEDS_OSD flag in their
 305 .Va h_flags
 306 field.
 307 The
 308 .Fa classes
 309 argument specifies a bitmask of
 310 .Nm
 311 classes which this subsystem associates with.
 312 If a
 313 .Nm
 314 module matches any of the classes in the bitmask, that module will be associated
 315 with the object.
 316 The
 317 .Fa hosd
 318 argument specifies the pointer to the object's
 319 .Vt struct osd
 320 which will be used to provide the persistent storage for use by
 321 .Nm
 322 modules.
 323 .Pp
 324 The
 325 .Fn khelp_destroy_osd
 326 function frees all memory that was associated with an object's
 327 .Vt struct osd
 328 by a previous call to
 329 .Fn khelp_init_osd .
 330 The
 331 .Fa hosd
 332 argument specifies the pointer to the object's
 333 .Vt struct osd
 334 which will be purged in preparation for destruction.
 335 .Sh IMPLEMENTATION NOTES
 336 .Nm
 337 modules are protected from being prematurely unloaded by a reference count.
 338 The count is incremented each time a subsystem calls
 339 .Fn khelp_init_osd
 340 causing persistent storage to be allocated for the module, and decremented for
 341 each corresponding call to
 342 .Fn khelp_destroy_osd .
 343 Only when a module's reference count has dropped to zero can the module be
 344 unloaded.
 345 .Sh RETURN VALUES
 346 The
 347 .Fn khelp_init_osd
 348 function returns zero if no errors occurred.
 349 It returns ENOMEM if a
 350 .Nm
 351 module which requires per-object storage fails to allocate the necessary memory.
 352 .Pp
 353 The
 354 .Fn khelp_destroy_osd
 355 function only returns zero to indicate that no errors occurred.
 356 .Pp
 357 The
 358 .Fn khelp_get_id
 359 function returns the unique numeric identifier for the registered
 360 .Nm
 361 module with name
 362 .Fa hname .
 363 It return -1 if no module with the specified name is currently registered.
 364 .Pp
 365 The
 366 .Fn khelp_get_osd
 367 function returns the pointer to the
 368 .Nm
 369 module's persistent object storage memory.
 370 If the module identified by
 371 .Fa id
 372 does not have persistent object storage registered with the object's
 373 .Fa hosd
 374 .Vt struct osd ,
 375 NULL is returned.
 376 .Pp
 377 The
 378 .Fn khelp_add_hhook
 379 function returns zero if no errors occurred.
 380 It returns ENOENT if it could not find the requested
 381 .Xr hhook 9
 382 point.
 383 It returns ENOMEM if
 384 .Xr malloc 9
 385 failed to allocate memory.
 386 It returns EEXIST if attempting to register the same hook function more than
 387 once for the same
 388 .Xr hhook 9
 389 point.
 390 .Pp
 391 The
 392 .Fn khelp_remove_hhook
 393 function returns zero if no errors occurred.
 394 It returns ENOENT if it could not find the requested
 395 .Xr hhook 9
 396 point.
 397 .Sh EXAMPLES
 398 A well commented example Khelp module can be found at:
 399 .Pa /usr/share/examples/kld/khelp/h_example.c
 400 .Pp
 401 The Enhanced Round Trip Time (ERTT)
 402 .Xr h_ertt 4
 403 .Nm
 404 module provides a more complex example of what is possible.
 405 .Sh SEE ALSO
 406 .Xr h_ertt 4 ,
 407 .Xr hhook 9 ,
 408 .Xr osd 9
 409 .Sh ACKNOWLEDGEMENTS
 410 Development and testing of this software were made possible in part by grants
 411 from the FreeBSD Foundation and Cisco University Research Program Fund at
 412 Community Foundation Silicon Valley.
 413 .Sh HISTORY
 414 The
 415 .Nm
 416 kernel helper framework first appeared in
 417 .Fx 9.0 .
 418 .Pp
 419 The
 420 .Nm
 421 framework was first released in 2010 by Lawrence Stewart whilst studying at
 422 Swinburne University's Centre for Advanced Internet Architectures, Melbourne,
 423 Australia.
 424 More details are available at:
 425 .Pp
 426 http://caia.swin.edu.au/urp/newtcp/
 427 .Sh AUTHORS
 428 .An -nosplit
 429 The
 430 .Nm
 431 framework was written by
 432 .An Lawrence Stewart Aq lstewart@FreeBSD.org .
 433 .Pp
 434 This manual page was written by
 435 .An David Hayes Aq david.hayes@ieee.org
 436 and
 437 .An Lawrence Stewart Aq lstewart@FreeBSD.org .