feat: improve user-mode and kernel-mode driver panic handlers by Alan632 · Pull Request #642 · microsoft/windows-drivers-rs

Alan632 · 2026-04-16T00:24:34Z

Description

Previous panic handlers would initiate an infinite loop.

This PR adds custom panic handler implementations for both WDM/KMDF and UMDF Rust drivers and focuses on providing best effort information to a debugger.

TODO: Update the UMDF cargo-wdk lib.rs template to include UMDF panic registration. New issue created to track this: Issue 646

Verification

Verified with sample-kmdf-driver (kernel mode) by initiating panic and extracting panic/bugcheck info from post mortem memory dump.
Verified with sample-umdf-driver (user mode) by initiating panic and viewing output in DebugView.

…rnel panic handler and clean up documentation

Copilot

Pull request overview

Adds improved panic handling for Windows Drivers Rust (WDR) targets: kernel-mode panics now trigger a bugcheck with source-location metadata, and UMDF drivers can install a std panic hook to emit panic info to the debugger.

Changes:

Implement WDM/KMDF panic handler that calls KeBugCheckEx with panic location parameters.
Add UMDF-only install_panic_hook() to print panic info (and break into debugger in debug builds).
Add wdk-panic build script + dependencies and update UMDF template to install the hook.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
crates/wdk-panic/src/lib.rs	Adds kernel bugcheck panic handler + UMDF panic hook installer and updates crate docs/cfgs.
crates/wdk-panic/build.rs	Adds build script to emit WDK cfg settings for conditional compilation.
crates/wdk-panic/Cargo.toml	Adds `wdk` dependency and `wdk-build` build-dependency.
crates/cargo-wdk/templates/umdf/lib.rs.tmp	Calls `wdk_panic::install_panic_hook()` in UMDF `DriverEntry`.
crates/cargo-wdk/templates/umdf/Cargo.toml.tmp	Adds `wdk-panic` dependency to UMDF template.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-16T00:33:50Z

+[dependencies]
+wdk.workspace = true
+
+[build-dependencies]
+wdk-build.workspace = true


wdk-panic now adds a new public API (install_panic_hook) and changes panic behavior for WDM/KMDF (bugcheck instead of an infinite loop), but the crate version remains 0.4.1. Please bump the crate version (and update the changelog in the release process) so downstream consumers/templates can depend on a version that actually contains this API/behavior.

version bumps happen in release prs

Copilot · 2026-04-16T00:33:50Z


 [dependencies]
 wdk = "0.4.1"
+wdk-panic = "0.4.1"


The UMDF template pins wdk-panic = "0.4.1", but this PR introduces the install_panic_hook API. If a user generates a project and pulls from crates.io, it will fail to compile unless the template is updated to the new wdk-panic version (or the template version is substituted during release).

Suggested change

wdk-panic = "0.4.1"

wdk-panic = "0.5.1"

Will update after release.

Can this not be added now? i think we had infra to not run certain tests in release prs

That logic works only in release-plz PRs so we can't switch to 0.5.1 in this PR. We have to wait until the next release.

…ivers-rs into panic_handler

Copilot

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-17T19:29:06Z

 pub unsafe extern "system" fn driver_entry(
   _driver: PDRIVER_OBJECT,
   _registry_path: PCUNICODE_STRING,
 ) -> NTSTATUS {


wdk_panic::install_panic_hook() is only defined under #[cfg(all(not(test), driver_model__driver_type = "UMDF"))]. Calling it unconditionally from driver_entry will fail to compile when building with cfg(test) (e.g., cargo test). Gate the call with #[cfg(not(test))] (or relax the cfg on install_panic_hook) so test builds don’t break.

Suggested change

) -> NTSTATUS {

) -> NTSTATUS {

#[cfg(not(test))]

…e_case Windows API

Copilot

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Alan632 <aln.noda7@gmail.com>

Copilot

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

codecov-commenter · 2026-04-17T23:09:54Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.45%. Comparing base (5748ea2) to head (26798a0).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #642      +/-   ##
==========================================
+ Coverage   78.44%   79.45%   +1.00%     
==========================================
  Files          25       26       +1     
  Lines        5201     5500     +299     
  Branches     5201     5500     +299     
==========================================
+ Hits         4080     4370     +290     
  Misses       1001     1001              
- Partials      120      129       +9

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…in umdf

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

…ivers-rs into panic_handler

Copilot

Pull request overview

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-20T22:32:49Z

+/// Registers a panic hook for UMDF drivers that prints panic information via
+/// [`wdk::println!`] and then aborts the host process.
+///
+/// Output is routed through [`OutputDebugStringA`], which is received by any


Rustdoc link [OutputDebugStringA] is unqualified and likely resolves to no item in this crate, which will trigger broken_intra_doc_links (docs CI uses RUSTDOCFLAGS=-D warnings). Prefer either fully qualifying it (e.g., wdk_sys::windows::OutputDebugStringA with an appropriate direct dependency) or formatting it as code (backticks) instead of an intra-doc link.

Suggested change

/// Output is routed through [`OutputDebugStringA`], which is received by any

/// Output is routed through `OutputDebugStringA`, which is received by any

wmmc88 · 2026-04-24T00:15:15Z

+#[cfg(all(not(test), driver_model__driver_type = "UMDF"))]
+pub fn install_panic_hook() {
+    std::panic::set_hook(Box::new(|info| {
+        wdk::println!("[PANIC] {info}");


do you have a sample output of how this looks like when you have a debugger attached to the umdf driver?

wmmc88 · 2026-04-24T00:15:15Z

+
+    // High, uncommon bugcheck code to avoid collision with OS-defined identifiers.
+    // Lower 24 bits spell `PNC` (0x50 'P', 0x4E 'N', 0x43 'C') for recognizability.
+    const BUGCHECK_RUST_CODE: u32 = 0x8050_4E43;


I think this reads better if we derive it from the ASCII tag instead of spelling the hex literal directly. Something like const RUST_PANIC_BUGCHECK_CODE: u32 = u32::from_be_bytes(*b"RPNC"); keeps the same value but makes the intent much clearer. Also i think starting with 0x8 is not provably necessary.

gurry

LGTM. Just one minor comment on a safety comment.

gurry · 2026-05-05T04:38:07Z

+        // SAFETY: `KeBugCheckEx` is a Windows kernel API exported by `ntoskrnl.exe`
+        // that is callable at any IRQL and never returns (it halts the system with a
+        // bugcheck). The parameters are scalar `usize` values recorded in the crash
+        // dump; `KeBugCheckEx` does not dereference `panic_filename_ptr` — it is stored
+        // as an opaque value for post-mortem analysis. The FFI signature matches the
+        // WDK declaration in `wdm.h`. This call is sound because:
+        // 1. The function is always available in kernel mode (linked via ntoskrnl.lib).
+        // 2. The calling convention is correct (`extern "system"` maps to the
+        //    appropriate Windows calling convention for the target architecture).
+        // 3. The `-> !` return type is upheld — `KeBugCheckEx` never returns.


A safety comment only needs to explain that you are calling the function correctly and upholding its pre-conditions, e.g. arguments being passed are valid, lifetimes are not violoated etc. It need not explain that the function is declared correctly which this comment seems to do.

(Assuming the declaration is correct) this function is always safe to call, regardless of arg values. So may be that's what the comment should say.

+1

i think the only thing worth calling out here is that KeBugCheckEx is callable at every irql

gurry · 2026-05-05T04:52:31Z

+/// wdk_panic::install_panic_hook();
+/// ```
+#[cfg(all(not(test), driver_model__driver_type = "UMDF"))]
+pub fn install_panic_hook() {


Longer term we could automatically insert a call to this function in a UMDF driver through the #[driver_entry] attribute provided by the wdf crate.

+1! there are various versions of attribute macros floating around to help with the friction around bridging the gap between c callbacks and rust functions. this is definitely one of the things we can put in the glue layer

gurry · 2026-05-05T06:27:04Z


 [dependencies]
 wdk = "0.4.1"
+wdk-panic = "0.4.1"


That logic works only in release-plz PRs so we can't switch to 0.5.1 in this PR. We have to wait until the next release.

Alan Ngo added 2 commits March 31, 2026 14:45

panic handler initial commit

74d6234

add dependency to wdk::dbg_break, add umdf panic handler, refactor ke…

201ed02

…rnel panic handler and clean up documentation

Alan632 self-assigned this Apr 16, 2026

Copilot AI review requested due to automatic review settings April 16, 2026 00:24

Copilot started reviewing on behalf of Alan632 April 16, 2026 00:27 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

Alan632 and others added 2 commits April 16, 2026 14:49

Merge branch 'main' into panic_handler

e78ad0c

update Cargo.lock

e44556f

Copilot AI review requested due to automatic review settings April 17, 2026 19:23

Copilot started reviewing on behalf of Alan632 April 17, 2026 19:24 View session

Alan632 and others added 3 commits April 17, 2026 12:25

Merge branch 'main' into panic_handler

aa2dfc1

formatting

018c845

Merge branch 'panic_handler' of https://github.com/Alan632/windows-dr…

f821aac

…ivers-rs into panic_handler

Copilot AI reviewed Apr 17, 2026

View reviewed changes

remove doc link for conditionally compiled fn, add allow for non_snak…

53c1a38

…e_case Windows API

Copilot AI review requested due to automatic review settings April 17, 2026 20:53

Copilot started reviewing on behalf of Alan632 April 17, 2026 20:53 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread crates/wdk-panic/src/lib.rs Outdated

Comment thread crates/cargo-wdk/templates/umdf/lib.rs.tmp

Comment thread crates/cargo-wdk/templates/umdf/Cargo.toml.tmp

Comment thread crates/wdk-panic/src/lib.rs Outdated

Alan Ngo and others added 2 commits April 17, 2026 15:19

remove pre-mature template change

7852eac

wording change

f8e1976

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Alan632 <aln.noda7@gmail.com>

Copilot AI review requested due to automatic review settings April 17, 2026 22:31

Copilot started reviewing on behalf of Alan632 April 17, 2026 22:32 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread crates/wdk-panic/src/lib.rs Outdated

Alan Ngo added 2 commits April 17, 2026 15:38

re-add unintentionally deleted dependency

863392d

removed _ from _info

df60442

Copilot AI review requested due to automatic review settings April 17, 2026 22:43

Copilot started reviewing on behalf of Alan632 April 17, 2026 22:44 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Comment thread crates/wdk-panic/build.rs

add tracing subscriber to build script, replace dbg_break with abort …

7561537

…in umdf

Merge branch 'main' into panic_handler

0c80100

Copilot AI review requested due to automatic review settings April 20, 2026 20:26

Copilot AI reviewed Apr 20, 2026

View reviewed changes

Alan Ngo added 3 commits April 20, 2026 14:36

change wording in documentation for umdf panic

f7a188c

Merge branch 'panic_handler' of https://github.com/Alan632/windows-dr…

a6e7ee5

…ivers-rs into panic_handler

update bugcheck code to high range to avoid official bugcheck codes

186ec88

Copilot AI review requested due to automatic review settings April 20, 2026 22:18

Copilot started reviewing on behalf of Alan632 April 20, 2026 22:18 View session

Alan632 marked this pull request as ready for review April 20, 2026 22:20

Alan632 added the enhancement New feature or request label Apr 20, 2026

Alan632 changed the title ~~feat: add panic handler for WDR~~ feat: add panic handler for windows-drivers-rs Apr 20, 2026

Copilot AI reviewed Apr 20, 2026

View reviewed changes

wmmc88 requested changes Apr 24, 2026

View reviewed changes

wmmc88 changed the title ~~feat: add panic handler for windows-drivers-rs~~ feat: improve user-mode and kernel-mode driver panic handlers Apr 30, 2026

gurry reviewed May 5, 2026

View reviewed changes

update bugcheck code to suggested ASCII tag, fix documentation

26798a0

	/// Output is routed through [`OutputDebugStringA`], which is received by any
	/// Output is routed through `OutputDebugStringA`, which is received by any

Conversation

Alan632 commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Verification

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

wmmc88 Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Alan632 Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

wmmc88 Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

gurry May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

codecov-commenter commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

wmmc88 Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

wmmc88 Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

gurry left a comment

Choose a reason for hiding this comment

Uh oh!

Alan632 commented Apr 16, 2026 •

edited

Loading

gurry May 5, 2026 •

edited

Loading

codecov-commenter commented Apr 17, 2026 •

edited

Loading

gurry May 5, 2026 •

edited

Loading

wmmc88 May 5, 2026 •

edited

Loading

gurry May 5, 2026 •

edited

Loading