1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
// Here rather than in Cargo.toml's [lints], which Cargo before 1.74 ignores.
use ;
// DbgPrintEx filter values from the WDK's dpfilter.h, which windows-sys does not define.
const DPFLTR_IHVDRIVER_ID: u32 = 77;
const DPFLTR_ERROR_LEVEL: u32 = 0;
// The bug check code that a panic reports unless the driver sets another: "RUST".
const DEFAULT_BUG_CHECK_CODE: u32 = u32from_be_bytes;
// Read by the panic handler. Each value stands alone, so Relaxed ordering is enough.
static COMPONENT_ID: AtomicU32 = new;
static LEVEL: AtomicU32 = new;
static BUG_CHECK_CODE: AtomicU32 = new;
/// Sets the `DbgPrintEx` component ID that the panic message is printed under.
///
/// The default is `DPFLTR_IHVDRIVER_ID` (77). Microsoft asks drivers to use one of the
/// six component IDs reserved for independent hardware vendors in the WDK's
/// `dpfilter.h`, so that their output is not mixed with that of Windows components:
///
/// | Component ID | Value | Driver type |
/// |---|---|---|
/// | `DPFLTR_IHVDRIVER_ID` | 77 | any other type of driver |
/// | `DPFLTR_IHVVIDEO_ID` | 78 | video |
/// | `DPFLTR_IHVAUDIO_ID` | 79 | audio |
/// | `DPFLTR_IHVNETWORK_ID` | 80 | network |
/// | `DPFLTR_IHVSTREAMING_ID` | 81 | kernel streaming |
/// | `DPFLTR_IHVBUS_ID` | 82 | bus |
///
/// Can be called at any IRQL. A panic before the first call uses the default, so call
/// it early, for example at the start of `DriverEntry`.
///
/// # Examples
///
/// ```ignore
/// // From the WDK's dpfilter.h.
/// const DPFLTR_IHVNETWORK_ID: u32 = 80;
///
/// ntpanic::set_component_id(DPFLTR_IHVNETWORK_ID);
/// ```
/// Sets the `DbgPrintEx` level that the panic message is printed at.
///
/// The default is `DPFLTR_ERROR_LEVEL` (0). Windows combines every component's filter
/// mask with a system-wide mask that enables only this level, so by default the panic
/// message is shown whatever the component. Any other level is shown only if the
/// component's filter mask enables it: changing the level can hide the panic message.
///
/// As with `DbgPrintEx`, a level from 0 to 31 selects a single bit (`1 << level`), and a
/// larger value is used as the bit field itself. The WDK's `dpfilter.h` names the first
/// four: `DPFLTR_ERROR_LEVEL` (0), `DPFLTR_WARNING_LEVEL` (1), `DPFLTR_TRACE_LEVEL` (2)
/// and `DPFLTR_INFO_LEVEL` (3). See [Reading and Filtering Debugging Messages].
///
/// Can be called at any IRQL. A panic before the first call uses the default.
///
/// # Examples
///
/// ```ignore
/// // From the WDK's dpfilter.h.
/// const DPFLTR_WARNING_LEVEL: u32 = 1;
///
/// ntpanic::set_level(DPFLTR_WARNING_LEVEL);
/// ```
///
/// [Reading and Filtering Debugging Messages]: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/reading-and-filtering-debugging-messages
/// Sets the bug check code that a panic reports.
///
/// The default is `0x52555354`, "RUST" in ASCII. Whatever the code, the four bug check
/// parameters are:
///
/// | Parameter | Value |
/// |---|---|
/// | 1 | the line number |
/// | 2 | the address of the file path, which is not null-terminated |
/// | 3 | the length of the file path, in bytes |
/// | 4 | the column number |
///
/// A panic without a location reports the path `<unknown>`, the line 0 and the column 0.
///
/// A code of your own lets crash analysis tell your driver's panics apart from those of
/// other drivers that use this crate. Choose one that Windows does not use (see the
/// [Bug Check Code Reference]): `WinDbg` describes a crash, and its parameters, by its
/// code, so reusing one of Windows' codes would make it misreport the panic.
///
/// Can be called at any IRQL. The handler reads the code when it bug-checks, after the
/// callback set with [`set_callback`], so a callback can also choose the code for the
/// panic at hand. A panic before the first call uses the default.
///
/// # Examples
///
/// ```ignore
/// ntpanic::set_bug_check_code(u32::from_be_bytes(*b"ACME"));
/// ```
///
/// [Bug Check Code Reference]: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/bug-check-code-reference2
/// A function for the panic handler to call, with the panic and the IRQL it occurred at;
/// see [`set_callback`].
pub type Callback = fn;
// The callback as a pointer, null when there is none. Stored with Release and read with
// Acquire, so that a panic on another processor sees what was written before setting it.
static CALLBACK: = new;
/// Sets a function for the panic handler to call before it bug-checks, or removes it.
///
/// The handler calls it with the panic, which gives its location and message, and the
/// IRQL the panic occurred at. It does so after printing the panic message, which it
/// skips above DIRQL, and before breaking into a debugger. Only the first panic calls it:
/// a later one, even inside the function itself, bug-checks without calling any callback,
/// including one set in the meantime.
///
/// The function runs where the panic occurred: on that thread's stack, at any IRQL up to
/// `HIGH_LEVEL`, and with the system in an unknown state. It must not wait or take locks,
/// must not allocate or touch pageable memory at `DISPATCH_LEVEL` or above, and must not
/// call `DbgPrintEx` above DIRQL. If it never returns, the system hangs instead of
/// bug-checking. To reset a device or add data to the crash dump, use a bug check callback
/// (`KeRegisterBugCheckReasonCallback`) instead: it is made for that, and it also runs for
/// bug checks that are not panics.
///
/// Can be called at any IRQL.
///
/// # Examples
///
/// ```ignore
/// use core::panic::PanicInfo;
///
/// // From the WDK's wdm.h.
/// const DISPATCH_LEVEL: u8 = 2;
///
/// fn log_panic(info: &PanicInfo, irql: u8) {
/// // A logger may allocate or touch pageable memory, which is safe only below
/// // DISPATCH_LEVEL.
/// if irql < DISPATCH_LEVEL {
/// log::error!("{info}");
/// }
/// }
///
/// ntpanic::set_callback(Some(log_panic));
/// ```
/// The callback, if one is set.
// DbgPrintEx transmits at most 512 bytes per call. The panic message keeps only the
// end of a long path, its informative part, and gives it half of that budget; the
// other half is left for the rest of the message.
const MAX_PRINTED_PATH_LEN: usize = 256;
/// The part of `path` that the panic message prints: all of it, or its last
/// `MAX_PRINTED_PATH_LEN` bytes.