std/backtrace/src/backtrace/
libunwind.rs

1//! Backtrace support using libunwind/gcc_s/etc APIs.
2//!
3//! This module contains the ability to unwind the stack using libunwind-style
4//! APIs. Note that there's a whole bunch of implementations of the
5//! libunwind-like API, and this is just trying to be compatible with most of
6//! them all at once instead of being picky.
7//!
8//! The libunwind API is powered by `_Unwind_Backtrace` and is in practice very
9//! reliable at generating a backtrace. It's not entirely clear how it does it
10//! (frame pointers? eh_frame info? both?) but it seems to work!
11//!
12//! Most of the complexity of this module is handling the various platform
13//! differences across libunwind implementations. Otherwise this is a pretty
14//! straightforward Rust binding to the libunwind APIs.
15//!
16//! This is the default unwinding API for all non-Windows platforms currently.
17
18use core::ffi::c_void;
19use core::ptr::addr_of_mut;
20
21pub enum Frame {
22    Raw(*mut uw::_Unwind_Context),
23    Cloned {
24        ip: *mut c_void,
25        sp: *mut c_void,
26        symbol_address: *mut c_void,
27    },
28}
29
30// With a raw libunwind pointer it should only ever be access in a readonly
31// threadsafe fashion, so it's `Sync`. When sending to other threads via `Clone`
32// we always switch to a version which doesn't retain interior pointers, so we
33// should be `Send` as well.
34unsafe impl Send for Frame {}
35unsafe impl Sync for Frame {}
36
37impl Frame {
38    pub fn ip(&self) -> *mut c_void {
39        let ctx = match *self {
40            Frame::Raw(ctx) => ctx,
41            Frame::Cloned { ip, .. } => return ip,
42        };
43        #[allow(unused_mut)]
44        let mut ip = unsafe { uw::_Unwind_GetIP(ctx) as *mut c_void };
45
46        // To reduce TCB size in SGX enclaves, we do not want to implement
47        // symbol resolution functionality. Rather, we can print the offset of
48        // the address here, which could be later mapped to correct function.
49        #[cfg(all(target_env = "sgx", target_vendor = "fortanix"))]
50        {
51            let image_base = super::sgx_image_base::get_image_base();
52            ip = usize::wrapping_sub(ip as usize, image_base as _) as _;
53        }
54        ip
55    }
56
57    pub fn sp(&self) -> *mut c_void {
58        match *self {
59            Frame::Raw(ctx) => unsafe { uw::get_sp(ctx) as *mut c_void },
60            Frame::Cloned { sp, .. } => sp,
61        }
62    }
63
64    pub fn symbol_address(&self) -> *mut c_void {
65        if let Frame::Cloned { symbol_address, .. } = *self {
66            return symbol_address;
67        }
68
69        // The macOS linker emits a "compact" unwind table that only includes an
70        // entry for a function if that function either has an LSDA or its
71        // encoding differs from that of the previous entry.  Consequently, on
72        // macOS, `_Unwind_FindEnclosingFunction` is unreliable (it can return a
73        // pointer to some totally unrelated function).  Instead, we just always
74        // return the ip.
75        //
76        // https://github.com/rust-lang/rust/issues/74771#issuecomment-664056788
77        //
78        // Note the `skip_inner_frames.rs` test is skipped on macOS due to this
79        // clause, and if this is fixed that test in theory can be run on macOS!
80        if cfg!(target_vendor = "apple") {
81            self.ip()
82        } else {
83            unsafe { uw::_Unwind_FindEnclosingFunction(self.ip()) }
84        }
85    }
86
87    pub fn module_base_address(&self) -> Option<*mut c_void> {
88        None
89    }
90}
91
92impl Clone for Frame {
93    fn clone(&self) -> Frame {
94        Frame::Cloned {
95            ip: self.ip(),
96            sp: self.sp(),
97            symbol_address: self.symbol_address(),
98        }
99    }
100}
101
102struct Bomb {
103    enabled: bool,
104}
105
106impl Drop for Bomb {
107    fn drop(&mut self) {
108        if self.enabled {
109            panic!("cannot panic during the backtrace function");
110        }
111    }
112}
113
114#[inline(always)]
115pub unsafe fn trace(mut cb: &mut dyn FnMut(&super::Frame) -> bool) {
116    uw::_Unwind_Backtrace(trace_fn, addr_of_mut!(cb).cast());
117
118    extern "C" fn trace_fn(
119        ctx: *mut uw::_Unwind_Context,
120        arg: *mut c_void,
121    ) -> uw::_Unwind_Reason_Code {
122        let cb = unsafe { &mut *arg.cast::<&mut dyn FnMut(&super::Frame) -> bool>() };
123        let cx = super::Frame {
124            inner: Frame::Raw(ctx),
125        };
126
127        let mut bomb = Bomb { enabled: true };
128        let keep_going = cb(&cx);
129        bomb.enabled = false;
130
131        if keep_going {
132            uw::_URC_NO_REASON
133        } else {
134            uw::_URC_FAILURE
135        }
136    }
137}
138
139/// Unwind library interface used for backtraces
140///
141/// Note that dead code is allowed as here are just bindings
142/// iOS doesn't use all of them it but adding more
143/// platform-specific configs pollutes the code too much
144#[allow(non_camel_case_types)]
145#[allow(non_snake_case)]
146#[allow(dead_code)]
147mod uw {
148    pub use self::_Unwind_Reason_Code::*;
149
150    use core::ffi::c_void;
151
152    #[repr(C)]
153    pub enum _Unwind_Reason_Code {
154        _URC_NO_REASON = 0,
155        _URC_FOREIGN_EXCEPTION_CAUGHT = 1,
156        _URC_FATAL_PHASE2_ERROR = 2,
157        _URC_FATAL_PHASE1_ERROR = 3,
158        _URC_NORMAL_STOP = 4,
159        _URC_END_OF_STACK = 5,
160        _URC_HANDLER_FOUND = 6,
161        _URC_INSTALL_CONTEXT = 7,
162        _URC_CONTINUE_UNWIND = 8,
163        _URC_FAILURE = 9, // used only by ARM EABI
164    }
165
166    pub enum _Unwind_Context {}
167
168    pub type _Unwind_Trace_Fn =
169        extern "C" fn(ctx: *mut _Unwind_Context, arg: *mut c_void) -> _Unwind_Reason_Code;
170
171    extern "C" {
172        pub fn _Unwind_Backtrace(
173            trace: _Unwind_Trace_Fn,
174            trace_argument: *mut c_void,
175        ) -> _Unwind_Reason_Code;
176    }
177
178    cfg_if::cfg_if! {
179        // available since GCC 4.2.0, should be fine for our purpose
180        if #[cfg(all(
181            not(all(target_os = "android", target_arch = "arm")),
182            not(all(target_os = "freebsd", target_arch = "arm")),
183            not(all(target_os = "linux", target_arch = "arm")),
184            not(all(target_os = "horizon", target_arch = "arm")),
185            not(all(target_os = "rtems", target_arch = "arm")),
186            not(all(target_os = "vita", target_arch = "arm")),
187        ))] {
188            extern "C" {
189                pub fn _Unwind_GetIP(ctx: *mut _Unwind_Context) -> libc::uintptr_t;
190                pub fn _Unwind_FindEnclosingFunction(pc: *mut c_void) -> *mut c_void;
191
192                #[cfg(not(all(target_os = "linux", target_arch = "s390x")))]
193                // This function is a misnomer: rather than getting this frame's
194                // Canonical Frame Address (aka the caller frame's SP) it
195                // returns this frame's SP.
196                //
197                // https://github.com/libunwind/libunwind/blob/d32956507cf29d9b1a98a8bce53c78623908f4fe/src/unwind/GetCFA.c#L28-L35
198                #[link_name = "_Unwind_GetCFA"]
199                pub fn get_sp(ctx: *mut _Unwind_Context) -> libc::uintptr_t;
200
201            }
202
203            // s390x uses a biased CFA value, therefore we need to use
204            // _Unwind_GetGR to get the stack pointer register (%r15)
205            // instead of relying on _Unwind_GetCFA.
206            #[cfg(all(target_os = "linux", target_arch = "s390x"))]
207            pub unsafe fn get_sp(ctx: *mut _Unwind_Context) -> libc::uintptr_t {
208                extern "C" {
209                    pub fn _Unwind_GetGR(ctx: *mut _Unwind_Context, index: libc::c_int) -> libc::uintptr_t;
210                }
211                _Unwind_GetGR(ctx, 15)
212            }
213        } else {
214            use core::ptr::addr_of_mut;
215
216            // On android and arm, the function `_Unwind_GetIP` and a bunch of
217            // others are macros, so we define functions containing the
218            // expansion of the macros.
219            //
220            // TODO: link to the header file that defines these macros, if you
221            // can find it. (I, fitzgen, cannot find the header file that some
222            // of these macro expansions were originally borrowed from.)
223            #[repr(C)]
224            enum _Unwind_VRS_Result {
225                _UVRSR_OK = 0,
226                _UVRSR_NOT_IMPLEMENTED = 1,
227                _UVRSR_FAILED = 2,
228            }
229            #[repr(C)]
230            enum _Unwind_VRS_RegClass {
231                _UVRSC_CORE = 0,
232                _UVRSC_VFP = 1,
233                _UVRSC_FPA = 2,
234                _UVRSC_WMMXD = 3,
235                _UVRSC_WMMXC = 4,
236            }
237            #[repr(C)]
238            enum _Unwind_VRS_DataRepresentation {
239                _UVRSD_UINT32 = 0,
240                _UVRSD_VFPX = 1,
241                _UVRSD_FPAX = 2,
242                _UVRSD_UINT64 = 3,
243                _UVRSD_FLOAT = 4,
244                _UVRSD_DOUBLE = 5,
245            }
246
247            type _Unwind_Word = libc::c_uint;
248            extern "C" {
249                fn _Unwind_VRS_Get(
250                    ctx: *mut _Unwind_Context,
251                    klass: _Unwind_VRS_RegClass,
252                    word: _Unwind_Word,
253                    repr: _Unwind_VRS_DataRepresentation,
254                    data: *mut c_void,
255                ) -> _Unwind_VRS_Result;
256            }
257
258            pub unsafe fn _Unwind_GetIP(ctx: *mut _Unwind_Context) -> libc::uintptr_t {
259                let mut val: _Unwind_Word = 0;
260                let ptr = addr_of_mut!(val);
261                let _ = _Unwind_VRS_Get(
262                    ctx,
263                    _Unwind_VRS_RegClass::_UVRSC_CORE,
264                    15,
265                    _Unwind_VRS_DataRepresentation::_UVRSD_UINT32,
266                    ptr.cast::<c_void>(),
267                );
268                (val & !1) as libc::uintptr_t
269            }
270
271            // R13 is the stack pointer on arm.
272            const SP: _Unwind_Word = 13;
273
274            pub unsafe fn get_sp(ctx: *mut _Unwind_Context) -> libc::uintptr_t {
275                let mut val: _Unwind_Word = 0;
276                let ptr = addr_of_mut!(val);
277                let _ = _Unwind_VRS_Get(
278                    ctx,
279                    _Unwind_VRS_RegClass::_UVRSC_CORE,
280                    SP,
281                    _Unwind_VRS_DataRepresentation::_UVRSD_UINT32,
282                    ptr.cast::<c_void>(),
283                );
284                val as libc::uintptr_t
285            }
286
287            // This function also doesn't exist on Android or ARM/Linux, so make it
288            // a no-op.
289            pub unsafe fn _Unwind_FindEnclosingFunction(pc: *mut c_void) -> *mut c_void {
290                pc
291            }
292        }
293    }
294}