std\backtrace\src\symbolize/
gimli.rs

1//! Support for symbolication using the `gimli` crate on crates.io
2//!
3//! This is the default symbolication implementation for Rust.
4
5use self::gimli::read::EndianSlice;
6use self::gimli::NativeEndian as Endian;
7use self::mmap::Mmap;
8use self::stash::Stash;
9use super::BytesOrWideString;
10use super::ResolveWhat;
11use super::SymbolName;
12use addr2line::gimli;
13use core::convert::TryInto;
14use core::mem;
15use libc::c_void;
16use mystd::ffi::OsString;
17use mystd::fs::File;
18use mystd::path::Path;
19use mystd::prelude::v1::*;
20
21#[cfg(backtrace_in_libstd)]
22mod mystd {
23    pub use crate::*;
24}
25#[cfg(not(backtrace_in_libstd))]
26extern crate std as mystd;
27
28cfg_if::cfg_if! {
29    if #[cfg(windows)] {
30        #[path = "gimli/mmap_windows.rs"]
31        mod mmap;
32    } else if #[cfg(target_vendor = "apple")] {
33        #[path = "gimli/mmap_unix.rs"]
34        mod mmap;
35    } else if #[cfg(any(
36        target_os = "android",
37        target_os = "freebsd",
38        target_os = "fuchsia",
39        target_os = "haiku",
40        target_os = "hurd",
41        target_os = "linux",
42        target_os = "openbsd",
43        target_os = "solaris",
44        target_os = "illumos",
45        target_os = "aix",
46        target_os = "cygwin",
47    ))] {
48        #[path = "gimli/mmap_unix.rs"]
49        mod mmap;
50    } else {
51        #[path = "gimli/mmap_fake.rs"]
52        mod mmap;
53    }
54}
55
56mod lru;
57mod stash;
58
59use lru::Lru;
60
61const MAPPINGS_CACHE_SIZE: usize = 4;
62
63struct Mapping {
64    // 'static lifetime is a lie to hack around lack of support for self-referential structs.
65    cx: Context<'static>,
66    _map: Mmap,
67    stash: Stash,
68}
69
70enum Either<A, B> {
71    #[allow(dead_code)]
72    A(A),
73    B(B),
74}
75
76impl Mapping {
77    /// Creates a `Mapping` by ensuring that the `data` specified is used to
78    /// create a `Context` and it can only borrow from that or the `Stash` of
79    /// decompressed sections or auxiliary data.
80    fn mk<F>(data: Mmap, mk: F) -> Option<Mapping>
81    where
82        F: for<'a> FnOnce(&'a [u8], &'a Stash) -> Option<Context<'a>>,
83    {
84        Mapping::mk_or_other(data, move |data, stash| {
85            let cx = mk(data, stash)?;
86            Some(Either::B(cx))
87        })
88    }
89
90    /// Creates a `Mapping` from `data`, or if the closure decides to, returns a
91    /// different mapping.
92    fn mk_or_other<F>(data: Mmap, mk: F) -> Option<Mapping>
93    where
94        F: for<'a> FnOnce(&'a [u8], &'a Stash) -> Option<Either<Mapping, Context<'a>>>,
95    {
96        let stash = Stash::new();
97        let cx = match mk(&data, &stash)? {
98            Either::A(mapping) => return Some(mapping),
99            Either::B(cx) => cx,
100        };
101        Some(Mapping {
102            // Convert to 'static lifetimes since the symbols should
103            // only borrow `map` and `stash` and we're preserving them below.
104            cx: unsafe { core::mem::transmute::<Context<'_>, Context<'static>>(cx) },
105            _map: data,
106            stash,
107        })
108    }
109}
110
111struct Context<'a> {
112    dwarf: addr2line::Context<EndianSlice<'a, Endian>>,
113    object: Object<'a>,
114    package: Option<gimli::DwarfPackage<EndianSlice<'a, Endian>>>,
115}
116
117impl<'data> Context<'data> {
118    // #[feature(optimize_attr)] is enabled when we're built inside libstd
119    #[cfg_attr(backtrace_in_libstd, optimize(size))]
120    fn new(
121        stash: &'data Stash,
122        object: Object<'data>,
123        sup: Option<Object<'data>>,
124        dwp: Option<Object<'data>>,
125    ) -> Option<Context<'data>> {
126        let mut sections = gimli::Dwarf::load(|id| -> Result<_, ()> {
127            if cfg!(not(target_os = "aix")) {
128                let data = object.section(stash, id.name()).unwrap_or(&[]);
129                Ok(EndianSlice::new(data, Endian))
130            } else if let Some(name) = id.xcoff_name() {
131                let data = object.section(stash, name).unwrap_or(&[]);
132                Ok(EndianSlice::new(data, Endian))
133            } else {
134                Ok(EndianSlice::new(&[], Endian))
135            }
136        })
137        .ok()?;
138
139        if let Some(sup) = sup {
140            sections
141                .load_sup(|id| -> Result<_, ()> {
142                    let data = sup.section(stash, id.name()).unwrap_or(&[]);
143                    Ok(EndianSlice::new(data, Endian))
144                })
145                .ok()?;
146        }
147        let dwarf = addr2line::Context::from_dwarf(sections).ok()?;
148
149        let mut package = None;
150        if let Some(dwp) = dwp {
151            package = Some(
152                gimli::DwarfPackage::load(
153                    |id| -> Result<_, gimli::Error> {
154                        let data = id
155                            .dwo_name()
156                            .and_then(|name| dwp.section(stash, name))
157                            .unwrap_or(&[]);
158                        Ok(EndianSlice::new(data, Endian))
159                    },
160                    EndianSlice::new(&[], Endian),
161                )
162                .ok()?,
163            );
164        }
165
166        Some(Context {
167            dwarf,
168            object,
169            package,
170        })
171    }
172
173    fn find_frames(
174        &'_ self,
175        stash: &'data Stash,
176        probe: u64,
177    ) -> gimli::Result<addr2line::FrameIter<'_, EndianSlice<'data, Endian>>> {
178        use addr2line::{LookupContinuation, LookupResult};
179
180        let mut l = self.dwarf.find_frames(probe);
181        loop {
182            let (load, continuation) = match l {
183                LookupResult::Output(output) => break output,
184                LookupResult::Load { load, continuation } => (load, continuation),
185            };
186
187            l = continuation.resume(handle_split_dwarf(self.package.as_ref(), stash, load));
188        }
189    }
190}
191
192fn mmap(path: &Path) -> Option<Mmap> {
193    let file = File::open(path).ok()?;
194    let len = file.metadata().ok()?.len().try_into().ok()?;
195    unsafe { Mmap::map(&file, len, 0) }
196}
197
198cfg_if::cfg_if! {
199    if #[cfg(any(windows, target_os = "cygwin"))] {
200        mod coff;
201        use self::coff::{handle_split_dwarf, Object};
202    } else if #[cfg(any(target_vendor = "apple"))] {
203        mod macho;
204        use self::macho::{handle_split_dwarf, Object};
205    } else if #[cfg(target_os = "aix")] {
206        mod xcoff;
207        use self::xcoff::{handle_split_dwarf, Object};
208    } else {
209        mod elf;
210        use self::elf::{handle_split_dwarf, Object};
211    }
212}
213
214cfg_if::cfg_if! {
215    if #[cfg(any(windows, target_os = "cygwin"))] {
216        mod libs_windows;
217        use libs_windows::native_libraries;
218    } else if #[cfg(target_vendor = "apple")] {
219        mod libs_macos;
220        use libs_macos::native_libraries;
221    } else if #[cfg(target_os = "illumos")] {
222        mod libs_illumos;
223        use libs_illumos::native_libraries;
224    } else if #[cfg(all(
225        any(
226            target_os = "linux",
227            target_os = "fuchsia",
228            target_os = "freebsd",
229            target_os = "hurd",
230            target_os = "openbsd",
231            target_os = "netbsd",
232            target_os = "nto",
233            target_os = "android",
234        ),
235        not(target_env = "uclibc"),
236    ))] {
237        mod libs_dl_iterate_phdr;
238        use libs_dl_iterate_phdr::native_libraries;
239        #[path = "gimli/parse_running_mmaps_unix.rs"]
240        mod parse_running_mmaps;
241    } else if #[cfg(target_env = "libnx")] {
242        mod libs_libnx;
243        use libs_libnx::native_libraries;
244    } else if #[cfg(target_os = "haiku")] {
245        mod libs_haiku;
246        use libs_haiku::native_libraries;
247    } else if #[cfg(target_os = "aix")] {
248        mod libs_aix;
249        use libs_aix::native_libraries;
250    } else {
251        // Everything else should doesn't know how to load native libraries.
252        fn native_libraries() -> Vec<Library> {
253            Vec::new()
254        }
255    }
256}
257
258#[derive(Default)]
259struct Cache {
260    /// All known shared libraries that have been loaded.
261    libraries: Vec<Library>,
262
263    /// Mappings cache where we retain parsed dwarf information.
264    ///
265    /// This list has a fixed capacity for its entire lifetime which never
266    /// increases. The `usize` element of each pair is an index into `libraries`
267    /// above where `usize::max_value()` represents the current executable. The
268    /// `Mapping` is corresponding parsed dwarf information.
269    ///
270    /// Note that this is basically an LRU cache and we'll be shifting things
271    /// around in here as we symbolize addresses.
272    mappings: Lru<(usize, Mapping), MAPPINGS_CACHE_SIZE>,
273}
274
275struct Library {
276    name: OsString,
277    #[cfg(target_os = "android")]
278    /// On Android, the dynamic linker [can map libraries directly from a
279    /// ZIP archive][ndk-linker-changes] (typically an `.apk`).
280    ///
281    /// The linker requires that these libraries are stored uncompressed
282    /// and page-aligned.
283    ///
284    /// These "embedded" libraries have filepaths of the form
285    /// `/path/to/my.apk!/lib/mylib.so` (where `/path/to/my.apk` is the archive
286    /// and `lib/mylib.so` is the name of the library within the archive).
287    ///
288    /// This mechanism is present on Android since API level 23.
289    ///
290    /// [ndk-linker-changes]: https://android.googlesource.com/platform/bionic/+/main/android-changes-for-ndk-developers.md#opening-shared-libraries-directly-from-an-apk
291    zip_offset: Option<u64>,
292    #[cfg(target_os = "aix")]
293    /// On AIX, the library mmapped can be a member of a big-archive file.
294    /// For example, with a big-archive named libfoo.a containing libbar.so,
295    /// one can use `dlopen("libfoo.a(libbar.so)", RTLD_MEMBER | RTLD_LAZY)`
296    /// to use the `libbar.so` library. In this case, only `libbar.so` is
297    /// mmapped, not the whole `libfoo.a`.
298    member_name: OsString,
299    /// Segments of this library loaded into memory, and where they're loaded.
300    segments: Vec<LibrarySegment>,
301    /// The "bias" of this library, typically where it's loaded into memory.
302    /// This value is added to each segment's stated address to get the actual
303    /// virtual memory address that the segment is loaded into. Additionally
304    /// this bias is subtracted from real virtual memory addresses to index into
305    /// debuginfo and the symbol table.
306    bias: usize,
307}
308
309struct LibrarySegment {
310    /// The stated address of this segment in the object file. This is not
311    /// actually where the segment is loaded, but rather this address plus the
312    /// containing library's `bias` is where to find it.
313    stated_virtual_memory_address: usize,
314    /// The size of this segment in memory.
315    len: usize,
316}
317
318fn create_mapping(lib: &Library) -> Option<Mapping> {
319    cfg_if::cfg_if! {
320        if #[cfg(target_os = "aix")] {
321            Mapping::new(lib.name.as_ref(), &lib.member_name)
322        } else if #[cfg(target_os = "android")] {
323            Mapping::new_android(lib.name.as_ref(), lib.zip_offset)
324        } else {
325            Mapping::new(lib.name.as_ref())
326        }
327    }
328}
329
330/// Try to extract the archive path from an "embedded" library path
331/// (e.g. `/path/to/my.apk` from `/path/to/my.apk!/mylib.so`).
332///
333/// Returns `None` if the path does not contain a `!/` separator.
334#[cfg(target_os = "android")]
335fn extract_zip_path_android(path: &mystd::ffi::OsStr) -> Option<&mystd::ffi::OsStr> {
336    use mystd::os::unix::ffi::OsStrExt;
337
338    path.as_bytes()
339        .windows(2)
340        .enumerate()
341        .find(|(_, chunk)| chunk == b"!/")
342        .map(|(index, _)| mystd::ffi::OsStr::from_bytes(path.as_bytes().split_at(index).0))
343}
344
345// unsafe because this is required to be externally synchronized
346pub unsafe fn clear_symbol_cache() {
347    unsafe {
348        Cache::with_global(|cache| cache.mappings.clear());
349    }
350}
351
352impl Cache {
353    fn new() -> Cache {
354        Cache {
355            mappings: Lru::default(),
356            libraries: native_libraries(),
357        }
358    }
359
360    // unsafe because this is required to be externally synchronized
361    // #[feature(optimize_attr)] is enabled when we're built inside libstd
362    #[cfg_attr(backtrace_in_libstd, optimize(size))]
363    unsafe fn with_global(f: impl FnOnce(&mut Self)) {
364        // A very small, very simple LRU cache for debug info mappings.
365        //
366        // The hit rate should be very high, since the typical stack doesn't cross
367        // between many shared libraries.
368        //
369        // The `addr2line::Context` structures are pretty expensive to create. Its
370        // cost is expected to be amortized by subsequent `locate` queries, which
371        // leverage the structures built when constructing `addr2line::Context`s to
372        // get nice speedups. If we didn't have this cache, that amortization would
373        // never happen, and symbolicating backtraces would be ssssllllooooowwww.
374        static mut MAPPINGS_CACHE: Option<Cache> = None;
375
376        unsafe {
377            // FIXME: https://github.com/rust-lang/backtrace-rs/issues/678
378            #[allow(static_mut_refs)]
379            f(MAPPINGS_CACHE.get_or_insert_with(Cache::new))
380        }
381    }
382
383    fn avma_to_svma(&self, addr: *const u8) -> Option<(usize, *const u8)> {
384        self.libraries
385            .iter()
386            .enumerate()
387            .filter_map(|(i, lib)| {
388                // First up, test if this `lib` has any segment containing the
389                // `addr` (handling relocation). If this check passes then we
390                // can continue below and actually translate the address.
391                //
392                // Note that we're using `wrapping_add` here to avoid overflow
393                // checks. It's been seen in the wild that the SVMA + bias
394                // computation overflows. It seems a bit odd that would happen
395                // but there's not a huge amount we can do about it other than
396                // probably just ignore those segments since they're likely
397                // pointing off into space. This originally came up in
398                // rust-lang/backtrace-rs#329.
399                if !lib.segments.iter().any(|s| {
400                    let svma = s.stated_virtual_memory_address;
401                    let start = svma.wrapping_add(lib.bias);
402                    let end = start.wrapping_add(s.len);
403                    let address = addr as usize;
404                    start <= address && address < end
405                }) {
406                    return None;
407                }
408
409                // Now that we know `lib` contains `addr`, we can offset with
410                // the bias to find the stated virtual memory address.
411                let svma = (addr as usize).wrapping_sub(lib.bias);
412                Some((i, svma as *const u8))
413            })
414            .next()
415    }
416
417    fn mapping_for_lib<'a>(&'a mut self, lib: usize) -> Option<(&'a mut Context<'a>, &'a Stash)> {
418        let cache_idx = self.mappings.iter().position(|(lib_id, _)| *lib_id == lib);
419
420        let cache_entry = if let Some(idx) = cache_idx {
421            self.mappings.move_to_front(idx)
422        } else {
423            // When the mapping is not in the cache, create a new mapping and insert it,
424            // which will also evict the oldest entry.
425            create_mapping(&self.libraries[lib])
426                .and_then(|mapping| self.mappings.push_front((lib, mapping)))
427        };
428
429        let (_, mapping) = cache_entry?;
430        let cx: &'a mut Context<'static> = &mut mapping.cx;
431        let stash: &'a Stash = &mapping.stash;
432        // don't leak the `'static` lifetime, make sure it's scoped to just
433        // ourselves
434        Some((
435            unsafe { mem::transmute::<&'a mut Context<'static>, &'a mut Context<'a>>(cx) },
436            stash,
437        ))
438    }
439}
440
441pub unsafe fn resolve(what: ResolveWhat<'_>, cb: &mut dyn FnMut(&super::Symbol)) {
442    let addr = what.address_or_ip();
443    let mut call = |sym: Symbol<'_>| {
444        // Extend the lifetime of `sym` to `'static` since we are unfortunately
445        // required to here, but it's only ever going out as a reference so no
446        // reference to it should be persisted beyond this frame anyway.
447        // SAFETY: praying the above is correct
448        let sym = unsafe { mem::transmute::<Symbol<'_>, Symbol<'static>>(sym) };
449        (cb)(&super::Symbol { inner: sym });
450    };
451
452    unsafe {
453        Cache::with_global(|cache| {
454            let (lib, addr) = match cache.avma_to_svma(addr.cast_const().cast::<u8>()) {
455                Some(pair) => pair,
456                None => return,
457            };
458
459            // Finally, get a cached mapping or create a new mapping for this file, and
460            // evaluate the DWARF info to find the file/line/name for this address.
461            let (cx, stash) = match cache.mapping_for_lib(lib) {
462                Some((cx, stash)) => (cx, stash),
463                None => return,
464            };
465            let mut any_frames = false;
466            if let Ok(mut frames) = cx.find_frames(stash, addr as u64) {
467                while let Ok(Some(frame)) = frames.next() {
468                    any_frames = true;
469                    let name = match frame.function {
470                        Some(f) => Some(f.name.slice()),
471                        None => cx.object.search_symtab(addr as u64),
472                    };
473                    call(Symbol::Frame {
474                        addr: addr as *mut c_void,
475                        location: frame.location,
476                        name,
477                    });
478                }
479            }
480            if !any_frames {
481                if let Some((object_cx, object_addr)) = cx.object.search_object_map(addr as u64) {
482                    if let Ok(mut frames) = object_cx.find_frames(stash, object_addr) {
483                        while let Ok(Some(frame)) = frames.next() {
484                            any_frames = true;
485                            call(Symbol::Frame {
486                                addr: addr as *mut c_void,
487                                location: frame.location,
488                                name: frame.function.map(|f| f.name.slice()),
489                            });
490                        }
491                    }
492                }
493            }
494            if !any_frames {
495                if let Some(name) = cx.object.search_symtab(addr as u64) {
496                    call(Symbol::Symtab { name });
497                }
498            }
499        });
500    }
501}
502
503pub enum Symbol<'a> {
504    /// We were able to locate frame information for this symbol, and
505    /// `addr2line`'s frame internally has all the nitty gritty details.
506    Frame {
507        addr: *mut c_void,
508        location: Option<addr2line::Location<'a>>,
509        name: Option<&'a [u8]>,
510    },
511    /// Couldn't find debug information, but we found it in the symbol table of
512    /// the elf executable.
513    Symtab { name: &'a [u8] },
514}
515
516impl Symbol<'_> {
517    pub fn name(&self) -> Option<SymbolName<'_>> {
518        match self {
519            Symbol::Frame { name, .. } => {
520                let name = name.as_ref()?;
521                Some(SymbolName::new(name))
522            }
523            Symbol::Symtab { name, .. } => Some(SymbolName::new(name)),
524        }
525    }
526
527    pub fn addr(&self) -> Option<*mut c_void> {
528        match self {
529            Symbol::Frame { addr, .. } => Some(*addr),
530            Symbol::Symtab { .. } => None,
531        }
532    }
533
534    pub fn filename_raw(&self) -> Option<BytesOrWideString<'_>> {
535        match self {
536            Symbol::Frame { location, .. } => {
537                let file = location.as_ref()?.file?;
538                Some(BytesOrWideString::Bytes(file.as_bytes()))
539            }
540            Symbol::Symtab { .. } => None,
541        }
542    }
543
544    pub fn filename(&self) -> Option<&Path> {
545        match self {
546            Symbol::Frame { location, .. } => {
547                let file = location.as_ref()?.file?;
548                Some(Path::new(file))
549            }
550            Symbol::Symtab { .. } => None,
551        }
552    }
553
554    pub fn lineno(&self) -> Option<u32> {
555        match self {
556            Symbol::Frame { location, .. } => location.as_ref()?.line,
557            Symbol::Symtab { .. } => None,
558        }
559    }
560
561    pub fn colno(&self) -> Option<u32> {
562        match self {
563            Symbol::Frame { location, .. } => location.as_ref()?.column,
564            Symbol::Symtab { .. } => None,
565        }
566    }
567}