Date: Mon, 20 Mar 2023 20:13:27 GMT From: Mitchell Horne <mhorne@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: d55c1877386f - main - kern_reboot(9): some updates Message-ID: <202303202013.32KKDRpK033129@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=d55c1877386fd411129ee6d4019beda37b7f1c89 commit d55c1877386fd411129ee6d4019beda37b7f1c89 Author: Mitchell Horne <mhorne@FreeBSD.org> AuthorDate: 2023-03-20 19:56:54 +0000 Commit: Mitchell Horne <mhorne@FreeBSD.org> CommitDate: 2023-03-20 20:12:12 +0000 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 | 3 +- share/man/man9/Makefile | 1 + share/man/man9/kern_reboot.9 | 108 +++++++++++++++++++++++++++++++------------ 3 files changed, 81 insertions(+), 31 deletions(-) diff --git a/lib/libc/sys/reboot.2 b/lib/libc/sys/reboot.2 index 99d5dcc42808..2e145e3651df 100644 --- a/lib/libc/sys/reboot.2 +++ b/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 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index eb6b37f41650..b03993b57860 100644 --- a/share/man/man9/Makefile +++ b/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 diff --git a/share/man/man9/kern_reboot.9 b/share/man/man9/kern_reboot.9 index fe8ccd7390c3..e88574cce0d1 100644 --- a/share/man/man9/kern_reboot.9 +++ b/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 -.Dt KERN_REBOOT 9 +.Dd March 20, 2023 +.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 -the system. +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 -and by whether or not the system has finished autoconfiguration. +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 -.Fn kern_reboot -and the +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 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. -.It -If rebooting after a crash (i.e., if +If rebooting after a panic +.Po .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 -or rebooted. +Execute all registered shutdown hooks. .It -If -.Dv RB_HALT -is set in -.Fa howto , -halts the system. -Otherwise, reboots the system. +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 -If the system has not finished autoconfiguration, .Fn kern_reboot -runs any shutdown hooks previously registered, -prints a message, and halts the system. +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. .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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202303202013.32KKDRpK033129>