std/backtrace/src/symbolize/gimli/
elf.rs

1#![allow(clippy::useless_conversion)]
2
3use super::mystd::ffi::OsStr;
4use super::mystd::fs;
5use super::mystd::os::unix::ffi::OsStrExt;
6use super::mystd::path::{Path, PathBuf};
7use super::Either;
8use super::{gimli, Context, Endian, EndianSlice, Mapping, Stash};
9use alloc::string::String;
10use alloc::sync::Arc;
11use alloc::vec::Vec;
12use core::convert::{TryFrom, TryInto};
13use core::str;
14#[cfg(feature = "ruzstd")]
15use object::elf::ELFCOMPRESS_ZSTD;
16use object::elf::{ELFCOMPRESS_ZLIB, ELF_NOTE_GNU, NT_GNU_BUILD_ID, SHF_COMPRESSED};
17use object::read::elf::{CompressionHeader, FileHeader, SectionHeader, SectionTable, Sym};
18use object::read::StringTable;
19use object::{BigEndian, Bytes, NativeEndian};
20
21#[cfg(target_pointer_width = "32")]
22type Elf = object::elf::FileHeader32<NativeEndian>;
23#[cfg(target_pointer_width = "64")]
24type Elf = object::elf::FileHeader64<NativeEndian>;
25
26impl Mapping {
27    pub fn new(path: &Path) -> Option<Mapping> {
28        let map = super::mmap(path)?;
29        Mapping::mk_or_other(map, |map, stash| {
30            let object = Object::parse(map)?;
31
32            // Try to locate an external debug file using the build ID.
33            if let Some(path_debug) = object.build_id().and_then(locate_build_id) {
34                if let Some(mapping) = Mapping::new_debug(path, path_debug, None) {
35                    return Some(Either::A(mapping));
36                }
37            }
38
39            // Try to locate an external debug file using the GNU debug link section.
40            if let Some((path_debug, crc)) = object.gnu_debuglink_path(path) {
41                if let Some(mapping) = Mapping::new_debug(path, path_debug, Some(crc)) {
42                    return Some(Either::A(mapping));
43                }
44            }
45
46            let dwp = Mapping::load_dwarf_package(path, stash);
47
48            Context::new(stash, object, None, dwp).map(Either::B)
49        })
50    }
51
52    /// On Android, shared objects can be loaded directly from a ZIP archive
53    /// (see: [`super::Library::zip_offset`]).
54    ///
55    /// If `zip_offset` is not None, we interpret the `path` as an
56    /// "embedded" library path, and the value of `zip_offset` tells us where
57    /// in the ZIP archive the library data starts.
58    ///
59    /// We expect `zip_offset` to be page-aligned because the dynamic linker
60    /// requires this. Otherwise, loading the embedded library will fail.
61    ///
62    /// If we fail to load an embedded library for any reason, we fallback to
63    /// interpreting the path as a literal file on disk (same as calling [`Self::new`]).
64    #[cfg(target_os = "android")]
65    pub fn new_android(path: &Path, zip_offset: Option<u64>) -> Option<Mapping> {
66        fn map_embedded_library(path: &Path, zip_offset: u64) -> Option<Mapping> {
67            // get path of ZIP archive (delimited by `!/`)
68            let zip_path = Path::new(super::extract_zip_path_android(path.as_os_str())?);
69
70            let file = fs::File::open(zip_path).ok()?;
71            let len = file.metadata().ok()?.len();
72
73            // NOTE: we map the remainder of the entire archive instead of just the library so we don't have to determine its length
74            // NOTE: mmap will fail if `zip_offset` is not page-aligned
75            let map = unsafe {
76                super::mmap::Mmap::map(&file, usize::try_from(len - zip_offset).ok()?, zip_offset)
77            }?;
78
79            Mapping::mk(map, |map, stash| {
80                Context::new(stash, Object::parse(&map)?, None, None)
81            })
82        }
83
84        // if ZIP offset is given, try mapping as a ZIP-embedded library
85        // otherwise, fallback to mapping as a literal filepath
86        if let Some(zip_offset) = zip_offset {
87            map_embedded_library(path, zip_offset).or_else(|| Self::new(path))
88        } else {
89            Self::new(path)
90        }
91    }
92
93    /// Load debuginfo from an external debug file.
94    fn new_debug(original_path: &Path, path: PathBuf, crc: Option<u32>) -> Option<Mapping> {
95        let map = super::mmap(&path)?;
96        Mapping::mk(map, |map, stash| {
97            let object = Object::parse(map)?;
98
99            if let Some(_crc) = crc {
100                // TODO: check crc
101            }
102
103            // Try to locate a supplementary object file.
104            let mut sup = None;
105            if let Some((path_sup, build_id_sup)) = object.gnu_debugaltlink_path(&path) {
106                if let Some(map_sup) = super::mmap(&path_sup) {
107                    let map_sup = stash.cache_mmap(map_sup);
108                    if let Some(sup_) = Object::parse(map_sup) {
109                        if sup_.build_id() == Some(build_id_sup) {
110                            sup = Some(sup_);
111                        }
112                    }
113                }
114            }
115
116            let dwp = Mapping::load_dwarf_package(original_path, stash);
117
118            Context::new(stash, object, sup, dwp)
119        })
120    }
121
122    /// Try to locate a DWARF package file.
123    fn load_dwarf_package<'data>(path: &Path, stash: &'data Stash) -> Option<Object<'data>> {
124        let mut path_dwp = path.to_path_buf();
125        let dwp_extension = path
126            .extension()
127            .map(|previous_extension| {
128                let mut previous_extension = previous_extension.to_os_string();
129                previous_extension.push(".dwp");
130                previous_extension
131            })
132            .unwrap_or_else(|| "dwp".into());
133        path_dwp.set_extension(dwp_extension);
134        if let Some(map_dwp) = super::mmap(&path_dwp) {
135            let map_dwp = stash.cache_mmap(map_dwp);
136            if let Some(dwp_) = Object::parse(map_dwp) {
137                return Some(dwp_);
138            }
139        }
140
141        None
142    }
143}
144
145struct ParsedSym {
146    address: u64,
147    size: u64,
148    name: u32,
149}
150
151pub struct Object<'a> {
152    /// Zero-sized type representing the native endianness.
153    ///
154    /// We could use a literal instead, but this helps ensure correctness.
155    endian: NativeEndian,
156    /// The entire file data.
157    data: &'a [u8],
158    sections: SectionTable<'a, Elf>,
159    strings: StringTable<'a>,
160    /// List of pre-parsed and sorted symbols by base address.
161    syms: Vec<ParsedSym>,
162}
163
164impl<'a> Object<'a> {
165    fn parse(data: &'a [u8]) -> Option<Object<'a>> {
166        let elf = Elf::parse(data).ok()?;
167        let endian = elf.endian().ok()?;
168        let sections = elf.sections(endian, data).ok()?;
169        let mut syms = sections
170            .symbols(endian, data, object::elf::SHT_SYMTAB)
171            .ok()?;
172        if syms.is_empty() {
173            syms = sections
174                .symbols(endian, data, object::elf::SHT_DYNSYM)
175                .ok()?;
176        }
177        let strings = syms.strings();
178
179        let mut syms = syms
180            .iter()
181            // Only look at function/object symbols. This mirrors what
182            // libbacktrace does and in general we're only symbolicating
183            // function addresses in theory. Object symbols correspond
184            // to data, and maybe someone's crazy enough to have a
185            // function go into static data?
186            .filter(|sym| {
187                let st_type = sym.st_type();
188                st_type == object::elf::STT_FUNC || st_type == object::elf::STT_OBJECT
189            })
190            // skip anything that's in an undefined section header,
191            // since it means it's an imported function and we're only
192            // symbolicating with locally defined functions.
193            .filter(|sym| sym.st_shndx(endian) != object::elf::SHN_UNDEF)
194            .map(|sym| {
195                let address = sym.st_value(endian).into();
196                let size = sym.st_size(endian).into();
197                let name = sym.st_name(endian);
198                ParsedSym {
199                    address,
200                    size,
201                    name,
202                }
203            })
204            .collect::<Vec<_>>();
205        syms.sort_unstable_by_key(|s| s.address);
206        Some(Object {
207            endian,
208            data,
209            sections,
210            strings,
211            syms,
212        })
213    }
214
215    pub fn section(&self, stash: &'a Stash, name: &str) -> Option<&'a [u8]> {
216        if let Some(section) = self.section_header(name) {
217            let mut data = Bytes(section.data(self.endian, self.data).ok()?);
218
219            // Check for DWARF-standard (gABI) compression, i.e., as generated
220            // by ld's `--compress-debug-sections=zlib-gabi` and
221            // `--compress-debug-sections=zstd` flags.
222            let flags: u64 = section.sh_flags(self.endian).into();
223            if (flags & u64::from(SHF_COMPRESSED)) == 0 {
224                // Not compressed.
225                return Some(data.0);
226            }
227
228            let header = data.read::<<Elf as FileHeader>::CompressionHeader>().ok()?;
229            match header.ch_type(self.endian) {
230                ELFCOMPRESS_ZLIB => {
231                    let size = usize::try_from(header.ch_size(self.endian)).ok()?;
232                    let buf = stash.allocate(size);
233                    decompress_zlib(data.0, buf)?;
234                    return Some(buf);
235                }
236                #[cfg(feature = "ruzstd")]
237                ELFCOMPRESS_ZSTD => {
238                    let size = usize::try_from(header.ch_size(self.endian)).ok()?;
239                    let buf = stash.allocate(size);
240                    decompress_zstd(data.0, buf)?;
241                    return Some(buf);
242                }
243                _ => return None, // Unknown compression type.
244            }
245        }
246
247        // Check for the nonstandard GNU compression format, i.e., as generated
248        // by ld's `--compress-debug-sections=zlib-gnu` flag. This means that if
249        // we're actually asking for `.debug_info` then we need to look up a
250        // section named `.zdebug_info`.
251        if !name.starts_with(".debug_") {
252            return None;
253        }
254        let debug_name = name[7..].as_bytes();
255        let compressed_section = self
256            .sections
257            .iter()
258            .filter_map(|header| {
259                let name = self.sections.section_name(self.endian, header).ok()?;
260                if name.starts_with(b".zdebug_") && &name[8..] == debug_name {
261                    Some(header)
262                } else {
263                    None
264                }
265            })
266            .next()?;
267        let mut data = Bytes(compressed_section.data(self.endian, self.data).ok()?);
268        if data.read_bytes(8).ok()?.0 != b"ZLIB\0\0\0\0" {
269            return None;
270        }
271        let size = usize::try_from(data.read::<object::U32Bytes<_>>().ok()?.get(BigEndian)).ok()?;
272        let buf = stash.allocate(size);
273        decompress_zlib(data.0, buf)?;
274        Some(buf)
275    }
276
277    fn section_header(&self, name: &str) -> Option<&<Elf as FileHeader>::SectionHeader> {
278        self.sections
279            .section_by_name(self.endian, name.as_bytes())
280            .map(|(_index, section)| section)
281    }
282
283    pub fn search_symtab(&self, addr: u64) -> Option<&[u8]> {
284        // Same sort of binary search as Windows above
285        let i = match self.syms.binary_search_by_key(&addr, |sym| sym.address) {
286            Ok(i) => i,
287            Err(i) => i.checked_sub(1)?,
288        };
289        let sym = self.syms.get(i)?;
290        if sym.address <= addr && addr <= sym.address + sym.size {
291            self.strings.get(sym.name).ok()
292        } else {
293            None
294        }
295    }
296
297    pub(super) fn search_object_map(&self, _addr: u64) -> Option<(&Context<'_>, u64)> {
298        None
299    }
300
301    fn build_id(&self) -> Option<&'a [u8]> {
302        for section in self.sections.iter() {
303            if let Ok(Some(mut notes)) = section.notes(self.endian, self.data) {
304                while let Ok(Some(note)) = notes.next() {
305                    if note.name() == ELF_NOTE_GNU && note.n_type(self.endian) == NT_GNU_BUILD_ID {
306                        return Some(note.desc());
307                    }
308                }
309            }
310        }
311        None
312    }
313
314    // The contents of the ".gnu_debuglink" section is documented at:
315    // https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html
316    fn gnu_debuglink_path(&self, path: &Path) -> Option<(PathBuf, u32)> {
317        let section = self.section_header(".gnu_debuglink")?;
318        let data = section.data(self.endian, self.data).ok()?;
319        let len = data.iter().position(|x| *x == 0)?;
320        let filename = OsStr::from_bytes(&data[..len]);
321        let offset = (len + 1 + 3) & !3;
322        let crc_bytes = data
323            .get(offset..offset + 4)
324            .and_then(|bytes| bytes.try_into().ok())?;
325        let crc = u32::from_ne_bytes(crc_bytes);
326        let path_debug = locate_debuglink(path, filename)?;
327        Some((path_debug, crc))
328    }
329
330    // The format of the ".gnu_debugaltlink" section is based on gdb.
331    fn gnu_debugaltlink_path(&self, path: &Path) -> Option<(PathBuf, &'a [u8])> {
332        let section = self.section_header(".gnu_debugaltlink")?;
333        let data = section.data(self.endian, self.data).ok()?;
334        let len = data.iter().position(|x| *x == 0)?;
335        let filename = OsStr::from_bytes(&data[..len]);
336        let build_id = &data[len + 1..];
337        let path_sup = locate_debugaltlink(path, filename, build_id)?;
338        Some((path_sup, build_id))
339    }
340}
341
342fn decompress_zlib(input: &[u8], output: &mut [u8]) -> Option<()> {
343    use miniz_oxide::inflate::core::inflate_flags::{
344        TINFL_FLAG_PARSE_ZLIB_HEADER, TINFL_FLAG_USING_NON_WRAPPING_OUTPUT_BUF,
345    };
346    use miniz_oxide::inflate::core::{decompress, DecompressorOxide};
347    use miniz_oxide::inflate::TINFLStatus;
348
349    let (status, in_read, out_read) = decompress(
350        &mut DecompressorOxide::new(),
351        input,
352        output,
353        0,
354        TINFL_FLAG_USING_NON_WRAPPING_OUTPUT_BUF | TINFL_FLAG_PARSE_ZLIB_HEADER,
355    );
356    if status == TINFLStatus::Done && in_read == input.len() && out_read == output.len() {
357        Some(())
358    } else {
359        None
360    }
361}
362
363#[cfg(feature = "ruzstd")]
364fn decompress_zstd(mut input: &[u8], mut output: &mut [u8]) -> Option<()> {
365    use ruzstd::frame::ReadFrameHeaderError;
366    use ruzstd::frame_decoder::FrameDecoderError;
367    use ruzstd::io::Read;
368
369    while !input.is_empty() {
370        let mut decoder = match ruzstd::StreamingDecoder::new(&mut input) {
371            Ok(decoder) => decoder,
372            Err(FrameDecoderError::ReadFrameHeaderError(ReadFrameHeaderError::SkipFrame {
373                length,
374                ..
375            })) => {
376                input = &input.get(length as usize..)?;
377                continue;
378            }
379            Err(_) => return None,
380        };
381        loop {
382            let bytes_written = decoder.read(output).ok()?;
383            if bytes_written == 0 {
384                break;
385            }
386            output = &mut output[bytes_written..];
387        }
388    }
389
390    if !output.is_empty() {
391        // Lengths didn't match, something is wrong.
392        return None;
393    }
394
395    Some(())
396}
397
398const DEBUG_PATH: &str = "/usr/lib/debug";
399
400fn debug_path_exists() -> bool {
401    cfg_if::cfg_if! {
402        if #[cfg(any(target_os = "freebsd", target_os = "hurd", target_os = "linux"))] {
403            use core::sync::atomic::{AtomicU8, Ordering};
404            static DEBUG_PATH_EXISTS: AtomicU8 = AtomicU8::new(0);
405
406            let mut exists = DEBUG_PATH_EXISTS.load(Ordering::Relaxed);
407            if exists == 0 {
408                exists = if Path::new(DEBUG_PATH).is_dir() {
409                    1
410                } else {
411                    2
412                };
413                DEBUG_PATH_EXISTS.store(exists, Ordering::Relaxed);
414            }
415            exists == 1
416        } else {
417            false
418        }
419    }
420}
421
422/// Locate a debug file based on its build ID.
423///
424/// The format of build id paths is documented at:
425/// https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html
426fn locate_build_id(build_id: &[u8]) -> Option<PathBuf> {
427    const BUILD_ID_PATH: &str = "/usr/lib/debug/.build-id/";
428    const BUILD_ID_SUFFIX: &str = ".debug";
429
430    if build_id.len() < 2 {
431        return None;
432    }
433
434    if !debug_path_exists() {
435        return None;
436    }
437
438    let mut path =
439        String::with_capacity(BUILD_ID_PATH.len() + BUILD_ID_SUFFIX.len() + build_id.len() * 2 + 1);
440    path.push_str(BUILD_ID_PATH);
441    path.push(char::from_digit((build_id[0] >> 4) as u32, 16)?);
442    path.push(char::from_digit((build_id[0] & 0xf) as u32, 16)?);
443    path.push('/');
444    for byte in &build_id[1..] {
445        path.push(char::from_digit((byte >> 4) as u32, 16)?);
446        path.push(char::from_digit((byte & 0xf) as u32, 16)?);
447    }
448    path.push_str(BUILD_ID_SUFFIX);
449    Some(PathBuf::from(path))
450}
451
452/// Locate a file specified in a `.gnu_debuglink` section.
453///
454/// `path` is the file containing the section.
455/// `filename` is from the contents of the section.
456///
457/// Search order is based on gdb, documented at:
458/// https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html
459///
460/// gdb also allows the user to customize the debug search path, but we don't.
461///
462/// gdb also supports debuginfod, but we don't yet.
463fn locate_debuglink(path: &Path, filename: &OsStr) -> Option<PathBuf> {
464    let path = fs::canonicalize(path).ok()?;
465    let parent = path.parent()?;
466    let mut f =
467        PathBuf::with_capacity(DEBUG_PATH.len() + parent.as_os_str().len() + filename.len() + 2);
468    let filename = Path::new(filename);
469
470    // Try "/parent/filename" if it differs from "path"
471    f.push(parent);
472    f.push(filename);
473    if f != path && f.is_file() {
474        return Some(f);
475    }
476
477    // Try "/parent/.debug/filename"
478    f.clear();
479    f.push(parent);
480    f.push(".debug");
481    f.push(filename);
482    if f.is_file() {
483        return Some(f);
484    }
485
486    if debug_path_exists() {
487        // Try "/usr/lib/debug/parent/filename"
488        f.clear();
489        f.push(DEBUG_PATH);
490        f.push(parent.strip_prefix("/").unwrap());
491        f.push(filename);
492        if f.is_file() {
493            return Some(f);
494        }
495    }
496
497    None
498}
499
500/// Locate a file specified in a `.gnu_debugaltlink` section.
501///
502/// `path` is the file containing the section.
503/// `filename` and `build_id` are the contents of the section.
504///
505/// Search order is based on gdb:
506/// - filename, which is either absolute or relative to `path`
507/// - the build ID path under `BUILD_ID_PATH`
508///
509/// gdb also allows the user to customize the debug search path, but we don't.
510///
511/// gdb also supports debuginfod, but we don't yet.
512fn locate_debugaltlink(path: &Path, filename: &OsStr, build_id: &[u8]) -> Option<PathBuf> {
513    let filename = Path::new(filename);
514    if filename.is_absolute() {
515        if filename.is_file() {
516            return Some(filename.into());
517        }
518    } else {
519        let path = fs::canonicalize(path).ok()?;
520        let parent = path.parent()?;
521        let mut f = PathBuf::from(parent);
522        f.push(filename);
523        if f.is_file() {
524            return Some(f);
525        }
526    }
527
528    locate_build_id(build_id)
529}
530
531pub(super) fn handle_split_dwarf<'data>(
532    package: Option<&gimli::DwarfPackage<EndianSlice<'data, Endian>>>,
533    stash: &'data Stash,
534    load: addr2line::SplitDwarfLoad<EndianSlice<'data, Endian>>,
535) -> Option<Arc<gimli::Dwarf<EndianSlice<'data, Endian>>>> {
536    if let Some(dwp) = package.as_ref() {
537        if let Ok(Some(cu)) = dwp.find_cu(load.dwo_id, &load.parent) {
538            return Some(Arc::new(cu));
539        }
540    }
541
542    let mut path = PathBuf::new();
543    if let Some(p) = load.comp_dir.as_ref() {
544        path.push(OsStr::from_bytes(&p));
545    }
546
547    path.push(OsStr::from_bytes(&load.path.as_ref()?));
548
549    if let Some(map_dwo) = super::mmap(&path) {
550        let map_dwo = stash.cache_mmap(map_dwo);
551        if let Some(dwo) = Object::parse(map_dwo) {
552            return gimli::Dwarf::load(|id| -> Result<_, ()> {
553                let data = id
554                    .dwo_name()
555                    .and_then(|name| dwo.section(stash, name))
556                    .unwrap_or(&[]);
557                Ok(EndianSlice::new(data, Endian))
558            })
559            .ok()
560            .map(|mut dwo_dwarf| {
561                dwo_dwarf.make_dwo(&load.parent);
562                Arc::new(dwo_dwarf)
563            });
564        }
565    }
566
567    None
568}