1 .\" Copyright (c) 2004 Joseph Koshy
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
31 .Nd kernel event handling functions
33 .In sys/eventhandler.h
34 .Fn EVENTHANDLER_DECLARE name type
35 .Fn EVENTHANDLER_DEFINE name func arg priority
36 .Fn EVENTHANDLER_INVOKE name ...
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
45 .Fo eventhandler_register
46 .Fa "struct eventhandler_list *list"
47 .Fa "const char *name"
53 .Fo eventhandler_deregister
54 .Fa "struct eventhandler_list *list"
55 .Fa "eventhandler_tag tag"
58 .Fo eventhandler_deregister_nowait
59 .Fa "struct eventhandler_list *list"
60 .Fa "eventhandler_tag tag"
62 .Ft "struct eventhandler_list *"
63 .Fn eventhandler_find_list "const char *name"
65 .Fn eventhandler_prune_list "struct eventhandler_list *list"
69 mechanism provides a way for kernel subsystems to register interest in
70 kernel events and have their callback functions invoked when these
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
77 which is an integer ranging from
78 .Dv EVENTHANDLER_PRI_FIRST
79 (highest priority), to
80 .Dv EVENTHANDLER_PRI_LAST
83 .Dv EVENTHANDLER_PRI_ANY
84 may be used if the handler does not have a specific priority
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
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
99 with callback functions of type
101 .It Fn EVENTHANDLER_DEFINE
104 to register a callback function
108 When invoked, function
110 will be invoked with argument
112 as its first parameter along with any additional parameters passed in
114 .Fn EVENTHANDLER_INVOKE
116 .It Fn EVENTHANDLER_REGISTER
117 This macro registers a callback function
121 When invoked, function
123 will be invoked with argument
125 as its first parameter along with any additional parameters passed in
127 .Fn EVENTHANDLER_INVOKE
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
136 from the event handler named by argument
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
141 .It Fn EVENTHANDLER_DEREGISTER_NOWAIT
142 This macro removes a previously registered callback associated with tag
144 from the event handler named by argument
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
154 This macro is a variadic one.
155 Additional arguments to the macro after the
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
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
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
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 .
182 The macros are implemented using the following functions:
183 .Bl -tag -width indent
184 .It Fn eventhandler_register
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"
191 A pointer to an existing event handler list, or
197 the event handler list corresponding to argument
201 The name of the event handler list.
203 A pointer to a callback function.
206 is passed to the callback function
208 as its first argument when it is invoked.
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
215 .Dv EVENTHANDLER_PRI_LAST .
219 .Fn eventhandler_register
222 that can later be used with
223 .Fn eventhandler_deregister
224 to remove the particular callback function.
225 .It Fn eventhandler_deregister
227 .Fn eventhandler_deregister
228 function removes the callback associated with tag
230 from the event handler list pointed to by
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
242 .Fn eventhandler_deregister
243 function removes the callback associated with tag
245 from the event handler list pointed to by
247 This function is safe to call from inside an event handler
249 .It Fn eventhandler_find_list
251 .Fn eventhandler_find_list
252 function returns a pointer to event handler list structure corresponding
255 .It Fn eventhandler_prune_list
257 .Fn eventhandler_prune_list
258 function removes all deregistered callbacks from the event list
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.
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.
285 Callback invoked to poll for dcons changes.
287 Callbacks invoked when a new entry is created under
289 .It Vt group_attach_event
290 Callback invoked when an interfance has been added to an interface group.
291 .It Vt group_change_event
292 Callback invoked when an change has been made to an interface group.
293 .It Vt group_detach_event
294 Callback invoked when an interfance has been removed from an interface group.
296 Callbacks invoked when an address is set up on a network interface.
297 .It Vt if_clone_event
298 Callbacks invoked when an interface is cloned.
299 .It Vt iflladdr_event
300 Callback invoked when an if link layer address event has happened.
301 .It Vt ifnet_arrival_event
302 Callbacks invoked when a new network interface appears.
303 .It Vt ifnet_departure_event
304 Callbacks invoked when a network interface is taken down.
305 .It Vt ifnet_link_event
306 Callback invoked when an interfance link event has happened.
308 Callbacks invoked after a linker file has been loaded.
310 Callbacks invoked after a linker file has been successfully unloaded.
311 .It Vt kld_unload_try
312 Callbacks invoked before a linker file is about to be unloaded.
313 These callbacks may be used to return an error and prevent the unload from
316 Callback invoked when an link layer event has happened.
317 .It Vt nmbclusters_change
318 Callback invoked when the number of mbuf clusters has changed.
320 Callback invoked when the number of mbufs has changed.
321 .It Vt maxsockets_change
322 Callback invoked when the maximum number of sockets has changed.
324 Callback invoked when root has been mounted.
325 .It Vt power_profile_change
326 Callbacks invoked when the power profile of the system changes.
328 Callback invoked when the system has resumed.
330 Callback invoked just before the system is suspended.
332 Callback invoked when a process is created.
334 Callback invoked when a process is destroyed.
336 Callbacks invoked when a process performs an
340 Callbacks invoked when a process exits.
342 Callback invoked when a process memory is destroyed.
343 This is never called.
345 Callbacks invoked when a process forks a child.
347 Callback invoked when a process is initialized.
348 .It Vt random_adaptor_attach
349 Callback invoked when a new random module has been loaded.
350 .It Vt register_framebuffer
351 Callback invoked when a new frame buffer is registered.
352 .It Vt route_redirect_event
353 Callback invoked when a route gets redirected to a new location.
354 .It Vt shutdown_pre_sync
355 Callbacks invoked at shutdown time, before file systems are synchronized.
356 .It Vt shutdown_post_sync
357 Callbacks invoked at shutdown time, after all file systems are synchronized.
358 .It Vt shutdown_final
359 Callbacks invoked just before halting the system.
360 .It Vt tcp_offload_listen_start
361 Callback invoked for TCP Offload to start listening for new connections.
362 .It Vt tcp_offload_listen_stop
363 Callback invoked ror TCP Offload to stop listening for new connections.
365 Callback invoked when a thread object is created.
367 Callback invoked when a thread object is destroyed.
369 Callback invoked when a thread object is initialized.
371 Callback invoked when a thread object is deinitalized.
372 .It Vt usb_dev_configured
373 Callback invoked when a USB device is configured
374 .It Vt unregister_framebuffer
375 Callback invoked when a frame buffer is deregistered.
377 Callback invoked when a file system is mounted.
379 Callback invoked when a file system is unmounted.
381 Callback invoked when the vlan configuration has changed.
383 Callback invoked when a vlan is destroyed.
385 Callbacks invoked when virtual memory is low.
387 Callbacks invoked when the system watchdog timer is reinitialized.
391 .Fn EVENTHANDLER_REGISTER
393 .Fn eventhandler_register
394 return a cookie of type
395 .Vt eventhandler_tag ,
396 which may be used in a subsequent call to
397 .Fn EVENTHANDLER_DEREGISTER
399 .Fn eventhandler_deregister .
402 .Fn eventhandler_find_list
404 returns a pointer to an event handler list corresponding to parameter
408 if no such list was found.
412 facility first appeared in
415 This manual page was written by
416 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org
418 .An Matt Joras Aq Mt mjoras@FreeBSD.org .