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
31pub trait Unwinder: Clone {
34 type UnwindRegs;
36
37 type Cache;
42
43 type Module;
46
47 fn add_module(&mut self, module: Self::Module);
52
53 fn remove_module(&mut self, module_avma_range_start: u64);
57
58 fn max_known_code_address(&self) -> u64;
65
66 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 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
93pub trait UnwinderWithDetails: Unwinder {
99 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
111pub 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 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 #[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 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 modules: Vec<Module<D>>,
276 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, 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 return None;
364 }
365 let i = insertion_index - 1;
366 let module = &self.modules[i];
367 if module.avma_range.end <= address {
368 return None;
370 }
371 (i, module)
372 }
373 };
374 if address < module.base_avma {
375 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 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
680enum ModuleUnwindDataInternal<D> {
693 #[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 EhFrameHdrAndEhFrame {
708 eh_frame_hdr: D,
709 eh_frame_hdr_table: Option<EhFrameHdrTable>,
711 eh_frame: D,
712 base_addresses: crate::dwarf::BaseAddresses,
713 },
714 DwarfCfiIndexAndEhFrame {
718 index: DwarfCfiIndex,
719 eh_frame: D,
720 base_addresses: crate::dwarf::BaseAddresses,
721 },
722 DwarfCfiIndexAndDebugFrame {
726 index: DwarfCfiIndex,
727 debug_frame: D,
728 base_addresses: crate::dwarf::BaseAddresses,
729 },
730 #[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 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 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#[cfg(feature = "macho")]
873struct TextByteData<D> {
874 pub bytes: D,
875 pub svma_range: Range<u64>,
876}
877
878pub struct Module<D> {
892 #[allow(unused)]
894 name: String,
895 avma_range: Range<u64>,
897 base_avma: u64,
900 base_svma: u64,
902 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
918pub trait ModuleSectionInfo<D> {
930 fn base_svma(&self) -> u64;
937
938 fn section_svma_range(&mut self, name: &[u8]) -> Option<Range<u64>>;
940
941 fn section_data(&mut self, name: &[u8]) -> Option<D>;
943
944 fn segment_svma_range(&mut self, _name: &[u8]) -> Option<Range<u64>> {
946 None
947 }
948
949 fn segment_data(&mut self, _name: &[u8]) -> Option<D> {
951 None
952 }
953}
954
955#[derive(Clone, Debug, Default, PartialEq, Eq)]
967pub struct ExplicitModuleSectionInfo<D> {
968 pub base_svma: u64,
973 pub text_svma: Option<Range<u64>>,
978 pub text: Option<D>,
983 pub stubs_svma: Option<Range<u64>>,
991 pub stub_helper_svma: Option<Range<u64>>,
1000 pub got_svma: Option<Range<u64>>,
1003 pub unwind_info: Option<D>,
1005 pub eh_frame_svma: Option<Range<u64>>,
1008 pub eh_frame: Option<D>,
1011 pub eh_frame_hdr_svma: Option<Range<u64>>,
1014 pub eh_frame_hdr: Option<D>,
1017 pub debug_frame: Option<D>,
1019 pub text_segment_svma: Option<Range<u64>>,
1021 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 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 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}