panic(9): some updates
- 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
This commit is contained in:
parent
87132d1dce
commit
d5e105bf7e
@ -1733,7 +1733,8 @@ MLINKS+=osd.9 osd_call.9 \
|
||||
osd.9 osd_reserve.9 \
|
||||
osd.9 osd_set.9 \
|
||||
osd.9 osd_set_reserved.9
|
||||
MLINKS+=panic.9 vpanic.9
|
||||
MLINKS+=panic.9 vpanic.9 \
|
||||
panic.9 KERNEL_PANICKED.9
|
||||
MLINKS+=pci.9 pci_alloc_msi.9 \
|
||||
pci.9 pci_alloc_msix.9 \
|
||||
pci.9 pci_disable_busmaster.9 \
|
||||
|
@ -1,7 +1,13 @@
|
||||
.\" $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
|
||||
@ -15,7 +21,7 @@
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by Michael Graff
|
||||
.\" 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
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
||||
@ -31,7 +37,7 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd April 23, 2015
|
||||
.Dd March 17, 2023
|
||||
.Dt PANIC 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -40,10 +46,12 @@
|
||||
.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
|
||||
@ -55,20 +63,97 @@ The message
|
||||
is a
|
||||
.Xr printf 3
|
||||
style format string.
|
||||
The message is printed to the console and the location
|
||||
.Fa panicstr
|
||||
is set to the address of the message text for retrieval from the OS
|
||||
core dump.
|
||||
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
|
||||
If the kernel debugger is installed control is passed to it, otherwise
|
||||
an attempt to save a core dump of the OS to a configured dump device
|
||||
is made.
|
||||
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 twice (from the disk sync routines, for example) the system is
|
||||
rebooted without syncing the disks.
|
||||
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
|
||||
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
|
||||
|
Loading…
Reference in New Issue
Block a user