share/man/man9/hhook.9

   1 .\"
   2 .\" Copyright (c) 2010-2011 The FreeBSD Foundation
   3 .\"
   4 .\" This documentation was written at the Centre for Advanced Internet
   5 .\" Architectures, Swinburne University of Technology, Melbourne, Australia by
   6 .\" David Hayes and Lawrence Stewart under sponsorship from the FreeBSD
   7 .\" 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 June 21, 2013
  33 .Dt HHOOK 9
  34 .Os
  35 .Sh NAME
  36 .Nm hhook ,
  37 .Nm hhook_head_register ,
  38 .Nm hhook_head_deregister ,
  39 .Nm hhook_head_deregister_lookup ,
  40 .Nm hhook_run_hooks ,
  41 .Nm HHOOKS_RUN_IF ,
  42 .Nm HHOOKS_RUN_LOOKUP_IF
  43 .Nd Helper Hook Framework
  44 .Sh SYNOPSIS
  45 .In sys/hhook.h
  46 .Ft typedef int
  47 .Fn "\*(lp*hhook_func_t\*(rp" "int32_t hhook_type" "int32_t hhook_id" \
  48 "void *udata" "void *ctx_data" "void *hdata" "struct osd *hosd"
  49 .Fn "int hhook_head_register" "int32_t hhook_type" "int32_t hhook_id" \
  50 "struct hhook_head **hhh" "uint32_t flags"
  51 .Fn "int hhook_head_deregister" "struct hhook_head *hhh"
  52 .Fn "int hhook_head_deregister_lookup" "int32_t hhook_type" "int32_t hhook_id"
  53 .Fn "void hhook_run_hooks" "struct hhook_head *hhh" "void *ctx_data" \
  54 "struct osd *hosd"
  55 .Fn HHOOKS_RUN_IF "hhh" "ctx_data" "hosd"
  56 .Fn HHOOKS_RUN_LOOKUP_IF "hhook_type" "hhook_id" "ctx_data" "hosd"
  57 .Sh DESCRIPTION
  58 .Nm
  59 provides a framework for managing and running arbitrary hook functions at
  60 defined hook points within the kernel.
  61 The KPI was inspired by
  62 .Xr pfil 9 ,
  63 and in many respects can be thought of as a more generic superset of pfil.
  64 .Pp
  65 The
  66 .Xr khelp 9
  67 and
  68 .Nm
  69 frameworks are tightly integrated.
  70 Khelp is responsible for registering and deregistering Khelp module hook
  71 functions with
  72 .Nm
  73 points.
  74 The KPI functions used by
  75 .Xr khelp 9
  76 to do this are not documented here as they are not relevant to consumers wishing
  77 to instantiate hook points.
  78 .Ss Information for Khelp Module Implementors
  79 Khelp modules indirectly interact with
  80 .Nm
  81 by defining appropriate hook functions for insertion into hook points.
  82 Hook functions must conform to the
  83 .Ft hhook_func_t
  84 function pointer declaration
  85 outlined in the
  86 .Sx SYNOPSIS .
  87 .Pp
  88 The
  89 .Fa hhook_type
  90 and
  91 .Fa hhook_id
  92 arguments identify the hook point which has called into the hook function.
  93 These are useful when a single hook function is registered for multiple hook
  94 points and wants to know which hook point has called into it.
  95 .In sys/hhook.h
  96 lists available
  97 .Fa hhook_type
  98 defines and subsystems which export hook points are responsible for defining
  99 the
 100 .Fa hhook_id
 101 value in appropriate header files.
 102 .Pp
 103 The
 104 .Fa udata
 105 argument will be passed to the hook function if it was specified in the
 106 .Vt struct hookinfo
 107 at hook registration time.
 108 .Pp
 109 The
 110 .Fa ctx_data
 111 argument contains context specific data from the hook point call site.
 112 The data type passed is subsystem dependent.
 113 .Pp
 114 The
 115 .Fa hdata
 116 argument is a pointer to the persistent per-object storage allocated for use by
 117 the module if required.
 118 The pointer will only ever be NULL if the module did not request per-object
 119 storage.
 120 .Pp
 121 The
 122 .Fa hosd
 123 argument can be used with the
 124 .Xr khelp 9
 125 framework's
 126 .Fn khelp_get_osd
 127 function to access data belonging to a different Khelp module.
 128 .Pp
 129 Khelp modules instruct the Khelp framework to register their hook functions with
 130 .Nm
 131 points by creating a
 132 .Vt "struct hookinfo"
 133 per hook point, which contains the following members:
 134 .Bd -literal -offset indent
 135 struct hookinfo {
 136         hhook_func_t    hook_func;
 137         struct helper   *hook_helper;
 138         void            *hook_udata;
 139         int32_t         hook_id;
 140         int32_t         hook_type;
 141 };
 142 .Ed
 143 .Pp
 144 Khelp modules are responsible for setting all members of the struct except
 145 .Va hook_helper
 146 which is handled by the Khelp framework.
 147 .Ss Creating and Managing Hook Points
 148 Kernel subsystems that wish to provide
 149 .Nm
 150 points typically need to make four and possibly five key changes to their
 151 implementation:
 152 .Bl -bullet
 153 .It
 154 Define a list of
 155 .Va hhook_id
 156 mappings in an appropriate subsystem header.
 157 .It
 158 Register each hook point with the
 159 .Fn hhook_head_register
 160 function during initialisation of the subsystem.
 161 .It
 162 Select or create a standardised data type to pass to hook functions as
 163 contextual data.
 164 .It
 165 Add a call to
 166 .Fn HHOOKS_RUN_IF
 167 or
 168 .Fn HHOOKS_RUN_IF_LOOKUP
 169 at the point in the subsystem's code where the hook point should be executed.
 170 .It
 171 If the subsystem can be dynamically added/removed at runtime, each hook
 172 point registered with the
 173 .Fn hhook_head_register
 174 function when the subsystem was initialised needs to be deregistered with the
 175 .Fn hhook_head_deregister
 176 or
 177 .Fn hhook_head_deregister_lookup
 178 functions when the subsystem is being deinitialised prior to removal.
 179 .El
 180 .Pp
 181 The
 182 .Fn hhook_head_register
 183 function registers a hook point with the
 184 .Nm
 185 framework.
 186 The
 187 .Fa hook_type
 188 argument defines the high level type for the hook point.
 189 Valid types are defined in
 190 .In sys/hhook.h
 191 and new types should be added as required.
 192 The
 193 .Fa hook_id
 194 argument specifies a unique, subsystem specific identifier for the hook point.
 195 The
 196 .Fa hhh
 197 argument will, if not NULL, be used to store a reference to the
 198 .Vt struct hhook_head
 199 created as part of the registration process.
 200 Subsystems will generally want to store a local copy of the
 201 .Vt struct hhook_head
 202 so that they can use the
 203 .Fn HHOOKS_RUN_IF
 204 macro to instantiate hook points.
 205 The HHOOK_WAITOK flag may be passed in via the
 206 .Fa flags
 207 argument if
 208 .Xr malloc 9
 209 is allowed to sleep waiting for memory to become available.
 210 If the hook point is within a virtualised subsystem (e.g. the network stack),
 211 the HHOOK_HEADISINVNET flag should be passed in via the
 212 .Fa flags
 213 argument so that the
 214 .Vt struct hhook_head
 215 created during the registration process will be added to a virtualised list.
 216 .Pp
 217 The
 218 .Fn hhook_head_deregister
 219 function deregisters a previously registered hook point from the
 220 .Nm
 221 framework.
 222 The
 223 .Fa hhh
 224 argument is the pointer to the
 225 .Vt struct hhook_head
 226 returned by
 227 .Fn hhoook_head_register
 228 when the hook point was registered.
 229 .Pp
 230 The
 231 .Fn hhook_head_deregister_lookup
 232 function can be used instead of
 233 .Fn hhook_head_deregister
 234 in situations where the caller does not have a cached copy of the
 235 .Vt struct hhook_head
 236 and wants to deregister a hook point using the appropriate
 237 .Fa hook_type
 238 and
 239 .Fa hook_id
 240 identifiers instead.
 241 .Pp
 242 The
 243 .Fn hhook_run_hooks
 244 function should normally not be called directly and should instead be called
 245 indirectly via the
 246 .Fn HHOOKS_RUN_IF
 247 macro.
 248 However, there may be circumstances where it is preferable to call the function
 249 directly, and so it is documented here for completeness.
 250 The
 251 .Fa hhh
 252 argument references the
 253 .Nm
 254 point to call all registered hook functions for.
 255 The
 256 .Fa ctx_data
 257 argument specifies a pointer to the contextual hook point data to pass into the
 258 hook functions.
 259 The
 260 .Fa hosd
 261 argument should be the pointer to the appropriate object's
 262 .Vt struct osd
 263 if the subsystem provides the ability for Khelp modules to associate per-object
 264 data.
 265 Subsystems which do not should pass NULL.
 266 .Pp
 267 The
 268 .Fn HHOOKS_RUN_IF
 269 macro is the preferred way to implement hook points.
 270 It only calls the
 271 .Fn hhook_run_hooks
 272 function if at least one hook function is registered for the hook point.
 273 By checking for registered hook functions, the macro minimises the cost
 274 associated with adding hook points to frequently used code paths by reducing to
 275 a simple if test in the common case where no hook functions are registered.
 276 The arguments are as described for the
 277 .Fn hhook_run_hooks
 278 function.
 279 .Pp
 280 The
 281 .Fn HHOOKS_RUN_IF_LOOKUP
 282 macro performs the same function as the
 283 .Fn HHOOKS_RUN_IF
 284 macro, but performs an additional step to look up the
 285 .Vt struct hhook_head
 286 for the specified
 287 .Fa hook_type
 288 and
 289 .Fa hook_id
 290 identifiers.
 291 It should not be used except in code paths which are infrequently executed
 292 because of the reference counting overhead associated with the look up.
 293 .Sh IMPLEMENTATION NOTES
 294 Each
 295 .Vt struct hhook_head
 296 protects its internal list of hook functions with a
 297 .Xr rmlock 9 .
 298 Therefore, anytime
 299 .Fn hhook_run_hooks
 300 is called directly or indirectly via the
 301 .Fn HHOOKS_RUN_IF
 302 or
 303 .Fn HHOOKS_RUN_IF_LOOKUP
 304 macros, a non-sleepable read lock will be acquired and held across the calls to
 305 all registered hook functions.
 306 .Sh RETURN VALUES
 307 .Fn hhook_head_register
 308 returns 0 if no errors occurred.
 309 It returns EEXIST if a hook point with the same
 310 .Fa hook_type
 311 and
 312 .Fa hook_id
 313 is already registered.
 314 It returns EINVAL if the HHOOK_HEADISINVNET flag is not set in
 315 .Fa flags
 316 because the implementation does not yet support hook points in non-virtualised
 317 subsystems (see the
 318 .Sx BUGS
 319 section for details).
 320 It returns ENOMEM if
 321 .Xr malloc 9
 322 failed to allocate memory for the new
 323 .Vt struct hhook_head .
 324 .Pp
 325 .Fn hhook_head_deregister
 326 and
 327 .Fn hhook_head_deregister_lookup
 328 return 0 if no errors occurred.
 329 They return ENOENT if
 330 .Fa hhh
 331 is NULL.
 332 They return EBUSY if the reference count of
 333 .Fa hhh
 334 is greater than one.
 335 .Sh EXAMPLES
 336 A well commented example Khelp module can be found at:
 337 .Pa /usr/share/examples/kld/khelp/h_example.c
 338 .Pp
 339 The
 340 .Xr tcp 4
 341 implementation provides two
 342 .Nm
 343 points which are called for packets sent/received when a connection is in the
 344 established phase.
 345 Search for HHOOK in the following files:
 346 .Pa sys/netinet/tcp_var.h ,
 347 .Pa sys/netinet/tcp_input.c ,
 348 .Pa sys/netinet/tcp_output.c
 349 and
 350 .Pa sys/netinet/tcp_subr.c .
 351 .Sh SEE ALSO
 352 .Xr khelp 9
 353 .Sh ACKNOWLEDGEMENTS
 354 Development and testing of this software were made possible in part by grants
 355 from the FreeBSD Foundation and Cisco University Research Program Fund at
 356 Community Foundation Silicon Valley.
 357 .Sh HISTORY
 358 The
 359 .Nm
 360 framework first appeared in
 361 .Fx 9.0 .
 362 .Pp
 363 The
 364 .Nm
 365 framework was first released in 2010 by Lawrence Stewart whilst studying at
 366 Swinburne University of Technology's Centre for Advanced Internet Architectures,
 367 Melbourne, Australia.
 368 More details are available at:
 369 .Pp
 370 http://caia.swin.edu.au/urp/newtcp/
 371 .Sh AUTHORS
 372 .An -nosplit
 373 The
 374 .Nm
 375 framework was written by
 376 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .
 377 .Pp
 378 This manual page was written by
 379 .An David Hayes Aq Mt david.hayes@ieee.org
 380 and
 381 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .