kern_reboot(9): some updates

- This function no longer disables interrupts
 - MLINK to reboot.9
 - The mentions of autoconfiguration is more about shutdown_nice(),
   coming in the next commit.
 - Describe the RB_* flags relevant to this function
 - Describe behaviour when shutdown hooks fail the reset
 - Describe expected execution contexts
 - Add FF copyright
 - xref panic(9)
 - xref this page in reboot(2)

Reviewed by:	markj
Discussed with:	rpokala, Pau Amma <pauamma@gundo.com>
MFC after:	1 week
Sponsored by:	The FreeBSD Foundation
Differential Revision:	https://reviews.freebsd.org/D39133

lib/libc/sys/reboot.2

@@ -156,7 +156,8 @@ The caller is not the super-user.
 .Xr halt 8 ,
 .Xr init 8 ,
 .Xr reboot 8 ,
-.Xr savecore 8
+.Xr savecore 8 ,
+.Xr reboot 9
 .Sh HISTORY
 The
 .Fn reboot

share/man/man9/Makefile

@@ -1335,6 +1335,7 @@ MLINKS+=intr_event.9 intr_event_add_handler.9 \
 	intr_event.9 intr_event_remove_handler.9 \
 	intr_event.9 intr_priority.9
 MLINKS+=KASSERT.9 MPASS.9
+MLINKS+=kern_reboot.9 reboot.9
 MLINKS+=kern_yield.9 maybe_yield.9 \
 	kern_yield.9 should_yield.9
 MLINKS+=kernacc.9 useracc.9

share/man/man9/kern_reboot.9

@@ -1,11 +1,18 @@
 .\"	$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:
@@ -18,7 +25,7 @@
 .\"    must display the following acknowledgement:
 .\"      This product includes software developed by Christopher G. Demetriou
 .\"      for the NetBSD Project.
-.\" 3. The name of the author may not be used to endorse or promote products
+.\" 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
@@ -34,16 +41,17 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd September 23, 2021
+.Dd March 20, 2023
-.Dt KERN_REBOOT 9
+.Dt REBOOT 9
 .Os
 .Sh NAME
 .Nm kern_reboot
-.Nd halt or reboot the system
+.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"
 .In sys/eventhandler.h
@@ -53,53 +61,92 @@
 .Sh DESCRIPTION
 The
 .Fn kern_reboot
-function handles final system shutdown, and either halts or reboots
+function handles final system shutdown, and either halts, reboots,
-the system.
+or powers down the system.
 The exact action to be taken is determined by the flags passed in
-.Fa howto
+.Fa howto .
-and by whether or not the system has finished autoconfiguration.
+.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
-If the system has finished autoconfiguration,
 .Fn kern_reboot
-does the following:
+performs the following actions:
 .Bl -enum -offset indent
 .It
-If this is the first invocation of
+Set the
-.Fn kern_reboot
+.Va rebooting
-and the
+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 not set in
+flag is set in
 .Fa howto ,
-syncs and unmounts the system disks by calling
+sync and unmount the system's disks by calling
 .Xr vfs_unmountall 9 .
 .It
-Disables interrupts.
+If rebooting after a panic
-.It
+.Po
-If rebooting after a crash (i.e., if
 .Dv RB_DUMP
 is set in
 .Fa howto ,
 but
 .Dv RB_HALT
-is not), saves a system crash dump.
+is not set
+.Pc ,
+initiate a system crash dump via
+.Fn doadump .
 .It
-Runs any shutdown hooks previously registered.
+Print a message indicating that the system is about to be halted
+or rebooted, and a report of the total system uptime.
 .It
-Prints a message indicating that the system is about to be halted
+Execute all registered shutdown hooks.
-or rebooted.
 .It
-If
+As a last resort, if none of the shutdown hooks handled the reboot, call the
-.Dv RB_HALT
+machine-dependent
-is set in
+.Fn cpu_reset
-.Fa howto ,
+function.
-halts the system.
+In the unlikely case that this is not supported,
-Otherwise, reboots the system.
+.Fn kern_reboot
+will loop forever at the end of the function.
+This requires a manual reset of the system.
 .El
 .Pp
-If the system has not finished autoconfiguration,
 .Fn kern_reboot
-runs any shutdown hooks previously registered,
+may be called from a typical kernel execution context, when the system is
-prints a message, and halts the system.
+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.
 .Sh RETURN VALUES
 The
 .Fn kern_reboot
@@ -107,4 +154,5 @@ function does not return.
 .Sh SEE ALSO
 .Xr reboot 2 ,
 .Xr EVENTHANDLER 9 ,
+.Xr panic 9 ,
 .Xr vfs_unmountall 9