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.Dd March 17, 2023 39.Dt PANIC 9 40.Os 41.Sh NAME 42.Nm panic 43.Nd bring down system on fatal error 44.Sh SYNOPSIS 45.In sys/types.h 46.In sys/systm.h 47.Vt extern char *panicstr; 48.Ft void 49.Fn panic "const char *fmt" ... 50.Ft void 51.Fn vpanic "const char *fmt" "va_list ap" 52.Fn KERNEL_PANICKED 53.Sh DESCRIPTION 54The 55.Fn panic 56and 57.Fn vpanic 58functions terminate the running system. 59The message 60.Fa fmt 61is a 62.Xr printf 3 63style format string. 64The message is printed to the console and 65.Va panicstr 66is set pointing to the address of the message text. 67This can be retrieved from a core dump at a later time. 68.Pp 69Upon entering the 70.Fn panic 71function the panicking thread disables interrupts and calls 72.Xr critical_enter 9 . 73This prevents the thread from being preempted or interrupted while the system 74is still in a running state. 75Next, it will instruct the other CPUs in the system to stop. 76This synchronizes with other threads to prevent concurrent panic conditions 77from interfering with one another. 78In the unlikely event of concurrent panics, only one panicking thread will proceed. 79.Pp 80Control will be passed to the kernel debugger via 81.Fn kdb_enter . 82This is conditional on a debugger being installed and enabled by the 83.Va debugger_on_panic 84variable; see 85.Xr ddb 4 86and 87.Xr gdb 4 . 88The debugger may initiate a system reset, or it may eventually return. 89.Pp 90Finally, 91.Xr kern_reboot 9 92is called to restart the system, and a kernel dump will be requested. 93If 94.Fn panic 95is called recursively (from the disk sync routines, for example), 96.Fn kern_reboot 97will be instructed not to sync the disks. 98.Pp 99The 100.Fn vpanic 101function implements the main body of 102.Fn panic . 103It is suitable to be called by functions which perform their own 104variable-length argument processing. 105In all other cases, 106.Fn panic 107is preferred. 108.Pp 109The 110.Fn KERNEL_PANICKED 111macro is the preferred way to determine if the system has panicked. 112It returns a boolean value. 113Most often this is used to avoid taking an action that cannot possibly succeed 114in a panic context. 115.Sh EXECUTION CONTEXT 116.\" TODO: This text describes the kernel debugger / kernel dump execution 117.\" context as well. It could be moved to a future kdb(9) page, and this 118.\" section would become a pointer. 119Once the panic has been initiated, code executing in a panic context is subject 120to the following restrictions: 121.Bl -bullet 122.It 123Single-threaded execution. 124The scheduler is disabled, and other CPUs are stopped/forced idle. 125Functions that manipulate the scheduler state must be avoided. 126This includes, but is not limited to, 127.Xr wakeup 9 128and 129.Xr sleepqueue 9 130functions. 131.It 132Interrupts are disabled. 133Device I/O (e.g. to the console) must be achieved with polling. 134.It 135Dynamic memory allocation cannot be relied on, and must be avoided. 136.It 137Lock acquisition/release will be ignored, meaning these operations will appear 138to succeed. 139.It 140Sleeping on a resource is not strictly prohibited, but will result in an 141immediate return from the sleep function. 142Time-based sleeps such as 143.Xr pause 9 144may be performed as a busy-wait. 145.El 146.Sh RETURN VALUES 147The 148.Fn panic 149and 150.Fn vpanic 151functions do not return. 152.Sh SEE ALSO 153.Xr printf 3 , 154.Xr ddb 4 , 155.Xr gdb 4 , 156.Xr KASSERT 9 , 157.Xr kern_reboot 9 158