Skip to main content

framehop/
unwinder.rs

1use alloc::string::String;
2use alloc::sync::Arc;
3use alloc::vec::Vec;
4use fallible_iterator::FallibleIterator;
5use gimli::{EndianSlice, LittleEndian};
6
7use crate::arch::Arch;
8use crate::cache::{AllocationPolicy, Cache};
9use crate::dwarf::{
10    DwarfCfiIndex, DwarfUnwinder, DwarfUnwinderError, DwarfUnwinding, EhFrameHdrTable,
11    UnwindSectionType,
12};
13use crate::error::{Error, UnwinderError};
14use crate::instruction_analysis::InstructionAnalysis;
15
16#[cfg(feature = "macho")]
17use crate::macho::{
18    CompactUnwindInfoUnwinder, CompactUnwindInfoUnwinding, CuiUnwindResult, TextBytes,
19};
20#[cfg(feature = "pe")]
21use crate::pe::{DataAtRvaRange, PeUnwinderError, PeUnwinding};
22use crate::rule_cache::CacheResult;
23use crate::unwind_result::UnwindResult;
24use crate::unwind_rule::UnwindRule;
25use crate::{FrameAddress, FramePointerFallbackReason, UnwindFrame, UnwindFrameOutcome};
26
27use core::marker::PhantomData;
28use core::ops::{Deref, Range};
29use core::sync::atomic::{AtomicU64, Ordering};
30
31/// Unwinder is the trait that each CPU architecture's concrete unwinder type implements.
32/// This trait's methods are what let you do the actual unwinding.
33pub trait Unwinder: Clone {
34    /// The unwind registers type for the targeted CPU architecture.
35    type UnwindRegs;
36
37    /// The unwind cache for the targeted CPU architecture.
38    /// This is an associated type because the cache stores unwind rules, whose concrete
39    /// type depends on the CPU arch, and because the cache can support different allocation
40    /// policies.
41    type Cache;
42
43    /// The module type. This is an associated type because the concrete type varies
44    /// depending on the type you use to give the module access to the unwind section data.
45    type Module;
46
47    /// Add a module that's loaded in the profiled process. This is how you provide unwind
48    /// information and address ranges.
49    ///
50    /// This should be called whenever a new module is loaded into the process.
51    fn add_module(&mut self, module: Self::Module);
52
53    /// Remove a module that was added before using `add_module`, keyed by the start
54    /// address of that module's address range. If no match is found, the call is ignored.
55    /// This should be called whenever a module is unloaded from the process.
56    fn remove_module(&mut self, module_avma_range_start: u64);
57
58    /// Returns the highest code address that is known in this process based on the module
59    /// address ranges. Returns 0 if no modules have been added.
60    ///
61    /// This method can be used together with
62    /// [`PtrAuthMask::from_max_known_address`](crate::aarch64::PtrAuthMask::from_max_known_address)
63    /// to make an educated guess at a pointer authentication mask for Aarch64 return addresses.
64    fn max_known_code_address(&self) -> u64;
65
66    /// Unwind a single frame, to recover return address and caller register values.
67    /// This is the main entry point for unwinding.
68    fn unwind_frame<F>(
69        &self,
70        address: FrameAddress,
71        regs: &mut Self::UnwindRegs,
72        cache: &mut Self::Cache,
73        read_stack: &mut F,
74    ) -> Result<Option<u64>, Error>
75    where
76        F: FnMut(u64) -> Result<u64, ()>;
77
78    /// Return an iterator that unwinds frame by frame until the end of the stack is found.
79    fn iter_frames<'u, 'c, 'r, F>(
80        &'u self,
81        pc: u64,
82        regs: Self::UnwindRegs,
83        cache: &'c mut Self::Cache,
84        read_stack: &'r mut F,
85    ) -> UnwindIterator<'u, 'c, 'r, Self, F>
86    where
87        F: FnMut(u64) -> Result<u64, ()>,
88    {
89        UnwindIterator::new(self, pc, regs, cache, read_stack)
90    }
91}
92
93/// An unwinder that reports whether each step used module unwind information
94/// or frame-pointer fallback.
95///
96/// This interface has the same recovery behavior as [`Unwinder`]. It adds the
97/// reason for a successful frame-pointer fallback to each result.
98pub trait UnwinderWithDetails: Unwinder {
99    /// Unwind one frame and report the source of the rule that was used.
100    fn unwind_frame_with_details<F>(
101        &self,
102        address: FrameAddress,
103        regs: &mut Self::UnwindRegs,
104        cache: &mut Self::Cache,
105        read_stack: &mut F,
106    ) -> Result<UnwindFrameOutcome, Error>
107    where
108        F: FnMut(u64) -> Result<u64, ()>;
109}
110
111/// An iterator for unwinding the entire stack, starting from the initial register values.
112///
113/// The first yielded frame is the instruction pointer. Subsequent addresses are return
114/// addresses.
115///
116/// This iterator attempts to detect if stack unwinding completed successfully, or if the
117/// stack was truncated prematurely. If it thinks that it successfully found the root
118/// function, it will complete with `Ok(None)`, otherwise it will complete with `Err(...)`.
119/// However, the detection does not work in all cases, so you should expect `Err(...)` to
120/// be returned even during normal operation. As a result, it is not recommended to use
121/// this iterator as a `FallibleIterator`, because you might lose the entire stack if the
122/// last iteration returns `Err(...)`.
123///
124/// Lifetimes:
125///
126///  - `'u`: The lifetime of the [`Unwinder`].
127///  - `'c`: The lifetime of the unwinder cache.
128///  - `'r`: The lifetime of the exclusive access to the `read_stack` callback.
129pub struct UnwindIterator<'u, 'c, 'r, U: Unwinder, F: FnMut(u64) -> Result<u64, ()>> {
130    unwinder: &'u U,
131    state: UnwindIteratorState,
132    regs: U::UnwindRegs,
133    cache: &'c mut U::Cache,
134    read_stack: &'r mut F,
135}
136
137enum UnwindIteratorState {
138    Initial(u64),
139    Unwinding(FrameAddress),
140    Done,
141}
142
143impl<'u, 'c, 'r, U: Unwinder, F: FnMut(u64) -> Result<u64, ()>> UnwindIterator<'u, 'c, 'r, U, F> {
144    /// Create a new iterator. You'd usually use [`Unwinder::iter_frames`] instead.
145    pub fn new(
146        unwinder: &'u U,
147        pc: u64,
148        regs: U::UnwindRegs,
149        cache: &'c mut U::Cache,
150        read_stack: &'r mut F,
151    ) -> Self {
152        Self {
153            unwinder,
154            state: UnwindIteratorState::Initial(pc),
155            regs,
156            cache,
157            read_stack,
158        }
159    }
160}
161
162impl<U: Unwinder, F: FnMut(u64) -> Result<u64, ()>> UnwindIterator<'_, '_, '_, U, F> {
163    /// Yield the next frame in the stack.
164    ///
165    /// The first frame is `Ok(Some(FrameAddress::InstructionPointer(...)))`.
166    /// Subsequent frames are `Ok(Some(FrameAddress::ReturnAddress(...)))`.
167    ///
168    /// If a root function has been reached, this iterator completes with `Ok(None)`.
169    /// Otherwise it completes with `Err(...)`, usually indicating that a certain stack
170    /// address could not be read.
171    #[allow(clippy::should_implement_trait)]
172    pub fn next(&mut self) -> Result<Option<FrameAddress>, Error> {
173        let next = match self.state {
174            UnwindIteratorState::Initial(pc) => {
175                self.state = UnwindIteratorState::Unwinding(FrameAddress::InstructionPointer(pc));
176                return Ok(Some(FrameAddress::InstructionPointer(pc)));
177            }
178            UnwindIteratorState::Unwinding(address) => {
179                self.unwinder
180                    .unwind_frame(address, &mut self.regs, self.cache, self.read_stack)?
181            }
182            UnwindIteratorState::Done => return Ok(None),
183        };
184        match next {
185            Some(return_address) => {
186                let return_address = FrameAddress::from_return_address(return_address)
187                    .ok_or(Error::ReturnAddressIsNull)?;
188                self.state = UnwindIteratorState::Unwinding(return_address);
189                Ok(Some(return_address))
190            }
191            None => {
192                self.state = UnwindIteratorState::Done;
193                Ok(None)
194            }
195        }
196    }
197}
198
199impl<U: UnwinderWithDetails, F: FnMut(u64) -> Result<u64, ()>> UnwindIterator<'_, '_, '_, U, F> {
200    /// Yield the next frame together with any frame-pointer fallback reason.
201    pub fn next_with_details(&mut self) -> Result<Option<UnwindFrame>, Error> {
202        let (next, fallback_reason) = match self.state {
203            UnwindIteratorState::Initial(pc) => {
204                self.state = UnwindIteratorState::Unwinding(FrameAddress::InstructionPointer(pc));
205                return Ok(Some(UnwindFrame::new(
206                    FrameAddress::InstructionPointer(pc),
207                    None,
208                )));
209            }
210            UnwindIteratorState::Unwinding(address) => {
211                let outcome = self.unwinder.unwind_frame_with_details(
212                    address,
213                    &mut self.regs,
214                    self.cache,
215                    self.read_stack,
216                )?;
217                (outcome.return_address(), outcome.fallback_reason())
218            }
219            UnwindIteratorState::Done => return Ok(None),
220        };
221        match next {
222            Some(return_address) => {
223                let return_address = FrameAddress::from_return_address(return_address)
224                    .ok_or(Error::ReturnAddressIsNull)?;
225                self.state = UnwindIteratorState::Unwinding(return_address);
226                Ok(Some(UnwindFrame::new(return_address, fallback_reason)))
227            }
228            None => {
229                self.state = UnwindIteratorState::Done;
230                Ok(None)
231            }
232        }
233    }
234}
235
236impl<U: Unwinder, F: FnMut(u64) -> Result<u64, ()>> FallibleIterator
237    for UnwindIterator<'_, '_, '_, U, F>
238{
239    type Item = FrameAddress;
240    type Error = Error;
241
242    fn next(&mut self) -> Result<Option<FrameAddress>, Error> {
243        self.next()
244    }
245}
246
247static GLOBAL_MODULES_GENERATION: AtomicU64 = AtomicU64::new(0);
248
249fn next_global_modules_generation() -> u64 {
250    GLOBAL_MODULES_GENERATION.fetch_add(1, Ordering::Relaxed)
251}
252
253cfg_if::cfg_if! {
254    if #[cfg(all(feature = "macho", feature = "pe"))] {
255        pub trait Unwinding:
256            Arch + DwarfUnwinding + InstructionAnalysis + CompactUnwindInfoUnwinding + PeUnwinding {}
257        impl<T: Arch + DwarfUnwinding + InstructionAnalysis + CompactUnwindInfoUnwinding + PeUnwinding>
258            Unwinding for T {}
259    } else if #[cfg(feature = "macho")] {
260        pub trait Unwinding:
261            Arch + DwarfUnwinding + InstructionAnalysis + CompactUnwindInfoUnwinding {}
262        impl<T: Arch + DwarfUnwinding + InstructionAnalysis + CompactUnwindInfoUnwinding> Unwinding for T {}
263    } else if #[cfg(feature = "pe")] {
264        pub trait Unwinding:
265            Arch + DwarfUnwinding + InstructionAnalysis  + PeUnwinding {}
266        impl<T: Arch + DwarfUnwinding + InstructionAnalysis + PeUnwinding> Unwinding for T {}
267    } else {
268        pub trait Unwinding: Arch + DwarfUnwinding + InstructionAnalysis {}
269        impl<T: Arch + DwarfUnwinding + InstructionAnalysis> Unwinding for T {}
270    }
271}
272
273pub struct UnwinderInternal<D, A, P> {
274    /// sorted by avma_range.start
275    modules: Vec<Module<D>>,
276    /// Incremented every time modules is changed.
277    modules_generation: u64,
278    _arch: PhantomData<A>,
279    _allocation_policy: PhantomData<P>,
280}
281
282impl<D, A, P> Default for UnwinderInternal<D, A, P> {
283    fn default() -> Self {
284        Self::new()
285    }
286}
287
288impl<D, A, P> Clone for UnwinderInternal<D, A, P> {
289    fn clone(&self) -> Self {
290        Self {
291            modules: self.modules.clone(),
292            modules_generation: self.modules_generation,
293            _arch: PhantomData,
294            _allocation_policy: PhantomData,
295        }
296    }
297}
298
299impl<D, A, P> UnwinderInternal<D, A, P> {
300    pub fn new() -> Self {
301        Self {
302            modules: Vec::new(),
303            modules_generation: next_global_modules_generation(),
304            _arch: PhantomData,
305            _allocation_policy: PhantomData,
306        }
307    }
308}
309
310fn fallback_depends_on_sample(error: UnwinderError) -> bool {
311    match error {
312        UnwinderError::Dwarf(
313            DwarfUnwinderError::StackPointerMovedBackwards
314            | DwarfUnwinderError::DidNotAdvance
315            | DwarfUnwinderError::CouldNotRecoverCfa
316            | DwarfUnwinderError::CouldNotRecoverReturnAddress
317            | DwarfUnwinderError::CouldNotRecoverFramePointer,
318        ) => true,
319        #[cfg(feature = "pe")]
320        UnwinderError::Pe(PeUnwinderError::MissingStackData(_)) => true,
321        _ => false,
322    }
323}
324
325impl<D: Deref<Target = [u8]>, A: Unwinding, P: AllocationPolicy> UnwinderInternal<D, A, P> {
326    pub fn add_module(&mut self, module: Module<D>) {
327        let insertion_index = match self
328            .modules
329            .binary_search_by_key(&module.avma_range.start, |module| module.avma_range.start)
330        {
331            Ok(i) => i, // unexpected
332            Err(i) => i,
333        };
334        self.modules.insert(insertion_index, module);
335        self.modules_generation = next_global_modules_generation();
336    }
337
338    pub fn remove_module(&mut self, module_address_range_start: u64) {
339        if let Ok(index) = self
340            .modules
341            .binary_search_by_key(&module_address_range_start, |module| {
342                module.avma_range.start
343            })
344        {
345            self.modules.remove(index);
346            self.modules_generation = next_global_modules_generation();
347        };
348    }
349
350    pub fn max_known_code_address(&self) -> u64 {
351        self.modules.last().map_or(0, |m| m.avma_range.end)
352    }
353
354    fn find_module_for_address(&self, address: u64) -> Option<(usize, u32)> {
355        let (module_index, module) = match self
356            .modules
357            .binary_search_by_key(&address, |m| m.avma_range.start)
358        {
359            Ok(i) => (i, &self.modules[i]),
360            Err(insertion_index) => {
361                if insertion_index == 0 {
362                    // address is before first known module
363                    return None;
364                }
365                let i = insertion_index - 1;
366                let module = &self.modules[i];
367                if module.avma_range.end <= address {
368                    // address is after this module
369                    return None;
370                }
371                (i, module)
372            }
373        };
374        if address < module.base_avma {
375            // Invalid base address
376            return None;
377        }
378        let relative_address = u32::try_from(address - module.base_avma).ok()?;
379        Some((module_index, relative_address))
380    }
381
382    fn with_cache<F, G>(
383        &self,
384        address: FrameAddress,
385        regs: &mut A::UnwindRegs,
386        cache: &mut Cache<A::UnwindRule, P>,
387        read_stack: &mut F,
388        callback: G,
389    ) -> Result<UnwindFrameOutcome, Error>
390    where
391        F: FnMut(u64) -> Result<u64, ()>,
392        G: FnOnce(
393            &Module<D>,
394            FrameAddress,
395            u32,
396            &mut A::UnwindRegs,
397            &mut Cache<A::UnwindRule, P>,
398            &mut F,
399        ) -> Result<UnwindResult<A::UnwindRule>, UnwinderError>,
400    {
401        let lookup_address = address.address_for_lookup();
402        let is_first_frame = !address.is_return_address();
403        let (unwind_rule, cached_fallback, dwarf_register_rules) =
404            match cache
405                .rule_cache
406                .lookup(lookup_address, self.modules_generation, is_first_frame)
407            {
408                CacheResult::Hit(unwind_rule, cached_fallback, dwarf_register_rules) => {
409                    (unwind_rule, cached_fallback, dwarf_register_rules)
410                }
411                CacheResult::Miss(cache_handle) => {
412                    let entry = match self.find_module_for_address(lookup_address) {
413                        None => (
414                            A::UnwindRule::fallback_rule(),
415                            Some(FramePointerFallbackReason::NoModule),
416                            None,
417                        ),
418                        Some((module_index, relative_lookup_address)) => {
419                            let module = &self.modules[module_index];
420                            match callback(
421                                module,
422                                address,
423                                relative_lookup_address,
424                                regs,
425                                cache,
426                                read_stack,
427                            ) {
428                                Ok(UnwindResult::ExecRule(rule)) => (rule, None, None),
429                                Ok(UnwindResult::ExecRuleWithDwarfRegisterRules(
430                                    rule,
431                                    register_rules,
432                                )) => (rule, None, Some(register_rules)),
433                                Ok(UnwindResult::ExecRuleWithFallback(rule, error)) => {
434                                    let reason = (!is_first_frame)
435                                        .then_some(FramePointerFallbackReason::UnwindInfo(error));
436                                    (rule, reason, None)
437                                }
438                                Ok(UnwindResult::Uncacheable(return_address)) => {
439                                    return Ok(UnwindFrameOutcome::new(Some(return_address), None));
440                                }
441                                Err(error) => {
442                                    let rule = A::UnwindRule::fallback_rule();
443                                    let reason = FramePointerFallbackReason::UnwindInfo(error);
444                                    if fallback_depends_on_sample(error) {
445                                        let return_address =
446                                            rule.exec(is_first_frame, regs, read_stack)?;
447                                        return Ok(UnwindFrameOutcome::new(
448                                            return_address,
449                                            Some(reason),
450                                        ));
451                                    } else {
452                                        (rule, Some(reason), None)
453                                    }
454                                }
455                            }
456                        }
457                    };
458                    cache
459                        .rule_cache
460                        .insert(cache_handle, entry.0, entry.1, entry.2);
461                    entry
462                }
463            };
464        let return_address = match dwarf_register_rules {
465            Some(register_rules) => unwind_rule.exec_with_dwarf_register_rules(
466                register_rules,
467                is_first_frame,
468                regs,
469                read_stack,
470            )?,
471            None => unwind_rule.exec(is_first_frame, regs, read_stack)?,
472        };
473        Ok(UnwindFrameOutcome::new(return_address, cached_fallback))
474    }
475
476    pub fn unwind_frame<F>(
477        &self,
478        address: FrameAddress,
479        regs: &mut A::UnwindRegs,
480        cache: &mut Cache<A::UnwindRule, P>,
481        read_stack: &mut F,
482    ) -> Result<Option<u64>, Error>
483    where
484        F: FnMut(u64) -> Result<u64, ()>,
485    {
486        self.unwind_frame_with_details(address, regs, cache, read_stack)
487            .map(UnwindFrameOutcome::return_address)
488    }
489
490    pub fn unwind_frame_with_details<F>(
491        &self,
492        address: FrameAddress,
493        regs: &mut A::UnwindRegs,
494        cache: &mut Cache<A::UnwindRule, P>,
495        read_stack: &mut F,
496    ) -> Result<UnwindFrameOutcome, Error>
497    where
498        F: FnMut(u64) -> Result<u64, ()>,
499    {
500        self.with_cache(address, regs, cache, read_stack, Self::unwind_frame_impl)
501    }
502
503    fn unwind_frame_impl<F>(
504        module: &Module<D>,
505        address: FrameAddress,
506        rel_lookup_address: u32,
507        regs: &mut A::UnwindRegs,
508        cache: &mut Cache<A::UnwindRule, P>,
509        read_stack: &mut F,
510    ) -> Result<UnwindResult<A::UnwindRule>, UnwinderError>
511    where
512        F: FnMut(u64) -> Result<u64, ()>,
513    {
514        let is_first_frame = !address.is_return_address();
515        let unwind_result = match &*module.unwind_data {
516            #[cfg(feature = "macho")]
517            ModuleUnwindDataInternal::CompactUnwindInfoAndEhFrame {
518                unwind_info,
519                eh_frame,
520                stubs_svma: stubs,
521                stub_helper_svma: stub_helper,
522                base_addresses,
523                text_data,
524            } => {
525                // eprintln!("unwinding with cui and eh_frame in module {}", module.name);
526                let text_bytes = text_data.as_ref().and_then(|data| {
527                    let offset_from_base =
528                        u32::try_from(data.svma_range.start.checked_sub(module.base_svma)?).ok()?;
529                    Some(TextBytes::new(offset_from_base, &data.bytes[..]))
530                });
531                let stubs_range = if let Some(stubs_range) = stubs {
532                    (
533                        (stubs_range.start - module.base_svma) as u32,
534                        (stubs_range.end - module.base_svma) as u32,
535                    )
536                } else {
537                    (0, 0)
538                };
539                let stub_helper_range = if let Some(stub_helper_range) = stub_helper {
540                    (
541                        (stub_helper_range.start - module.base_svma) as u32,
542                        (stub_helper_range.end - module.base_svma) as u32,
543                    )
544                } else {
545                    (0, 0)
546                };
547                let mut unwinder = CompactUnwindInfoUnwinder::<A>::new(
548                    &unwind_info[..],
549                    text_bytes,
550                    stubs_range,
551                    stub_helper_range,
552                );
553
554                let unwind_result = unwinder.unwind_frame(rel_lookup_address, is_first_frame)?;
555                match unwind_result {
556                    CuiUnwindResult::ExecRule(rule) => UnwindResult::ExecRule(rule),
557                    CuiUnwindResult::NeedDwarf(fde_offset) => {
558                        let eh_frame_data =
559                            eh_frame.as_deref().ok_or(UnwinderError::NoDwarfData)?;
560                        let mut dwarf_unwinder = DwarfUnwinder::<_, A, _>::new(
561                            EndianSlice::new(eh_frame_data, LittleEndian),
562                            UnwindSectionType::EhFrame,
563                            None,
564                            &mut cache.gimli_unwind_context,
565                            base_addresses.clone(),
566                            module.base_svma,
567                        );
568                        dwarf_unwinder.unwind_frame_with_fde::<_, P::GimliEvaluationStorage<_>>(
569                            regs,
570                            is_first_frame,
571                            rel_lookup_address,
572                            fde_offset,
573                            read_stack,
574                        )?
575                    }
576                }
577            }
578            ModuleUnwindDataInternal::EhFrameHdrAndEhFrame {
579                eh_frame_hdr,
580                eh_frame_hdr_table,
581                eh_frame,
582                base_addresses,
583            } => {
584                let eh_frame_hdr_data = &eh_frame_hdr[..];
585                let mut dwarf_unwinder = DwarfUnwinder::<_, A, _>::new(
586                    EndianSlice::new(eh_frame, LittleEndian),
587                    UnwindSectionType::EhFrame,
588                    eh_frame_hdr_table.is_none().then_some(eh_frame_hdr_data),
589                    &mut cache.gimli_unwind_context,
590                    base_addresses.clone(),
591                    module.base_svma,
592                );
593                let fde_offset = match eh_frame_hdr_table {
594                    Some(table) => {
595                        table.fde_offset_for_relative_address(eh_frame_hdr_data, rel_lookup_address)
596                    }
597                    None => dwarf_unwinder.get_fde_offset_for_relative_address(rel_lookup_address),
598                }
599                .ok_or(UnwinderError::EhFrameHdrCouldNotFindAddress)?;
600                dwarf_unwinder.unwind_frame_with_fde::<_, P::GimliEvaluationStorage<_>>(
601                    regs,
602                    is_first_frame,
603                    rel_lookup_address,
604                    fde_offset,
605                    read_stack,
606                )?
607            }
608            ModuleUnwindDataInternal::DwarfCfiIndexAndEhFrame {
609                index,
610                eh_frame,
611                base_addresses,
612            } => {
613                let mut dwarf_unwinder = DwarfUnwinder::<_, A, _>::new(
614                    EndianSlice::new(eh_frame, LittleEndian),
615                    UnwindSectionType::EhFrame,
616                    None,
617                    &mut cache.gimli_unwind_context,
618                    base_addresses.clone(),
619                    module.base_svma,
620                );
621                let fde_offset = index
622                    .fde_offset_for_relative_address(rel_lookup_address)
623                    .ok_or(UnwinderError::DwarfCfiIndexCouldNotFindAddress)?;
624                dwarf_unwinder.unwind_frame_with_fde::<_, P::GimliEvaluationStorage<_>>(
625                    regs,
626                    is_first_frame,
627                    rel_lookup_address,
628                    fde_offset,
629                    read_stack,
630                )?
631            }
632            ModuleUnwindDataInternal::DwarfCfiIndexAndDebugFrame {
633                index,
634                debug_frame,
635                base_addresses,
636            } => {
637                let mut dwarf_unwinder = DwarfUnwinder::<_, A, _>::new(
638                    EndianSlice::new(debug_frame, LittleEndian),
639                    UnwindSectionType::DebugFrame,
640                    None,
641                    &mut cache.gimli_unwind_context,
642                    base_addresses.clone(),
643                    module.base_svma,
644                );
645                let fde_offset = index
646                    .fde_offset_for_relative_address(rel_lookup_address)
647                    .ok_or(UnwinderError::DwarfCfiIndexCouldNotFindAddress)?;
648                dwarf_unwinder.unwind_frame_with_fde::<_, P::GimliEvaluationStorage<_>>(
649                    regs,
650                    is_first_frame,
651                    rel_lookup_address,
652                    fde_offset,
653                    read_stack,
654                )?
655            }
656            #[cfg(feature = "pe")]
657            ModuleUnwindDataInternal::PeUnwindInfo {
658                pdata,
659                rdata,
660                xdata,
661                text,
662            } => <A as PeUnwinding>::unwind_frame(
663                crate::pe::PeSections {
664                    pdata,
665                    rdata: rdata.as_ref(),
666                    xdata: xdata.as_ref(),
667                    text: text.as_ref(),
668                },
669                rel_lookup_address,
670                regs,
671                is_first_frame,
672                read_stack,
673            )?,
674            ModuleUnwindDataInternal::None => return Err(UnwinderError::NoModuleUnwindData),
675        };
676        Ok(unwind_result)
677    }
678}
679
680/// The unwind data that should be used when unwinding addresses inside this module.
681/// Unwind data describes how to recover register values of the caller frame.
682///
683/// The type of unwind information you use depends on the platform and what's available
684/// in the binary.
685///
686/// Type arguments:
687///
688///  - `D`: The type for unwind section data. This allows carrying owned data on the
689///    module, e.g. `Vec<u8>`. But it could also be a wrapper around mapped memory from
690///    a file or a different process, for example. It just needs to provide a slice of
691///    bytes via its `Deref` implementation.
692enum ModuleUnwindDataInternal<D> {
693    /// Used on macOS, with mach-O binaries. Compact unwind info is in the `__unwind_info`
694    /// section and is sometimes supplemented with DWARF CFI information in the `__eh_frame`
695    /// section. `__stubs` and `__stub_helper` ranges are used by the unwinder.
696    #[cfg(feature = "macho")]
697    CompactUnwindInfoAndEhFrame {
698        unwind_info: D,
699        eh_frame: Option<D>,
700        stubs_svma: Option<Range<u64>>,
701        stub_helper_svma: Option<Range<u64>>,
702        base_addresses: crate::dwarf::BaseAddresses,
703        text_data: Option<TextByteData<D>>,
704    },
705    /// Used with ELF binaries (Linux and friends), in the `.eh_frame_hdr` and `.eh_frame`
706    /// sections. Contains an index and DWARF CFI.
707    EhFrameHdrAndEhFrame {
708        eh_frame_hdr: D,
709        /// Set when `eh_frame_hdr` has a table layout that can be searched in place.
710        eh_frame_hdr_table: Option<EhFrameHdrTable>,
711        eh_frame: D,
712        base_addresses: crate::dwarf::BaseAddresses,
713    },
714    /// Used with ELF binaries (Linux and friends), in the `.eh_frame` section. Contains
715    /// DWARF CFI. We create a binary index for the FDEs when a module with this unwind
716    /// data type is added.
717    DwarfCfiIndexAndEhFrame {
718        index: DwarfCfiIndex,
719        eh_frame: D,
720        base_addresses: crate::dwarf::BaseAddresses,
721    },
722    /// Used with ELF binaries (Linux and friends), in the `.debug_frame` section. Contains
723    /// DWARF CFI. We create a binary index for the FDEs when a module with this unwind
724    /// data type is added.
725    DwarfCfiIndexAndDebugFrame {
726        index: DwarfCfiIndex,
727        debug_frame: D,
728        base_addresses: crate::dwarf::BaseAddresses,
729    },
730    /// Used with PE binaries (Windows).
731    #[cfg(feature = "pe")]
732    PeUnwindInfo {
733        pdata: D,
734        rdata: Option<DataAtRvaRange<D>>,
735        xdata: Option<DataAtRvaRange<D>>,
736        text: Option<DataAtRvaRange<D>>,
737    },
738    /// No unwind information is used. Unwinding in this module will use a fallback rule
739    /// (usually frame pointer unwinding).
740    None,
741}
742
743impl<D: Deref<Target = [u8]>> ModuleUnwindDataInternal<D> {
744    fn new(section_info: &mut impl ModuleSectionInfo<D>) -> Self {
745        use crate::dwarf::base_addresses_and_text_range;
746
747        #[cfg(feature = "macho")]
748        if let Some(unwind_info) = section_info.section_data(b"__unwind_info") {
749            let eh_frame = section_info.section_data(b"__eh_frame");
750            let stubs = section_info.section_svma_range(b"__stubs");
751            let stub_helper = section_info.section_svma_range(b"__stub_helper");
752            let (base_addresses, text_range) = base_addresses_and_text_range(section_info);
753            // Get the bytes of the executable code (instructions).
754            //
755            // In mach-O objects, executable code is stored in the `__TEXT` segment, which contains
756            // multiple executable sections such as `__text`, `__stubs`, and `__stub_helper`. If we
757            // don't have the full `__TEXT` segment contents, we can fall back to the contents of
758            // just the `__text` section.
759            let text_data = if let (Some(bytes), Some(svma_range)) = (
760                section_info.segment_data(b"__TEXT"),
761                section_info.segment_svma_range(b"__TEXT"),
762            ) {
763                Some(TextByteData { bytes, svma_range })
764            } else if let (Some(bytes), Some(svma_range)) =
765                (section_info.section_data(b"__text"), text_range)
766            {
767                Some(TextByteData { bytes, svma_range })
768            } else {
769                None
770            };
771            return ModuleUnwindDataInternal::CompactUnwindInfoAndEhFrame {
772                unwind_info,
773                eh_frame,
774                stubs_svma: stubs,
775                stub_helper_svma: stub_helper,
776                base_addresses,
777                text_data,
778            };
779        }
780
781        #[cfg(feature = "pe")]
782        if let Some(pdata) = section_info.section_data(b".pdata") {
783            let mut range_and_data = |name| {
784                let rva_range = section_info.section_svma_range(name).and_then(|range| {
785                    Some(Range {
786                        start: (range.start - section_info.base_svma()).try_into().ok()?,
787                        end: (range.end - section_info.base_svma()).try_into().ok()?,
788                    })
789                })?;
790                let data = section_info.section_data(name)?;
791                Some(DataAtRvaRange { data, rva_range })
792            };
793            return ModuleUnwindDataInternal::PeUnwindInfo {
794                pdata,
795                rdata: range_and_data(b".rdata"),
796                xdata: range_and_data(b".xdata"),
797                text: range_and_data(b".text"),
798            };
799        }
800
801        if let Some(eh_frame) = section_info
802            .section_data(b".eh_frame")
803            .or_else(|| section_info.section_data(b"__eh_frame"))
804        {
805            let (base_addresses, _) = base_addresses_and_text_range(section_info);
806            if let Some(eh_frame_hdr) = section_info
807                .section_data(b".eh_frame_hdr")
808                .or_else(|| section_info.section_data(b"__eh_frame_hdr"))
809            {
810                let eh_frame_hdr_table = EhFrameHdrTable::try_new(
811                    &eh_frame_hdr,
812                    &base_addresses,
813                    section_info.base_svma(),
814                );
815                ModuleUnwindDataInternal::EhFrameHdrAndEhFrame {
816                    eh_frame_hdr,
817                    eh_frame_hdr_table,
818                    eh_frame,
819                    base_addresses,
820                }
821            } else {
822                match DwarfCfiIndex::try_new_eh_frame(
823                    &eh_frame,
824                    &base_addresses,
825                    section_info.base_svma(),
826                ) {
827                    Ok(index) => ModuleUnwindDataInternal::DwarfCfiIndexAndEhFrame {
828                        index,
829                        eh_frame,
830                        base_addresses,
831                    },
832                    Err(_) => ModuleUnwindDataInternal::None,
833                }
834            }
835        } else if let Some(debug_frame) = section_info.section_data(b".debug_frame") {
836            let (base_addresses, _) = base_addresses_and_text_range(section_info);
837            match DwarfCfiIndex::try_new_debug_frame(
838                &debug_frame,
839                &base_addresses,
840                section_info.base_svma(),
841            ) {
842                Ok(index) => ModuleUnwindDataInternal::DwarfCfiIndexAndDebugFrame {
843                    index,
844                    debug_frame,
845                    base_addresses,
846                },
847                Err(_) => ModuleUnwindDataInternal::None,
848            }
849        } else {
850            ModuleUnwindDataInternal::None
851        }
852    }
853}
854
855/// Used to supply raw instruction bytes to the unwinder, which uses it to analyze
856/// instructions in order to provide high quality unwinding inside function prologues and
857/// epilogues.
858///
859/// This is only needed on macOS, because mach-O `__unwind_info` and `__eh_frame` only
860/// cares about accuracy in function bodies, not in function prologues and epilogues.
861///
862/// On Linux, compilers produce `.eh_frame` and `.debug_frame` which provides correct
863/// unwind information for all instructions including those in function prologues and
864/// epilogues, so instruction analysis is not needed.
865///
866/// Type arguments:
867///
868///  - `D`: The type for unwind section data. This allows carrying owned data on the
869///    module, e.g. `Vec<u8>`. But it could also be a wrapper around mapped memory from
870///    a file or a different process, for example. It just needs to provide a slice of
871///    bytes via its `Deref` implementation.
872#[cfg(feature = "macho")]
873struct TextByteData<D> {
874    pub bytes: D,
875    pub svma_range: Range<u64>,
876}
877
878/// Information about a module that is loaded in a process. You might know this under a
879/// different name, for example: (Shared) library, binary image, DSO ("Dynamic shared object")
880///
881/// The unwinder needs to have an up-to-date list of modules so that it can match an
882/// absolute address to the right module, and so that it can find that module's unwind
883/// information.
884///
885/// Type arguments:
886///
887///  - `D`: The type for unwind section data. This allows carrying owned data on the
888///    module, e.g. `Vec<u8>`. But it could also be a wrapper around mapped memory from
889///    a file or a different process, for example. It just needs to provide a slice of
890///    bytes via its `Deref` implementation.
891pub struct Module<D> {
892    /// The name or file path of the module. Unused, it's just there for easier debugging.
893    #[allow(unused)]
894    name: String,
895    /// The address range where this module is mapped into the process.
896    avma_range: Range<u64>,
897    /// The base address of this module, in the process's address space. On Linux, the base
898    /// address can sometimes be different from the start address of the mapped range.
899    base_avma: u64,
900    /// The base address of this module, according to the module.
901    base_svma: u64,
902    /// The unwind data that should be used for unwinding addresses from this module.
903    unwind_data: Arc<ModuleUnwindDataInternal<D>>,
904}
905
906impl<D> Clone for Module<D> {
907    fn clone(&self) -> Self {
908        Self {
909            name: self.name.clone(),
910            avma_range: self.avma_range.clone(),
911            base_avma: self.base_avma,
912            base_svma: self.base_svma,
913            unwind_data: self.unwind_data.clone(),
914        }
915    }
916}
917
918/// Information about a module's sections (and segments).
919///
920/// This trait is used as an interface to module information, and each function with `&mut self` is
921/// called at most once with a particular argument (e.g., `section_data(b".text")` will be called
922/// at most once, so it can move data out of the underlying type if desired).
923///
924/// Type arguments:
925///
926///  - `D`: The type for section data. This allows carrying owned data on the module, e.g.
927///    `Vec<u8>`. But it could also be a wrapper around mapped memory from a file or a different
928///    process, for example.
929pub trait ModuleSectionInfo<D> {
930    /// Return the base address stated in the module.
931    ///
932    /// For mach-O objects, this is the vmaddr of the __TEXT segment. For ELF objects, this is
933    /// zero. For PE objects, this is the image base address.
934    ///
935    /// This is used to convert between SVMAs and relative addresses.
936    fn base_svma(&self) -> u64;
937
938    /// Get the given section's memory range, as stated in the module.
939    fn section_svma_range(&mut self, name: &[u8]) -> Option<Range<u64>>;
940
941    /// Get the given section's data. This will only be called once per section.
942    fn section_data(&mut self, name: &[u8]) -> Option<D>;
943
944    /// Get the given segment's memory range, as stated in the module.
945    fn segment_svma_range(&mut self, _name: &[u8]) -> Option<Range<u64>> {
946        None
947    }
948
949    /// Get the given segment's data. This will only be called once per segment.
950    fn segment_data(&mut self, _name: &[u8]) -> Option<D> {
951        None
952    }
953}
954
955/// Explicit addresses and data of various sections in the module. This implements
956/// the `ModuleSectionInfo` trait.
957///
958/// Unless otherwise stated, these are SVMAs, "stated virtual memory addresses", i.e. addresses as
959/// stated in the object, as opposed to AVMAs, "actual virtual memory addresses", i.e. addresses in
960/// the virtual memory of the profiled process.
961///
962/// Code addresses inside a module's unwind information are usually written down as SVMAs,
963/// or as relative addresses. For example, DWARF CFI can have code addresses expressed as
964/// relative-to-.text addresses or as absolute SVMAs. And mach-O compact unwind info
965/// contains addresses relative to the image base address.
966#[derive(Clone, Debug, Default, PartialEq, Eq)]
967pub struct ExplicitModuleSectionInfo<D> {
968    /// The image base address, as stated in the object. For mach-O objects, this is the
969    /// vmaddr of the `__TEXT` segment. For ELF objects, this is zero.
970    ///
971    /// This is used to convert between SVMAs and relative addresses.
972    pub base_svma: u64,
973    /// The address range of the `__text` or `.text` section. This is where most of the compiled
974    /// code is stored.
975    ///
976    /// This is used to detect whether we need to do instruction analysis for an address.
977    pub text_svma: Option<Range<u64>>,
978    /// The data of the `__text` or `.text` section. This is where most of the compiled code is
979    /// stored. For mach-O binaries, this does not need to be supplied if `text_segment` is supplied.
980    ///
981    /// This is used to handle function prologues and epilogues in some cases.
982    pub text: Option<D>,
983    /// The address range of the mach-O `__stubs` section. Contains small pieces of
984    /// executable code for calling imported functions. Code inside this section is not
985    /// covered by the unwind information in `__unwind_info`.
986    ///
987    /// This is used to exclude addresses in this section from incorrectly applying
988    /// `__unwind_info` opcodes. It is also used to infer unwind rules for the known
989    /// structure of stub functions.
990    pub stubs_svma: Option<Range<u64>>,
991    /// The address range of the mach-O `__stub_helper` section. Contains small pieces of
992    /// executable code for calling imported functions. Code inside this section is not
993    /// covered by the unwind information in `__unwind_info`.
994    ///
995    /// This is used to exclude addresses in this section from incorrectly applying
996    /// `__unwind_info` opcodes. It is also used to infer unwind rules for the known
997    /// structure of stub helper
998    /// functions.
999    pub stub_helper_svma: Option<Range<u64>>,
1000    /// The address range of the `.got` section (Global Offset Table). This is used
1001    /// during DWARF CFI processing, to resolve got-relative addresses.
1002    pub got_svma: Option<Range<u64>>,
1003    /// The data of the `__unwind_info` section of mach-O binaries.
1004    pub unwind_info: Option<D>,
1005    /// The address range of the `__eh_frame` or `.eh_frame` section. This is used during DWARF CFI
1006    /// processing, to resolve eh_frame-relative addresses.
1007    pub eh_frame_svma: Option<Range<u64>>,
1008    /// The data of the `__eh_frame` or `.eh_frame` section. This is used during DWARF CFI
1009    /// processing, to resolve eh_frame-relative addresses.
1010    pub eh_frame: Option<D>,
1011    /// The address range of the `.eh_frame_hdr` section. This is used during DWARF CFI processing,
1012    /// to resolve eh_frame_hdr-relative addresses.
1013    pub eh_frame_hdr_svma: Option<Range<u64>>,
1014    /// The data of the `.eh_frame_hdr` section. This is used during DWARF CFI processing, to
1015    /// resolve eh_frame_hdr-relative addresses.
1016    pub eh_frame_hdr: Option<D>,
1017    /// The data of the `.debug_frame` section. The related address range is not needed.
1018    pub debug_frame: Option<D>,
1019    /// The address range of the `__TEXT` segment of mach-O binaries, if available.
1020    pub text_segment_svma: Option<Range<u64>>,
1021    /// The data of the `__TEXT` segment of mach-O binaries, if available.
1022    pub text_segment: Option<D>,
1023}
1024
1025impl<D> ModuleSectionInfo<D> for ExplicitModuleSectionInfo<D>
1026where
1027    D: Deref<Target = [u8]>,
1028{
1029    fn base_svma(&self) -> u64 {
1030        self.base_svma
1031    }
1032
1033    fn section_svma_range(&mut self, name: &[u8]) -> Option<Range<u64>> {
1034        match name {
1035            b"__text" | b".text" => self.text_svma.clone(),
1036            b"__stubs" => self.stubs_svma.clone(),
1037            b"__stub_helper" => self.stub_helper_svma.clone(),
1038            b"__eh_frame" | b".eh_frame" => self.eh_frame_svma.clone(),
1039            b"__eh_frame_hdr" | b".eh_frame_hdr" => self.eh_frame_hdr_svma.clone(),
1040            b"__got" | b".got" => self.got_svma.clone(),
1041            _ => None,
1042        }
1043    }
1044    fn section_data(&mut self, name: &[u8]) -> Option<D> {
1045        match name {
1046            b"__text" | b".text" => self.text.take(),
1047            b"__unwind_info" => self.unwind_info.take(),
1048            b"__eh_frame" | b".eh_frame" => self.eh_frame.take(),
1049            b"__eh_frame_hdr" | b".eh_frame_hdr" => self.eh_frame_hdr.take(),
1050            b"__debug_frame" | b".debug_frame" => self.debug_frame.take(),
1051            _ => None,
1052        }
1053    }
1054    fn segment_svma_range(&mut self, name: &[u8]) -> Option<Range<u64>> {
1055        match name {
1056            b"__TEXT" => self.text_segment_svma.clone(),
1057            _ => None,
1058        }
1059    }
1060    fn segment_data(&mut self, name: &[u8]) -> Option<D> {
1061        match name {
1062            b"__TEXT" => self.text_segment.take(),
1063            _ => None,
1064        }
1065    }
1066}
1067
1068impl<D: Deref<Target = [u8]>> Module<D> {
1069    pub fn new(
1070        name: String,
1071        avma_range: core::ops::Range<u64>,
1072        base_avma: u64,
1073        mut section_info: impl ModuleSectionInfo<D>,
1074    ) -> Self {
1075        let unwind_data = ModuleUnwindDataInternal::new(&mut section_info);
1076
1077        Self {
1078            name,
1079            avma_range,
1080            base_avma,
1081            base_svma: section_info.base_svma(),
1082            unwind_data: Arc::new(unwind_data),
1083        }
1084    }
1085
1086    pub fn avma_range(&self) -> core::ops::Range<u64> {
1087        self.avma_range.clone()
1088    }
1089
1090    pub fn base_avma(&self) -> u64 {
1091        self.base_avma
1092    }
1093
1094    pub fn name(&self) -> &str {
1095        &self.name
1096    }
1097}
1098
1099#[cfg(test)]
1100mod tests {
1101    use super::*;
1102    use crate::cache::MayAllocateDuringUnwind;
1103    use crate::x86_64::{ArchX86_64, UnwindRegsX86_64, UnwindRuleX86_64};
1104
1105    type TestUnwinder = UnwinderInternal<Vec<u8>, ArchX86_64, MayAllocateDuringUnwind>;
1106    type TestCache = Cache<UnwindRuleX86_64, MayAllocateDuringUnwind>;
1107
1108    #[derive(Default)]
1109    struct ConsumingSections {
1110        ranges: alloc::collections::BTreeMap<Vec<u8>, Range<u64>>,
1111        data: alloc::collections::BTreeMap<Vec<u8>, Vec<u8>>,
1112        reads: alloc::collections::BTreeSet<(&'static str, Vec<u8>)>,
1113    }
1114
1115    impl ConsumingSections {
1116        fn record_read(&mut self, method: &'static str, name: &[u8]) {
1117            assert!(
1118                self.reads.insert((method, name.to_vec())),
1119                "repeated {method}({name:?})"
1120            );
1121        }
1122    }
1123
1124    impl ModuleSectionInfo<Vec<u8>> for ConsumingSections {
1125        fn base_svma(&self) -> u64 {
1126            0x1000
1127        }
1128
1129        fn section_svma_range(&mut self, name: &[u8]) -> Option<Range<u64>> {
1130            self.record_read("section_svma_range", name);
1131            self.ranges.remove(name)
1132        }
1133
1134        fn section_data(&mut self, name: &[u8]) -> Option<Vec<u8>> {
1135            self.record_read("section_data", name);
1136            self.data.remove(name)
1137        }
1138
1139        fn segment_svma_range(&mut self, name: &[u8]) -> Option<Range<u64>> {
1140            self.record_read("segment_svma_range", name);
1141            None
1142        }
1143
1144        fn segment_data(&mut self, name: &[u8]) -> Option<Vec<u8>> {
1145            self.record_read("segment_data", name);
1146            None
1147        }
1148    }
1149
1150    #[test]
1151    fn dwarf_index_retains_bases_from_a_consuming_section_provider() {
1152        for section_name in [b".eh_frame".as_slice(), b".debug_frame"] {
1153            let mut sections = ConsumingSections::default();
1154            for (name, start) in [
1155                (b".eh_frame".as_slice(), 0x2000),
1156                (b".eh_frame_hdr", 0x3000),
1157                (b".text", 0x4000),
1158                (b".got", 0x5000),
1159            ] {
1160                sections.ranges.insert(name.to_vec(), start..start + 0x100);
1161            }
1162            sections.data.insert(section_name.to_vec(), Vec::new());
1163            let unwind_data = ModuleUnwindDataInternal::new(&mut sections);
1164            let bases = match (section_name, unwind_data) {
1165                (
1166                    b".eh_frame",
1167                    ModuleUnwindDataInternal::DwarfCfiIndexAndEhFrame { base_addresses, .. },
1168                )
1169                | (
1170                    b".debug_frame",
1171                    ModuleUnwindDataInternal::DwarfCfiIndexAndDebugFrame { base_addresses, .. },
1172                ) => base_addresses,
1173                _ => panic!("expected a DWARF index for {section_name:?}"),
1174            };
1175            assert_eq!(
1176                bases,
1177                gimli::BaseAddresses::default()
1178                    .set_eh_frame(0x2000)
1179                    .set_eh_frame_hdr(0x3000)
1180                    .set_text(0x4000)
1181                    .set_got(0x5000)
1182            );
1183        }
1184    }
1185
1186    #[cfg(feature = "macho")]
1187    #[test]
1188    fn compact_unwind_reuses_the_consumed_text_range() {
1189        let mut sections = ConsumingSections::default();
1190        sections.data.insert(b"__unwind_info".to_vec(), Vec::new());
1191        sections.data.insert(b"__text".to_vec(), alloc::vec![0x90]);
1192        sections.ranges.insert(b"__text".to_vec(), 0x4000..0x4001);
1193        let ModuleUnwindDataInternal::CompactUnwindInfoAndEhFrame {
1194            base_addresses,
1195            text_data: Some(text_data),
1196            ..
1197        } = ModuleUnwindDataInternal::new(&mut sections)
1198        else {
1199            panic!("expected compact unwind information with instruction bytes");
1200        };
1201        assert_eq!(base_addresses.eh_frame.text, Some(0x4000));
1202        assert_eq!(text_data.svma_range, 0x4000..0x4001);
1203        assert_eq!(text_data.bytes, [0x90]);
1204    }
1205
1206    fn module_without_unwind_data() -> Module<Vec<u8>> {
1207        Module {
1208            name: "test".into(),
1209            avma_range: 0x1000..0x2000,
1210            base_avma: 0x1000,
1211            base_svma: 0,
1212            unwind_data: Arc::new(ModuleUnwindDataInternal::None),
1213        }
1214    }
1215
1216    #[test]
1217    fn detailed_unwind_reports_a_successful_frame_pointer_fallback() {
1218        let unwinder = TestUnwinder::new();
1219        let mut cache = TestCache::new();
1220        let mut regs = UnwindRegsX86_64::new(0x1100, 0x2000, 0x3000);
1221        let mut read_stack = |address| match address {
1222            0x3000 => Ok(0x4000),
1223            0x3008 => Ok(0x5000),
1224            _ => Err(()),
1225        };
1226
1227        let outcome = unwinder
1228            .unwind_frame_with_details(
1229                FrameAddress::from_instruction_pointer(0x1100),
1230                &mut regs,
1231                &mut cache,
1232                &mut read_stack,
1233            )
1234            .unwrap();
1235
1236        assert_eq!(outcome.return_address(), Some(0x5000));
1237        assert_eq!(
1238            outcome.fallback_reason(),
1239            Some(FramePointerFallbackReason::NoModule)
1240        );
1241    }
1242
1243    #[test]
1244    fn sample_dependent_dwarf_failure_is_retried() {
1245        let mut unwinder = TestUnwinder::new();
1246        unwinder.add_module(module_without_unwind_data());
1247        let mut cache = TestCache::new();
1248        let address = FrameAddress::from_instruction_pointer(0x1100);
1249
1250        let mut regs = UnwindRegsX86_64::new(0x1100, 0x2000, 0x3000);
1251        let mut fallback_stack = |stack_address| match stack_address {
1252            0x3000 => Ok(0x4000),
1253            0x3008 => Ok(0x5000),
1254            _ => Err(()),
1255        };
1256        let outcome = unwinder
1257            .with_cache(
1258                address,
1259                &mut regs,
1260                &mut cache,
1261                &mut fallback_stack,
1262                |_, _, _, _, _, _| {
1263                    Err(UnwinderError::Dwarf(DwarfUnwinderError::CouldNotRecoverCfa))
1264                },
1265            )
1266            .unwrap();
1267        assert_eq!(outcome.return_address(), Some(0x5000));
1268        assert_eq!(
1269            outcome.fallback_reason(),
1270            Some(FramePointerFallbackReason::UnwindInfo(
1271                UnwinderError::Dwarf(DwarfUnwinderError::CouldNotRecoverCfa)
1272            ))
1273        );
1274
1275        let mut regs = UnwindRegsX86_64::new(0x1100, 0x2000, 0x3000);
1276        let mut dwarf_stack = |stack_address| match stack_address {
1277            0x2008 => Ok(0x6000),
1278            _ => Err(()),
1279        };
1280        let mut retried = false;
1281        let outcome = unwinder
1282            .with_cache(
1283                address,
1284                &mut regs,
1285                &mut cache,
1286                &mut dwarf_stack,
1287                |_, _, _, _, _, _| {
1288                    retried = true;
1289                    Ok(UnwindResult::ExecRule(UnwindRuleX86_64::OffsetSp {
1290                        sp_offset_by_8: 2,
1291                    }))
1292                },
1293            )
1294            .unwrap();
1295        assert!(retried);
1296        assert_eq!(outcome.return_address(), Some(0x6000));
1297        assert_eq!(outcome.fallback_reason(), None);
1298
1299        let mut regs = UnwindRegsX86_64::new(0x1100, 0x2000, 0x3000);
1300        let outcome = unwinder
1301            .clone()
1302            .with_cache(
1303                address,
1304                &mut regs,
1305                &mut cache,
1306                &mut dwarf_stack,
1307                |_, _, _, _, _, _| panic!("the successful rule should be cached"),
1308            )
1309            .unwrap();
1310        assert_eq!(outcome.return_address(), Some(0x6000));
1311        assert_eq!(cache.rule_cache.stats().misses(), 2);
1312        assert_eq!(cache.rule_cache.stats().hits(), 1);
1313    }
1314
1315    #[test]
1316    fn dwarf_rows_with_callee_saved_registers_are_cached() {
1317        use crate::dwarf::tests::{eh_frame_with_fde, X86_64_CIE};
1318        use crate::x86_64::Reg;
1319        use gimli::X86_64;
1320
1321        // CIE: CFA=rsp+8, ra=[CFA-8]. FDE for 0x1000..0x1100: CFA=rsp+32, rbp=[CFA-16],
1322        // rbx=[CFA-24], r12=[CFA-32].
1323        let (eh_frame, _) = eh_frame_with_fde(
1324            &X86_64_CIE,
1325            0x1000..0x1100,
1326            &[
1327                gimli::DW_CFA_def_cfa_offset.0,
1328                32,
1329                gimli::DW_CFA_offset.0 | X86_64::RBP.0 as u8,
1330                2,
1331                gimli::DW_CFA_offset.0 | X86_64::RBX.0 as u8,
1332                3,
1333                gimli::DW_CFA_offset.0 | X86_64::R12.0 as u8,
1334                4,
1335            ],
1336        );
1337        let mut unwinder = TestUnwinder::new();
1338        unwinder.add_module(Module::new(
1339            "test".into(),
1340            0x1000..0x1100,
1341            0,
1342            ExplicitModuleSectionInfo {
1343                eh_frame: Some(eh_frame),
1344                ..Default::default()
1345            },
1346        ));
1347        let mut cache = TestCache::new();
1348        let mut read_stack = |address| match address {
1349            0x8000 => Ok(0x1200),
1350            0x8008 => Ok(0x1300),
1351            0x8010 => Ok(0x9100),
1352            0x8018 => Ok(0x3000),
1353            _ => Err(()),
1354        };
1355        // The miss and the cache hit must recover the same registers.
1356        for _ in 0..2 {
1357            let mut regs = UnwindRegsX86_64::new(0x1000, 0x8000, 0x9000);
1358            regs.set(Reg::RAX, 0xaa);
1359            regs.set(Reg::R13, 0xdd);
1360            let address = FrameAddress::from_return_address(0x1011).unwrap();
1361            let outcome = unwinder
1362                .unwind_frame_with_details(address, &mut regs, &mut cache, &mut read_stack)
1363                .unwrap();
1364            assert_eq!(outcome.return_address(), Some(0x3000));
1365            assert_eq!((regs.sp(), regs.bp()), (0x8020, 0x9100));
1366            assert_eq!(regs.get_if_set(Reg::RBX), Some(0x1300));
1367            assert_eq!(regs.get_if_set(Reg::R12), Some(0x1200));
1368            assert_eq!(regs.get_if_set(Reg::R13), Some(0xdd));
1369            assert_eq!(regs.get_if_set(Reg::RAX), None);
1370        }
1371        assert_eq!(cache.rule_cache.stats().hits(), 1);
1372    }
1373}