d5e105bf7e
- 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: https://reviews.freebsd.org/D39132
160 lines
5.1 KiB
Groff
160 lines
5.1 KiB
Groff
.\" $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
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by Michael Graff
|
|
.\" for the NetBSD Project.
|
|
.\" 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
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd March 17, 2023
|
|
.Dt PANIC 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm panic
|
|
.Nd bring down system on fatal error
|
|
.Sh SYNOPSIS
|
|
.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 KERNEL_PANICKED
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn panic
|
|
and
|
|
.Fn vpanic
|
|
functions terminate the running system.
|
|
The message
|
|
.Fa fmt
|
|
is a
|
|
.Xr printf 3
|
|
style format string.
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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
|
|
and
|
|
.Xr gdb 4 .
|
|
The debugger may initiate a system reset, or it may eventually return.
|
|
.Pp
|
|
Finally,
|
|
.Xr kern_reboot 9
|
|
is called to restart the system, and a kernel dump will be requested.
|
|
If
|
|
.Fn panic
|
|
is called recursively (from the disk sync routines, for example),
|
|
.Fn kern_reboot
|
|
will be instructed not to sync the disks.
|
|
.Pp
|
|
The
|
|
.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.
|
|
.Pp
|
|
The
|
|
.Fn KERNEL_PANICKED
|
|
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.
|
|
.Sh EXECUTION 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
|
|
.It
|
|
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
|
|
and
|
|
.Xr sleepqueue 9
|
|
functions.
|
|
.It
|
|
Interrupts are disabled.
|
|
Device I/O (e.g. to the console) must be achieved with polling.
|
|
.It
|
|
Dynamic memory allocation cannot be relied on, and must be avoided.
|
|
.It
|
|
Lock acquisition/release will be ignored, meaning these operations will appear
|
|
to succeed.
|
|
.It
|
|
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.
|
|
.El
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn panic
|
|
and
|
|
.Fn vpanic
|
|
functions do not return.
|
|
.Sh SEE ALSO
|
|
.Xr printf 3 ,
|
|
.Xr ddb 4 ,
|
|
.Xr gdb 4 ,
|
|
.Xr KASSERT 9 ,
|
|
.Xr kern_reboot 9
|