diff --git a/share/man/man9/kern_reboot.9 b/share/man/man9/kern_reboot.9 index d120a437c521..a82b53382687 100644 --- a/share/man/man9/kern_reboot.9 +++ b/share/man/man9/kern_reboot.9 @@ -1,191 +1,302 @@ .\" $NetBSD: boot.9,v 1.2 1996/09/24 07:01:26 ghudson Exp $ .\" .\" SPDX-License-Identifier: BSD-4-Clause .\" .\" Copyright (c) 1997 .\" Mike Pritchard. All rights reserved. .\" .\" Copyright (c) 1994 Christopher G. Demetriou .\" All rights reserved. .\" .\" Copyright (c) 2021,2023 The FreeBSD Foundation .\" .\" Portions of this documentation were written by Mitchell Horne .\" under sponsorship from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by Christopher G. Demetriou .\" for the NetBSD Project. .\" 4. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 20, 2023 .Dt REBOOT 9 .Os .Sh NAME .Nm kern_reboot , .Nm shutdown_nice .Nd reboot, halt, or power off the system .Sh SYNOPSIS .In sys/types.h .In sys/systm.h .In sys/reboot.h .Vt extern int rebooting; .Ft void .Fn kern_reboot "int howto" .Ft void .Fn shutdown_nice "int howto" .In sys/eventhandler.h .Fn EVENTHANDLER_REGISTER "shutdown_pre_sync" "shutdown_fn" "private" "priority" .Fn EVENTHANDLER_REGISTER "shutdown_post_sync" "shutdown_fn" "private" "priority" .Fn EVENTHANDLER_REGISTER "shutdown_final" "shutdown_fn" "private" "priority" .Sh DESCRIPTION The .Fn kern_reboot function handles final system shutdown, and either halts, reboots, or powers down the system. The exact action to be taken is determined by the flags passed in .Fa howto . .Pp The relevant flags are: .Bl -tag -compact -offset indent -width "RB_POWERCYCLE" .It Dv RB_HALT Halt the system in-place rather than restarting. .It Dv RB_POWEROFF Power down the system rather than restarting. .It Dv RB_POWERCYCLE Request a power-cycle in addition to restarting. .It Dv RB_NOSYNC Do not sync filesystems during shutdown. .It Dv RB_DUMP Dump kernel memory during shutdown. .El .Pp The .Fa howto field, and its full list of flags are described in additional detail by .Xr reboot 2 . .Pp .Fn kern_reboot performs the following actions: .Bl -enum -offset indent .It Set the .Va rebooting variable to .Dv 1 , indicating that the reboot process has begun and cannot be stopped. .It Set the .Va kdb_active variable to .Dv 0 , indicating that execution has left the kernel debugger, if it was previously active. .It Unless the .Dv RB_NOSYNC flag is set in .Fa howto , sync and unmount the system's disks by calling .Xr vfs_unmountall 9 . .It If rebooting after a panic .Po .Dv RB_DUMP is set in .Fa howto , but .Dv RB_HALT is not set .Pc , initiate a system crash dump via .Fn doadump . .It Print a message indicating that the system is about to be halted or rebooted, and a report of the total system uptime. .It Execute all registered shutdown hooks. +See +.Sx SHUTDOWN HOOKS +below. .It As a last resort, if none of the shutdown hooks handled the reboot, call the machine-dependent .Fn cpu_reset function. In the unlikely case that this is not supported, .Fn kern_reboot will loop forever at the end of the function. This requires a manual reset of the system. .El .Pp .Fn kern_reboot may be called from a typical kernel execution context, when the system is running normally. It may also be called as the final step of a kernel panic, or from the kernel debugger. Therefore, the code in this function is subject to restrictions described by the .Sx EXECUTION CONTEXT section of the .Xr panic 9 man page. .Pp The .Fn shutdown_nice function is the intended path for performing a clean reboot or shutdown when the system is operating under normal conditions. Calling this function will send a signal to the .Xr init 8 process, instructing it to perform a shutdown. When .Xr init 8 has cleanly terminated its children, it will perform the .Xr reboot 2 system call, which in turn calls .Fn kern_reboot . .Pp If .Fn shutdown_nice is called before the .Xr init 8 process has been spawned, or if the system has panicked or otherwise halted, .Fn kern_reboot will be called directly. +.Sh SHUTDOWN HOOKS +The system defines three separate +.Xr EVENTHANDLER 9 +events, which are invoked successively during the shutdown procedure. +These are +.Va shutdown_pre_sync , +.Va shutdown_post_sync , +and +.Va shutdown_final . +They will be executed unconditionally in the listed order. +Handler functions registered to any of these events will receive the value of +.Fa howto +as their second argument, which may be used to decide what action to take. +.Pp +The +.Va shutdown_pre_sync +event is invoked before syncing filesystems to disk. +It enables any action or state transition that must happen before this point to +take place. +.Pp +The +.Va shutdown_post_sync +event is invoked at the point immediately after the filesystem sync has +finished. +It enables, for example, disk drivers to complete the sync by flushing their +cache to disk. +Note that this event still takes place before the optional kernel core dump. +.Pp +The +.Va shutdown_final +event is invoked as the very last step of +.Fn kern_reboot . +Drivers and subsystems such as +.Xr acpi 4 +can register handlers to this event that will perform the actual reboot, +power-off, or halt. +.Pp +Notably, the +.Va shutdown_final +event is also the point at which all kernel modules will have their shutdown +.Po +.Dv MOD_SHUTDOWN +.Pc +hooks executed, and when the +.Xr DEVICE_SHUTDOWN 9 +method will be executed recursively on all devices. +.Pp +All event handlers, like +.Fn kern_reboot +itself, may be run in either normal shutdown context or a kernel panic or +debugger context. +Handler functions are expected to take care not to trigger recursive panics. .Sh RETURN VALUES The .Fn kern_reboot function does not return. .Pp The .Fn shutdown_nice function will usually return to its caller, having initiated the asynchronous system shutdown. It will not return when called from a panic or debugger context, or during early boot. +.Sh EXAMPLES +A hypothetical driver, foo(4), defines a +.Va shutdown_final +event handler that can handle system power-off by writing to a device register, +but it does not handle halt or reset. +.Bd -literal -offset indent +void +foo_poweroff_handler(struct void *arg, int howto) +{ + struct foo_softc *sc = arg; + uint32_t reg; + + if ((howto & RB_POWEROFF) != 0) { + reg = FOO_POWEROFF; + WRITE4(sc, FOO_POWEROFF_REG, reg); + } +} +.Ed +.Pp +The handler is then registered in the device attach routine: +.Bd -literal -offset indent +int +foo_attach(device_t dev) +{ + struct foo_softc *sc; + + ... + + /* Pass the device's software context as the private arg. */ + EVENTHANDLER_REGISTER(shutdown_final, foo_poweroff_handler, sc, + SHUTDOWN_PRI_DEFAULT); + + ... +} +.Ed +.Pp +This +.Va shutdown_final +handler uses the +.Dv RB_NOSYNC +flag to detect that a panic or other unusual condition has occurred, and +returns early: +.Bd -literal -offset indent +void +bar_shutdown_final(struct void *arg, int howto) +{ + + if ((howto & RB_NOSYNC) != 0) + return; + + /* Some code that is not panic-safe. */ + ... +} +.Ed .Sh SEE ALSO .Xr reboot 2 , .Xr init 8 , +.Xr DEVICE_SHUTDOWN 9 , .Xr EVENTHANDLER 9 , +.Xr module 9 , .Xr panic 9 , .Xr vfs_unmountall 9 diff --git a/sys/sys/eventhandler.h b/sys/sys/eventhandler.h index 8c45431c83c3..be5a027f4743 100644 --- a/sys/sys/eventhandler.h +++ b/sys/sys/eventhandler.h @@ -1,324 +1,331 @@ /*- * SPDX-License-Identifier: BSD-2-Clause-FreeBSD * * Copyright (c) 1999 Michael Smith * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * * $FreeBSD$ */ #ifndef _SYS_EVENTHANDLER_H_ #define _SYS_EVENTHANDLER_H_ #include #include #include #include #include #ifdef VIMAGE struct eventhandler_entry_vimage { void (* func)(void); /* Original function registered. */ void *ee_arg; /* Original argument registered. */ void *sparep[2]; }; #endif struct eventhandler_list { char *el_name; int el_flags; /* Unused. */ u_int el_runcount; struct mtx el_lock; TAILQ_ENTRY(eventhandler_list) el_link; TAILQ_HEAD(,eventhandler_entry) el_entries; }; #define EHL_LOCK(p) mtx_lock(&(p)->el_lock) #define EHL_UNLOCK(p) mtx_unlock(&(p)->el_lock) #define EHL_LOCK_ASSERT(p, x) mtx_assert(&(p)->el_lock, x) /* * Macro to invoke the handlers for a given event. */ #define _EVENTHANDLER_INVOKE(name, list, ...) do { \ struct eventhandler_entry *_ep; \ struct eventhandler_entry_ ## name *_t; \ \ EHL_LOCK_ASSERT((list), MA_OWNED); \ (list)->el_runcount++; \ KASSERT((list)->el_runcount > 0, \ ("eventhandler_invoke: runcount overflow")); \ CTR0(KTR_EVH, "eventhandler_invoke(\"" __STRING(name) "\")"); \ TAILQ_FOREACH(_ep, &((list)->el_entries), ee_link) { \ if (_ep->ee_priority != EHE_DEAD_PRIORITY) { \ EHL_UNLOCK((list)); \ _t = (struct eventhandler_entry_ ## name *)_ep; \ CTR1(KTR_EVH, "eventhandler_invoke: executing %p", \ (void *)_t->eh_func); \ _t->eh_func(_ep->ee_arg , ## __VA_ARGS__); \ EHL_LOCK((list)); \ } \ } \ KASSERT((list)->el_runcount > 0, \ ("eventhandler_invoke: runcount underflow")); \ (list)->el_runcount--; \ if ((list)->el_runcount == 0) \ eventhandler_prune_list(list); \ EHL_UNLOCK((list)); \ } while (0) /* * You can optionally use the EVENTHANDLER_LIST and EVENTHANDLER_DIRECT macros * to pre-define a symbol for the eventhandler list. This symbol can be used by * EVENTHANDLER_DIRECT_INVOKE, which has the advantage of not needing to do a * locked search of the global list of eventhandler lists. At least * EVENTHANDLER_LIST_DEFINE must be used for EVENTHANDLER_DIRECT_INVOKE to * work. EVENTHANDLER_LIST_DECLARE is only needed if the call to * EVENTHANDLER_DIRECT_INVOKE is in a different compilation unit from * EVENTHANDLER_LIST_DEFINE. If the events are even relatively high frequency * it is suggested that you directly define a list for them. */ #define EVENTHANDLER_LIST_DEFINE(name) \ struct eventhandler_list *_eventhandler_list_ ## name ; \ static void _ehl_init_ ## name (void * ctx __unused) \ { \ _eventhandler_list_ ## name = eventhandler_create_list(#name); \ } \ SYSINIT(name ## _ehl_init, SI_SUB_EVENTHANDLER, SI_ORDER_ANY, \ _ehl_init_ ## name, NULL); \ struct __hack #define EVENTHANDLER_DIRECT_INVOKE(name, ...) do { \ struct eventhandler_list *_el; \ \ _el = _eventhandler_list_ ## name ; \ if (!TAILQ_EMPTY(&_el->el_entries)) { \ EHL_LOCK(_el); \ _EVENTHANDLER_INVOKE(name, _el , ## __VA_ARGS__); \ } \ } while (0) #define EVENTHANDLER_DEFINE(name, func, arg, priority) \ static eventhandler_tag name ## _tag; \ static void name ## _evh_init(void *ctx) \ { \ name ## _tag = EVENTHANDLER_REGISTER(name, func, ctx, \ priority); \ } \ SYSINIT(name ## _evh_init, SI_SUB_CONFIGURE, SI_ORDER_ANY, \ name ## _evh_init, arg); \ struct __hack #define EVENTHANDLER_INVOKE(name, ...) \ do { \ struct eventhandler_list *_el; \ \ if ((_el = eventhandler_find_list(#name)) != NULL) \ _EVENTHANDLER_INVOKE(name, _el , ## __VA_ARGS__); \ } while (0) #define EVENTHANDLER_REGISTER(name, func, arg, priority) \ eventhandler_register(NULL, #name, func, arg, priority) #define EVENTHANDLER_DEREGISTER(name, tag) \ do { \ struct eventhandler_list *_el; \ \ if ((_el = eventhandler_find_list(#name)) != NULL) \ eventhandler_deregister(_el, tag); \ } while (0) #define EVENTHANDLER_DEREGISTER_NOWAIT(name, tag) \ do { \ struct eventhandler_list *_el; \ \ if ((_el = eventhandler_find_list(#name)) != NULL) \ eventhandler_deregister_nowait(_el, tag); \ } while (0) eventhandler_tag eventhandler_register(struct eventhandler_list *list, const char *name, void *func, void *arg, int priority); void eventhandler_deregister(struct eventhandler_list *list, eventhandler_tag tag); void eventhandler_deregister_nowait(struct eventhandler_list *list, eventhandler_tag tag); struct eventhandler_list *eventhandler_find_list(const char *name); void eventhandler_prune_list(struct eventhandler_list *list); struct eventhandler_list *eventhandler_create_list(const char *name); #ifdef VIMAGE typedef void (*vimage_iterator_func_t)(void *, ...); eventhandler_tag vimage_eventhandler_register(struct eventhandler_list *list, const char *name, void *func, void *arg, int priority, vimage_iterator_func_t); #endif /* * Standard system event queues. */ /* Generic priority levels */ #define EVENTHANDLER_PRI_FIRST 0 #define EVENTHANDLER_PRI_ANY 10000 #define EVENTHANDLER_PRI_LAST 20000 -/* Shutdown events */ +/* + * Successive shutdown events invoked by kern_reboot(9). + * + * Handlers will receive the 'howto' value as their second argument. + * + * All handlers must be prepared to be executed from a panic/debugger context; + * see the man page for details. + */ typedef void (*shutdown_fn)(void *, int); #define SHUTDOWN_PRI_FIRST EVENTHANDLER_PRI_FIRST #define SHUTDOWN_PRI_DEFAULT EVENTHANDLER_PRI_ANY #define SHUTDOWN_PRI_LAST EVENTHANDLER_PRI_LAST EVENTHANDLER_DECLARE(shutdown_pre_sync, shutdown_fn); /* before fs sync */ EVENTHANDLER_DECLARE(shutdown_post_sync, shutdown_fn); /* after fs sync */ EVENTHANDLER_DECLARE(shutdown_final, shutdown_fn); /* Power state change events */ typedef void (*power_change_fn)(void *); EVENTHANDLER_DECLARE(power_resume, power_change_fn); EVENTHANDLER_DECLARE(power_suspend, power_change_fn); EVENTHANDLER_DECLARE(power_suspend_early, power_change_fn); /* Low memory event */ typedef void (*vm_lowmem_handler_t)(void *, int); #define LOWMEM_PRI_DEFAULT EVENTHANDLER_PRI_FIRST EVENTHANDLER_DECLARE(vm_lowmem, vm_lowmem_handler_t); /* Some of mbuf(9) zones reached maximum */ EVENTHANDLER_DECLARE(mbuf_lowmem, vm_lowmem_handler_t); /* Root mounted event */ typedef void (*mountroot_handler_t)(void *); EVENTHANDLER_DECLARE(mountroot, mountroot_handler_t); /* File system mount events */ struct mount; struct vnode; struct thread; typedef void (*vfs_mounted_notify_fn)(void *, struct mount *, struct vnode *, struct thread *); typedef void (*vfs_unmounted_notify_fn)(void *, struct mount *, struct thread *); EVENTHANDLER_DECLARE(vfs_mounted, vfs_mounted_notify_fn); EVENTHANDLER_DECLARE(vfs_unmounted, vfs_unmounted_notify_fn); /* * Process events * process_fork and exit handlers are called without Giant. * exec handlers are called with Giant, but that is by accident. */ struct proc; struct image_params; typedef void (*exitlist_fn)(void *, struct proc *); typedef void (*forklist_fn)(void *, struct proc *, struct proc *, int); typedef void (*execlist_fn)(void *, struct proc *, struct image_params *); typedef void (*proc_ctor_fn)(void *, struct proc *); typedef void (*proc_dtor_fn)(void *, struct proc *); typedef void (*proc_init_fn)(void *, struct proc *); typedef void (*proc_fini_fn)(void *, struct proc *); EVENTHANDLER_DECLARE(process_ctor, proc_ctor_fn); EVENTHANDLER_DECLARE(process_dtor, proc_dtor_fn); EVENTHANDLER_DECLARE(process_init, proc_init_fn); EVENTHANDLER_DECLARE(process_fini, proc_fini_fn); EVENTHANDLER_DECLARE(process_exit, exitlist_fn); EVENTHANDLER_DECLARE(process_fork, forklist_fn); EVENTHANDLER_DECLARE(process_exec, execlist_fn); /* * application dump event */ typedef void (*app_coredump_start_fn)(void *, struct thread *, char *name); typedef void (*app_coredump_progress_fn)(void *, struct thread *td, int byte_count); typedef void (*app_coredump_finish_fn)(void *, struct thread *td); typedef void (*app_coredump_error_fn)(void *, struct thread *td, char *msg, ...); EVENTHANDLER_DECLARE(app_coredump_start, app_coredump_start_fn); EVENTHANDLER_DECLARE(app_coredump_progress, app_coredump_progress_fn); EVENTHANDLER_DECLARE(app_coredump_finish, app_coredump_finish_fn); EVENTHANDLER_DECLARE(app_coredump_error, app_coredump_error_fn); typedef void (*thread_ctor_fn)(void *, struct thread *); typedef void (*thread_dtor_fn)(void *, struct thread *); typedef void (*thread_fini_fn)(void *, struct thread *); typedef void (*thread_init_fn)(void *, struct thread *); EVENTHANDLER_DECLARE(thread_ctor, thread_ctor_fn); EVENTHANDLER_DECLARE(thread_dtor, thread_dtor_fn); EVENTHANDLER_DECLARE(thread_init, thread_init_fn); EVENTHANDLER_DECLARE(thread_fini, thread_fini_fn); typedef void (*uma_zone_chfn)(void *); EVENTHANDLER_DECLARE(nmbclusters_change, uma_zone_chfn); EVENTHANDLER_DECLARE(nmbufs_change, uma_zone_chfn); EVENTHANDLER_DECLARE(maxsockets_change, uma_zone_chfn); /* Kernel linker file load and unload events */ struct linker_file; typedef void (*kld_load_fn)(void *, struct linker_file *); typedef void (*kld_unload_fn)(void *, const char *, caddr_t, size_t); typedef void (*kld_unload_try_fn)(void *, struct linker_file *, int *); EVENTHANDLER_DECLARE(kld_load, kld_load_fn); EVENTHANDLER_DECLARE(kld_unload, kld_unload_fn); EVENTHANDLER_DECLARE(kld_unload_try, kld_unload_try_fn); /* Generic graphics framebuffer interface */ struct fb_info; typedef void (*register_framebuffer_fn)(void *, struct fb_info *); typedef void (*unregister_framebuffer_fn)(void *, struct fb_info *); EVENTHANDLER_DECLARE(register_framebuffer, register_framebuffer_fn); EVENTHANDLER_DECLARE(unregister_framebuffer, unregister_framebuffer_fn); /* Veto ada attachment */ struct cam_path; struct ata_params; typedef void (*ada_probe_veto_fn)(void *, struct cam_path *, struct ata_params *, int *); EVENTHANDLER_DECLARE(ada_probe_veto, ada_probe_veto_fn); /* Swap device events */ struct swdevt; typedef void (*swapon_fn)(void *, struct swdevt *); typedef void (*swapoff_fn)(void *, struct swdevt *); EVENTHANDLER_DECLARE(swapon, swapon_fn); EVENTHANDLER_DECLARE(swapoff, swapoff_fn); /* newbus device events */ enum evhdev_detach { EVHDEV_DETACH_BEGIN, /* Before detach() is called */ EVHDEV_DETACH_COMPLETE, /* After detach() returns 0 */ EVHDEV_DETACH_FAILED /* After detach() returns err */ }; typedef void (*device_attach_fn)(void *, device_t); typedef void (*device_detach_fn)(void *, device_t, enum evhdev_detach); typedef void (*device_nomatch_fn)(void *, device_t); EVENTHANDLER_DECLARE(device_attach, device_attach_fn); EVENTHANDLER_DECLARE(device_detach, device_detach_fn); EVENTHANDLER_DECLARE(device_nomatch, device_nomatch_fn); /* Interface address addition and removal event */ struct ifaddr; typedef void (*rt_addrmsg_fn)(void *, struct ifaddr *, int); EVENTHANDLER_DECLARE(rt_addrmsg, rt_addrmsg_fn); #endif /* _SYS_EVENTHANDLER_H_ */