Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Native crash capture on Windows, and startup steps in crash reports (#1215)

bherbruckd20b0fab65d5
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 841b505e2e..ea56a9e4e4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -328,7 +328,7 @@ jobs:
with:
key: windows-startup
- name: Backend order and probing on Windows
- run: cargo test -p solidcraft --profile ci --locked -- startup::tests
+ run: cargo test -p solidcraft --profile ci --locked -- startup::tests native_crash::tests
- name: Build the app
run: cargo build -p solidcraft --profile ci --locked
- name: Start the app under different settings
diff --git a/AGENTS.md b/AGENTS.md
index a83fb38b03..dd5e3ea9a8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,9 +27,11 @@ new uses of it anywhere else. Public docs/web/Flatpak deployments use project Pa
## Never crash
People trust SolidCraft with their designs; a crash loses their work. **This outranks feature work.**
- **No panics in non-test code:** no `unwrap()`, `expect()`, `panic!`, `unreachable!`, `todo!`,
- `unimplemented!`; no `unsafe` (`unsafe_code = "forbid"`). The one exception is two functions in
- `apps/solidcraft/src/open_documents.rs` (that crate denies it instead): macOS hands Finder files
- only to an Objective-C method.
+ `unimplemented!`; no `unsafe` (`unsafe_code = "forbid"`). The two exceptions, in the app crate
+ (which denies it instead), have no safe API: two functions in
+ `apps/solidcraft/src/open_documents.rs` (macOS hands Finder files only to an Objective-C
+ method) and the Windows-only `apps/solidcraft/src/native_crash.rs` (the exception filter that
+ records crashes inside native code such as graphics drivers).
- **Errors are `Result<T, E>`** through the crate's error type and `?`. An unfinished feature
returns an error ("not supported yet: …"); it never panics.
- **Input-derived numbers are hostile** (command parameters, design files, control-channel
diff --git a/CLAUDE.md b/CLAUDE.md
index b2d0592599..005b82191d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -27,9 +27,11 @@ new uses of it anywhere else. Public docs/web/Flatpak deployments use project Pa
## Never crash
People trust SolidCraft with their designs; a crash loses their work. **This outranks feature work.**
- **No panics in non-test code:** no `unwrap()`, `expect()`, `panic!`, `unreachable!`, `todo!`,
- `unimplemented!`; no `unsafe` (`unsafe_code = "forbid"`). The one exception is two functions in
- `apps/solidcraft/src/open_documents.rs` (that crate denies it instead): macOS hands Finder files
- only to an Objective-C method.
+ `unimplemented!`; no `unsafe` (`unsafe_code = "forbid"`). The two exceptions, in the app crate
+ (which denies it instead), have no safe API: two functions in
+ `apps/solidcraft/src/open_documents.rs` (macOS hands Finder files only to an Objective-C
+ method) and the Windows-only `apps/solidcraft/src/native_crash.rs` (the exception filter that
+ records crashes inside native code such as graphics drivers).
- **Errors are `Result<T, E>`** through the crate's error type and `?`. An unfinished feature
returns an error ("not supported yet: …"); it never panics.
- **Input-derived numbers are hostile** (command parameters, design files, control-channel
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5c69637193..2ff450ce1c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -107,8 +107,9 @@ The [README](README.md#architecture) has the layer table. The short version:
`cargo xtask assets` enforces this.
4. **Never crash.** People trust a CAD app with their work.
- Non-test code never uses `unwrap`, `expect`, `panic!` or indexing on input-derived data.
- There's no `unsafe` outside `apps/solidcraft/src/open_documents.rs` (macOS file-open events),
- and the compiler denies it.
+ There's no `unsafe` outside `apps/solidcraft/src/open_documents.rs` (macOS file-open events)
+ and `apps/solidcraft/src/native_crash.rs` (Windows native crash capture), and the compiler
+ denies it.
- An unsupported case returns an error ("not supported yet: …"); it never panics.
- Every call into truck goes through `solidcraft_kernel::guard`.
- Every crash fix comes with a regression test.
diff --git a/Cargo.lock b/Cargo.lock
index f537310aac..a572a852c8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3466,6 +3466,7 @@ dependencies = [
"solidcraft-engine",
"solidcraft-ui-egui",
"ureq",
+ "windows-sys 0.61.2",
"winit",
]
diff --git a/apps/solidcraft/Cargo.toml b/apps/solidcraft/Cargo.toml
index 55825d62cd..ab7835c17b 100644
--- a/apps/solidcraft/Cargo.toml
+++ b/apps/solidcraft/Cargo.toml
@@ -7,8 +7,9 @@ license.workspace = true
publish = false
default-run = "solidcraft"
-# The workspace lints, except unsafe_code: denied, not forbidden, so that src/open_documents.rs can
-# allow it (macOS file-open events have no safe API). Keep the rest in sync with [workspace.lints].
+# The workspace lints, except unsafe_code: denied, not forbidden, so that src/open_documents.rs
+# (macOS file-open events) and src/native_crash.rs (Windows exception filter) can allow it: neither
+# has a safe API. Keep the rest in sync with [workspace.lints].
[lints.rust]
unsafe_code = "deny"
@@ -41,6 +42,18 @@ quick-xml = { workspace = true }
[target.'cfg(target_os = "windows")'.dependencies]
hidapi = { version = "2.6.7", default-features = false, features = ["windows-native"] }
+# Native crash capture (src/native_crash.rs): the exception filter, the faulting module, a minidump.
+windows-sys = { version = "0.61", features = [
+ "Win32_Foundation",
+ "Win32_Security",
+ "Win32_Storage_FileSystem",
+ "Win32_System_Diagnostics_Debug",
+ "Win32_System_IO",
+ "Win32_System_Kernel",
+ "Win32_System_LibraryLoader",
+ "Win32_System_Memory",
+ "Win32_System_Threading",
+] }
[target.'cfg(target_os = "macos")'.dependencies]
# Files opened from Finder and the Dock (src/open_documents.rs); all already come with eframe and rfd.
diff --git a/apps/solidcraft/src/main.rs b/apps/solidcraft/src/main.rs
index 4896e2aa5c..1c6beb3d8f 100644
--- a/apps/solidcraft/src/main.rs
+++ b/apps/solidcraft/src/main.rs
@@ -19,6 +19,8 @@
#[path = "../../../assets/icons/app/shared/source/app_icon.rs"]
mod app_icon;
mod control_server;
+#[cfg(target_os = "windows")]
+mod native_crash;
#[cfg(target_os = "macos")]
mod open_documents;
#[cfg(any(target_os = "windows", target_os = "linux"))]
@@ -32,14 +34,24 @@ struct App {
solve: SolveApp,
/// The settings folder whose start marker the first frame clears (`startup::started`).
starting: Option<std::path::PathBuf>,
+ /// Frames begun; the second one means the first was drawn (startup is over).
+ frames: u32,
#[cfg(any(target_os = "windows", target_os = "linux"))]
space_mouse: space_mouse::SpaceMouse,
}
impl eframe::App for App {
fn logic(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
- if let Some(dir) = self.starting.take() {
- startup::started(&dir);
+ if self.frames < 2 {
+ self.frames += 1;
+ // A second frame right away, which means the first was presented: the app is up.
+ ctx.request_repaint();
+ if self.frames == 2 {
+ solidcraft_engine::crash::phase(solidcraft_engine::crash::RUNNING);
+ if let Some(dir) = self.starting.take() {
+ startup::started(&dir);
+ }
+ }
}
// The design on screen is the one whose commands a crash report replays.
self.solve.session.crash_journal = solidcraft_engine::crash::enabled();
@@ -392,6 +404,12 @@ fn main() -> eframe::Result {
solidcraft_engine::crash::install(dir, build)
})
.unwrap_or_default();
+ // A crash in native code (a graphics driver) says where it happened: the exception and the
+ // module on Windows, and on every system the startup step the app was in.
+ #[cfg(target_os = "windows")]
+ native_crash::install();
+ eframe::egui_wgpu::set_startup_hook(startup_step);
+ solidcraft_engine::crash::phase("window");
let options = eframe::NativeOptions {
viewport: app_viewport()?,
depth_buffer: DEPTH_BITS,
@@ -435,6 +453,7 @@ fn main() -> eframe::Result {
options,
Box::new(move |cc| {
created_in_app.store(true, std::sync::atomic::Ordering::SeqCst);
+ solidcraft_engine::crash::phase("app setup");
solidcraft_ui_egui::fonts::setup_fonts(&cc.egui_ctx);
let mut app = SolveApp::new(Session::default(), services(cc));
app.custom_titlebar = CUSTOM_TITLEBAR;
@@ -445,7 +464,12 @@ fn main() -> eframe::Result {
}
if let Some(rs) = &cc.wgpu_render_state {
eprintln!("SolidCraft graphics: {:?}, MSAA {}x (requested {}x)", rs.adapter.get_info().backend, rs.msaa_samples, samples);
+ solidcraft_engine::crash::phase("viewport pipelines (shader compile)");
app.set_wgpu(rs, DEPTH_BITS, STENCIL_BITS, rs.msaa_samples);
+ // The graphics driver is loaded now; it may have put its own exception filter
+ // in front of ours.
+ #[cfg(target_os = "windows")]
+ native_crash::reinstall();
// A saved anti-aliasing the device can't do: back to the default, with a notice.
solidcraft_ui_egui::prefs::check_msaa(&mut app, u32::from(samples));
let info = rs.adapter.get_info();
@@ -497,9 +521,11 @@ fn main() -> eframe::Result {
}
#[cfg(any(target_os = "windows", target_os = "linux"))]
let space_mouse = space_mouse::SpaceMouse::start(&cc.egui_ctx);
+ solidcraft_engine::crash::phase("first frame");
Ok(Box::new(App {
solve: app,
starting,
+ frames: 0,
#[cfg(any(target_os = "windows", target_os = "linux"))]
space_mouse,
}))
@@ -512,6 +538,15 @@ fn main() -> eframe::Result {
}
}
+/// egui-wgpu is about to start a step of getting the graphics device and the window's surface up:
+/// the crash journal keeps it, and the adapter once it is picked.
+fn startup_step(step: &'static str, detail: &str) {
+ if step == eframe::egui_wgpu::STEP_ADAPTER_CHOSEN {
+ solidcraft_engine::crash::set_environment(&format!("Renderer: {detail}"));
+ }
+ solidcraft_engine::crash::phase(step);
+}
+
/// The renderer settings: with `cpu`, the software adapter (WARP, lavapipe, llvmpipe). The
/// backends come from `startup::choose_backends` (on Windows D3D12 first, and only the backend
/// in use is started); `preference` is `graphics.json`'s `backend`.
diff --git a/apps/solidcraft/src/native_crash.rs b/apps/solidcraft/src/native_crash.rs
new file mode 100644
index 0000000000..bcaf847bbf
--- /dev/null
+++ b/apps/solidcraft/src/native_crash.rs
@@ -0,0 +1,285 @@
+//! Windows: what a crash in native code leaves behind (docs/crash-reports.md).
+//!
+//! A crash inside a graphics driver or another DLL (an access violation, a stack overflow) is no
+//! Rust panic: the panic hook never runs and the next start only found "an unclean exit". An
+//! unhandled-exception filter now writes, before the process goes, a small JSON file with the
+//! exception code, the faulting module and the offset into it, and a minidump, next to the run's
+//! crash journal (`solidcraft_engine::crash::native_paths`). The next start puts both into the
+//! unclean exit's report, with the startup step the journal says the app was in.
+//!
+//! Installing an exception filter and asking the system which module holds an address have no
+//! safe API, hence the `unsafe_code` allowance on this module (the app crate denies it; see
+//! `open_documents.rs` for the other one). The filter runs on a thread that may have a broken
+//! heap or almost no stack left: it doesn't allocate, formats into a buffer on the stack, and
+//! skips the minidump after a stack overflow.
+#![allow(unsafe_code)]
+
+use std::fmt::Write as _;
+use std::os::windows::ffi::OsStrExt;
+use std::path::Path;
+use std::sync::OnceLock;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+
+use windows_sys::Win32::Foundation::{CloseHandle, GENERIC_WRITE, HANDLE, HMODULE, INVALID_HANDLE_VALUE};
+use windows_sys::Win32::Storage::FileSystem::{CREATE_ALWAYS, CreateFileW, FILE_ATTRIBUTE_NORMAL, WriteFile};
+use windows_sys::Win32::System::Diagnostics::Debug::{
+ EXCEPTION_CONTINUE_SEARCH, EXCEPTION_POINTERS, MINIDUMP_EXCEPTION_INFORMATION, MiniDumpNormal, MiniDumpWithThreadInfo,
+ MiniDumpWithUnloadedModules, MiniDumpWriteDump, SetUnhandledExceptionFilter,
+};
+use windows_sys::Win32::System::LibraryLoader::{
+ GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS, GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, GetModuleFileNameW, GetModuleHandleExW,
+};
+use windows_sys::Win32::System::Threading::{GetCurrentProcess, GetCurrentProcessId, GetCurrentThreadId};
+
+/// Where the filter writes (NUL-terminated UTF-16), set once by [`install`].
+struct Paths {
+ info: Vec<u16>,
+ dump: Vec<u16>,
+}
+
+static PATHS: OnceLock<Paths> = OnceLock::new();
+/// The filter that was installed before ours (called after ours), as an address.
+static PREVIOUS: AtomicUsize = AtomicUsize::new(0);
+/// The filter has started writing (a second exception while it does is left alone).
+static BUSY: AtomicBool = AtomicBool::new(false);
+
+const STATUS_ACCESS_VIOLATION: u32 = 0xC000_0005;
+const STATUS_IN_PAGE_ERROR: u32 = 0xC000_0006;
+const STATUS_STACK_OVERFLOW: u32 = 0xC000_00FD;
+
+/// Catch native crashes from now on (after `solidcraft_engine::crash::install`; nothing without it).
+pub fn install() {
+ let Some((info, dump)) = solidcraft_engine::crash::native_paths() else { return };
+ let wide = |p: &Path| p.as_os_str().encode_wide().chain([0]).collect::<Vec<u16>>();
+ if PATHS.set(Paths { info: wide(&info), dump: wide(&dump) }).is_ok() {
+ set_filter();
+ }
+}
+
+/// Put the filter back on top: a DLL loaded since (a graphics driver) may have set its own,
+/// which is then called after ours.
+pub fn reinstall() {
+ if PATHS.get().is_some() {
+ set_filter();
+ }
+}
+
+fn set_filter() {
+ // SAFETY: `filter` has the signature the system calls it with and stays valid for the
+ // process's life.
+ let previous = unsafe { SetUnhandledExceptionFilter(Some(filter)) };
+ if let Some(p) = previous
+ && p as usize != filter as *const () as usize
+ {
+ PREVIOUS.store(p as usize, Ordering::SeqCst);
+ }
+}
+
+/// The unhandled-exception filter: record, then let the previous filter (or the system) go on.
+unsafe extern "system" fn filter(pointers: *const EXCEPTION_POINTERS) -> i32 {
+ if !BUSY.swap(true, Ordering::SeqCst) {
+ // SAFETY: the system passes valid exception pointers for the duration of the call.
+ unsafe { record(pointers) };
+ }
+ let previous = PREVIOUS.load(Ordering::SeqCst);
+ if previous != 0 && previous != filter as *const () as usize {
+ // SAFETY: the address came from `SetUnhandledExceptionFilter` as a filter of this type.
+ let previous: unsafe extern "system" fn(*const EXCEPTION_POINTERS) -> i32 = unsafe { std::mem::transmute(previous) };
+ // SAFETY: as for this filter.
+ return unsafe { previous(pointers) };
+ }
+ EXCEPTION_CONTINUE_SEARCH
+}
+
+/// A fixed buffer to format into without allocating (what doesn't fit is cut off).
+struct Buf {
+ bytes: [u8; 2048],
+ len: usize,
+}
+
+impl std::fmt::Write for Buf {
+ fn write_str(&mut self, s: &str) -> std::fmt::Result {
+ let room = self.bytes.len().saturating_sub(self.len);
+ let n = s.len().min(room);
+ if let (Some(to), Some(from)) = (self.bytes.get_mut(self.len..self.len + n), s.as_bytes().get(..n)) {
+ to.copy_from_slice(from);
+ self.len += n;
+ }
+ Ok(())
+ }
+}
+
+/// The usual names of the exception codes a crash shows.
+fn code_name(code: u32) -> &'static str {
+ match code {
+ STATUS_ACCESS_VIOLATION => "EXCEPTION_ACCESS_VIOLATION",
+ STATUS_IN_PAGE_ERROR => "EXCEPTION_IN_PAGE_ERROR",
+ STATUS_STACK_OVERFLOW => "EXCEPTION_STACK_OVERFLOW",
+ 0xC000_001D => "EXCEPTION_ILLEGAL_INSTRUCTION",
+ 0xC000_0094 => "EXCEPTION_INT_DIVIDE_BY_ZERO",
+ 0xC000_0096 => "EXCEPTION_PRIV_INSTRUCTION",
+ 0xC000_008C => "EXCEPTION_ARRAY_BOUNDS_EXCEEDED",
+ 0xC000_0374 => "STATUS_HEAP_CORRUPTION",
+ 0xC000_0409 => "STATUS_STACK_BUFFER_OVERRUN",
+ 0xC000_0602 => "STATUS_FAIL_FAST_EXCEPTION",
+ 0x8000_0003 => "EXCEPTION_BREAKPOINT",
+ 0xE06D_7363 => "C++ exception",
+ _ => "exception",
+ }
+}
+
+/// Write what `pointers` says into the info file, then the minidump.
+unsafe fn record(pointers: *const EXCEPTION_POINTERS) {
+ let Some(paths) = PATHS.get() else { return };
+ if pointers.is_null() {
+ return;
+ }
+ // SAFETY: checked non-null; the system keeps it valid during the filter.
+ let rec = unsafe { (*pointers).ExceptionRecord };
+ if rec.is_null() {
+ return;
+ }
+ // SAFETY: as above.
+ let rec = unsafe { &*rec };
+ let code = rec.ExceptionCode as u32;
+ let address = rec.ExceptionAddress as usize;
+ let mut module: HMODULE = std::ptr::null_mut();
+ let mut name = [0u16; 512];
+ // SAFETY: FROM_ADDRESS takes the address in place of a name; UNCHANGED_REFCOUNT means no
+ // handle to release; `name` is as long as we say.
+ let len = unsafe {
+ if GetModuleHandleExW(
+ GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS | GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT,
+ address as *const u16,
+ &mut module,
+ ) != 0
+ {
+ GetModuleFileNameW(module, name.as_mut_ptr(), name.len() as u32) as usize
+ } else {
+ 0
+ }
+ };
+ // SAFETY: no preconditions.
+ let thread = unsafe { GetCurrentThreadId() };
+ let mut b = Buf { bytes: [0; 2048], len: 0 };
+ let _ = write!(b, "{{\"code\":\"0x{code:08X}\",\"name\":\"{}\",\"address\":\"0x{address:016X}\",\"thread\":{thread}", code_name(code));
+ if len > 0 {
+ let _ = write!(b, ",\"offset\":\"0x{:X}\",\"module\":\"", address.wrapping_sub(module as usize));
+ for c in char::decode_utf16(name.iter().take(len).copied()) {
+ let _ = match c.unwrap_or(char::REPLACEMENT_CHARACTER) {
+ '"' => b.write_str("\\\""),
+ '\\' => b.write_str("\\\\"),
+ c if (c as u32) < 0x20 => b.write_str("?"),
+ c => b.write_char(c),
+ };
+ }
+ let _ = b.write_str("\"");
+ }
+ if matches!(code, STATUS_ACCESS_VIOLATION | STATUS_IN_PAGE_ERROR) && rec.NumberParameters >= 2 {
+ let what = match rec.ExceptionInformation[0] {
+ 0 => "read of",
+ 1 => "write to",
+ 8 => "execution at",
+ _ => "access to",
+ };
+ let _ = write!(b, ",\"detail\":\"{what} 0x{:016X}\"", rec.ExceptionInformation[1]);
+ }
+ let _ = b.write_str("}");
+ let bytes = b.bytes.get(..b.len).unwrap_or_default();
+ // SAFETY: NUL-terminated path; the handle is closed below.
+ unsafe {
+ let file = create(&paths.info);
+ if !file.is_null() {
+ let mut written = 0u32;
+ WriteFile(file, bytes.as_ptr(), bytes.len() as u32, &mut written, std::ptr::null_mut());
+ CloseHandle(file);
+ }
+ }
+ // After a stack overflow there is no stack left for writing a minidump.
+ if code == STATUS_STACK_OVERFLOW {
+ return;
+ }
+ // SAFETY: as above; the exception information points at this thread's exception.
+ unsafe {
+ let file = create(&paths.dump);
+ if !file.is_null() {
+ let exception = MINIDUMP_EXCEPTION_INFORMATION { ThreadId: thread, ExceptionPointers: pointers as *mut _, ClientPointers: 0 };
+ MiniDumpWriteDump(
+ GetCurrentProcess(),
+ GetCurrentProcessId(),
+ file,
+ MiniDumpNormal | MiniDumpWithThreadInfo | MiniDumpWithUnloadedModules,
+ &exception,
+ std::ptr::null(),
+ std::ptr::null(),
+ );
+ CloseHandle(file);
+ }
+ }
+}
+
+/// A new file at `path` (NUL-terminated) for writing, or null.
+unsafe fn create(path: &[u16]) -> HANDLE {
+ // SAFETY: the caller passes a NUL-terminated path.
+ let h = unsafe { CreateFileW(path.as_ptr(), GENERIC_WRITE, 0, std::ptr::null(), CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, std::ptr::null_mut()) };
+ if h == INVALID_HANDLE_VALUE { std::ptr::null_mut() } else { h }
+}
+
+#[cfg(test)]
+mod tests {
+ use std::path::PathBuf;
+
+ /// The child half: install crash reporting and the filter, then fault in native code.
+ #[test]
+ fn child() {
+ let Some(dir) = std::env::var_os("SOLIDCRAFT_NATIVE_CRASH_CHILD") else { return };
+ let build = solidcraft_engine::crash::Build { version: "9.9.9", commit: "abc1234", built: "2026-10-14" };
+ let fresh = solidcraft_engine::crash::install(PathBuf::from(dir), build);
+ println!("FRESH {}", serde_json::to_string(&fresh).unwrap_or_default());
+ if std::env::var_os("SOLIDCRAFT_NATIVE_CRASH_FAULT").is_none() {
+ solidcraft_engine::crash::end_session();
+ return;
+ }
+ super::install();
+ solidcraft_engine::crash::phase("device creation");
+ // SAFETY: none; this is the crash under test (a read of address 16, as a null struct
+ // pointer's field would be).
+ let v = unsafe { std::ptr::read_volatile(16 as *const u64) };
+ println!("unreachable {v}");
+ }
+
+ fn run(dir: &std::path::Path, fault: bool) -> std::process::Output {
+ let mut c = std::process::Command::new(std::env::current_exe().unwrap());
+ c.args(["--exact", "native_crash::tests::child", "--test-threads=1", "--nocapture"]).env("SOLIDCRAFT_NATIVE_CRASH_CHILD", dir);
+ if fault {
+ c.env("SOLIDCRAFT_NATIVE_CRASH_FAULT", "1");
+ }
+ c.output().unwrap()
+ }
+
+ #[test]
+ fn an_access_violation_is_reported_with_its_module_step_and_minidump() {
+ let dir = std::env::temp_dir().join(format!("solidcraft-native-crash-{}", std::process::id()));
+ let _ = std::fs::remove_dir_all(&dir);
+ let out = run(&dir, true);
+ assert_eq!(out.status.code().map(|c| c as u32), Some(super::STATUS_ACCESS_VIOLATION), "{out:?}");
+ let sessions: Vec<PathBuf> = std::fs::read_dir(dir.join("sessions")).unwrap().flatten().map(|e| e.path()).collect();
+ let info = sessions.iter().find(|p| p.to_string_lossy().ends_with(".native.json")).expect("the filter wrote what it caught");
+ let v: serde_json::Value = serde_json::from_slice(&std::fs::read(info).unwrap()).unwrap();
+ assert_eq!(v["code"], "0xC0000005", "{v}");
+ assert_eq!(v["detail"], "read of 0x0000000000000010", "{v}");
+ assert!(v["module"].as_str().unwrap().to_lowercase().contains("solidcraft"), "the fault is in the test binary: {v}");
+ let dump = sessions.iter().find(|p| p.extension().is_some_and(|e| e == "dmp")).expect("a minidump");
+ assert_eq!(std::fs::read(dump).unwrap().get(..4), Some(&b"MDMP"[..]));
+ // The next start reports it.
+ let out = run(&dir, false);
+ assert!(out.status.success(), "{out:?}");
+ let reports = solidcraft_engine::crash::list(&dir);
+ assert_eq!(reports.len(), 1, "{reports:?}");
+ let r = solidcraft_engine::crash::read(&dir, &reports[0].id).unwrap();
+ assert!(r["message"].as_str().unwrap().contains("EXCEPTION_ACCESS_VIOLATION (0xC0000005) in solidcraft"), "{r}");
+ assert!(r["message"].as_str().unwrap().contains("during startup (device creation"), "{r}");
+ assert!(r.get("minidump_path").is_some(), "{r}");
+ let _ = std::fs::remove_dir_all(&dir);
+ }
+}
diff --git a/crates/engine/src/crash.rs b/crates/engine/src/crash.rs
index f3c8844d6b..6342e048a5 100644
--- a/crates/engine/src/crash.rs
+++ b/crates/engine/src/crash.rs
@@ -17,8 +17,15 @@
//! written again; at most [`MAX_NEW_PER_SESSION`] new reports per run, [`MAX_REPORTS`]
//! reports, [`MAX_TOTAL_BYTES`] on disk, nothing older than [`MAX_AGE_DAYS`] days.
//!
+//! - **Startup steps** ([`phase`]): the journal keeps the step the app is in while it gets its
+//! window and graphics device up, so a crash inside a graphics driver still says where it
+//! happened, and the renderer ([`set_environment`]) once it is known.
+//! - **Native crashes** (Windows): the app's exception filter writes what it caught (exception
+//! code, faulting module and offset) and a minidump next to the journal ([`native_paths`]);
+//! the next start puts both into the unclean exit's report.
+//!
//! Reports are folders `crashes/<time>-<signature>/` holding `report.json`, and when known
-//! `design.solidcraft` and `replay.json`. Nothing is ever sent anywhere.
+//! `design.solidcraft`, `replay.json` and `minidump.dmp`. Nothing is ever sent anywhere.
use std::backtrace::Backtrace;
use std::cell::{Cell, RefCell};
@@ -93,8 +100,13 @@ struct State {
known: Mutex<HashMap<u64, (u64, String)>>,
written: AtomicUsize,
started: u64,
+ /// When the app started, in milliseconds (for how far into the start a step came).
+ started_ms: u64,
}
+/// The startup step that ends startup: the app is up and drawing.
+pub const RUNNING: &str = "running";
+
static STATE: OnceLock<State> = OnceLock::new();
/// The hook is writing a report (a panic inside it must not write another).
static IN_HOOK: AtomicBool = AtomicBool::new(false);
@@ -131,6 +143,10 @@ fn now() -> u64 {
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map_or(0, |d| d.as_secs())
}
+fn now_ms() -> u64 {
+ std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map_or(0, |d| u64::try_from(d.as_millis()).unwrap_or(u64::MAX))
+}
+
/// `secs` since 1970 as (year, month, day, hour, minute, second) in UTC.
fn civil(secs: u64) -> (i64, i64, i64, u64, u64, u64) {
let days = i64::try_from(secs / 86_400).unwrap_or(0);
@@ -279,10 +295,12 @@ fn frames(bt: &str) -> Vec<String> {
pub fn install(dir: PathBuf, build: Build) -> Vec<Summary> {
let _ = fs::create_dir_all(dir.join("sessions"));
let started = now();
+ let started_ms = now_ms();
for path in dead_journals(&dir) {
unclean_exit(&dir, &build, &path);
let _ = fs::remove_file(&path);
}
+ remove_stray_native_files(&dir);
prune(&dir, started);
// Reports the user has been told about (by id).
let seen_file = dir.join(".seen");
@@ -304,6 +322,7 @@ pub fn install(dir: PathBuf, build: Build) -> Vec<Summary> {
known: Mutex::new(known),
written: AtomicUsize::new(0),
started,
+ started_ms,
})
.is_ok()
{
@@ -323,6 +342,53 @@ pub fn set_environment(text: &str) {
&& let Ok(mut e) = s.environment.lock()
{
*e = limited(text, 500);
+ if let Ok(mut j) = s.journal.lock() {
+ let line = json!({ "environment": *e }).to_string();
+ j.write(&line);
+ j.environment = Some(line);
+ }
+ }
+}
+
+/// The app is about to start a step of getting up (`"window"`, `"device creation"`, …; [`RUNNING`]
+/// once it draws): the journal keeps the latest, so a crash nothing catches (inside a graphics
+/// driver, say) is still reported with the step it happened in.
+pub fn phase(step: &str) {
+ let Some(s) = STATE.get() else { return };
+ if let Ok(mut j) = s.journal.lock() {
+ if j.phase_step.as_deref() == Some(step) {
+ return;
+ }
+ let line = json!({ "phase": limited(step, 200), "ms": now_ms().saturating_sub(s.started_ms) }).to_string();
+ j.write(&line);
+ j.phase = Some(line);
+ j.phase_step = Some(step.to_string());
+ }
+}
+
+/// Where a native crash handler writes what it caught for this run: a small JSON file
+/// (`code`, `name`, `address`, `module`, `offset`, `detail`, `thread`) and a minidump. The next
+/// start reports both with this run's unclean exit. `None` before [`install`] or without a journal.
+pub fn native_paths() -> Option<(PathBuf, PathBuf)> {
+ let s = STATE.get()?;
+ let j = s.journal.lock().ok()?;
+ j.path.as_ref().map(|p| native_paths_for(p))
+}
+
+fn native_paths_for(journal: &Path) -> (PathBuf, PathBuf) {
+ (journal.with_extension("native.json"), journal.with_extension("dmp"))
+}
+
+/// Native crash files whose journal is gone (their report was written, or never will be).
+fn remove_stray_native_files(dir: &Path) {
+ for path in fs::read_dir(dir.join("sessions")).into_iter().flatten().flatten().map(|e| e.path()).take(200) {
+ let name = path.file_name().and_then(|n| n.to_str()).unwrap_or_default();
+ let stem = name.strip_suffix(".native.json").or_else(|| name.strip_suffix(".dmp"));
+ if let Some(stem) = stem
+ && !path.with_file_name(format!("{stem}.jsonl")).exists()
+ {
+ let _ = fs::remove_file(&path);
+ }
}
}
@@ -473,6 +539,8 @@ pub(crate) fn command_done(
recent,
base: json!("the design as it was when the command started"),
notes: Vec::new(),
+ fields: serde_json::Map::new(),
+ attach: Vec::new(),
};
write_report(state, kind, Some(&p), extra);
}
@@ -508,6 +576,10 @@ struct Journal {
header: String,
/// Where the running command's line starts (to take it back when it changed nothing).
running_at: Option<u64>,
+ /// The latest startup step's line and name, and the renderer's line (kept across rebases).
+ phase: Option<String>,
+ phase_step: Option<String>,
+ environment: Option<String>,
}
impl Journal {
@@ -517,7 +589,18 @@ impl Journal {
// Append-only handles cannot truncate on Windows; seek explicitly for each write.
let file = OpenOptions::new().create(true).truncate(false).read(true).write(true).open(&path).ok().filter(|f| f.try_lock().is_ok());
let header = json!({ "start": utc(started), "pid": std::process::id(), "version": build.version, "commit": build.commit }).to_string();
- let mut j = Journal { path: file.as_ref().map(|_| path), file, bytes: 0, full: false, last_doc: 0, header, running_at: None };
+ let mut j = Journal {
+ path: file.as_ref().map(|_| path),
+ file,
+ bytes: 0,
+ full: false,
+ last_doc: 0,
+ header,
+ running_at: None,
+ phase: None,
+ phase_step: None,
+ environment: None,
+ };
j.rebase(&json!("new"), 0);
j
}
@@ -547,6 +630,9 @@ impl Journal {
let h = self.header.clone();
self.write(&h);
self.record(&json!({ "base": base }));
+ for line in [self.phase.clone(), self.environment.clone()].into_iter().flatten() {
+ self.write(&line);
+ }
}
fn run(&mut self, id: &str, params: &Value) {
@@ -601,6 +687,10 @@ struct JournalRead {
recent: Vec<Value>,
complete: bool,
reported: bool,
+ /// The latest startup step and how many milliseconds after the start it began.
+ phase: Option<(String, u64)>,
+ /// The renderer, once known.
+ environment: Option<String>,
}
// Read through the lock-owning file object. On Windows an independently opened
@@ -626,7 +716,10 @@ fn read_journal_file(mut file: File) -> JournalRead {
r.header = v;
continue;
}
- r.reported = v.get("reported").is_some();
+ // Startup steps and the renderer say nothing about whether the run was reported.
+ if v.get("phase").is_none() && v.get("environment").is_none() {
+ r.reported = v.get("reported").is_some();
+ }
if let Some(b) = v.get("base") {
r.base = b.clone();
r.replay.clear();
@@ -655,6 +748,10 @@ fn read_journal_file(mut file: File) -> JournalRead {
}
} else if v.get("full").is_some() {
r.complete = false;
+ } else if let Some(p) = v.get("phase").and_then(Value::as_str) {
+ r.phase = Some((p.to_string(), v.get("ms").and_then(Value::as_u64).unwrap_or(0)));
+ } else if let Some(e) = v.get("environment").and_then(Value::as_str) {
+ r.environment = Some(e.to_string());
}
}
r.in_flight = running;
@@ -678,33 +775,84 @@ fn dead_journals(dir: &Path) -> Vec<PathBuf> {
fn unclean_exit(dir: &Path, build: &Build, journal: &Path) {
let j = read_journal(journal);
+ let (native_file, dump_file) = native_paths_for(journal);
+ let native = fs::read(&native_file).ok().and_then(|b| serde_json::from_slice::<Value>(&b).ok()).filter(Value::is_object);
if j.reported {
return;
}
let was = j.header.get("version").and_then(Value::as_str).unwrap_or("?");
let when = j.header.get("start").and_then(Value::as_str).unwrap_or("?");
let doing = j.in_flight.as_ref().and_then(|c| c.get("command")).and_then(Value::as_str);
- let message = match doing {
- Some(c) => format!("SolidCraft {was} (started {when}) ended without a clean exit while running `{c}`"),
- None => format!("SolidCraft {was} (started {when}) ended without a clean exit between commands"),
+ // A run that never got to drawing died while starting up: say at which step.
+ let starting = j.phase.as_ref().filter(|(p, _)| p != RUNNING).map(|(p, ms)| (p.clone(), *ms));
+ let during = match (&starting, doing) {
+ (Some((p, ms)), _) => format!("during startup ({p}, {:.1} s after launch)", *ms as f64 / 1000.0),
+ (None, Some(c)) => format!("while running `{c}`"),
+ (None, None) => "between commands".to_string(),
+ };
+ let field = |k: &str| native.as_ref().and_then(|n| n.get(k)).and_then(Value::as_str).map(|v| limited(v, 300));
+ let (message, location, signature_text, backtrace) = match &native {
+ Some(_) => {
+ let code = field("code").unwrap_or_else(|| "?".into());
+ let name = field("name").unwrap_or_else(|| "exception".into());
+ let module = field("module").unwrap_or_else(|| "(unknown module)".into());
+ let short = module.rsplit(['\\', '/']).next().unwrap_or(&module).to_string();
+ let offset = field("offset").unwrap_or_else(|| "?".into());
+ let at = format!("{short}+{offset}");
+ let mut frames = vec![format!("{code} {name}{}", field("detail").map(|d| format!(" ({d})")).unwrap_or_default())];
+ frames.push(format!("at {module}+{offset} (address {})", field("address").unwrap_or_else(|| "?".into())));
+ if let Some(t) = native.as_ref().and_then(|n| n.get("thread")).and_then(Value::as_u64) {
+ frames.push(format!("on thread {t}"));
+ }
+ (
+ format!("SolidCraft {was} (started {when}) crashed with {name} ({code}) in {at} {during}"),
+ format!("native exception in {at}"),
+ format!("{code} {short} {}", starting.as_ref().map_or(doing.unwrap_or("idle"), |(p, _)| p.as_str())),
+ frames,
+ )
+ }
+ None => (
+ format!("SolidCraft {was} (started {when}) ended without a clean exit {during}"),
+ match (&starting, doing) {
+ (Some((p, _)), _) => format!("unclean exit during startup: {p}"),
+ (None, c) => format!("unclean exit in {}", c.unwrap_or("(between commands)")),
+ },
+ match &starting {
+ Some((p, _)) => format!("startup: {p}"),
+ None => doing.unwrap_or("idle").to_string(),
+ },
+ Vec::new(),
+ ),
};
// A temporary state just for this report (the app's own is not set up yet).
let state = State {
dir: dir.to_path_buf(),
build: build.clone(),
- environment: Mutex::new(String::new()),
- journal: Mutex::new(Journal { path: None, file: None, bytes: 0, full: true, last_doc: 0, header: String::new(), running_at: None }),
+ environment: Mutex::new(j.environment.clone().unwrap_or_default()),
+ journal: Mutex::new(Journal {
+ path: None,
+ file: None,
+ bytes: 0,
+ full: true,
+ last_doc: 0,
+ header: String::new(),
+ running_at: None,
+ phase: None,
+ phase_step: None,
+ environment: None,
+ }),
known: Mutex::new(list(dir).into_iter().filter_map(|s| sig_of(&s.id).map(|sig| (sig, (0, s.id)))).collect()),
written: AtomicUsize::new(0),
started: now(),
+ started_ms: now_ms(),
};
let p = Panic {
message,
- location: format!("unclean exit in {}", doing.unwrap_or("(between commands)")),
+ location,
thread: "(unknown)".into(),
- backtrace: Vec::new(),
+ backtrace,
recovered: false,
- signature: signature("unclean exit", doing.unwrap_or("idle")),
+ signature: signature(if native.is_some() { "native exception" } else { "unclean exit" }, &signature_text),
};
if let Ok(mut k) = state.known.lock()
&& let Some(e) = k.get_mut(&p.signature)
@@ -715,7 +863,13 @@ fn unclean_exit(dir: &Path, build: &Build, journal: &Path) {
bump(dir, &id, n);
return;
}
- let extra = from_journal(j);
+ let mut extra = from_journal(j);
+ if let Some(n) = native {
+ extra.fields.insert("native".into(), n);
+ if dump_file.is_file() {
+ extra.attach.push(("minidump".into(), dump_file, "minidump.dmp".into()));
+ }
+ }
write_report(&state, "unclean_exit", Some(&p), extra);
}
@@ -729,6 +883,10 @@ struct Extra {
recent: Vec<Value>,
base: Value,
notes: Vec<String>,
+ /// More top-level fields for the report (`startup_phase`, `native`).
+ fields: serde_json::Map<String, Value>,
+ /// Files moved into the report's folder: (key in `files`, source, name in the folder).
+ attach: Vec<(String, PathBuf, String)>,
}
/// Design and replay from a journal: the base design (autosave or saved file) and the commands
@@ -762,7 +920,20 @@ fn from_journal(j: JournalRead) -> Extra {
if j.base.as_str() == Some("unknown") {
notes.push("the design changed outside commands before this; it cannot be rebuilt from the journal".into());
}
- Extra { command: j.in_flight, design, replay: replay.then(|| json!({ "commands": commands })), recent: j.recent, base: j.base, notes }
+ let mut fields = serde_json::Map::new();
+ if let Some((p, ms)) = j.phase.filter(|(p, _)| p != RUNNING) {
+ fields.insert("startup_phase".into(), json!({ "step": p, "ms": ms }));
+ }
+ Extra {
+ command: j.in_flight,
+ design,
+ replay: replay.then(|| json!({ "commands": commands })),
+ recent: j.recent,
+ base: j.base,
+ notes,
+ fields,
+ attach: Vec::new(),
+ }
}
fn write_from_journal(state: &State, kind: &str, p: Option<&Panic>) -> Option<String> {
@@ -805,13 +976,19 @@ fn write_report(state: &State, kind: &str, p: Option<&Panic>, extra: Extra) -> O
{
files.insert("replay".into(), json!("replay.json"));
}
+ for (key, from, name) in &extra.attach {
+ let to = folder.join(name);
+ if fs::rename(from, &to).is_ok() || fs::copy(from, &to).is_ok() {
+ files.insert(key.clone(), json!(name));
+ }
+ }
let reproduce = match (files.contains_key("replay"), files.contains_key("design")) {
(true, true) => Some(format!("solidcraft-cli crashes replay {id}")),
(true, false) => Some(format!("solidcraft-cli crashes replay {id} (starts from a new design)")),
_ => None,
};
let environment = state.environment.lock().map(|e| e.clone()).unwrap_or_default();
- let report = json!({
+ let mut report = json!({
"format": FORMAT,
"id": id,
"kind": kind,
@@ -833,6 +1010,11 @@ fn write_report(state: &State, kind: &str, p: Option<&Panic>, extra: Extra) -> O
"reproduce": reproduce,
"notes": notes,
});
+ if let Some(r) = report.as_object_mut() {
+ for (k, v) in extra.fields {
+ r.entry(k).or_insert(v);
+ }
+ }
let bytes = serde_json::to_vec_pretty(&report).ok()?;
solidcraft_io::write_atomic(&folder.join("report.json"), &bytes, false).ok()?;
prune(&state.dir, t);
@@ -957,7 +1139,7 @@ pub fn read(dir: &Path, id: &str) -> std::result::Result<Value, String> {
let folder = dir.join(id);
let mut v = read_report_file(&folder.join("report.json")).ok_or_else(|| format!("no crash report `{id}`"))?;
v["path"] = json!(folder.to_string_lossy());
- for (k, f) in [("design_path", "design.solidcraft"), ("replay_path", "replay.json")] {
+ for (k, f) in [("design_path", "design.solidcraft"), ("replay_path", "replay.json"), ("minidump_path", "minidump.dmp")] {
if folder.join(f).is_file() {
v[k] = json!(folder.join(f).to_string_lossy());
}
diff --git a/crates/engine/src/crash_tests.rs b/crates/engine/src/crash_tests.rs
index fc4d24bdcf..eca51d209e 100644
--- a/crates/engine/src/crash_tests.rs
+++ b/crates/engine/src/crash_tests.rs
@@ -20,6 +20,24 @@ fn child() {
};
let fresh = install(PathBuf::from(dir), build());
println!("FRESH {}", serde_json::to_string(&fresh).unwrap());
+ // Dying while starting up, before any command: in a graphics driver, with or without what
+ // a native crash handler caught.
+ if mode == "startup" || mode == "native" {
+ phase("window");
+ phase("adapter request");
+ set_environment("Renderer: Vulkan Test GPU (driver 1.2.3)");
+ phase("device creation");
+ if mode == "native" {
+ let (info, dump) = native_paths().unwrap();
+ fs::write(
+ info,
+ r#"{"code":"0xC0000005","name":"EXCEPTION_ACCESS_VIOLATION","detail":"read of 0x0000000000000010","address":"0x00007FFB12345678","module":"C:\\Windows\\System32\\DriverStore\\igvk64.dll","offset":"0x64EA72","thread":4242}"#,
+ )
+ .unwrap();
+ fs::write(dump, b"MDMP fake").unwrap();
+ }
+ std::process::abort();
+ }
set_environment("Renderer: test");
let mut s = Session { crash_journal: true, ..Default::default() };
s.execute("solid.box", &json!({"length": 10, "width": 20, "height": 30})).unwrap();
@@ -187,6 +205,69 @@ fn render_settings_survive_unclean_exit_and_journal_replay() {
let _ = fs::remove_dir_all(&d);
}
+#[test]
+fn a_crash_while_starting_up_names_the_step_and_the_renderer() {
+ let d = fresh_dir("startup");
+ let (_, ok) = run_child(&d, "startup");
+ assert!(!ok, "the child aborted");
+ let (_, ok) = run_child(&d, "none");
+ assert!(ok);
+ let (s, v) = only_report(&d);
+ assert_eq!(s.kind, "unclean_exit");
+ assert!(s.message.contains("during startup (device creation"), "{}", s.message);
+ assert_eq!(v["location"], "unclean exit during startup: device creation");
+ assert_eq!(v["startup_phase"]["step"], "device creation");
+ assert_eq!(v["system"]["environment"], "Renderer: Vulkan Test GPU (driver 1.2.3)", "{v}");
+ let _ = fs::remove_dir_all(&d);
+}
+
+#[test]
+fn a_native_crash_is_reported_with_the_module_the_step_and_the_minidump() {
+ let d = fresh_dir("native");
+ let (_, ok) = run_child(&d, "native");
+ assert!(!ok, "the child aborted");
+ let (_, ok) = run_child(&d, "none");
+ assert!(ok);
+ let (s, v) = only_report(&d);
+ assert_eq!(s.kind, "unclean_exit");
+ assert!(s.message.contains("EXCEPTION_ACCESS_VIOLATION (0xC0000005) in igvk64.dll+0x64EA72 during startup (device creation"), "{}", s.message);
+ assert_eq!(v["location"], "native exception in igvk64.dll+0x64EA72");
+ assert_eq!(v["native"]["thread"], 4242);
+ let bt: Vec<&str> = v["backtrace"].as_array().unwrap().iter().map(|f| f.as_str().unwrap()).collect();
+ assert_eq!(bt[0], "0xC0000005 EXCEPTION_ACCESS_VIOLATION (read of 0x0000000000000010)");
+ assert!(bt[1].contains("igvk64.dll+0x64EA72"), "{bt:?}");
+ assert_eq!(fs::read(v["minidump_path"].as_str().unwrap()).unwrap(), b"MDMP fake");
+ assert_eq!(v["files"]["minidump"], "minidump.dmp");
+ // Nothing is left behind next to the journals.
+ let left: Vec<_> = fs::read_dir(d.join("sessions")).unwrap().flatten().map(|e| e.file_name()).collect();
+ assert!(left.iter().all(|n| n.to_string_lossy().ends_with(".jsonl")), "{left:?}");
+ // The same crash again is counted, not written again.
+ let _ = run_child(&d, "native");
+ let _ = run_child(&d, "none");
+ let (s, _) = only_report(&d);
+ assert_eq!(s.count, 2);
+ let _ = fs::remove_dir_all(&d);
+}
+
+#[test]
+fn startup_steps_survive_a_rebase_and_running_ends_startup() {
+ let d = fresh_dir("rebase");
+ fs::create_dir_all(d.join("sessions")).unwrap();
+ let mut j = Journal::open(&d, &build(), now());
+ j.phase = Some(json!({"phase": "first frame", "ms": 5}).to_string());
+ j.environment = Some(json!({"environment": "Renderer: X"}).to_string());
+ j.rebase(&json!("new"), 1);
+ let r = read_journal(j.path.as_ref().unwrap());
+ assert_eq!(r.phase, Some(("first frame".to_string(), 5)));
+ assert_eq!(r.environment.as_deref(), Some("Renderer: X"));
+ j.write(&json!({"phase": RUNNING, "ms": 9}).to_string());
+ let r = read_journal(j.path.as_ref().unwrap());
+ assert_eq!(r.phase, Some((RUNNING.to_string(), 9)));
+ assert!(from_journal(r).fields.get("startup_phase").is_none(), "a running app is past startup");
+ drop(j);
+ let _ = fs::remove_dir_all(&d);
+}
+
#[test]
fn a_journal_reads_back_its_base_commands_and_the_one_in_flight() {
let d = fresh_dir("journal");
diff --git a/crates/ui-egui/src/issue_report.rs b/crates/ui-egui/src/issue_report.rs
index 9b3f4bc546..30b6040c78 100644
--- a/crates/ui-egui/src/issue_report.rs
+++ b/crates/ui-egui/src/issue_report.rs
@@ -298,7 +298,7 @@ pub fn crash_draft(report: &serde_json::Value) -> Draft {
let what = match report.get("kind").and_then(serde_json::Value::as_str) {
Some("command_panic") => "An internal error stopped a command (the design was left unchanged)",
Some("kernel_panic_recovered") => "The geometry kernel hit an internal error (caught; the operation failed)",
- Some("unclean_exit") => "SolidCraft closed unexpectedly (abort, stack overflow or the process was killed)",
+ Some("unclean_exit") => "SolidCraft closed unexpectedly (abort, stack overflow, a crash in a graphics driver or the process was killed)",
_ => "SolidCraft hit an internal error",
};
let command = report.get("command").and_then(|c| c.get("command")).and_then(serde_json::Value::as_str);
diff --git a/docs/crash-reports.md b/docs/crash-reports.md
index dae819170e..911090e80b 100644
--- a/docs/crash-reports.md
+++ b/docs/crash-reports.md
@@ -58,7 +58,7 @@ A folder `crashes/<YYYYMMDD-HHMMSS>-<signature>/`:
- `command_panic`: a command hit an internal error; it was caught and the design was left unchanged
- `kernel_panic_recovered`: the third-party geometry kernel panicked and was caught. This is harmless on the desktop, but it would crash the web build.
- `panic`: an internal error outside any command
- - `unclean_exit`: the app ended without a hook seeing it (an abort, a stack overflow, a segfault, or the process being killed). It is found at the next start.
+ - `unclean_exit`: the app ended without a hook seeing it (an abort, a stack overflow, a segfault, a crash inside a graphics driver, or the process being killed). It is found at the next start. When the app died while starting up, the message and `location` name the startup step (see below). On Windows, a crash in native code also says the exception, the module it happened in and the offset into it.
- `message`, `location` (file:line), `thread`
- `backtrace`: frames `symbol (file:line)`, without the panic machinery, std internals or the user's home folder
- `app` (version, commit, build date), `system` (OS, architecture, renderer and GPU), `session.uptime_s`
@@ -67,8 +67,24 @@ A folder `crashes/<YYYYMMDD-HHMMSS>-<signature>/`:
- `base`: what the replay starts from (the design before the command, an autosave, a saved file or a new design)
- `count`, `first_seen`, `last_seen`: the same crash repeats only increase `count`
- `notes`: what is missing and why, for example a design too large to copy
+ - `startup_phase`: `{step, ms}` when the app died before it drew its first frame: the step it
+ was in (`window`, `graphics instance`, `window surface`, `adapter request`, `adapter chosen`,
+ `device creation`, `egui renderer (shader compile)`, `surface configure`, `app setup`,
+ `viewport pipelines (shader compile)`, `first frame`, `first frame (present)`) and how many
+ milliseconds after launch it began. `system.environment` names the renderer (backend, GPU,
+ driver) as soon as the adapter is picked, so it is there even when the device never started.
+ - `native` (Windows): what the exception filter caught: `code`, `name`, `address`, `module`,
+ `offset` (into the module), `detail` (for an access violation, the address read or written)
+ and `thread`. The `backtrace` then shows the same in two lines.
- `design.solidcraft`: the design the replay starts from
- `replay.json`: `{"commands": [{command, params}, …]}`
+- `minidump.dmp` (Windows, native crashes): the threads' stacks and the loaded modules at the
+ crash, for WinDbg or Visual Studio. It holds stack memory only, not the design, but it stays
+ on this computer like the rest of the report; share it only on request.
+
+A crash that ends the process without any exception (a fail-fast, which is how an abort ends on
+Windows) still gets the startup step. Windows can also keep its own dumps of every crash: set
+`DumpFolder` under `HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps`.
## How it stays cheap and small
diff --git a/vendor/README.md b/vendor/README.md
index e5e9c1a62c..948b86fcd6 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -125,6 +125,10 @@ SolidCraft changes:
guarantees 1x and 4x).
- `src/setup.rs`: the default device asks for the adapter's largest 2D texture (at least 8192)
instead of exactly 8192.
+- `src/lib.rs`, `src/winit.rs`: `set_startup_hook` is told before each step of getting the
+ device and the window's surface up (instance, surface, adapter request, the chosen adapter,
+ device, renderer, surface configure, first present), so the app's crash journal can say which
+ step a crash inside the graphics driver happened in.
- `src/lib.rs`, `src/winit.rs`: a window larger than the device's largest texture gets a surface
clamped to it (`clamp_surface_extent`, aspect ratio kept) and egui is drawn at the matching
smaller scale, instead of a `Surface::configure` validation panic (#869). The resize path and
diff --git a/vendor/egui-wgpu/src/lib.rs b/vendor/egui-wgpu/src/lib.rs
index b69c65ae6d..604955c66e 100644
--- a/vendor/egui-wgpu/src/lib.rs
+++ b/vendor/egui-wgpu/src/lib.rs
@@ -41,6 +41,35 @@ use std::sync::Arc;
use epaint::mutex::RwLock;
+/// SolidCraft: what [`set_startup_hook`] is told before each step of getting the graphics
+/// device and the window's surface up, so a crash inside the driver (with no Rust panic) can
+/// still say which step it died in. `detail` is empty except for [`STEP_ADAPTER_CHOSEN`].
+pub type StartupHook = fn(step: &'static str, detail: &str);
+
+static STARTUP_HOOK: std::sync::OnceLock<StartupHook> = std::sync::OnceLock::new();
+
+/// SolidCraft: the steps [`StartupHook`] is told about, in order.
+pub const STEP_INSTANCE: &str = "graphics instance";
+pub const STEP_SURFACE: &str = "window surface";
+pub const STEP_ADAPTER: &str = "adapter request";
+/// The adapter was picked; `detail` names it, its backend and driver.
+pub const STEP_ADAPTER_CHOSEN: &str = "adapter chosen";
+pub const STEP_DEVICE: &str = "device creation";
+pub const STEP_RENDERER: &str = "egui renderer (shader compile)";
+pub const STEP_SURFACE_CONFIGURE: &str = "surface configure";
+pub const STEP_FIRST_PRESENT: &str = "first frame (present)";
+
+/// SolidCraft: install the startup hook (once; later calls are ignored).
+pub fn set_startup_hook(hook: StartupHook) {
+ let _ = STARTUP_HOOK.set(hook);
+}
+
+pub(crate) fn startup_step(step: &'static str, detail: &str) {
+ if let Some(hook) = STARTUP_HOOK.get() {
+ hook(step, detail);
+ }
+}
+
/// An error produced by egui-wgpu.
#[derive(thiserror::Error, Debug)]
pub enum WgpuError {
@@ -226,6 +255,7 @@ impl RenderState {
wgpu::Backends::all()
};
+ startup_step(STEP_ADAPTER, ""); // SolidCraft
instance.enumerate_adapters(backends).await
};
@@ -257,6 +287,16 @@ impl RenderState {
}
}?;
+ // SolidCraft: name the adapter before the driver is asked for a device.
+ let info = adapter.get_info();
+ startup_step(
+ STEP_ADAPTER_CHOSEN,
+ &format!(
+ "{:?} {} ({:?}, driver {} {})",
+ info.backend, info.name, info.device_type, info.driver, info.driver_info
+ ),
+ );
+ startup_step(STEP_DEVICE, "");
let (device, queue) = {
profiling::scope!("request_device");
adapter
@@ -303,6 +343,7 @@ impl RenderState {
msaa_samples,
..options
};
+ startup_step(STEP_RENDERER, ""); // SolidCraft
let renderer = Renderer::new(&device, target_format, options);
// On wasm, depending on feature flags, wgpu objects may or may not implement sync.
diff --git a/vendor/egui-wgpu/src/winit.rs b/vendor/egui-wgpu/src/winit.rs
index 117f7c49a4..a2c00fe4cb 100644
--- a/vendor/egui-wgpu/src/winit.rs
+++ b/vendor/egui-wgpu/src/winit.rs
@@ -27,6 +27,9 @@ struct SurfaceState {
needs_recreate: bool,
}
+/// SolidCraft: whether a frame was presented yet (`crate::STEP_FIRST_PRESENT`).
+static FIRST_PRESENT: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
+
/// Everything you need to paint egui with [`wgpu`] on [`winit`].
///
/// Alternatively you can use [`crate::Renderer`] directly.
@@ -70,6 +73,7 @@ impl Painter {
options: RendererOptions,
) -> Self {
let (capture_tx, capture_rx) = capture_channel();
+ crate::startup_step(crate::STEP_INSTANCE, ""); // SolidCraft
let instance = config.wgpu_setup.new_instance().await;
Self {
@@ -206,6 +210,7 @@ impl Painter {
if let Some(window) = window {
let size = window.inner_size();
if !self.surfaces.contains_key(&viewport_id) {
+ crate::startup_step(crate::STEP_SURFACE, ""); // SolidCraft
let surface = self.instance.create_surface(window)?;
self.add_surface(surface, viewport_id, size).await?;
}
@@ -259,6 +264,7 @@ impl Painter {
self.options.msaa_samples = render_state.msaa_samples;
self.render_state = Some(render_state);
}
+ crate::startup_step(crate::STEP_SURFACE_CONFIGURE, ""); // SolidCraft
self.install_surface(surface, viewport_id, size.width, size.height, false);
Ok(())
}
@@ -628,6 +634,10 @@ impl Painter {
profiling::scope!("get_current_texture");
// This is what vsync-waiting happens on my Mac.
let start = web_time::Instant::now();
+ // SolidCraft: the first frame is the last startup step.
+ if !FIRST_PRESENT.swap(true, std::sync::atomic::Ordering::Relaxed) {
+ crate::startup_step(crate::STEP_FIRST_PRESENT, "");
+ }
let output_frame = surface_state.surface.get_current_texture();
vsync_sec += start.elapsed().as_secs_f32();
output_frame