From ebb6cc53ab7eb5e25c8828b4dbfd9c91162f04ae Mon Sep 17 00:00:00 2001 From: yhamil04 <147720712+yhamil04@users.noreply.github.com> Date: Tue, 27 Oct 2026 00:14:00 +0000 Subject: [PATCH] Crash reports: capture native crashes on macOS (#2113) (#6593) * claim: #2113 Co-Authored-By: Claude Opus 5.5 * Crash reports: capture native crashes on macOS (#2113) A signal handler for SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGTRAP and SIGABRT writes the same .native.json as the Windows exception filter: the signal, the faulting module and offset, the thread and a frame-pointer walk. The next start reports it instead of "an unclean exit". The signal then goes on to the previous handler or the default action, so macOS still writes its own crash report. native_crash_macos.rs joins the crash-safety skill's list of files that may use unsafe (no safe API can catch these signals). Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- Cargo.lock | 1 + apps/solidcraft/Cargo.toml | 8 +- apps/solidcraft/src/main.rs | 8 +- apps/solidcraft/src/native_crash_macos.rs | 879 ++++++++++++++++++++++ crates/engine/src/crash.rs | 19 +- crates/engine/src/crash_tests.rs | 37 +- docs/crash-reports.md | 22 +- skills/solidcraft-crash-safety/SKILL.md | 2 +- 8 files changed, 959 insertions(+), 17 deletions(-) create mode 100644 apps/solidcraft/src/native_crash_macos.rs diff --git a/Cargo.lock b/Cargo.lock index a9d4b0114..11c4b535b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4217,6 +4217,7 @@ dependencies = [ "getrandom 0.3.4", "hidapi", "keyring", + "libc", "log", "muda", "objc2 0.6.5", diff --git a/apps/solidcraft/Cargo.toml b/apps/solidcraft/Cargo.toml index 8a725965a..53ea9b447 100644 --- a/apps/solidcraft/Cargo.toml +++ b/apps/solidcraft/Cargo.toml @@ -13,8 +13,9 @@ bundled-render-library = ["solidcraft-engine/bundled-render-library"] raytrace-cpu = ["solidcraft-engine/raytrace-cpu"] # The workspace lints, except unsafe_code: denied, not forbidden, so that src/open_documents.rs -# (macOS file-open events), src/native_crash.rs (Windows exception filter) and src/native_frame.rs -# (Windows resize border, taskbar icon) can allow it: none has a safe API. Keep the rest in sync with [workspace.lints]. +# (macOS file-open events), src/native_crash.rs (Windows exception filter), src/native_crash_macos.rs +# (macOS crash signal handler) and src/native_frame.rs (Windows resize border, taskbar icon) can +# allow it: none has a safe API. Keep the rest in sync with [workspace.lints]. [lints.rust] unsafe_code = "deny" @@ -88,6 +89,9 @@ objc2 = "0.6" objc2-app-kit = { version = "0.3", default-features = false, features = ["std", "NSApplication", "NSResponder", "NSWindow"] } objc2-foundation = { version = "0.3", default-features = false, features = ["std", "block2", "NSArray", "NSNotification", "NSOperation", "NSProcessInfo", "NSString", "NSURL"] } block2 = "0.6" +# Native crash capture (src/native_crash_macos.rs): the signal handler, the faulting module +# (already in the tree through many crates). +libc = "0.2" [target.'cfg(all(unix, not(target_os = "macos")))'.dependencies] winit = { version = "0.30", default-features = false, features = ["x11"] } diff --git a/apps/solidcraft/src/main.rs b/apps/solidcraft/src/main.rs index 7e64e362e..81cba098d 100644 --- a/apps/solidcraft/src/main.rs +++ b/apps/solidcraft/src/main.rs @@ -24,6 +24,8 @@ mod control_server; mod device_lost; #[cfg(target_os = "windows")] mod native_crash; +#[cfg(target_os = "macos")] +mod native_crash_macos; #[cfg(target_os = "windows")] mod native_frame; #[cfg(target_os = "macos")] @@ -757,10 +759,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. + // A crash in native code (a graphics driver) says where it happened: the exception or signal + // and the module on Windows and macOS, and on every system the startup step the app was in. #[cfg(target_os = "windows")] native_crash::install(); + #[cfg(target_os = "macos")] + native_crash_macos::install(); // Windows with only OpenGL to start: the system title bar instead of ours (#2063). let started = match &wgpu_options.wgpu_setup { eframe::egui_wgpu::WgpuSetup::CreateNew(setup) => setup.instance_descriptor.backends, diff --git a/apps/solidcraft/src/native_crash_macos.rs b/apps/solidcraft/src/native_crash_macos.rs new file mode 100644 index 000000000..637b084bf --- /dev/null +++ b/apps/solidcraft/src/native_crash_macos.rs @@ -0,0 +1,879 @@ +//! macOS: what a crash in native code leaves behind (docs/crash-reports.md). +//! +//! A crash inside a graphics driver or another library (a segfault, an `abort()`, a stack +//! overflow) is no Rust panic: the panic hook never runs and the next start only found "an +//! unclean exit". A signal handler for SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGTRAP (how a trap +//! instruction arrives on Apple silicon) and SIGABRT now writes, before the process goes, the +//! same small JSON file as the Windows filter (`native_crash.rs`): the signal, the faulting +//! module and the offset into it, and a short frame-pointer walk, next to the run's crash journal +//! (`solidcraft_engine::crash::native_paths`). The next start puts it into the unclean exit's +//! report. The signal then goes on to the handler that was there before (the standard library's +//! stack overflow message) or to the default action, so the process still dies of it and macOS +//! still writes its own crash report (`~/Library/Logs/DiagnosticReports`; the file names the +//! `pid` the JSON records). +//! +//! Installing a signal handler and asking dyld which image holds an address have no safe API, +//! hence the `unsafe_code` allowance on this module (the app crate denies it). The handler runs +//! on a thread that may have a broken heap, or on the small alternate stack after a stack +//! overflow: it doesn't allocate, formats into a buffer on the stack, and only reads memory on +//! the thread's own stack. It writes what it knows from the signal first and only then calls +//! `dladdr` (not on POSIX's async-signal-safe list; it takes dyld's recursive reader lock and +//! doesn't allocate) to name the modules, rewriting the file, so a hang or a fault in there +//! still leaves a record. +#![allow(unsafe_code)] + +use std::ffi::{CStr, CString, c_int, c_void}; +use std::fmt::Write as _; +use std::os::unix::ffi::OsStrExt; +use std::sync::OnceLock; +use std::sync::atomic::{AtomicBool, AtomicI32, AtomicUsize, Ordering}; + +use libc::{SIGABRT, SIGBUS, SIGFPE, SIGILL, SIGSEGV, SIGTRAP, siginfo_t}; + +/// The signals a crash arrives as, in the order of [`PREVIOUS`]. +const SIGNALS: [c_int; 6] = [SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGTRAP, SIGABRT]; +/// Frames the walk records (the faulting instruction first). +const MAX_FRAMES: usize = 24; +/// A fault this far below a thread's stack is taken for a stack overflow. +const GUARD: usize = 64 << 10; + +/// Where the handler writes (NUL-terminated), set once by [`install`]. +static PATH: OnceLock = OnceLock::new(); +/// The handler that was installed before ours for each of [`SIGNALS`] (called after ours), as an +/// address (`SIG_DFL` is 0, `SIG_IGN` 1), and its `sa_flags`. +static PREVIOUS: [AtomicUsize; 6] = [const { AtomicUsize::new(libc::SIG_DFL) }; 6]; +static PREVIOUS_FLAGS: [AtomicI32; 6] = [const { AtomicI32::new(0) }; 6]; +/// The handler has started writing (a second signal while it does is only passed on). +static BUSY: AtomicBool = AtomicBool::new(false); + +/// Catch native crashes from now on (after `solidcraft_engine::crash::install`; nothing without it). +pub fn install() { + let Some((info, _)) = solidcraft_engine::crash::native_paths() else { return }; + let Ok(path) = CString::new(info.as_os_str().as_bytes()) else { return }; + if PATH.set(path).is_err() { + return; + } + for (slot, &signal) in SIGNALS.iter().enumerate() { + // SAFETY: `sigaction` is plain data; all zeros is a valid (empty) value. + let mut ours: libc::sigaction = unsafe { std::mem::zeroed() }; + ours.sa_sigaction = handler as *const () as usize; + // On the alternate stack the standard library gives each of its threads, so that a stack + // overflow can still be recorded. + ours.sa_flags = libc::SA_SIGINFO | libc::SA_ONSTACK; + // SAFETY: as above. + let mut old: libc::sigaction = unsafe { std::mem::zeroed() }; + // SAFETY: `handler` has the signature SA_SIGINFO calls it with and stays valid for the + // process's life; both structs are valid for the call. + if unsafe { libc::sigaction(signal, &ours, &mut old) } == 0 + && old.sa_sigaction != ours.sa_sigaction + && let (Some(p), Some(f)) = (PREVIOUS.get(slot), PREVIOUS_FLAGS.get(slot)) + { + f.store(old.sa_flags, Ordering::SeqCst); + p.store(old.sa_sigaction, Ordering::SeqCst); + } + } +} + +/// The signal handler: record, then pass the signal on. +unsafe extern "C" fn handler(signal: c_int, info: *mut siginfo_t, context: *mut c_void) { + // SAFETY: `__error` is this thread's errno, restored for whatever runs after us. + let errno = unsafe { *libc::__error() }; + let slot = SIGNALS.iter().position(|&s| s == signal).unwrap_or(0); + let previous = PREVIOUS.get(slot).map_or(libc::SIG_DFL, |p| p.load(Ordering::SeqCst)); + // SAFETY: the system passes a valid siginfo and the interrupted thread's context for the + // duration of an SA_SIGINFO handler. + let f = unsafe { fault(signal, info, context) }; + // Someone sent a signal the app ignored before: still nothing to record. + let ignored = previous == libc::SIG_IGN && !f.fault; + if !ignored && !BUSY.swap(true, Ordering::SeqCst) { + record(&f); + } + // SAFETY: as above. + unsafe { pass_on(signal, slot, previous, f.fault, info, context) }; + // SAFETY: as above. + unsafe { *libc::__error() = errno }; +} + +/// The signal comes from the faulting instruction itself (not `kill`, `raise` or `abort`), so +/// returning runs it again: on arm64, the exception the thread last took matches the signal. +/// macOS gives a SIGSEGV sent with `kill` the same `si_code` as a real one (SEGV_ACCERR), but +/// the exception is then the thread's last system call (or something long past, whose fault +/// address doesn't match). +#[cfg(any(target_arch = "aarch64", test))] +fn arm64_fault(signal: c_int, si_code: c_int, addr: usize, esr: u32, far: u64) -> bool { + const ABORTS: [u32; 4] = [0x20, 0x21, 0x24, 0x25]; + const SVC: u32 = 0x15; + let class = esr >> 26; + signal != SIGABRT + && (1..0x10000).contains(&si_code) + && match signal { + SIGSEGV | SIGBUS => ABORTS.contains(&class) && far as usize == addr, + _ => class != SVC && !ABORTS.contains(&class), + } +} + +/// As [`arm64_fault`], from the x86 trap number and page-fault address. +#[cfg(any(target_arch = "x86_64", test))] +fn x86_fault(signal: c_int, si_code: c_int, addr: usize, trapno: u16, faultvaddr: u64) -> bool { + signal != SIGABRT + && (1..0x10000).contains(&si_code) + && match signal { + SIGSEGV | SIGBUS => (trapno == 14 && faultvaddr as usize == addr) || matches!(trapno, 12 | 13), + SIGILL => trapno == 6, + SIGFPE => matches!(trapno, 0 | 16 | 19), + SIGTRAP => matches!(trapno, 1 | 3), + _ => false, + } +} + +/// Hand the signal to the previous handler, or to the default action. A crash signal that was +/// only sent goes to the default action: the handler before ours (the standard library's, for +/// SIGSEGV and SIGBUS) expects a fault that happens again when it returns. +unsafe fn pass_on(signal: c_int, slot: usize, previous: usize, fault: bool, info: *mut siginfo_t, context: *mut c_void) { + let ours = handler as *const () as usize; + if previous != libc::SIG_DFL && previous != libc::SIG_IGN && previous != ours && (fault || signal == SIGABRT) { + let flags = PREVIOUS_FLAGS.get(slot).map_or(0, |f| f.load(Ordering::SeqCst)); + if flags & libc::SA_SIGINFO != 0 { + // SAFETY: the address came from `sigaction` as an SA_SIGINFO handler. + let previous: unsafe extern "C" fn(c_int, *mut siginfo_t, *mut c_void) = unsafe { std::mem::transmute(previous) }; + // SAFETY: as for this handler. + unsafe { previous(signal, info, context) }; + } else { + // SAFETY: the address came from `sigaction` as a plain handler. + let previous: unsafe extern "C" fn(c_int) = unsafe { std::mem::transmute(previous) }; + // SAFETY: as for this handler. + unsafe { previous(signal) }; + } + return; + } + if previous == libc::SIG_IGN && !fault { + return; + } + // SAFETY: as in `install`. + let mut default: libc::sigaction = unsafe { std::mem::zeroed() }; + default.sa_sigaction = libc::SIG_DFL; + // SAFETY: a valid struct; restoring the default action is async-signal-safe. + unsafe { libc::sigaction(signal, &default, std::ptr::null_mut()) }; + // A fault happens again when we return, now with the default action, so macOS reports it at + // the instruction; anything else is raised again, and arrives once this handler returns. + if !fault { + // SAFETY: async-signal-safe. + unsafe { libc::raise(signal) }; + } +} + +/// The darwin `ucontext_t`, up to the pointer to the machine context (``). +#[repr(C)] +struct UContext { + _onstack: c_int, + _sigmask: u32, + _stack: libc::stack_t, + _link: *mut c_void, + _mcsize: usize, + mcontext: *const MContext, +} + +/// The darwin arm64 machine context: exception state, then the general registers +/// (``; the floating-point state that follows isn't read). +#[cfg(target_arch = "aarch64")] +#[repr(C)] +struct MContext { + far: u64, + esr: u32, + _exception: u32, + _x: [u64; 29], + fp: u64, + _lr: u64, + _sp: u64, + pc: u64, +} + +/// The darwin x86_64 machine context: exception state, then the general registers +/// (``; rax rbx rcx rdx rdi rsi rbp rsp r8–r15, then rip). +#[cfg(target_arch = "x86_64")] +#[repr(C)] +struct MContext { + trapno: u16, + _cpu: u16, + err: u32, + faultvaddr: u64, + gpr: [u64; 16], + rip: u64, +} + +/// What the faulting instruction did to its address, when the processor says. +#[derive(Clone, Copy, Debug, PartialEq)] +enum Access { + Unknown, + Read, + Write, + Execute, +} + +/// What a crash signal says, read out of the signal before anything is looked up. +#[derive(Clone, Copy, Debug)] +struct Fault { + signal: c_int, + si_code: c_int, + /// `si_addr`: the address that faulted (for SIGILL, SIGFPE and SIGTRAP, the instruction). + addr: usize, + pc: usize, + fp: usize, + access: Access, + /// It comes from the faulting instruction (not `kill`, `raise` or `abort`). + fault: bool, + /// The process that sent the signal (0 or our own for a fault or an `abort()`). + sender: i32, + pid: i32, + thread: u64, + thread_name: [u8; 64], + /// The thread's stack, `[low, high)` (0, 0 when unknown). + stack: (usize, usize), +} + +impl Fault { + /// The fault hit just below the thread's stack: the stack ran out. + fn overflow(&self) -> bool { + let (low, high) = self.stack; + matches!(self.signal, SIGSEGV | SIGBUS) && high > low && self.addr < low.saturating_add(4096) && self.addr >= low.saturating_sub(GUARD) + } + + fn signal_name(&self) -> &'static str { + match self.signal { + SIGSEGV => "SIGSEGV", + SIGBUS => "SIGBUS", + SIGILL => "SIGILL", + SIGFPE => "SIGFPE", + SIGTRAP => "SIGTRAP", + SIGABRT => "SIGABRT", + _ => "signal", + } + } + + fn name(&self) -> &'static str { + if self.overflow() { + return "stack overflow"; + } + match self.signal { + SIGSEGV => "segmentation fault", + SIGBUS => "bus error", + SIGILL => "illegal instruction", + SIGFPE => "arithmetic exception", + SIGTRAP => "trap", + SIGABRT => "abort", + _ => "signal", + } + } + + /// The `si_code` names that say something about a crash. + fn code_name(&self) -> Option<&'static str> { + Some(match (self.signal, self.si_code) { + (SIGSEGV, 1) => "SEGV_MAPERR", + (SIGSEGV, 2) => "SEGV_ACCERR", + (SIGBUS, 1) => "BUS_ADRALN", + (SIGBUS, 2) => "BUS_ADRERR", + (SIGBUS, 3) => "BUS_OBJERR", + (SIGFPE, 7) => "FPE_INTDIV", + (SIGFPE, 8) => "FPE_INTOVF", + _ => return None, + }) + } + + /// One line on what happened: the address read or written, a stack overflow, who sent it. + fn detail(&self, b: &mut Buf) { + if self.sender != 0 && self.sender != self.pid { + let _ = write!(b, "sent by process {}", self.sender); + return; + } + if !self.fault { + if self.signal != SIGABRT { + let _ = b.write_str("sent with kill or raise, not a fault"); + } + return; + } + let what = match self.access { + Access::Read => "read of", + Access::Write => "write to", + Access::Execute => "execution at", + Access::Unknown => "access to", + }; + if self.overflow() { + let _ = write!(b, "{what} 0x{:016X}, below the thread's stack", self.addr); + } else if matches!(self.signal, SIGSEGV | SIGBUS) { + let _ = write!(b, "{what} 0x{:016X}", self.addr); + } else { + let _ = write!(b, "at 0x{:016X}", self.addr); + } + if let Some(c) = self.code_name() { + let _ = write!(b, " ({c})"); + } + } +} + +/// An image that holds an address, as `dladdr` names it. +struct Module<'a> { + path: &'a [u8], + base: usize, + symbol: Option<(&'a [u8], usize)>, +} + +/// A fixed buffer to format into without allocating (what doesn't fit is cut off). +struct Buf { + bytes: [u8; 8192], + len: usize, +} + +impl Buf { + fn new() -> Buf { + Buf { bytes: [0; 8192], len: 0 } + } + + fn room(&self) -> usize { + self.bytes.len().saturating_sub(self.len) + } + + fn as_bytes(&self) -> &[u8] { + self.bytes.get(..self.len).unwrap_or_default() + } + + /// `s` as the inside of a JSON string, at most `max` bytes of it (bytes that aren't UTF-8 + /// and control characters become `?`). + fn escaped(&mut self, s: &[u8], max: usize) { + for chunk in s.get(..s.len().min(max)).unwrap_or_default().utf8_chunks() { + for c in chunk.valid().chars() { + let _ = match c { + '"' => self.write_str("\\\""), + '\\' => self.write_str("\\\\"), + c if (c as u32) < 0x20 => self.write_str("?"), + c => self.write_char(c), + }; + } + if !chunk.invalid().is_empty() { + let _ = self.write_str("?"); + } + } + } +} + +impl std::fmt::Write for Buf { + fn write_str(&mut self, s: &str) -> std::fmt::Result { + let n = s.len().min(self.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 last part of a path. +fn file_name(path: &[u8]) -> &[u8] { + path.rsplit(|&c| c == b'/').next().unwrap_or(path) +} + +/// The report: what the signal says, then (with `resolve`) the module of the faulting +/// instruction and the `frames`. Always valid JSON: frames stop while there is room to close it. +fn json(b: &mut Buf, f: &Fault, frames: &[usize], resolve: impl Fn(usize, bool) -> Option>) { + let signal = f.signal_name(); + let _ = write!(b, "{{\"signal\":\"{signal}\",\"number\":{},\"code\":\"{signal}\",\"name\":\"{}\"", f.signal, f.name()); + let _ = write!(b, ",\"si_code\":{},\"address\":\"0x{:016X}\",\"thread\":{},\"pid\":{}", f.si_code, f.pc, f.thread, f.pid); + let name = f.thread_name.split(|&c| c == 0).next().unwrap_or_default(); + if !name.is_empty() { + let _ = b.write_str(",\"thread_name\":\""); + b.escaped(name, 64); + let _ = b.write_str("\""); + } + let mark = b.len; + let _ = b.write_str(",\"detail\":\""); + let start = b.len; + f.detail(b); + if b.len == start { + b.len = mark; + } else { + let _ = b.write_str("\""); + } + if let Some(m) = resolve(f.pc, false) { + let _ = write!(b, ",\"offset\":\"0x{:X}\",\"module\":\"", f.pc.wrapping_sub(m.base)); + b.escaped(m.path, 300); + let _ = b.write_str("\""); + } + if !frames.is_empty() { + let _ = b.write_str(",\"frames\":["); + for (i, &at) in frames.iter().enumerate() { + // A frame is at most ~300 bytes; keep room for it and the closing `]}`. + if b.room() < 400 { + break; + } + if i > 0 { + let _ = b.write_str(","); + } + let _ = b.write_str("\""); + // A return address points after the call: look up the call itself. + match resolve(at, i > 0) { + Some(m) => { + b.escaped(file_name(m.path), 100); + let _ = write!(b, "+0x{:X}", at.wrapping_sub(m.base)); + if let Some((symbol, start)) = m.symbol { + let _ = b.write_str(" "); + b.escaped(symbol, 160); + let _ = write!(b, "+0x{:X}", at.wrapping_sub(start)); + } + } + None => { + let _ = write!(b, "0x{at:016X}"); + } + } + let _ = b.write_str("\""); + } + let _ = b.write_str("]"); + } + let _ = b.write_str("}"); +} + +/// The return addresses up the frame-pointer chain from `fp`, after `pc`. `read` gives the word +/// at an address; frames outside `stack`, misaligned or not going up end the walk. +fn walk(pc: usize, fp: usize, stack: (usize, usize), read: impl Fn(usize) -> Option, out: &mut [usize; MAX_FRAMES]) -> usize { + let (low, high) = stack; + let mut n = 0; + if let Some(slot) = out.get_mut(n) { + *slot = pc; + n += 1; + } + let mut fp = fp; + while n < MAX_FRAMES { + let in_stack = fp >= low && fp.checked_add(16).is_some_and(|end| end <= high); + if !fp.is_multiple_of(8) || !in_stack { + break; + } + let (Some(next), Some(ret)) = (read(fp), read(fp + 8)) else { break }; + let ret = strip_pointer_auth(ret); + if ret == 0 { + break; + } + if let Some(slot) = out.get_mut(n) { + *slot = ret; + n += 1; + } + if next <= fp { + break; + } + fp = next; + } + n +} + +/// Return addresses saved by arm64e code carry a signature in their top bits. +fn strip_pointer_auth(addr: usize) -> usize { + if cfg!(target_arch = "aarch64") { addr & 0x0000_7FFF_FFFF_FFFF } else { addr } +} + +/// Read what the signal and the interrupted thread's registers say. +unsafe fn fault(signal: c_int, info: *const siginfo_t, context: *const c_void) -> Fault { + let mut f = Fault { + signal, + si_code: 0, + addr: 0, + pc: 0, + fp: 0, + access: Access::Unknown, + fault: false, + sender: 0, + // SAFETY: async-signal-safe. + pid: unsafe { libc::getpid() }, + thread: 0, + thread_name: [0; 64], + stack: (0, 0), + }; + if !info.is_null() { + // SAFETY: the system passes a valid siginfo for the duration of the handler. + let info = unsafe { &*info }; + f.si_code = info.si_code; + f.addr = info.si_addr as usize; + f.sender = info.si_pid; + // Without registers (never seen), the signal's own code has to do. + f.fault = signal != SIGABRT && (1..0x10000).contains(&f.si_code); + } + let context = context as *const UContext; + // SAFETY: an SA_SIGINFO handler's third argument is the interrupted thread's ucontext, whose + // machine context pointer the kernel fills in. + let mcontext = if context.is_null() { std::ptr::null() } else { unsafe { (*context).mcontext } }; + if !mcontext.is_null() { + // SAFETY: as above. + let m = unsafe { &*mcontext }; + #[cfg(target_arch = "aarch64")] + { + f.pc = strip_pointer_auth(m.pc as usize); + f.fp = m.fp as usize; + f.fault = arm64_fault(signal, f.si_code, f.addr, m.esr, m.far); + // A data abort says whether it was a write (WnR); an instruction abort is execution. + f.access = match m.esr >> 26 { + 0x24 | 0x25 if m.esr & (1 << 6) != 0 => Access::Write, + 0x24 | 0x25 => Access::Read, + 0x20 | 0x21 => Access::Execute, + _ => Access::Unknown, + }; + } + #[cfg(target_arch = "x86_64")] + { + f.pc = m.rip as usize; + f.fp = m.gpr.get(6).copied().unwrap_or(0) as usize; + f.fault = x86_fault(signal, f.si_code, f.addr, m.trapno, m.faultvaddr); + // A page fault's error code: bit 4 instruction fetch, bit 1 write. + f.access = match (m.trapno, m.err) { + (14, e) if e & 0x10 != 0 => Access::Execute, + (14, e) if e & 0x2 != 0 => Access::Write, + (14, _) => Access::Read, + _ => Access::Unknown, + }; + } + } + if f.pc == 0 && matches!(signal, SIGILL | SIGFPE | SIGTRAP) { + f.pc = f.addr; + } + // SAFETY: these read the calling thread's own pthread structure; the buffers are as long as + // we say. + unsafe { + let me = libc::pthread_self(); + libc::pthread_threadid_np(me, &mut f.thread); + libc::pthread_getname_np(me, f.thread_name.as_mut_ptr().cast(), f.thread_name.len()); + let high = libc::pthread_get_stackaddr_np(me) as usize; + let size = libc::pthread_get_stacksize_np(me); + if let Some(low) = high.checked_sub(size) { + f.stack = (low, high); + } + } + f +} + +/// The image that holds `addr` (the call before it, for a return address). +fn resolve(addr: usize, return_address: bool) -> Option> { + let at = if return_address { addr.saturating_sub(1) } else { addr }; + // SAFETY: `Dl_info` is plain data; all zeros is a valid value. + let mut info: libc::Dl_info = unsafe { std::mem::zeroed() }; + // SAFETY: `dladdr` only reads dyld's image list; the strings it returns live as long as the + // image, which a crashing process never unloads. + unsafe { + if libc::dladdr(at as *const c_void, &mut info) == 0 || info.dli_fname.is_null() { + return None; + } + let symbol = (!info.dli_sname.is_null()).then(|| (CStr::from_ptr(info.dli_sname).to_bytes(), info.dli_saddr as usize)); + Some(Module { path: CStr::from_ptr(info.dli_fname).to_bytes(), base: info.dli_fbase as usize, symbol }) + } +} + +/// Write what the signal says into the info file, then again with the modules and frames. +fn record(f: &Fault) { + let Some(path) = PATH.get() else { return }; + // SAFETY: NUL-terminated path; the descriptor is closed below. + let fd = unsafe { libc::open(path.as_ptr(), libc::O_WRONLY | libc::O_CREAT | libc::O_TRUNC | libc::O_CLOEXEC, 0o600) }; + if fd < 0 { + return; + } + let mut b = Buf::new(); + json(&mut b, f, &[], |_, _| None); + let bytes = b.as_bytes(); + // SAFETY: the buffer is as long as we say. + unsafe { libc::write(fd, bytes.as_ptr().cast(), bytes.len()) }; + let mut frames = [0usize; MAX_FRAMES]; + // SAFETY: `walk` only reads inside the thread's own stack, 8-byte aligned. + let n = walk(f.pc, f.fp, f.stack, |at| Some(unsafe { (at as *const usize).read() }), &mut frames); + b.len = 0; + json(&mut b, f, frames.get(..n).unwrap_or_default(), resolve); + let bytes = b.as_bytes(); + // SAFETY: as above. + unsafe { + if libc::pwrite(fd, bytes.as_ptr().cast(), bytes.len(), 0) == bytes.len() as isize { + libc::ftruncate(fd, bytes.len() as libc::off_t); + } + libc::close(fd); + } +} + +#[cfg(test)] +mod tests { + use std::os::unix::process::ExitStatusExt; + use std::path::{Path, PathBuf}; + + use super::*; + + fn fault(signal: c_int, si_code: c_int, addr: usize) -> Fault { + let mut thread_name = [0u8; 64]; + thread_name[..4].copy_from_slice(b"main"); + Fault { + signal, + si_code, + addr, + pc: 0x1_0000_1234, + fp: 0, + access: Access::Read, + fault: true, + sender: 0, + pid: 77, + thread: 4242, + thread_name, + stack: (0x7000_0000, 0x7080_0000), + } + } + + fn report(f: &Fault, frames: &[usize]) -> serde_json::Value { + let mut b = Buf::new(); + json(&mut b, f, frames, |at, _| { + (at >= 0x1_0000_0000).then_some(Module { + path: b"/Applications/SolidCraft.app/Contents/MacOS/solidcraft", + base: 0x1_0000_0000, + symbol: Some((b"_ZN4main17h0123456789abcdefE", 0x1_0000_1200)), + }) + }); + serde_json::from_slice(b.as_bytes()).unwrap() + } + + #[test] + fn a_segfault_says_the_signal_the_address_read_and_the_module() { + let v = report(&fault(SIGSEGV, 1, 0x10), &[0x1_0000_1234, 0x1_0000_2000, 0x5000]); + assert_eq!(v["signal"], "SIGSEGV"); + assert_eq!(v["code"], "SIGSEGV"); + assert_eq!(v["name"], "segmentation fault"); + assert_eq!(v["detail"], "read of 0x0000000000000010 (SEGV_MAPERR)"); + assert_eq!(v["address"], "0x0000000100001234"); + assert_eq!(v["module"], "/Applications/SolidCraft.app/Contents/MacOS/solidcraft"); + assert_eq!(v["offset"], "0x1234"); + assert_eq!(v["thread"], 4242); + assert_eq!(v["thread_name"], "main"); + assert_eq!(v["pid"], 77); + let frames: Vec<&str> = v["frames"].as_array().unwrap().iter().map(|f| f.as_str().unwrap()).collect(); + assert_eq!( + frames, + ["solidcraft+0x1234 _ZN4main17h0123456789abcdefE+0x34", "solidcraft+0x2000 _ZN4main17h0123456789abcdefE+0xE00", "0x0000000000005000"] + ); + } + + #[test] + fn a_fault_below_the_stack_is_a_stack_overflow() { + let mut f = fault(SIGBUS, 2, 0x7000_0000 - 0x100); + f.access = Access::Write; + let v = report(&f, &[]); + assert_eq!(v["name"], "stack overflow"); + assert_eq!(v["code"], "SIGBUS"); + assert_eq!(v["detail"], "write to 0x000000006FFFFF00, below the thread's stack (BUS_ADRERR)"); + // Far below it, or inside it, it is not. + assert_eq!(report(&fault(SIGBUS, 2, 0x10), &[])["name"], "bus error"); + assert_eq!(report(&fault(SIGSEGV, 2, 0x7040_0000), &[])["name"], "segmentation fault"); + // Nor without knowing the stack. + let mut f = fault(SIGSEGV, 1, 0x7000_0000 - 0x100); + f.stack = (0, 0); + assert_eq!(report(&f, &[])["name"], "segmentation fault"); + } + + #[test] + fn an_abort_or_a_signal_sent_by_another_process_has_no_address_detail() { + let mut f = fault(SIGABRT, 0, 0); + f.fault = false; + f.sender = 77; + let v = report(&f, &[]); + assert_eq!(v["signal"], "SIGABRT"); + assert_eq!(v["name"], "abort"); + assert!(v.get("detail").is_none(), "{v}"); + let mut f = fault(SIGSEGV, 0x10001, 0); + f.fault = false; + f.sender = 501; + assert_eq!(report(&f, &[])["detail"], "sent by process 501"); + // `kill` without a sender, or `raise`. + f.sender = 0; + assert_eq!(report(&f, &[])["detail"], "sent with kill or raise, not a fault"); + // A trap names the instruction. + assert_eq!(report(&fault(SIGTRAP, 1, 0x1_0000_1234), &[])["detail"], "at 0x0000000100001234"); + } + + #[test] + fn only_a_fault_runs_again_when_the_handler_returns() { + // Measured on an M5 Pro, macOS 27: a read of address 16, then `kill -SEGV` while the + // thread waits in a system call. Both have si_code 2. + assert!(arm64_fault(SIGSEGV, 2, 0x10, 0x9200_0046, 0x10)); + assert!(!arm64_fault(SIGSEGV, 2, 0, 0x5600_0080, 0)); + assert!(!arm64_fault(SIGBUS, 1, 0, 0x5600_0080, 0)); + // A data abort long past, while the signal names no address. + assert!(!arm64_fault(SIGSEGV, 2, 0, 0x9200_0046, 0x10)); + // A trap instruction (BRK) or an undefined one; but not a system call. + assert!(arm64_fault(SIGTRAP, 1, 0x1000, 0xF200_0001, 0)); + assert!(arm64_fault(SIGILL, 1, 0x1000, 0x0200_0000, 0)); + assert!(!arm64_fault(SIGILL, 1, 0x1000, 0x5600_0080, 0)); + // Sent: SI_USER, no code, or an abort. + assert!(!arm64_fault(SIGSEGV, 0x10001, 0x10, 0x9200_0046, 0x10)); + assert!(!arm64_fault(SIGTRAP, 0, 0, 0xF200_0001, 0)); + assert!(!arm64_fault(SIGABRT, 1, 0, 0x5600_0080, 0)); + // x86_64: a page fault at its address, a general protection fault, ud2, int3. + assert!(x86_fault(SIGSEGV, 1, 0x10, 14, 0x10)); + assert!(!x86_fault(SIGSEGV, 1, 0, 14, 0x10)); + assert!(x86_fault(SIGSEGV, 1, 0, 13, 0)); + assert!(x86_fault(SIGILL, 1, 0x1000, 6, 0)); + assert!(x86_fault(SIGTRAP, 1, 0x1000, 3, 0)); + assert!(!x86_fault(SIGILL, 1, 0x1000, 14, 0)); + } + + #[test] + fn names_with_quotes_control_characters_or_bad_utf8_stay_valid_json() { + let mut f = fault(SIGILL, 1, 0x1_0000_1234); + f.thread_name = [0; 64]; + f.thread_name[..7].copy_from_slice(b"a\"b\\\n\xFFc"); + let v = report(&f, &[]); + assert_eq!(v["thread_name"], "a\"b\\??c"); + } + + #[test] + fn a_report_with_long_names_still_closes_its_json() { + let long: &'static [u8] = Box::leak(vec![b'x'; 4000].into_boxed_slice()); + let f = fault(SIGSEGV, 1, 0x10); + let mut b = Buf::new(); + json(&mut b, &f, &[0x1_0000_1234; MAX_FRAMES], |_, _| Some(Module { path: long, base: 0x1_0000_0000, symbol: Some((long, 0x1_0000_0000)) })); + let v: serde_json::Value = serde_json::from_slice(b.as_bytes()).unwrap(); + assert_eq!(v["module"].as_str().unwrap().len(), 300); + let frames = v["frames"].as_array().unwrap(); + assert!(!frames.is_empty() && frames.len() <= MAX_FRAMES, "{}", frames.len()); + } + + #[test] + fn the_frame_walk_stays_on_the_stack_and_goes_up() { + let stack = (0x1000, 0x2000); + // Three frames: 0x1100 -> 0x1200 -> 0x1300 -> 0 (end). + let memory = |at: usize| match at { + 0x1100 => Some(0x1200), + 0x1108 => Some(0xA), + 0x1200 => Some(0x1300), + 0x1208 => Some(0xB), + 0x1300 => Some(0), + 0x1308 => Some(0xC), + _ => None, + }; + let mut out = [0; MAX_FRAMES]; + let n = walk(0x9, 0x1100, stack, memory, &mut out); + assert_eq!(&out[..n], &[0x9, 0xA, 0xB, 0xC]); + // A frame pointer off the stack, misaligned, or one that doesn't go up ends the walk. + assert_eq!(walk(0x9, 0x3000, stack, memory, &mut out), 1); + assert_eq!(walk(0x9, 0x1101, stack, memory, &mut out), 1); + let looping = |at: usize| if at.is_multiple_of(16) { Some(at) } else { Some(0xA) }; + assert_eq!(walk(0x9, 0x1100, stack, looping, &mut out), 2); + // A chain that never ends stops at MAX_FRAMES. + let endless = |at: usize| if at.is_multiple_of(16) { Some(at + 16) } else { Some(0xA) }; + assert_eq!(walk(0x9, 0x1000, stack, endless, &mut out), MAX_FRAMES); + } + + /// The child half: install crash reporting and the handler, then crash the way + /// `SOLIDCRAFT_NATIVE_CRASH_FAULT` says. + #[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-25" }; + let fresh = solidcraft_engine::crash::install(PathBuf::from(dir), build); + println!("FRESH {}", serde_json::to_string(&fresh).unwrap_or_default()); + let Some(fault) = std::env::var_os("SOLIDCRAFT_NATIVE_CRASH_FAULT") else { + solidcraft_engine::crash::end_session(); + return; + }; + super::install(); + solidcraft_engine::crash::phase("device creation"); + match fault.to_str() { + Some("abort") => std::process::abort(), + Some("overflow") => println!("unreachable {}", recurse(0)), + Some("raise") => { + // SAFETY: none needed; this is the crash under test. + unsafe { libc::raise(SIGSEGV) }; + println!("survived"); + } + _ => segfault(), + } + } + + /// Runs out of stack. + #[inline(never)] + fn recurse(n: u64) -> u64 { + let a = std::hint::black_box([n; 64]); + if n == u64::MAX { 0 } else { recurse(n + 1).wrapping_add(a[0]) } + } + + /// The crash under test: a read of address 16, as a null struct pointer's field would be. + #[inline(never)] + fn segfault() { + // SAFETY: none; this is the crash under test. + let v = unsafe { std::ptr::read_volatile(std::hint::black_box(16usize) as *const u64) }; + println!("unreachable {v}"); + } + + fn run(dir: &Path, fault: Option<&str>) -> std::process::Output { + let mut c = std::process::Command::new(std::env::current_exe().unwrap()); + c.args(["--exact", "native_crash_macos::tests::child", "--test-threads=1", "--nocapture"]).env("SOLIDCRAFT_NATIVE_CRASH_CHILD", dir); + if let Some(f) = fault { + c.env("SOLIDCRAFT_NATIVE_CRASH_FAULT", f); + } + c.output().unwrap() + } + + /// Crash a child the way `fault` says; returns what the handler wrote and the next start's report. + fn crash(name: &str, fault: &str, signal: c_int) -> (serde_json::Value, serde_json::Value, String) { + let dir = std::env::temp_dir().join(format!("solidcraft-native-crash-{name}-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + let out = run(&dir, Some(fault)); + assert_eq!(out.status.signal(), Some(signal), "the child died of the signal itself: {out:?}"); + let stderr = String::from_utf8_lossy(&out.stderr).into_owned(); + let info = + std::fs::read_dir(dir.join("sessions")).unwrap().flatten().map(|e| e.path()).find(|p| p.to_string_lossy().ends_with(".native.json")); + let info = info.expect("the handler wrote what it caught"); + let v: serde_json::Value = serde_json::from_slice(&std::fs::read(info).unwrap()).unwrap(); + // The next start reports it. + let out = run(&dir, None); + 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(); + let _ = std::fs::remove_dir_all(&dir); + (v, r, stderr) + } + + #[test] + fn a_segfault_is_reported_with_its_signal_module_frames_and_step() { + let (v, r, _) = crash("segv", "segv", SIGSEGV); + assert_eq!(v["signal"], "SIGSEGV", "{v}"); + // Address 16 is in __PAGEZERO, mapped without access: SEGV_ACCERR. + assert_eq!(v["detail"], "read of 0x0000000000000010 (SEGV_ACCERR)", "{v}"); + assert!(v["module"].as_str().unwrap().contains("solidcraft"), "the fault is in the test binary: {v}"); + let frames = v["frames"].as_array().unwrap(); + assert!(frames.len() >= 3, "{v}"); + assert!(frames.iter().any(|f| f.as_str().unwrap().contains("child")), "the walk reaches the test that crashed: {v}"); + let message = r["message"].as_str().unwrap(); + assert!(message.contains("segmentation fault (SIGSEGV) in solidcraft"), "{r}"); + assert!(message.contains("during startup (device creation"), "{r}"); + assert_eq!(r["kind"], "unclean_exit"); + assert_eq!(r["native"]["signal"], "SIGSEGV"); + assert!(r["backtrace"].as_array().unwrap().iter().any(|f| f.as_str().unwrap().contains("segfault")), "{r}"); + } + + #[test] + fn an_abort_is_reported_as_sigabrt_with_the_code_that_called_it() { + let (v, r, _) = crash("abrt", "abort", SIGABRT); + assert_eq!(v["signal"], "SIGABRT", "{v}"); + assert!(v.get("detail").is_none(), "{v}"); + let frames = v["frames"].as_array().unwrap(); + assert!(frames.iter().any(|f| f.as_str().unwrap().contains("abort")), "{v}"); + assert!(r["message"].as_str().unwrap().contains("abort (SIGABRT)"), "{r}"); + } + + #[test] + fn a_stack_overflow_is_recorded_and_the_standard_library_still_says_so() { + // The fault on the guard page is recorded on the alternate stack; the standard library's + // handler, called after ours, prints its message and aborts. + let (v, r, stderr) = crash("overflow", "overflow", SIGABRT); + assert!(matches!(v["signal"].as_str(), Some("SIGSEGV" | "SIGBUS")), "{v}"); + assert_eq!(v["name"], "stack overflow", "{v}"); + assert!(v["detail"].as_str().unwrap().contains("below the thread's stack"), "{v}"); + assert!(stderr.contains("has overflowed its stack"), "{stderr}"); + assert!(r["message"].as_str().unwrap().contains("stack overflow ("), "{r}"); + } + + #[test] + fn a_segfault_signal_that_was_only_sent_still_ends_the_app() { + // The standard library's handler, which comes before ours, returns expecting the fault + // to happen again; a sent signal never does, so it goes to the default action instead. + let (v, r, _) = crash("raise", "raise", SIGSEGV); + assert_eq!(v["detail"], "sent with kill or raise, not a fault", "{v}"); + assert!(r["message"].as_str().unwrap().contains("(SIGSEGV)"), "{r}"); + } +} diff --git a/crates/engine/src/crash.rs b/crates/engine/src/crash.rs index dfb29d383..65875180e 100644 --- a/crates/engine/src/crash.rs +++ b/crates/engine/src/crash.rs @@ -20,9 +20,10 @@ //! - **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. +//! - **Native crashes** (Windows, macOS): the app's exception filter or signal handler writes what +//! it caught (exception code or signal, faulting module and offset, on macOS a walk up the stack) +//! and on Windows a minidump next to the journal ([`native_paths`]); the next start puts them +//! into the unclean exit's report. //! //! Reports are folders `crashes/