From nobody Mon Mar 20 20:13:30 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 4PgQsk46S4z40Br8; Mon, 20 Mar 2023 20:13:30 +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 4PgQsk1mmCz3JF2; Mon, 20 Mar 2023 20:13:30 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679343210; 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=rY3zq4raVW6hMAPnJK7vkf49ZrSu1dspoVStVz8leq0=; b=e5L6iyLTwr1SHLIfxrhPb2zCR2msApRjGulaJAnbu6RoP4NXUWMq0NFy35lVolzwo//dBN 1G5Bi6QkrqyrwWG2XA8Hzj6ZbZEzQEjcwkdBn0nrX/nQI8YHLege3VbEn3FrKEyiu+WR/K idfxsMum8FCCHYRhrHVu9CqfCXQZzwmBrjw2QeOHl7EfZlDTT4J0UkwX8H3pnhN9+QRd7b EcdiqUtjCVwPMkg5AZt3rzcVWBQwnYdl1ot9Z+xbT5DaNrvjeNpiWcqeaZC4+Whkn0JSq3 sY7QpWNhdeptY0xFMw/zZRCZY5/KS084UP1NH6uspQ/hyPAj39mRv70949g/gA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679343210; 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=rY3zq4raVW6hMAPnJK7vkf49ZrSu1dspoVStVz8leq0=; b=Xuqfji32r4266kdq3TQf85XhHZmSEsopBw49a9q2FmyPkzxA/o/O5sfsX3T4vGjdAL4wK5 Zr1O/HA1Zm3AmZyfXgoxt2h8ySQY15DfNr9mLzZn6f3U/1ea/OO8EZczwbIpiMvTqUA1Rb uDZQjYa4QHS+6KQGwtJWil693shBAfjyXXvw/Q0NkhsRLZJ9ToYq+/nz3FSSEUQA+so3T3 h4VYhR1A6OJqBP+pkMjO8ug091LpJidEFbAwDmEf8G2aJHCzjliU57I+FGohlOXe1Uhm/A yGfSMJ6otqy7BNy9+p9TumF3CMbTYPrOh7vSMh/UYjL3ZN6wfiQoW1vsG+k5RQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1679343210; a=rsa-sha256; cv=none; b=IUEP8V75g+mUsQNlZVfXpNdLc7MSjQoECXQF/6XjBcoG75q/fXRzKctzT19yFR09eCTOXv g81VYkS3hjnW6nm/fL+2J+yeVWJIwC8a7KMI4+oz8e75kojl7kvhOO6BDkfrKf4EJWK+zk yyS0n+hB51GiJ5DbwTzrXm0os7AjOr1f1D55ehCvU9SavE02ljwtIYeXXbyByAc3pYQQxX WQsXHbykeZeGeddqWLV452J2NWFXHLjmjvCdlfvKx0TZ0DXzKiRmW0AbHQJkuMtl5YP7t9 FnePkVnXm4gq8tTnLWqjfzJ+SkVFSdMiwuz6cXAzefMhHnrSFphbi7TjpfkYtg== 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 4PgQsk0t1FzkDX; Mon, 20 Mar 2023 20:13:30 +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 32KKDU57033179; Mon, 20 Mar 2023 20:13:30 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 32KKDUS6033178; Mon, 20 Mar 2023 20:13:30 GMT (envelope-from git) Date: Mon, 20 Mar 2023 20:13:30 GMT Message-Id: <202303202013.32KKDUS6033178@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Mitchell Horne Subject: git: f6f8cbda8efc - main - kern_reboot(9): describe event handlers 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/main X-Git-Reftype: branch X-Git-Commit: f6f8cbda8efcd32a312655842097e9095ee3e0fb Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=f6f8cbda8efcd32a312655842097e9095ee3e0fb commit f6f8cbda8efcd32a312655842097e9095ee3e0fb Author: Mitchell Horne AuthorDate: 2023-03-20 19:58:48 +0000 Commit: Mitchell Horne CommitDate: 2023-03-20 20:12:12 +0000 kern_reboot(9): describe event handlers Add more details about the execution and purpose of these shutdown handlers. Make a point to mention the requirement that they can be run in a normal or panic context. Add some simple examples. Add a brief comment to the declaration in sys/eventhandler.h. Reviewed by: markj Discussed with: rpokala, Pau Amma MFC after: 1 week Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D39135 --- share/man/man9/kern_reboot.9 | 111 +++++++++++++++++++++++++++++++++++++++++++ sys/sys/eventhandler.h | 9 +++- 2 files changed, 119 insertions(+), 1 deletion(-) diff --git a/share/man/man9/kern_reboot.9 b/share/man/man9/kern_reboot.9 index d120a437c521..a82b53382687 100644 --- a/share/man/man9/kern_reboot.9 +++ b/share/man/man9/kern_reboot.9 @@ -128,6 +128,9 @@ Print a message indicating that the system is about to be halted or rebooted, and a report of the total system uptime. .It Execute all registered shutdown hooks. +See +.Sx SHUTDOWN HOOKS +below. .It As a last resort, if none of the shutdown hooks handled the reboot, call the machine-dependent @@ -172,6 +175,58 @@ is called before the process has been spawned, or if the system has panicked or otherwise halted, .Fn kern_reboot will be called directly. +.Sh SHUTDOWN HOOKS +The system defines three separate +.Xr EVENTHANDLER 9 +events, which are invoked successively during the shutdown procedure. +These are +.Va shutdown_pre_sync , +.Va shutdown_post_sync , +and +.Va shutdown_final . +They will be executed unconditionally in the listed order. +Handler functions registered to any of these events will receive the value of +.Fa howto +as their second argument, which may be used to decide what action to take. +.Pp +The +.Va shutdown_pre_sync +event is invoked before syncing filesystems to disk. +It enables any action or state transition that must happen before this point to +take place. +.Pp +The +.Va shutdown_post_sync +event is invoked at the point immediately after the filesystem sync has +finished. +It enables, for example, disk drivers to complete the sync by flushing their +cache to disk. +Note that this event still takes place before the optional kernel core dump. +.Pp +The +.Va shutdown_final +event is invoked as the very last step of +.Fn kern_reboot . +Drivers and subsystems such as +.Xr acpi 4 +can register handlers to this event that will perform the actual reboot, +power-off, or halt. +.Pp +Notably, the +.Va shutdown_final +event is also the point at which all kernel modules will have their shutdown +.Po +.Dv MOD_SHUTDOWN +.Pc +hooks executed, and when the +.Xr DEVICE_SHUTDOWN 9 +method will be executed recursively on all devices. +.Pp +All event handlers, like +.Fn kern_reboot +itself, may be run in either normal shutdown context or a kernel panic or +debugger context. +Handler functions are expected to take care not to trigger recursive panics. .Sh RETURN VALUES The .Fn kern_reboot @@ -183,9 +238,65 @@ function will usually return to its caller, having initiated the asynchronous system shutdown. It will not return when called from a panic or debugger context, or during early boot. +.Sh EXAMPLES +A hypothetical driver, foo(4), defines a +.Va shutdown_final +event handler that can handle system power-off by writing to a device register, +but it does not handle halt or reset. +.Bd -literal -offset indent +void +foo_poweroff_handler(struct void *arg, int howto) +{ + struct foo_softc *sc = arg; + uint32_t reg; + + if ((howto & RB_POWEROFF) != 0) { + reg = FOO_POWEROFF; + WRITE4(sc, FOO_POWEROFF_REG, reg); + } +} +.Ed +.Pp +The handler is then registered in the device attach routine: +.Bd -literal -offset indent +int +foo_attach(device_t dev) +{ + struct foo_softc *sc; + + ... + + /* Pass the device's software context as the private arg. */ + EVENTHANDLER_REGISTER(shutdown_final, foo_poweroff_handler, sc, + SHUTDOWN_PRI_DEFAULT); + + ... +} +.Ed +.Pp +This +.Va shutdown_final +handler uses the +.Dv RB_NOSYNC +flag to detect that a panic or other unusual condition has occurred, and +returns early: +.Bd -literal -offset indent +void +bar_shutdown_final(struct void *arg, int howto) +{ + + if ((howto & RB_NOSYNC) != 0) + return; + + /* Some code that is not panic-safe. */ + ... +} +.Ed .Sh SEE ALSO .Xr reboot 2 , .Xr init 8 , +.Xr DEVICE_SHUTDOWN 9 , .Xr EVENTHANDLER 9 , +.Xr module 9 , .Xr panic 9 , .Xr vfs_unmountall 9 diff --git a/sys/sys/eventhandler.h b/sys/sys/eventhandler.h index 8c45431c83c3..be5a027f4743 100644 --- a/sys/sys/eventhandler.h +++ b/sys/sys/eventhandler.h @@ -184,7 +184,14 @@ eventhandler_tag vimage_eventhandler_register(struct eventhandler_list *list, #define EVENTHANDLER_PRI_ANY 10000 #define EVENTHANDLER_PRI_LAST 20000 -/* Shutdown events */ +/* + * Successive shutdown events invoked by kern_reboot(9). + * + * Handlers will receive the 'howto' value as their second argument. + * + * All handlers must be prepared to be executed from a panic/debugger context; + * see the man page for details. + */ typedef void (*shutdown_fn)(void *, int); #define SHUTDOWN_PRI_FIRST EVENTHANDLER_PRI_FIRST