1.\" $NetBSD: panic.9,v 1.2 1996/10/09 17:20:04 explorer Exp $ 2.\" 3.\" SPDX-License-Identifier: BSD-4-Clause 4.\" 5.\" Copyright (c) 1996 Michael Graff. 6.\" All rights reserved. 7.\" Copyright (c) 2023 The FreeBSD Foundation 8.\" 9.\" Portions of this documentation were written by Mitchell Horne 10.\" under sponsorship from the FreeBSD Foundation. 11.\" 12.\" Redistribution and use in source and binary forms, with or without 13.\" modification, are permitted provided that the following conditions 14.\" are met: 15.\" 1. Redistributions of source code must retain the above copyright 16.\" notice, this list of conditions and the following disclaimer. 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in the 19.\" documentation and/or other materials provided with the distribution. 20.\" 3. All advertising materials mentioning features or use of this software 21.\" must display the following acknowledgement: 22.\" This product includes software developed by Michael Graff 23.\" for the NetBSD Project. 24.\" 4. The name of the author may not be used to endorse or promote products 25.\" derived from this software without specific prior written permission 26.\" 27.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 28.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 29.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 30.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 31.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 32.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 33.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 34.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 35.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 36.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 37.\" 38.\" $FreeBSD$ 39.\" 40.Dd March 17, 2023 41.Dt PANIC 9 42.Os 43.Sh NAME 44.Nm panic 45.Nd bring down system on fatal error 46.Sh SYNOPSIS 47.In sys/types.h 48.In sys/systm.h 49.Vt extern char *panicstr; 50.Ft void 51.Fn panic "const char *fmt" ... 52.Ft void 53.Fn vpanic "const char *fmt" "va_list ap" 54.Fn KERNEL_PANICKED 55.Sh DESCRIPTION 56The 57.Fn panic 58and 59.Fn vpanic 60functions terminate the running system. 61The message 62.Fa fmt 63is a 64.Xr printf 3 65style format string. 66The message is printed to the console and 67.Va panicstr 68is set pointing to the address of the message text. 69This can be retrieved from a core dump at a later time. 70.Pp 71Upon entering the 72.Fn panic 73function the panicking thread disables interrupts and calls 74.Xr critical_enter 9 . 75This prevents the thread from being preempted or interrupted while the system 76is still in a running state. 77Next, it will instruct the other CPUs in the system to stop. 78This synchronizes with other threads to prevent concurrent panic conditions 79from interfering with one another. 80In the unlikely event of concurrent panics, only one panicking thread will proceed. 81.Pp 82Control will be passed to the kernel debugger via 83.Fn kdb_enter . 84This is conditional on a debugger being installed and enabled by the 85.Va debugger_on_panic 86variable; see 87.Xr ddb 4 88and 89.Xr gdb 4 . 90The debugger may initiate a system reset, or it may eventually return. 91.Pp 92Finally, 93.Xr kern_reboot 9 94is called to restart the system, and a kernel dump will be requested. 95If 96.Fn panic 97is called recursively (from the disk sync routines, for example), 98.Fn kern_reboot 99will be instructed not to sync the disks. 100.Pp 101The 102.Fn vpanic 103function implements the main body of 104.Fn panic . 105It is suitable to be called by functions which perform their own 106variable-length argument processing. 107In all other cases, 108.Fn panic 109is preferred. 110.Pp 111The 112.Fn KERNEL_PANICKED 113macro is the preferred way to determine if the system has panicked. 114It returns a boolean value. 115Most often this is used to avoid taking an action that cannot possibly succeed 116in a panic context. 117.Sh EXECUTION CONTEXT 118.\" TODO: This text describes the kernel debugger / kernel dump execution 119.\" context as well. It could be moved to a future kdb(9) page, and this 120.\" section would become a pointer. 121Once the panic has been initiated, code executing in a panic context is subject 122to the following restrictions: 123.Bl -bullet 124.It 125Single-threaded execution. 126The scheduler is disabled, and other CPUs are stopped/forced idle. 127Functions that manipulate the scheduler state must be avoided. 128This includes, but is not limited to, 129.Xr wakeup 9 130and 131.Xr sleepqueue 9 132functions. 133.It 134Interrupts are disabled. 135Device I/O (e.g. to the console) must be achieved with polling. 136.It 137Dynamic memory allocation cannot be relied on, and must be avoided. 138.It 139Lock acquisition/release will be ignored, meaning these operations will appear 140to succeed. 141.It 142Sleeping on a resource is not strictly prohibited, but will result in an 143immediate return from the sleep function. 144Time-based sleeps such as 145.Xr pause 9 146may be performed as a busy-wait. 147.El 148.Sh RETURN VALUES 149The 150.Fn panic 151and 152.Fn vpanic 153functions do not return. 154.Sh SEE ALSO 155.Xr printf 3 , 156.Xr ddb 4 , 157.Xr gdb 4 , 158.Xr KASSERT 9 , 159.Xr kern_reboot 9 160