git: 86e2335d10e5 - stable/13 - panic(9): some updates

From: Mitchell Horne <>
Date: Mon, 27 Mar 2023 17:21:54 UTC
The branch stable/13 has been updated by mhorne:


commit 86e2335d10e560c6b1809df58ce03864c5d09431
Author:     Mitchell Horne <>
AuthorDate: 2023-03-20 19:55:55 +0000
Commit:     Mitchell Horne <>
CommitDate: 2023-03-27 17:18:48 +0000

    panic(9): some updates
     - Better description of what the panic() function does
     - Document KERNEL_PANICKED()
     - Add a section describing panic execution context
     - Add SEE ALSO
    Reviewed by:    kib, markj, rpokala
    MFC after:      1 week
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:
    (cherry picked from commit d5e105bf7e4cb7e80eb4a4f8960bd6dd12fc4885)
 share/man/man9/Makefile |   3 +-
 share/man/man9/panic.9  | 109 ++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 99 insertions(+), 13 deletions(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index bab0cfb76134..f9ace3802494 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1729,7 +1729,8 @@ MLINKS+=osd.9 osd_call.9 \
 	osd.9 osd_reserve.9 \
 	osd.9 osd_set.9 \
 	osd.9 osd_set_reserved.9
-MLINKS+=panic.9 vpanic.9
+MLINKS+=panic.9 vpanic.9 \
 MLINKS+=PCBGROUP.9 in_pcbgroup_byhash.9 \
 	PCBGROUP.9 in_pcbgroup_byinpcb.9 \
 	PCBGROUP.9 in_pcbgroup_destroy.9 \
diff --git a/share/man/man9/panic.9 b/share/man/man9/panic.9
index c467b86dd5a1..bc9b1b9e85fb 100644
--- a/share/man/man9/panic.9
+++ b/share/man/man9/panic.9
@@ -1,7 +1,13 @@
 .\"     $NetBSD: panic.9,v 1.2 1996/10/09 17:20:04 explorer Exp $
+.\" SPDX-License-Identifier: BSD-4-Clause
 .\" Copyright (c) 1996 Michael Graff.
 .\" All rights reserved.
+.\" Copyright (c) 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
@@ -15,7 +21,7 @@
 .\"    must display the following acknowledgement:
 .\"      This product includes software developed by Michael Graff
 .\"      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
@@ -31,7 +37,7 @@
 .\" $FreeBSD$
-.Dd April 23, 2015
+.Dd March 17, 2023
 .Dt PANIC 9
@@ -40,10 +46,12 @@
 .In sys/types.h
 .In sys/systm.h
+.Vt extern char *panicstr;
 .Ft void
 .Fn panic "const char *fmt" ...
 .Ft void
 .Fn vpanic "const char *fmt" "va_list ap"
 .Fn panic
@@ -55,20 +63,97 @@ The message
 is a
 .Xr printf 3
 style format string.
-The message is printed to the console and the location
-.Fa panicstr
-is set to the address of the message text for retrieval from the OS
-core dump.
+The message is printed to the console and
+.Va panicstr
+is set pointing to the address of the message text.
+This can be retrieved from a core dump at a later time.
-If the kernel debugger is installed control is passed to it, otherwise
-an attempt to save a core dump of the OS to a configured dump device
-is made.
+Upon entering the
+.Fn panic
+function the panicking thread disables interrupts and calls
+.Xr critical_enter 9 .
+This prevents the thread from being preempted or interrupted while the system
+is still in a running state.
+Next, it will instruct the other CPUs in the system to stop.
+This synchronizes with other threads to prevent concurrent panic conditions
+from interfering with one another.
+In the unlikely event of concurrent panics, only one panicking thread will proceed.
+Control will be passed to the kernel debugger via
+.Fn kdb_enter .
+This is conditional on a debugger being installed and enabled by the
+.Va debugger_on_panic
+variable; see
+.Xr ddb 4
+.Xr gdb 4 .
+The debugger may initiate a system reset, or it may eventually return.
+.Xr kern_reboot 9
+is called to restart the system, and a kernel dump will be requested.
 .Fn panic
-is called twice (from the disk sync routines, for example) the system is
-rebooted without syncing the disks.
+is called recursively (from the disk sync routines, for example),
+.Fn kern_reboot
+will be instructed not to sync the disks.
+.Fn vpanic
+function implements the main body of
+.Fn panic .
+It is suitable to be called by functions which perform their own
+variable-length argument processing.
+In all other cases,
+.Fn panic
+is preferred.
+macro is the preferred way to determine if the system has panicked.
+It returns a boolean value.
+Most often this is used to avoid taking an action that cannot possibly succeed
+in a panic context.
+.\" TODO: This text describes the kernel debugger / kernel dump execution
+.\" context as well. It could be moved to a future kdb(9) page, and this
+.\" section would become a pointer.
+Once the panic has been initiated, code executing in a panic context is subject
+to the following restrictions:
+.Bl -bullet
+Single-threaded execution.
+The scheduler is disabled, and other CPUs are stopped/forced idle.
+Functions that manipulate the scheduler state must be avoided.
+This includes, but is not limited to,
+.Xr wakeup 9
+.Xr sleepqueue 9
+Interrupts are disabled.
+Device I/O (e.g. to the console) must be achieved with polling.
+Dynamic memory allocation cannot be relied on, and must be avoided.
+Lock acquisition/release will be ignored, meaning these operations will appear
+to succeed.
+Sleeping on a resource is not strictly prohibited, but will result in an
+immediate return from the sleep function.
+Time-based sleeps such as
+.Xr pause 9
+may be performed as a busy-wait.
 .Fn panic
-function does not return.
+.Fn vpanic
+functions do not return.
+.Xr printf 3 ,
+.Xr ddb 4 ,
+.Xr gdb 4 ,
+.Xr KASSERT 9 ,
+.Xr kern_reboot 9