Crash reports: capture native crashes on macOS (#2113) (#6593)

* claim: #2113

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Crash reports: capture native crashes on macOS (#2113)

A signal handler for SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGTRAP and SIGABRT
writes the same <journal>.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 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
yhamil04
2026-10-27 00:14:00 +00:00
committed by GitHub
parent 924724dc89
commit ebb6cc53ab
8 changed files with 959 additions and 17 deletions
Generated
+1
View File
@@ -4217,6 +4217,7 @@ dependencies = [
"getrandom 0.3.4",
"hidapi",
"keyring",
"libc",
"log",
"muda",
"objc2 0.6.5",
+6 -2
View File
@@ -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"] }
+6 -2
View File
@@ -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,
+879
View File
@@ -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<CString> = 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 (`<sys/_types/_ucontext.h>`).
#[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
/// (`<mach/arm/_structs.h>`; 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
/// (`<mach/i386/_structs.h>`; 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<Module<'static>>) {
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<usize>, 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<Module<'static>> {
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}");
}
}
+14 -5
View File
@@ -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/<time>-<signature>/` holding `report.json`, and when known
//! `design.solidcraft`, `replay.json` and `minidump.dmp`. Nothing is ever sent anywhere.
@@ -368,7 +369,8 @@ pub fn phase(step: &str) {
}
/// 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
/// (`code`, `name`, `address`, `module`, `offset`, `detail`, `thread`, and from macOS
/// `thread_name` and `frames`) 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()?;
@@ -843,7 +845,14 @@ fn unclean_exit(dir: &Path, build: &Build, journal: &Path) {
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}"));
frames.push(match field("thread_name").filter(|n| !n.is_empty()) {
Some(n) => format!("on thread {t} ({n})"),
None => format!("on thread {t}"),
});
}
// The handler's own walk up the stack (macOS): `module+offset symbol+offset`.
if let Some(walk) = native.as_ref().and_then(|n| n.get("frames")).and_then(Value::as_array) {
frames.extend(walk.iter().filter_map(Value::as_str).take(MAX_FRAMES).map(|f| limited(f, 300)));
}
(
format!("SolidCraft {was} (started {when}) crashed with {name} ({code}) in {at} {during}"),
+36 -1
View File
@@ -22,7 +22,7 @@ fn child() {
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" {
if mode == "startup" || mode == "native" || mode == "signal" {
phase("window");
phase("adapter request");
set_environment("Renderer: Vulkan Test GPU (driver 1.2.3)");
@@ -36,6 +36,18 @@ fn child() {
.unwrap();
fs::write(dump, b"MDMP fake").unwrap();
}
// What the macOS signal handler writes: no minidump, a walk up the stack instead (with
// a frame that isn't text, one far too long, and far too many).
if mode == "signal" {
let (info, _) = native_paths().unwrap();
let mut frames = vec![json!("libAGXMetalG13X.dylib+0x1A2B3C"), json!(42), json!("x".repeat(5000))];
frames.extend((0..100).map(|i| json!(format!("solidcraft+0x{i:X} frame{i}"))));
let v = json!({"signal": "SIGSEGV", "number": 11, "code": "SIGSEGV", "name": "segmentation fault",
"detail": "read of 0x0000000000000010 (SEGV_MAPERR)", "address": "0x0000000201A2B3C0",
"module": "/System/Library/Extensions/AGXMetalG13X.bundle/Contents/MacOS/libAGXMetalG13X.dylib",
"offset": "0x1A2B3C", "thread": 4242, "thread_name": "main", "pid": 77, "frames": frames});
fs::write(info, v.to_string()).unwrap();
}
std::process::abort();
}
set_environment("Renderer: test");
@@ -383,6 +395,29 @@ fn a_native_crash_is_reported_with_the_module_the_step_and_the_minidump() {
let _ = fs::remove_dir_all(&d);
}
#[test]
fn a_crash_signal_is_reported_with_its_thread_and_its_walk_up_the_stack() {
let d = fresh_dir("signal");
let (_, ok) = run_child(&d, "signal");
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("segmentation fault (SIGSEGV) in libAGXMetalG13X.dylib+0x1A2B3C during startup (device creation"), "{}", s.message);
assert_eq!(v["native"]["signal"], "SIGSEGV");
let bt: Vec<&str> = v["backtrace"].as_array().unwrap().iter().map(|f| f.as_str().unwrap()).collect();
assert_eq!(bt[0], "SIGSEGV segmentation fault (read of 0x0000000000000010 (SEGV_MAPERR))");
assert_eq!(bt[2], "on thread 4242 (main)");
assert_eq!(bt[3], "libAGXMetalG13X.dylib+0x1A2B3C");
// Frames that aren't text are dropped, long ones cut, and only so many kept.
assert_eq!(bt[4], format!("{}… (5000 bytes)", "x".repeat(300)));
assert_eq!(bt[5], "solidcraft+0x0 frame0");
assert_eq!(bt.len(), 3 + MAX_FRAMES, "{bt:?}");
assert!(v.get("minidump_path").is_none(), "{v}");
let _ = fs::remove_dir_all(&d);
}
#[test]
fn startup_steps_survive_a_rebase_and_running_ends_startup() {
let d = fresh_dir("rebase");
+16 -6
View File
@@ -47,7 +47,8 @@ A fixed crash turns into a regression test with the same two files.
`diagnostics.crash_test` has three modes:
- `panic`: an internal error in a command
- `kernel`: an internal error inside the geometry kernel
- `abort`: the app ends at once, and the report appears at the next start
- `abort`: the app ends at once, and the report appears at the next start. On macOS the
signal handler catches it, so the report names SIGABRT and the frames that called `abort()`.
## What a report holds
@@ -58,7 +59,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`: a previous session ended without recording a clean exit. It is detected at the next start, which may be days later. Possible causes include an abort, a stack overflow, a segfault, a crash inside a graphics driver, a system shutdown, or the process being forcibly stopped. This kind alone does not identify the cause. When the app died while starting up, the message and `location` name the startup step (see below). On Windows, a captured native exception also says the exception, the module it happened in and the offset into it.
- `unclean_exit`: a previous session ended without recording a clean exit. It is detected at the next start, which may be days later. Possible causes include an abort, a stack overflow, a segfault, a crash inside a graphics driver, a system shutdown, or the process being forcibly stopped. This kind alone does not identify the cause. When the app died while starting up, the message and `location` name the startup step (see below). On Windows and macOS, a captured native crash also says the exception or signal, 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`
@@ -74,12 +75,21 @@ A folder `crashes/<YYYYMMDD-HHMMSS>-<signature>/`:
`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.
- `native` (Windows and macOS): what the native crash handler caught: `code`, `name`,
`address` (of the faulting instruction), `module`, `offset` (into the module), `detail` (for
an access violation or a segfault, the address read or written) and `thread`. The `backtrace`
then shows the same in two lines.
- On macOS, where a signal handler catches SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGTRAP and SIGABRT,
`code` and `signal` are the signal's name (`SIGSEGV`), `name` says it in words (`segmentation
fault`, or `stack overflow` when the fault is just below the thread's stack), and it adds
`si_code`, `thread_name`, `pid` and `frames`: up to 24 `module+offset symbol+offset` lines
walked up the frame pointers from the faulting instruction, which the `backtrace` lists too.
The process still ends with the signal, so macOS also writes its own crash report, with every
thread's stack: `~/Library/Logs/DiagnosticReports/solidcraft-<date>.ips` (Console ▸ Crash
Reports), whose `pid` is the one in `native`.
- `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
- `minidump.dmp` (Windows, native crashes; on macOS, see the system's own report above): 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.
+1 -1
View File
@@ -10,7 +10,7 @@ People trust SolidCraft with their designs. This outranks feature work.
## In non-test code
- No `unwrap()`, `expect()`, `panic!`, `unreachable!`, `todo!` or `unimplemented!`. Every production crate root carries `#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]`; `cargo xtask ci` runs clippy with `-D warnings`.
- No `unsafe` (`unsafe_code = "forbid"`). The exceptions, in the app crate and in `crates/threedx-client` (which deny it instead), have no safe API:
- macOS only: `crates/threedx-client/src/macos.rs` (loads the 3Dconnexion driver's client framework at run time and calls through its function pointers), and two functions in `apps/solidcraft/src/open_documents.rs` (macOS hands Finder files only to an Objective-C method)
- macOS only: `crates/threedx-client/src/macos.rs` (loads the 3Dconnexion driver's client framework at run time and calls through its function pointers), two functions in `apps/solidcraft/src/open_documents.rs` (macOS hands Finder files only to an Objective-C method), and `apps/solidcraft/src/native_crash_macos.rs` (the signal handler that records crashes inside native code, as `native_crash.rs` does on Windows)
- Windows only: `apps/solidcraft/src/native_crash.rs` (the exception filter that records crashes inside native code such as graphics drivers), `apps/solidcraft/src/native_frame.rs` (the window procedure that answers the resize-border hit test of the window without OS decorations, and gives its class the icon the taskbar falls back on) and `apps/solidcraft/src/space_mouse/windows_hid.rs` (asks Plug and Play which HID interfaces are 3D mice, so no other device is sent anything)
- 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 input): `get()` not `[i]`, finite checks, caps on sizes and loop counts.