SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! 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}");
}
}