share/man/man9/EVENTHANDLER.9

   1 .\" Copyright (c) 2004 Joseph Koshy
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd October 1, 2017
  27 .Dt EVENTHANDLER 9
  28 .Os
  29 .Sh NAME
  30 .Nm EVENTHANDLER
  31 .Nd kernel event handling functions
  32 .Sh SYNOPSIS
  33 .In sys/eventhandler.h
  34 .Fn EVENTHANDLER_DECLARE name type
  35 .Fn EVENTHANDLER_DEFINE name func arg priority
  36 .Fn EVENTHANDLER_INVOKE name ...
  37 .Ft eventhandler_tag
  38 .Fn EVENTHANDLER_REGISTER name func arg priority
  39 .Fn EVENTHANDLER_DEREGISTER name tag
  40 .Fn EVENTHANDLER_DEREGISTER_NOWAIT name tag
  41 .Ft eventhandler_tag
  42 .Fo eventhandler_register
  43 .Fa "struct eventhandler_list *list"
  44 .Fa "const char *name"
  45 .Fa "void *func"
  46 .Fa "void *arg"
  47 .Fa "int priority"
  48 .Fc
  49 .Ft void
  50 .Fo eventhandler_deregister
  51 .Fa "struct eventhandler_list *list"
  52 .Fa "eventhandler_tag tag"
  53 .Fc
  54 .Ft void
  55 .Fo eventhandler_deregister_nowait
  56 .Fa "struct eventhandler_list *list"
  57 .Fa "eventhandler_tag tag"
  58 .Fc
  59 .Ft "struct eventhandler_list *"
  60 .Fn eventhandler_find_list "const char *name"
  61 .Ft void
  62 .Fn eventhandler_prune_list "struct eventhandler_list *list"
  63 .Sh DESCRIPTION
  64 The
  65 .Nm
  66 mechanism provides a way for kernel subsystems to register interest in
  67 kernel events and have their callback functions invoked when these
  68 events occur.
  69 .Pp
  70 Callback functions are invoked in order of priority.
  71 The relative priority of each callback among other callbacks
  72 associated with an event is given by argument
  73 .Fa priority ,
  74 which is an integer ranging from
  75 .Dv EVENTHANDLER_PRI_FIRST
  76 (highest priority), to
  77 .Dv EVENTHANDLER_PRI_LAST
  78 (lowest priority).
  79 The symbol
  80 .Dv EVENTHANDLER_PRI_ANY
  81 may be used if the handler does not have a specific priority
  82 associated with it.
  83 .Pp
  84 The normal way to use this subsystem is via the macro interface.
  85 The macros that can be used for working with event handlers and callback
  86 function lists are:
  87 .Bl -tag -width indent
  88 .It Fn EVENTHANDLER_DECLARE
  89 This macro declares an event handler named by argument
  90 .Fa name
  91 with callback functions of type
  92 .Fa type .
  93 .It Fn EVENTHANDLER_DEFINE
  94 This macro uses
  95 .Xr SYSINIT 9
  96 to register a callback function
  97 .Fa func
  98 with event handler
  99 .Fa name .
 100 When invoked, function
 101 .Fa func
 102 will be invoked with argument
 103 .Fa arg
 104 as its first parameter along with any additional parameters passed in
 105 via macro
 106 .Fn EVENTHANDLER_INVOKE
 107 (see below).
 108 .It Fn EVENTHANDLER_REGISTER
 109 This macro registers a callback function
 110 .Fa func
 111 with event handler
 112 .Fa name .
 113 When invoked, function
 114 .Fa func
 115 will be invoked with argument
 116 .Fa arg
 117 as its first parameter along with any additional parameters passed in
 118 via macro
 119 .Fn EVENTHANDLER_INVOKE
 120 (see below).
 121 If registration is successful,
 122 .Fn EVENTHANDLER_REGISTER
 123 returns a cookie of type
 124 .Vt eventhandler_tag .
 125 .It Fn EVENTHANDLER_DEREGISTER
 126 This macro removes a previously registered callback associated with tag
 127 .Fa tag
 128 from the event handler named by argument
 129 .Fa name .
 130 It waits until no threads are running handlers for this event before
 131 returning, making it safe to unload a module immediately upon return
 132 from this function.
 133 .It Fn EVENTHANDLER_DEREGISTER_NOWAIT
 134 This macro removes a previously registered callback associated with tag
 135 .Fa tag
 136 from the event handler named by argument
 137 .Fa name .
 138 Upon return, one or more threads could still be running the removed
 139 function(s), but no new calls will be made.
 140 To remove a handler function from within that function, use this
 141 version of deregister, to avoid a deadlock.
 142 .It Fn EVENTHANDLER_INVOKE
 143 This macro is used to invoke all the callbacks associated with event
 144 handler
 145 .Fa name .
 146 This macro is a variadic one.
 147 Additional arguments to the macro after the
 148 .Fa name
 149 parameter are passed as the second and subsequent arguments to each
 150 registered callback function.
 151 .El
 152 .Pp
 153 The macros are implemented using the following functions:
 154 .Bl -tag -width indent
 155 .It Fn eventhandler_register
 156 The
 157 .Fn eventhandler_register
 158 function is used to register a callback with a given event.
 159 The arguments expected by this function are:
 160 .Bl -tag -width ".Fa priority"
 161 .It Fa list
 162 A pointer to an existing event handler list, or
 163 .Dv NULL .
 164 If
 165 .Fa list
 166 is
 167 .Dv NULL ,
 168 the event handler list corresponding to argument
 169 .Fa name
 170 is used.
 171 .It Fa name
 172 The name of the event handler list.
 173 .It Fa func
 174 A pointer to a callback function.
 175 Argument
 176 .Fa arg
 177 is passed to the callback function
 178 .Fa func
 179 as its first argument when it is invoked.
 180 .It Fa priority
 181 The relative priority of this callback among all the callbacks
 182 registered for this event.
 183 Valid values are those in the range
 184 .Dv EVENTHANDLER_PRI_FIRST
 185 to
 186 .Dv EVENTHANDLER_PRI_LAST .
 187 .El
 188 .Pp
 189 The
 190 .Fn eventhandler_register
 191 function returns a
 192 .Fa tag
 193 that can later be used with
 194 .Fn eventhandler_deregister
 195 to remove the particular callback function.
 196 .It Fn eventhandler_deregister
 197 The
 198 .Fn eventhandler_deregister
 199 function removes the callback associated with tag
 200 .Fa tag
 201 from the event handler list pointed to by
 202 .Fa list .
 203 If
 204 .Fa tag
 205 is
 206 .Va NULL ,
 207 all callback functions for the event are removed.
 208 This function will not return until all threads have exited from the
 209 removed handler callback function(s).
 210 This function is not safe to call from inside an event handler callback.
 211 .It Fn eventhandler_deregister_nowait
 212 The
 213 .Fn eventhandler_deregister
 214 function removes the callback associated with tag
 215 .Fa tag
 216 from the event handler list pointed to by
 217 .Fa list .
 218 This function is safe to call from inside an event handler
 219 callback.
 220 .It Fn eventhandler_find_list
 221 The
 222 .Fn eventhandler_find_list
 223 function returns a pointer to event handler list structure corresponding
 224 to event
 225 .Fa name .
 226 .It Fn eventhandler_prune_list
 227 The
 228 .Fn eventhandler_prune_list
 229 function removes all deregistered callbacks from the event list
 230 .Fa list .
 231 .El
 232 .Ss Kernel Event Handlers
 233 The following event handlers are present in the kernel:
 234 .Bl -tag -width indent
 235 .It Vt acpi_sleep_event
 236 Callbacks invoked when the system is being sent to sleep.
 237 .It Vt acpi_wakeup_event
 238 Callbacks invoked when the system is being woken up.
 239 .It Vt app_coredump_start
 240 Callbacks invoked at start of application core dump.
 241 .It Vt app_coredump_progress
 242 Callbacks invoked during progress of application core dump.
 243 .It Vt app_coredump_finish
 244 Callbacks invoked at finish of application core dump.
 245 .It Vt app_coredump_error
 246 Callbacks invoked on error of application core dump.
 247 .It Vt bpf_track
 248 Callbacks invoked when a BPF listener attaches to/detaches from network interface.
 249 .It Vt cpufreq_levels_changed
 250 Callback invoked when cpu frequency levels have changed.
 251 .It Vt cpufreq_post_change
 252 Callback invoked after cpu frequency has changed.
 253 .It Vt cpufreq_pre_change
 254 Callback invoked before cpu frequency has changed.
 255 .It Vt dcons_poll
 256 Callback invoked to poll for dcons changes.
 257 .It Vt dev_clone
 258 Callbacks invoked when a new entry is created under
 259 .Pa /dev .
 260 .It Vt group_attach_event
 261 Callback invoked when an interfance has been added to an interface group.
 262 .It Vt group_change_event
 263 Callback invoked when an change has been made to an interface group.
 264 .It Vt group_detach_event
 265 Callback invoked when an interfance has been removed from an interface group.
 266 .It Vt ifaddr_event
 267 Callbacks invoked when an address is set up on a network interface.
 268 .It Vt if_clone_event
 269 Callbacks invoked when an interface is cloned.
 270 .It Vt iflladdr_event
 271 Callback invoked when an if link layer address event has happened.
 272 .It Vt ifnet_arrival_event
 273 Callbacks invoked when a new network interface appears.
 274 .It Vt ifnet_departure_event
 275 Callbacks invoked when a network interface is taken down.
 276 .It Vt ifnet_link_event
 277 Callback invoked when an interfance link event has happened.
 278 .It Vt kld_load
 279 Callbacks invoked after a linker file has been loaded.
 280 .It Vt kld_unload
 281 Callbacks invoked after a linker file has been successfully unloaded.
 282 .It Vt kld_unload_try
 283 Callbacks invoked before a linker file is about to be unloaded.
 284 These callbacks may be used to return an error and prevent the unload from
 285 proceeding.
 286 .It Vt lle_event
 287 Callback invoked when an link layer event has happened.
 288 .It Vt nmbclusters_change
 289 Callback invoked when the number of mbuf clusters has changed.
 290 .It Vt nmbufs_change
 291 Callback invoked when the number of mbufs has changed.
 292 .It Vt maxsockets_change
 293 Callback invoked when the maximum number of sockets has changed.
 294 .It Vt mountroot
 295 Callback invoked when root has been mounted.
 296 .It Vt power_profile_change
 297 Callbacks invoked when the power profile of the system changes.
 298 .It Vt power_resume
 299 Callback invoked when the system has resumed.
 300 .It Vt power_suspend
 301 Callback invoked just before the system is suspended.
 302 .It Vt process_ctor
 303 Callback invoked when a process is created.
 304 .It Vt process_dtor
 305 Callback invoked when a process is destroyed.
 306 .It Vt process_exec
 307 Callbacks invoked when a process performs an
 308 .Fn exec
 309 operation.
 310 .It Vt process_exit
 311 Callbacks invoked when a process exits.
 312 .It Vt process_fini
 313 Callback invoked when a process memory is destroyed.
 314 This is never called.
 315 .It Vt process_fork
 316 Callbacks invoked when a process forks a child.
 317 .It Vt process_init
 318 Callback invoked when a process is initalized.
 319 .It Vt random_adaptor_attach
 320 Callback invoked when a new random module has been loaded.
 321 .It Vt register_framebuffer
 322 Callback invoked when a new frame buffer is registered.
 323 .It Vt route_redirect_event
 324 Callback invoked when a route gets redirected to a new location.
 325 .It Vt shutdown_pre_sync
 326 Callbacks invoked at shutdown time, before file systems are synchronized.
 327 .It Vt shutdown_post_sync
 328 Callbacks invoked at shutdown time, after all file systems are synchronized.
 329 .It Vt shutdown_final
 330 Callbacks invoked just before halting the system.
 331 .It Vt tcp_offload_listen_start
 332 Callback invoked for TCP Offload to start listening for new connections.
 333 .It Vt tcp_offload_listen_stop
 334 Callback invoked ror TCP Offload to stop listening for new connections.
 335 .It Vt thread_ctor
 336 Callback invoked when a thread object is created.
 337 .It Vt thread_dtor
 338 Callback invoked when a thread object is destroyed.
 339 .It Vt thread_init
 340 Callback invoked when a thread object is initalized.
 341 .It Vt thread_fini
 342 Callback invoked when a thread object is deinitalized.
 343 .It Vt usb_dev_configured
 344 Callback invoked when a USB device is configured
 345 .It Vt unregister_framebuffer
 346 Callback invoked when a frame buffer is deregistered.
 347 .It Vt vfs_mounted
 348 Callback invoked when a file system is mounted.
 349 .It Vt vfs_unmounted
 350 Callback invoked when a file system is unmounted.
 351 .It Vt vlan_config
 352 Callback invoked when the vlan configuration has changed.
 353 .It Vt vlan_unconfig
 354 Callback invoked when a vlan is destroyed.
 355 .It Vt vm_lowmem
 356 Callbacks invoked when virtual memory is low.
 357 .It Vt watchdog_list
 358 Callbacks invoked when the system watchdog timer is reinitialized.
 359 .El
 360 .Sh RETURN VALUES
 361 The macro
 362 .Fn EVENTHANDLER_REGISTER
 363 and function
 364 .Fn eventhandler_register
 365 return a cookie of type
 366 .Vt eventhandler_tag ,
 367 which may be used in a subsequent call to
 368 .Fn EVENTHANDLER_DEREGISTER
 369 or
 370 .Fn eventhandler_deregister .
 371 .Pp
 372 The
 373 .Fn eventhandler_find_list
 374 function
 375 returns a pointer to an event handler list corresponding to parameter
 376 .Fa name ,
 377 or
 378 .Dv NULL
 379 if no such list was found.
 380 .Sh HISTORY
 381 The
 382 .Nm
 383 facility first appeared in
 384 .Fx 4.0 .
 385 .Sh AUTHORS
 386 This manual page was written by
 387 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org .