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_reserve.9 \
|
||||||
osd.9 osd_set.9 \
|
osd.9 osd_set.9 \
|
||||||
osd.9 osd_set_reserved.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 \
|
MLINKS+=pci.9 pci_alloc_msi.9 \
|
||||||
pci.9 pci_alloc_msix.9 \
|
pci.9 pci_alloc_msix.9 \
|
||||||
pci.9 pci_disable_busmaster.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 $
|
.\" $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.
|
.\" Copyright (c) 1996 Michael Graff.
|
||||||
.\" All rights reserved.
|
.\" 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
|
.\" 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
|
||||||
@ -15,7 +21,7 @@
|
|||||||
.\" 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
|
||||||
@ -31,7 +37,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd April 23, 2015
|
.Dd March 17, 2023
|
||||||
.Dt PANIC 9
|
.Dt PANIC 9
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -40,10 +46,12 @@
|
|||||||
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
||||||
.In sys/types.h
|
.In sys/types.h
|
||||||
.In sys/systm.h
|
.In sys/systm.h
|
||||||
|
.Vt extern char *panicstr;
|
||||||
.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
|
||||||
@ -55,20 +63,97 @@ The message
|
|||||||
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
|
||||||
|
.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
|
.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
|
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.
|
||||||
|
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
|
.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
|
||||||
|
Loading…
Reference in New Issue
Block a user