From nobody Mon Mar 27 17:21:54 2023 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4PlfkV3qfCz41p8h; Mon, 27 Mar 2023 17:21:54 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4PlfkV2v9Xz4Qss; Mon, 27 Mar 2023 17:21:54 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679937714; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=z6IgNjE3jkifOXq277Dt5shRabJ5HExRS/xtj5K2h0A=; b=AxZFckItTcndx41pQHc73quyryM2z+tXDOesTp53NtPzbFnt0+Cmr+tWLZgK+R1d3GCOqd vARXKoy45+qoRc+ypk0mY9/y8xKa6gmOugZ3qp+qgeyz+jf+uCBnjlelTEDq0tGO4Jz1m8 CP0FPRTr8yWgYrhRvHe5Ry0miu2Hav66DlUo2tgOgnxbrfDTv/VP0JIl5HWHxH7I0etqnq EYmjwZCA7trdGUUvlp01l5HC+Dho3dwOX+LeQ2a27ONFd153N1TH+l1dRMEOld0FUPU9IQ ZRf6a7lkRIT8mOsx5rxJu1xW85penxHb5kDpa18Wvb/Q4oL21Rva5qjCR8c32w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679937714; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=z6IgNjE3jkifOXq277Dt5shRabJ5HExRS/xtj5K2h0A=; b=ApuhqGjhkC36+pMb1S6ojGaQCchjWKhZuD54+PrqRcbFdV7PSlgIrpWWyKUqR5fq9yWCcJ 2+Ln8y8N/F4uInKXDr3STnW6jtfgTUVmOlKaPAxIFyFzxgF7y/1Y5MJLJvbNoW3wJ5NTMV /rbD4WvobqhQxnni2OXsZkPyTM3YQXUm66O/PLg1YzTxIDlsaVCi4oFV+JzwNfPmNINqOW RBv6S93qaJX8J1ZGCK9VgUtkGY9N2znSPo14NAXSgysp7ihMe/DceVMB7ekj7swfb+3yVv ymKQWvcpKIbL5QXSgXaez/7iglXrXTdap/tBz1C17EzSGs+rrCL3eeypcYvpYg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1679937714; a=rsa-sha256; cv=none; b=TY9qpIoUVZJHmZDyjV5t6xFm3sFzuN//HWfOAKREVz9yNr1NJYY5z0S2brO7YA7IZIYj6d arqjA/Hl7mpk60xApveazNqOO3c+XSTSUyvw0UVQIAbj+uOhi+GmmaNfaGVkBiixGfkCyO 5MtpbuL4QknPG0SXRU67C0NrMM5VkhnKnYknJ6x0I8N9H1hJbOR6tTS0EG77VtmKwAmOFE XtvTVN5QS0yWlyygA0H9pfCVfLfP6ScNVSm5z/oa85kD2JJsVGux3IdghelQ8IJ/BKIMgZ 0eHYdoCwOJqrZGS1LfPZ1gYDmxTI9d0h5Ws3cg4J+WwiqBTv27bRL39iuR0ssw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4PlfkV1rYNzW25; Mon, 27 Mar 2023 17:21:54 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 32RHLsX4051948; Mon, 27 Mar 2023 17:21:54 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 32RHLsew051947; Mon, 27 Mar 2023 17:21:54 GMT (envelope-from git) Date: Mon, 27 Mar 2023 17:21:54 GMT Message-Id: <202303271721.32RHLsew051947@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Mitchell Horne Subject: git: 86e2335d10e5 - stable/13 - panic(9): some updates List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: mhorne X-Git-Repository: src X-Git-Refname: refs/heads/stable/13 X-Git-Reftype: branch X-Git-Commit: 86e2335d10e560c6b1809df58ce03864c5d09431 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch stable/13 has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=86e2335d10e560c6b1809df58ce03864c5d09431 commit 86e2335d10e560c6b1809df58ce03864c5d09431 Author: Mitchell Horne AuthorDate: 2023-03-20 19:55:55 +0000 Commit: Mitchell Horne CommitDate: 2023-03-27 17:18:48 +0000 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 (cherry picked from commit d5e105bf7e4cb7e80eb4a4f8960bd6dd12fc4885) --- share/man/man9/Makefile | 3 +- share/man/man9/panic.9 | 109 ++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 99 insertions(+), 13 deletions(-) diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index bab0cfb76134..f9ace3802494 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1729,7 +1729,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+=PCBGROUP.9 in_pcbgroup_byhash.9 \ PCBGROUP.9 in_pcbgroup_byinpcb.9 \ PCBGROUP.9 in_pcbgroup_destroy.9 \ diff --git a/share/man/man9/panic.9 b/share/man/man9/panic.9 index c467b86dd5a1..bc9b1b9e85fb 100644 --- a/share/man/man9/panic.9 +++ b/share/man/man9/panic.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