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.\" $FreeBSD$ 43.\" 44.Dd March 20, 2023 45.Dt REBOOT 9 46.Os 47.Sh NAME 48.Nm kern_reboot , 49.Nm shutdown_nice 50.Nd reboot, halt, or power off the system 51.Sh SYNOPSIS 52.In sys/types.h 53.In sys/systm.h 54.In sys/reboot.h 55.Vt extern int rebooting; 56.Ft void 57.Fn kern_reboot "int howto" 58.Ft void 59.Fn shutdown_nice "int howto" 60.In sys/eventhandler.h 61.Fn EVENTHANDLER_REGISTER "shutdown_pre_sync" "shutdown_fn" "private" "priority" 62.Fn EVENTHANDLER_REGISTER "shutdown_post_sync" "shutdown_fn" "private" "priority" 63.Fn EVENTHANDLER_REGISTER "shutdown_final" "shutdown_fn" "private" "priority" 64.Sh DESCRIPTION 65The 66.Fn kern_reboot 67function handles final system shutdown, and either halts, reboots, 68or powers down the system. 69The exact action to be taken is determined by the flags passed in 70.Fa howto . 71.Pp 72The relevant flags are: 73.Bl -tag -compact -offset indent -width "RB_POWERCYCLE" 74.It Dv RB_HALT 75Halt the system in-place rather than restarting. 76.It Dv RB_POWEROFF 77Power down the system rather than restarting. 78.It Dv RB_POWERCYCLE 79Request a power-cycle in addition to restarting. 80.It Dv RB_NOSYNC 81Do not sync filesystems during shutdown. 82.It Dv RB_DUMP 83Dump kernel memory during shutdown. 84.El 85.Pp 86The 87.Fa howto 88field, and its full list of flags are described in additional detail by 89.Xr reboot 2 . 90.Pp 91.Fn kern_reboot 92performs the following actions: 93.Bl -enum -offset indent 94.It 95Set the 96.Va rebooting 97variable to 98.Dv 1 , 99indicating that the reboot process has begun and cannot be stopped. 100.It 101Set the 102.Va kdb_active 103variable to 104.Dv 0 , 105indicating that execution has left the kernel debugger, if it was previously 106active. 107.It 108Unless the 109.Dv RB_NOSYNC 110flag is set in 111.Fa howto , 112sync and unmount the system's disks by calling 113.Xr vfs_unmountall 9 . 114.It 115If rebooting after a panic 116.Po 117.Dv RB_DUMP 118is set in 119.Fa howto , 120but 121.Dv RB_HALT 122is not set 123.Pc , 124initiate a system crash dump via 125.Fn doadump . 126.It 127Print a message indicating that the system is about to be halted 128or rebooted, and a report of the total system uptime. 129.It 130Execute all registered shutdown hooks. 131See 132.Sx SHUTDOWN HOOKS 133below. 134.It 135As a last resort, if none of the shutdown hooks handled the reboot, call the 136machine-dependent 137.Fn cpu_reset 138function. 139In the unlikely case that this is not supported, 140.Fn kern_reboot 141will loop forever at the end of the function. 142This requires a manual reset of the system. 143.El 144.Pp 145.Fn kern_reboot 146may be called from a typical kernel execution context, when the system is 147running normally. 148It may also be called as the final step of a kernel panic, or from the kernel 149debugger. 150Therefore, the code in this function is subject to restrictions described by 151the 152.Sx EXECUTION CONTEXT 153section of the 154.Xr panic 9 155man page. 156.Pp 157The 158.Fn shutdown_nice 159function is the intended path for performing a clean reboot or shutdown when 160the system is operating under normal conditions. 161Calling this function will send a signal to the 162.Xr init 8 163process, instructing it to perform a shutdown. 164When 165.Xr init 8 166has cleanly terminated its children, it will perform the 167.Xr reboot 2 168system call, which in turn calls 169.Fn kern_reboot . 170.Pp 171If 172.Fn shutdown_nice 173is called before the 174.Xr init 8 175process has been spawned, or if the system has panicked or otherwise halted, 176.Fn kern_reboot 177will be called directly. 178.Sh SHUTDOWN HOOKS 179The system defines three separate 180.Xr EVENTHANDLER 9 181events, which are invoked successively during the shutdown procedure. 182These are 183.Va shutdown_pre_sync , 184.Va shutdown_post_sync , 185and 186.Va shutdown_final . 187They will be executed unconditionally in the listed order. 188Handler functions registered to any of these events will receive the value of 189.Fa howto 190as their second argument, which may be used to decide what action to take. 191.Pp 192The 193.Va shutdown_pre_sync 194event is invoked before syncing filesystems to disk. 195It enables any action or state transition that must happen before this point to 196take place. 197.Pp 198The 199.Va shutdown_post_sync 200event is invoked at the point immediately after the filesystem sync has 201finished. 202It enables, for example, disk drivers to complete the sync by flushing their 203cache to disk. 204Note that this event still takes place before the optional kernel core dump. 205.Pp 206The 207.Va shutdown_final 208event is invoked as the very last step of 209.Fn kern_reboot . 210Drivers and subsystems such as 211.Xr acpi 4 212can register handlers to this event that will perform the actual reboot, 213power-off, or halt. 214.Pp 215Notably, the 216.Va shutdown_final 217event is also the point at which all kernel modules will have their shutdown 218.Po 219.Dv MOD_SHUTDOWN 220.Pc 221hooks executed, and when the 222.Xr DEVICE_SHUTDOWN 9 223method will be executed recursively on all devices. 224.Pp 225All event handlers, like 226.Fn kern_reboot 227itself, may be run in either normal shutdown context or a kernel panic or 228debugger context. 229Handler functions are expected to take care not to trigger recursive panics. 230.Sh RETURN VALUES 231The 232.Fn kern_reboot 233function does not return. 234.Pp 235The 236.Fn shutdown_nice 237function will usually return to its caller, having initiated the asynchronous 238system shutdown. 239It will not return when called from a panic or debugger context, or during 240early boot. 241.Sh EXAMPLES 242A hypothetical driver, foo(4), defines a 243.Va shutdown_final 244event handler that can handle system power-off by writing to a device register, 245but it does not handle halt or reset. 246.Bd -literal -offset indent 247void 248foo_poweroff_handler(struct void *arg, int howto) 249{ 250 struct foo_softc *sc = arg; 251 uint32_t reg; 252 253 if ((howto & RB_POWEROFF) != 0) { 254 reg = FOO_POWEROFF; 255 WRITE4(sc, FOO_POWEROFF_REG, reg); 256 } 257} 258.Ed 259.Pp 260The handler is then registered in the device attach routine: 261.Bd -literal -offset indent 262int 263foo_attach(device_t dev) 264{ 265 struct foo_softc *sc; 266 267 ... 268 269 /* Pass the device's software context as the private arg. */ 270 EVENTHANDLER_REGISTER(shutdown_final, foo_poweroff_handler, sc, 271 SHUTDOWN_PRI_DEFAULT); 272 273 ... 274} 275.Ed 276.Pp 277This 278.Va shutdown_final 279handler uses the 280.Dv RB_NOSYNC 281flag to detect that a panic or other unusual condition has occurred, and 282returns early: 283.Bd -literal -offset indent 284void 285bar_shutdown_final(struct void *arg, int howto) 286{ 287 288 if ((howto & RB_NOSYNC) != 0) 289 return; 290 291 /* Some code that is not panic-safe. */ 292 ... 293} 294.Ed 295.Sh SEE ALSO 296.Xr reboot 2 , 297.Xr init 8 , 298.Xr DEVICE_SHUTDOWN 9 , 299.Xr EVENTHANDLER 9 , 300.Xr module 9 , 301.Xr panic 9 , 302.Xr vfs_unmountall 9 303