xref: /freebsd/share/man/man9/panic.9 (revision e6bfd18d21b225af6a0ed67ceeaf1293b7b9eba5)
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