git: 26337c10f060 - stable/12 - boot(9): update to match reality

[Mitchell Horne]

The branch stable/12 has been updated by mhorne:

URL: https://cgit.FreeBSD.org/src/commit/?id=26337c10f060e6a25b1708d421056d28a5b608b0

commit 26337c10f060e6a25b1708d421056d28a5b608b0
Author:     Mitchell Horne <mhorne at FreeBSD.org>
AuthorDate: 2021-09-28 14:36:09 +0000
Commit:     Mitchell Horne <mhorne at FreeBSD.org>
CommitDate: 2021-10-04 14:17:05 +0000

    boot(9): update to match reality
    
    This function was renamed to kern_reboot() in 2010, but the man page has
    failed to keep in sync. Bring it up to date on the rename, add the
    shutdown hooks to the synopsis, and document the (obvious) fact that
    kern_reboot() does not return.
    
    Fix an outdated reference to the old name in kern_reboot(), and leave a
    reference to the man page so future readers might find it before any
    large changes.
    
    Reviewed by:    imp, markj
    MFC after:      3 days
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D32085
    
    (cherry picked from commit 800e74955d4e5f90e7258956ba42228350f71049)
---
 ObsoleteFiles.inc                        |  3 +++
 share/man/man9/Makefile                  |  2 +-
 share/man/man9/{boot.9 => kern_reboot.9} | 26 ++++++++++++++++++--------
 sys/kern/kern_shutdown.c                 |  5 +++--
 4 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc
index 3c505f9610f4..14c313c55377 100644
--- a/ObsoleteFiles.inc
+++ b/ObsoleteFiles.inc
@@ -38,6 +38,9 @@
 #   xargs -n1 | sort | uniq -d;
 # done
 
+# 20210923: rename boot(9) to kern_reboot(9)
+OLD_FILES+=usr/share/man/man9/boot.9.gz
+
 # 20201004: logo files renamed to type-agnostic gfx-*.lua
 OLD_FILES+=boot/lua/logo-beastie.lua
 OLD_FILES+=boot/lua/logo-beastiebw.lua
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 60ee6ea5aa1a..4068181e6327 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -16,7 +16,6 @@ MAN=	accept_filter.9 \
 	bhnd_erom.9 \
 	bios.9 \
 	bitset.9 \
-	boot.9 \
 	bpf.9 \
 	buf.9 \
 	buf_ring.9 \
@@ -178,6 +177,7 @@ MAN=	accept_filter.9 \
 	intro.9 \
 	ithread.9 \
 	KASSERT.9 \
+	kern_reboot.9 \
 	kern_testfrwk.9 \
 	kernacc.9 \
 	kernel_mount.9 \
diff --git a/share/man/man9/boot.9 b/share/man/man9/kern_reboot.9
similarity index 85%
rename from share/man/man9/boot.9
rename to share/man/man9/kern_reboot.9
index cbd0099e4e18..587d4ab114db 100644
--- a/share/man/man9/boot.9
+++ b/share/man/man9/kern_reboot.9
@@ -34,21 +34,25 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 14, 1997
-.Dt BOOT 9
+.Dd Sept 23, 2021
+.Dt KERN_REBOOT 9
 .Os
 .Sh NAME
-.Nm boot
+.Nm kern_reboot
 .Nd halt or reboot the system
 .Sh SYNOPSIS
 .In sys/types.h
 .In sys/systm.h
 .In sys/reboot.h
 .Ft void
-.Fn boot "int howto"
+.Fn kern_reboot "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 boot
+.Fn kern_reboot
 function handles final system shutdown, and either halts or reboots
 the system.
 The exact action to be taken is determined by the flags passed in
@@ -56,12 +60,12 @@ The exact action to be taken is determined by the flags passed in
 and by whether or not the system has finished autoconfiguration.
 .Pp
 If the system has finished autoconfiguration,
-.Fn boot
+.Fn kern_reboot
 does the following:
 .Bl -enum -offset indent
 .It
 If this is the first invocation of
-.Fn boot
+.Fn kern_reboot
 and the
 .Dv RB_NOSYNC
 flag is not set in
@@ -93,8 +97,14 @@ Otherwise, reboots the system.
 .El
 .Pp
 If the system has not finished autoconfiguration,
-.Fn boot
+.Fn kern_reboot
 runs any shutdown hooks previously registered,
 prints a message, and halts the system.
+.Sh RETURN VALUES
+The
+.Fn kern_reboot
+function does not return.
 .Sh SEE ALSO
+.Xr reboot 2
+.Xr EVENTHANDLER 9
 .Xr vfs_unmountall 9
diff --git a/sys/kern/kern_shutdown.c b/sys/kern/kern_shutdown.c
index b8183afec745..969280513e40 100644
--- a/sys/kern/kern_shutdown.c
+++ b/sys/kern/kern_shutdown.c
@@ -386,7 +386,8 @@ doadump(boolean_t textdump)
 }
 
 /*
- * Shutdown the system cleanly to prepare for reboot, halt, or power off.
+ * kern_reboot(9): Shut down the system cleanly to prepare for reboot, halt, or
+ * power off.
  */
 void
 kern_reboot(int howto)
@@ -415,7 +416,7 @@ kern_reboot(int howto)
 		sched_bind(curthread, CPU_FIRST());
 		thread_unlock(curthread);
 		KASSERT(PCPU_GET(cpuid) == CPU_FIRST(),
-		    ("boot: not running on cpu 0"));
+		    ("%s: not running on cpu 0", __func__));
 	}
 #endif
 	/* We're in the process of rebooting. */