Differential D39132 Diff 119145 share/man/man9/panic.9

Changeset View

Standalone View

share/man/man9/panic.9

.\" $NetBSD: panic.9,v 1.2 1996/10/09 17:20:04 explorer Exp $ .\" $NetBSD: panic.9,v 1.2 1996/10/09 17:20:04 explorer Exp $

.\" .\"

.\" SPDX-License-Identifier: BSD-4-Clause

.\"

.\" .\"

.\" 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 .\" Redistribution and use in source and binary forms, with or without

.\" modification, are permitted provided that the following conditions .\" modification, are permitted provided that the following conditions

.\" are met: .\" are met:

.\" 1. Redistributions of source code must retain the above copyright .\" 1. Redistributions of source code must retain the above copyright

.\" notice, this list of conditions and the following disclaimer. .\" notice, this list of conditions and the following disclaimer.

.\" 2. Redistributions in binary form must reproduce the above copyright .\" 2. Redistributions in binary form must reproduce the above copyright

.\" notice, this list of conditions and the following disclaimer in the .\" notice, this list of conditions and the following disclaimer in the

.\" documentation and/or other materials provided with the distribution. .\" documentation and/or other materials provided with the distribution.

.\" 3. All advertising materials mentioning features or use of this software .\" 3. All advertising materials mentioning features or use of this software

.\" must display the following acknowledgement: .\" must display the following acknowledgement:

.\" This product includes software developed by Michael Graff .\" This product includes software developed by Michael Graff

.\" for the NetBSD Project. .\" 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 .\" derived from this software without specific prior written permission

.\" .\"

.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR

.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.

.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,

.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT

.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF

.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

.\" .\"

.\" $FreeBSD$ .\" $FreeBSD$

.\" .\"

.Dd April 23, 2015 .Dd March 17, 2023

.Dt PANIC 9 .Dt PANIC 9

.Os .Os

.Sh NAME .Sh NAME

.Nm panic .Nm panic

.Nd bring down system on fatal error .Nd bring down system on fatal error

.Sh SYNOPSIS .Sh SYNOPSIS

.In sys/types.h .In sys/types.h

.In sys/systm.h .In sys/systm.h

.Vt extern char *panicstr;

kibUnsubmitted

Not Done

Again, traditionally it was sys/systm.h, and we should offer either of the headers as the correct one.

kib: Again, traditionally it was sys/systm.h, and we should offer either of the headers as the…

.Ft void .Ft void

.Fn panic "const char *fmt" ... .Fn panic "const char *fmt" ...

.Ft void .Ft void

.Fn vpanic "const char *fmt" "va_list ap" .Fn vpanic "const char *fmt" "va_list ap"

.Fn KERNEL_PANICKED

.Sh DESCRIPTION .Sh DESCRIPTION

The The

.Fn panic .Fn panic

and and

.Fn vpanic .Fn vpanic

functions terminate the running system. functions terminate the running system.

The message The message

.Fa fmt .Fa fmt

is a is a

.Xr printf 3 .Xr printf 3

style format string. style format string.

The message is printed to the console and the location The message is printed to the console and

.Fa panicstr .Va panicstr

is set to the address of the message text for retrieval from the OS is set pointing to the address of the message text.

core dump. This can be retrieved from a core dump at a later time.

.Pp .Pp

If the kernel debugger is installed control is passed to it, otherwise Upon entering the

an attempt to save a core dump of the OS to a configured dump device .Fn panic

is made. function the panicking thread disables interrupts and calls

markjUnsubmitted

Done

I would just say that it disables interrupts. spinlock_enter() just happens to be the name of the MI function used for that purpose.

markj: I would just say that it disables interrupts. spinlock_enter() just happens to be the name of…

mhorneAuthorUnsubmitted

Done

@rpokala I added a short paragraph that clarifies vpanic(), but I prefer to keep mentions of it out of the main body of the description.

@markj yes, I thought that name was somewhat suspect.

mhorne: @rpokala I added a short paragraph that clarifies vpanic(), but I prefer to keep mentions of it…

rpokalaUnsubmitted

Done

When
.Fn panic
or
.Fn vpanic
is entered, the calling thread takes its spinlock.

rpokala: When .Fn panic or .Fn vpanic is entered, the calling thread takes its spinlock.

.Xr critical_enter 9 .

markjUnsubmitted

Not Done

Not related to the patch, just a general question: why do spinlock_enter()/_exit() enter a critical section at all? I would expect disabling interrupts to have the same effect, at least in non-INVARIANTS kernels.

markj: Not related to the patch, just a general question: why do spinlock_enter()/_exit() enter a…

kibUnsubmitted

Not Done

To prevent context switches in the code executed under spinlock. As an example, imagine that some code took a spinlock, then does critical_enter()/critical_exit(). If owe_preempt is set, we end up trying to reschedule.

kib: To prevent context switches in the code executed under spinlock. As an example, imagine that…

markjUnsubmitted

Not Done

Oops, of course. Thanks.

markj: Oops, of course. Thanks.

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.

kibUnsubmitted

Not Done

I believe the 'first time' is somewhat confusing. The situation you describe is actually the concurrent calls.

kib: I believe the 'first time' is somewhat confusing. The situation you describe is actually the…

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.

rpokalaUnsubmitted

Done

In the unlikely event of concurrent panics, only one panicking thread will proceed.

rpokala: In the unlikely event of concurrent panics, only one panicking thread will proceed.

markjUnsubmitted

Done

This can be retrieved from a core dump at a later time.

.Pp

- When entering the

+ Upon entering the

.Fn panic

markj:

.Pp .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

rpokalaUnsubmitted

Done

is called to restart the system, attempting a kernel dump in the process.

rpokala: is called to restart the system, attempting a kernel dump in the process.

variable; see

.Xr ddb 4

markjUnsubmitted

Done

It'd be worth mentioning debugger_on_panic IMO.

markj: It'd be worth mentioning `debugger_on_panic` IMO.

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 If

.Fn panic .Fn panic

is called twice (from the disk sync routines, for example) the system is is called recursively (from the disk sync routines, for example),

rebooted without syncing the disks. .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.

markjUnsubmitted

Done

Interrupts are disabled.

- Device I/O (e.g. console) must be achieved with polling.

+ 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.

markj:

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

markjUnsubmitted

Done

Dynamic memory allocation cannot be relied on, and must be avoided.

.It

- Lock acquisition/release will be ignored, meaning these calls will appear to

+ Lock acquisition/release will be ignored, meaning these operations will appear to

succeed.

markj:

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

markjUnsubmitted

Done

Maybe "called recursively" would be more clear?

markj: Maybe "called recursively" would be more clear?

.Sh RETURN VALUES .Sh RETURN VALUES

The The

.Fn panic .Fn panic

function does not return. 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