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 September 17, 2020
  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 .Fn EVENTHANDLER_LIST_DECLARE name
  42 .Fn EVENTHANDLER_LIST_DEFINE name
  43 .Fn EVENTHANDLER_DIRECT_INVOKE name
  44 .Ft eventhandler_tag
  45 .Fo eventhandler_register
  46 .Fa "struct eventhandler_list *list"
  47 .Fa "const char *name"
  48 .Fa "void *func"
  49 .Fa "void *arg"
  50 .Fa "int priority"
  51 .Fc
  52 .Ft void
  53 .Fo eventhandler_deregister
  54 .Fa "struct eventhandler_list *list"
  55 .Fa "eventhandler_tag tag"
  56 .Fc
  57 .Ft void
  58 .Fo eventhandler_deregister_nowait
  59 .Fa "struct eventhandler_list *list"
  60 .Fa "eventhandler_tag tag"
  61 .Fc
  62 .Ft "struct eventhandler_list *"
  63 .Fn eventhandler_find_list "const char *name"
  64 .Ft void
  65 .Fn eventhandler_prune_list "struct eventhandler_list *list"
  66 .Sh DESCRIPTION
  67 The
  68 .Nm
  69 mechanism provides a way for kernel subsystems to register interest in
  70 kernel events and have their callback functions invoked when these
  71 events occur.
  72 .Pp
  73 Callback functions are invoked in order of priority.
  74 The relative priority of each callback among other callbacks
  75 associated with an event is given by argument
  76 .Fa priority ,
  77 which is an integer ranging from
  78 .Dv EVENTHANDLER_PRI_FIRST
  79 (highest priority), to
  80 .Dv EVENTHANDLER_PRI_LAST
  81 (lowest priority).
  82 The symbol
  83 .Dv EVENTHANDLER_PRI_ANY
  84 may be used if the handler does not have a specific priority
  85 associated with it.
  86 .Pp
  87 The normal way to use this subsystem is via the macro interface.
  88 For events that are high frequency it is suggested that you additionally use
  89 .Fn EVENTHANDLER_LIST_DEFINE
  90 so that the event handlers can be invoked directly using
  91 .Fn EVENTHANDLER_DIRECT_INVOKE
  92 (see below).
  93 This saves the invoker from having to do a locked traversal of a global
  94 list of event handler lists.
  95 .Bl -tag -width indent
  96 .It Fn EVENTHANDLER_DECLARE
  97 This macro declares an event handler named by argument
  98 .Fa name
  99 with callback functions of type
 100 .Fa type .
 101 .It Fn EVENTHANDLER_DEFINE
 102 This macro uses
 103 .Xr SYSINIT 9
 104 to register a callback function
 105 .Fa func
 106 with event handler
 107 .Fa name .
 108 When invoked, function
 109 .Fa func
 110 will be invoked with argument
 111 .Fa arg
 112 as its first parameter along with any additional parameters passed in
 113 via macro
 114 .Fn EVENTHANDLER_INVOKE
 115 (see below).
 116 .It Fn EVENTHANDLER_REGISTER
 117 This macro registers a callback function
 118 .Fa func
 119 with event handler
 120 .Fa name .
 121 When invoked, function
 122 .Fa func
 123 will be invoked with argument
 124 .Fa arg
 125 as its first parameter along with any additional parameters passed in
 126 via macro
 127 .Fn EVENTHANDLER_INVOKE
 128 (see below).
 129 If registration is successful,
 130 .Fn EVENTHANDLER_REGISTER
 131 returns a cookie of type
 132 .Vt eventhandler_tag .
 133 .It Fn EVENTHANDLER_DEREGISTER
 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 It waits until no threads are running handlers for this event before
 139 returning, making it safe to unload a module immediately upon return
 140 from this function.
 141 .It Fn EVENTHANDLER_DEREGISTER_NOWAIT
 142 This macro removes a previously registered callback associated with tag
 143 .Fa tag
 144 from the event handler named by argument
 145 .Fa name .
 146 Upon return, one or more threads could still be running the removed
 147 function(s), but no new calls will be made.
 148 To remove a handler function from within that function, use this
 149 version of deregister, to avoid a deadlock.
 150 .It Fn EVENTHANDLER_INVOKE
 151 This macro is used to invoke all the callbacks associated with event
 152 handler
 153 .Fa name .
 154 This macro is a variadic one.
 155 Additional arguments to the macro after the
 156 .Fa name
 157 parameter are passed as the second and subsequent arguments to each
 158 registered callback function.
 159 .It Fn EVENTHANDLER_LIST_DEFINE
 160 This macro defines a reference to an event handler list named by
 161 argument
 162 .Fa name .
 163 It uses
 164 .Xr SYSINIT 9
 165 to initialize the reference and the eventhandler list.
 166 .It Fn EVENTHANDLER_LIST_DECLARE
 167 This macro declares an event handler list named by argument
 168 .Fa name .
 169 This is only needed for users of
 170 .Fn EVENTHANDLER_DIRECT_INVOKE
 171 which are not in the same compilation unit of that list's definition.
 172 .It Fn EVENTHANDLER_DIRECT_INVOKE
 173 This macro invokes the event handlers registered for the list named by
 174 argument
 175 .Fa name .
 176 This macro can only be used if the list was defined with
 177 .Fn EVENTHANDLER_LIST_DEFINE .
 178 The macro is variadic with the same semantics as
 179 .Fn EVENTHANDLER_INVOKE .
 180 .El
 181 .Pp
 182 The macros are implemented using the following functions:
 183 .Bl -tag -width indent
 184 .It Fn eventhandler_register
 185 The
 186 .Fn eventhandler_register
 187 function is used to register a callback with a given event.
 188 The arguments expected by this function are:
 189 .Bl -tag -width ".Fa priority"
 190 .It Fa list
 191 A pointer to an existing event handler list, or
 192 .Dv NULL .
 193 If
 194 .Fa list
 195 is
 196 .Dv NULL ,
 197 the event handler list corresponding to argument
 198 .Fa name
 199 is used.
 200 .It Fa name
 201 The name of the event handler list.
 202 .It Fa func
 203 A pointer to a callback function.
 204 Argument
 205 .Fa arg
 206 is passed to the callback function
 207 .Fa func
 208 as its first argument when it is invoked.
 209 .It Fa priority
 210 The relative priority of this callback among all the callbacks
 211 registered for this event.
 212 Valid values are those in the range
 213 .Dv EVENTHANDLER_PRI_FIRST
 214 to
 215 .Dv EVENTHANDLER_PRI_LAST .
 216 .El
 217 .Pp
 218 The
 219 .Fn eventhandler_register
 220 function returns a
 221 .Fa tag
 222 that can later be used with
 223 .Fn eventhandler_deregister
 224 to remove the particular callback function.
 225 .It Fn eventhandler_deregister
 226 The
 227 .Fn eventhandler_deregister
 228 function removes the callback associated with tag
 229 .Fa tag
 230 from the event handler list pointed to by
 231 .Fa list .
 232 If
 233 .Fa tag
 234 is
 235 .Va NULL ,
 236 all callback functions for the event are removed.
 237 This function will not return until all threads have exited from the
 238 removed handler callback function(s).
 239 This function is not safe to call from inside an event handler callback.
 240 .It Fn eventhandler_deregister_nowait
 241 The
 242 .Fn eventhandler_deregister
 243 function removes the callback associated with tag
 244 .Fa tag
 245 from the event handler list pointed to by
 246 .Fa list .
 247 This function is safe to call from inside an event handler
 248 callback.
 249 .It Fn eventhandler_find_list
 250 The
 251 .Fn eventhandler_find_list
 252 function returns a pointer to event handler list structure corresponding
 253 to event
 254 .Fa name .
 255 .It Fn eventhandler_prune_list
 256 The
 257 .Fn eventhandler_prune_list
 258 function removes all deregistered callbacks from the event list
 259 .Fa list .
 260 .El
 261 .Ss Kernel Event Handlers
 262 The following event handlers are present in the kernel:
 263 .Bl -tag -width indent
 264 .It Vt acpi_sleep_event
 265 Callbacks invoked when the system is being sent to sleep.
 266 .It Vt acpi_wakeup_event
 267 Callbacks invoked when the system is being woken up.
 268 .It Vt app_coredump_start
 269 Callbacks invoked at start of application core dump.
 270 .It Vt app_coredump_progress
 271 Callbacks invoked during progress of application core dump.
 272 .It Vt app_coredump_finish
 273 Callbacks invoked at finish of application core dump.
 274 .It Vt app_coredump_error
 275 Callbacks invoked on error of application core dump.
 276 .It Vt bpf_track
 277 Callbacks invoked when a BPF listener attaches to/detaches from network interface.
 278 .It Vt cpufreq_levels_changed
 279 Callback invoked when cpu frequency levels have changed.
 280 .It Vt cpufreq_post_change
 281 Callback invoked after cpu frequency has changed.
 282 .It Vt cpufreq_pre_change
 283 Callback invoked before cpu frequency has changed.
 284 .It Vt dcons_poll
 285 Callback invoked to poll for dcons changes.
 286 .It Vt device_attach
 287 Callback invoked after a device has attached.
 288 .It Vt device_detach
 289 Callbacks invoked before and after a device has detached.
 290 .It Vt dev_clone
 291 Callbacks invoked when a new entry is created under
 292 .Pa /dev .
 293 .It Vt group_attach_event
 294 Callback invoked when an interfance has been added to an interface group.
 295 .It Vt group_change_event
 296 Callback invoked when an change has been made to an interface group.
 297 .It Vt group_detach_event
 298 Callback invoked when an interfance has been removed from an interface group.
 299 .It Vt ifaddr_event
 300 Callbacks invoked when an address is set up on a network interface.
 301 .It Vt ifaddr_event_ext
 302 Callback invoked when an address has been added or removed from an interface.
 303 .It Vt if_clone_event
 304 Callbacks invoked when an interface is cloned.
 305 .It Vt iflladdr_event
 306 Callback invoked when an if link layer address event has happened.
 307 .It Vt ifnet_arrival_event
 308 Callbacks invoked when a new network interface appears.
 309 .It Vt ifnet_departure_event
 310 Callbacks invoked when a network interface is taken down.
 311 .It Vt ifnet_link_event
 312 Callback invoked when an interfance link event has happened.
 313 .It Vt kld_load
 314 Callbacks invoked after a linker file has been loaded.
 315 .It Vt kld_unload
 316 Callbacks invoked after a linker file has been successfully unloaded.
 317 .It Vt kld_unload_try
 318 Callbacks invoked before a linker file is about to be unloaded.
 319 These callbacks may be used to return an error and prevent the unload from
 320 proceeding.
 321 .It Vt lle_event
 322 Callback invoked when an link layer event has happened.
 323 .It Vt nmbclusters_change
 324 Callback invoked when the number of mbuf clusters has changed.
 325 .It Vt nmbufs_change
 326 Callback invoked when the number of mbufs has changed.
 327 .It Vt maxsockets_change
 328 Callback invoked when the maximum number of sockets has changed.
 329 .It Vt mountroot
 330 Callback invoked when root has been mounted.
 331 .It Vt power_profile_change
 332 Callbacks invoked when the power profile of the system changes.
 333 .It Vt power_resume
 334 Callback invoked when the system has resumed.
 335 .It Vt power_suspend
 336 Callback invoked just before the system is suspended.
 337 .It Vt process_ctor
 338 Callback invoked when a process is created.
 339 .It Vt process_dtor
 340 Callback invoked when a process is destroyed.
 341 .It Vt process_exec
 342 Callbacks invoked when a process performs an
 343 .Fn exec
 344 operation.
 345 .It Vt process_exit
 346 Callbacks invoked when a process exits.
 347 .It Vt process_fini
 348 Callback invoked when a process memory is destroyed.
 349 This is never called.
 350 .It Vt process_fork
 351 Callbacks invoked when a process forks a child.
 352 .It Vt process_init
 353 Callback invoked when a process is initialized.
 354 .It Vt random_adaptor_attach
 355 Callback invoked when a new random module has been loaded.
 356 .It Vt register_framebuffer
 357 Callback invoked when a new frame buffer is registered.
 358 .It Vt route_redirect_event
 359 Callback invoked when a route gets redirected to a new location.
 360 .It Vt shutdown_pre_sync
 361 Callbacks invoked at shutdown time, before file systems are synchronized.
 362 .It Vt shutdown_post_sync
 363 Callbacks invoked at shutdown time, after all file systems are synchronized.
 364 .It Vt shutdown_final
 365 Callbacks invoked just before halting the system.
 366 .It Vt tcp_offload_listen_start
 367 Callback invoked for TCP Offload to start listening for new connections.
 368 .It Vt tcp_offload_listen_stop
 369 Callback invoked ror TCP Offload to stop listening for new connections.
 370 .It Vt thread_ctor
 371 Callback invoked when a thread object is created.
 372 .It Vt thread_dtor
 373 Callback invoked when a thread object is destroyed.
 374 .It Vt thread_init
 375 Callback invoked when a thread object is initialized.
 376 .It Vt thread_fini
 377 Callback invoked when a thread object is deinitalized.
 378 .It Vt usb_dev_configured
 379 Callback invoked when a USB device is configured
 380 .It Vt unregister_framebuffer
 381 Callback invoked when a frame buffer is deregistered.
 382 .It Vt vfs_mounted
 383 Callback invoked when a file system is mounted.
 384 .It Vt vfs_unmounted
 385 Callback invoked when a file system is unmounted.
 386 .It Vt vlan_config
 387 Callback invoked when the vlan configuration has changed.
 388 .It Vt vlan_unconfig
 389 Callback invoked when a vlan is destroyed.
 390 .It Vt vm_lowmem
 391 Callbacks invoked when virtual memory is low.
 392 .It Vt vxlan_start
 393 Callback invoked when a vxlan interface starts.
 394 .It Vt vxlan_stop
 395 Callback invoked when a vxlan interface stops.
 396 .It Vt watchdog_list
 397 Callbacks invoked when the system watchdog timer is reinitialized.
 398 .El
 399 .Sh RETURN VALUES
 400 The macro
 401 .Fn EVENTHANDLER_REGISTER
 402 and function
 403 .Fn eventhandler_register
 404 return a cookie of type
 405 .Vt eventhandler_tag ,
 406 which may be used in a subsequent call to
 407 .Fn EVENTHANDLER_DEREGISTER
 408 or
 409 .Fn eventhandler_deregister .
 410 .Pp
 411 The
 412 .Fn eventhandler_find_list
 413 function
 414 returns a pointer to an event handler list corresponding to parameter
 415 .Fa name ,
 416 or
 417 .Dv NULL
 418 if no such list was found.
 419 .Sh HISTORY
 420 The
 421 .Nm
 422 facility first appeared in
 423 .Fx 4.0 .
 424 .Sh AUTHORS
 425 This manual page was written by
 426 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org
 427 and
 428 .An Matt Joras Aq Mt mjoras@FreeBSD.org .