1.\" $NetBSD: boot.9,v 1.2 1996/09/24 07:01:26 ghudson Exp $ 2.\" 3.\" SPDX-License-Identifier: BSD-4-Clause 4.\" 5.\" Copyright (c) 1997 6.\" Mike Pritchard. All rights reserved. 7.\" 8.\" Copyright (c) 1994 Christopher G. Demetriou 9.\" All rights reserved. 10.\" 11.\" Copyright (c) 2021,2023 The FreeBSD Foundation 12.\" 13.\" Portions of this documentation were written by Mitchell Horne 14.\" under sponsorship from the FreeBSD Foundation. 15.\" 16.\" Redistribution and use in source and binary forms, with or without 17.\" modification, are permitted provided that the following conditions 18.\" are met: 19.\" 1. Redistributions of source code must retain the above copyright 20.\" notice, this list of conditions and the following disclaimer. 21.\" 2. Redistributions in binary form must reproduce the above copyright 22.\" notice, this list of conditions and the following disclaimer in the 23.\" documentation and/or other materials provided with the distribution. 24.\" 3. All advertising materials mentioning features or use of this software 25.\" must display the following acknowledgement: 26.\" This product includes software developed by Christopher G. Demetriou 27.\" for the NetBSD Project. 28.\" 4. The name of the author may not be used to endorse or promote products 29.\" derived from this software without specific prior written permission 30.\" 31.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 32.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 33.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 34.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 35.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 36.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 37.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 38.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 39.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 40.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 41.\" 42.Dd November 23, 2023 43.Dt REBOOT 9 44.Os 45.Sh NAME 46.Nm kern_reboot , 47.Nm shutdown_nice 48.Nd reboot, halt, or power off the system 49.Sh SYNOPSIS 50.In sys/types.h 51.In sys/systm.h 52.In sys/reboot.h 53.Vt extern int rebooting; 54.Ft void 55.Fn kern_reboot "int howto" 56.Ft void 57.Fn shutdown_nice "int howto" 58.In sys/eventhandler.h 59.Fn EVENTHANDLER_REGISTER "shutdown_pre_sync" "shutdown_fn" "private" "priority" 60.Fn EVENTHANDLER_REGISTER "shutdown_post_sync" "shutdown_fn" "private" "priority" 61.Fn EVENTHANDLER_REGISTER "shutdown_final" "shutdown_fn" "private" "priority" 62.Sh DESCRIPTION 63The 64.Fn kern_reboot 65function handles final system shutdown, and either halts, reboots, 66or powers down the system. 67The exact action to be taken is determined by the flags passed in 68.Fa howto . 69.Pp 70The relevant flags are: 71.Bl -tag -compact -offset indent -width "RB_POWERCYCLE" 72.It Dv RB_HALT 73Halt the system in-place rather than restarting. 74.It Dv RB_POWEROFF 75Power down the system rather than restarting. 76.It Dv RB_POWERCYCLE 77Request a power-cycle in addition to restarting. 78.It Dv RB_NOSYNC 79Do not sync filesystems during shutdown. 80.It Dv RB_DUMP 81Dump kernel memory during shutdown. 82.El 83.Pp 84The 85.Fa howto 86field, and its full list of flags are described in additional detail by 87.Xr reboot 2 . 88.Pp 89.Fn kern_reboot 90performs the following actions: 91.Bl -enum -offset indent 92.It 93Set the 94.Va rebooting 95variable to 96.Dv 1 , 97indicating that the reboot process has begun and cannot be stopped. 98.It 99Unless the 100.Dv RB_NOSYNC 101flag is set in 102.Fa howto , 103sync and unmount the system's disks by calling 104.Xr vfs_unmountall 9 . 105.It 106If rebooting after a panic 107.Po 108.Dv RB_DUMP 109is set in 110.Fa howto , 111but 112.Dv RB_HALT 113is not set 114.Pc , 115initiate a system crash dump via 116.Fn doadump . 117.It 118Print a message indicating that the system is about to be halted 119or rebooted, and a report of the total system uptime. 120.It 121Execute all registered shutdown hooks. 122See 123.Sx SHUTDOWN HOOKS 124below. 125.It 126As a last resort, if none of the shutdown hooks handled the reboot, call the 127machine-dependent 128.Fn cpu_reset 129function. 130In the unlikely case that this is not supported, 131.Fn kern_reboot 132will loop forever at the end of the function. 133This requires a manual reset of the system. 134.El 135.Pp 136.Fn kern_reboot 137may be called from a typical kernel execution context, when the system is 138running normally. 139It may also be called as the final step of a kernel panic, or from the kernel 140debugger. 141Therefore, the code in this function is subject to restrictions described by 142the 143.Sx EXECUTION CONTEXT 144section of the 145.Xr panic 9 146man page. 147.Pp 148The 149.Fn shutdown_nice 150function is the intended path for performing a clean reboot or shutdown when 151the system is operating under normal conditions. 152Calling this function will send a signal to the 153.Xr init 8 154process, instructing it to perform a shutdown. 155When 156.Xr init 8 157has cleanly terminated its children, it will perform the 158.Xr reboot 2 159system call, which in turn calls 160.Fn kern_reboot . 161.Pp 162If 163.Fn shutdown_nice 164is called before the 165.Xr init 8 166process has been spawned, or if the system has panicked or otherwise halted, 167.Fn kern_reboot 168will be called directly. 169.Sh SHUTDOWN HOOKS 170The system defines three separate 171.Xr EVENTHANDLER 9 172events, which are invoked successively during the shutdown procedure. 173These are 174.Va shutdown_pre_sync , 175.Va shutdown_post_sync , 176and 177.Va shutdown_final . 178They will be executed unconditionally in the listed order. 179Handler functions registered to any of these events will receive the value of 180.Fa howto 181as their second argument, which may be used to decide what action to take. 182.Pp 183The 184.Va shutdown_pre_sync 185event is invoked before syncing filesystems to disk. 186It enables any action or state transition that must happen before this point to 187take place. 188.Pp 189The 190.Va shutdown_post_sync 191event is invoked at the point immediately after the filesystem sync has 192finished. 193It enables, for example, disk drivers to complete the sync by flushing their 194cache to disk. 195Note that this event still takes place before the optional kernel core dump. 196.Pp 197The 198.Va shutdown_final 199event is invoked as the very last step of 200.Fn kern_reboot . 201Drivers and subsystems such as 202.Xr acpi 4 203can register handlers to this event that will perform the actual reboot, 204power-off, or halt. 205.Pp 206Notably, the 207.Va shutdown_final 208event is also the point at which all kernel modules will have their shutdown 209.Po 210.Dv MOD_SHUTDOWN 211.Pc 212hooks executed, and when the 213.Xr DEVICE_SHUTDOWN 9 214method will be executed recursively on all devices. 215.Pp 216All event handlers, like 217.Fn kern_reboot 218itself, may be run in either normal shutdown context or a kernel panic or 219debugger context. 220Handler functions are expected to take care not to trigger recursive panics. 221.Sh RETURN VALUES 222The 223.Fn kern_reboot 224function does not return. 225.Pp 226The 227.Fn shutdown_nice 228function will usually return to its caller, having initiated the asynchronous 229system shutdown. 230It will not return when called from a panic or debugger context, or during 231early boot. 232.Sh EXAMPLES 233A hypothetical driver, foo(4), defines a 234.Va shutdown_final 235event handler that can handle system power-off by writing to a device register, 236but it does not handle halt or reset. 237.Bd -literal -offset indent 238void 239foo_poweroff_handler(struct void *arg, int howto) 240{ 241 struct foo_softc *sc = arg; 242 uint32_t reg; 243 244 if ((howto & RB_POWEROFF) != 0) { 245 reg = FOO_POWEROFF; 246 WRITE4(sc, FOO_POWEROFF_REG, reg); 247 } 248} 249.Ed 250.Pp 251The handler is then registered in the device attach routine: 252.Bd -literal -offset indent 253int 254foo_attach(device_t dev) 255{ 256 struct foo_softc *sc; 257 258 ... 259 260 /* Pass the device's software context as the private arg. */ 261 EVENTHANDLER_REGISTER(shutdown_final, foo_poweroff_handler, sc, 262 SHUTDOWN_PRI_DEFAULT); 263 264 ... 265} 266.Ed 267.Pp 268This 269.Va shutdown_final 270handler uses the 271.Dv RB_NOSYNC 272flag to detect that a panic or other unusual condition has occurred, and 273returns early: 274.Bd -literal -offset indent 275void 276bar_shutdown_final(struct void *arg, int howto) 277{ 278 279 if ((howto & RB_NOSYNC) != 0) 280 return; 281 282 /* Some code that is not panic-safe. */ 283 ... 284} 285.Ed 286.Sh SEE ALSO 287.Xr reboot 2 , 288.Xr init 8 , 289.Xr DEVICE_SHUTDOWN 9 , 290.Xr EVENTHANDLER 9 , 291.Xr module 9 , 292.Xr panic 9 , 293.Xr vfs_unmountall 9 294