1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898
// Copyright 2015 Ted Mielczarek. See the COPYRIGHT
// file at the top-level directory of this distribution.
//! Unwind stack frames for a thread.
#[cfg(all(doctest, feature = "http"))]
doc_comment::doctest!("../README.md");
mod amd64;
mod arm;
mod arm64;
mod arm64_old;
mod mips;
pub mod symbols;
pub mod system_info;
mod x86;
use minidump::*;
use minidump_common::utils::basename;
use scroll::ctx::{SizeWith, TryFromCtx};
use std::borrow::Cow;
use std::collections::{BTreeMap, BTreeSet, HashSet};
use std::convert::TryFrom;
use std::io::{self, Write};
use tracing::trace;
pub use crate::symbols::*;
pub use crate::system_info::*;
#[derive(Clone, Copy)]
struct GetCallerFrameArgs<'a, P> {
callee_frame: &'a StackFrame,
grand_callee_frame: Option<&'a StackFrame>,
stack_memory: UnifiedMemory<'a, 'a>,
modules: &'a MinidumpModuleList,
system_info: &'a SystemInfo,
symbol_provider: &'a P,
}
impl<P> GetCallerFrameArgs<'_, P> {
fn valid(&self) -> &MinidumpContextValidity {
&self.callee_frame.context.valid
}
}
mod impl_prelude {
pub(crate) use super::{
CfiStackWalker, FrameTrust, GetCallerFrameArgs, StackFrame, SymbolProvider,
};
}
/// Indicates how well the instruction pointer derived during
/// stack walking is trusted. Since the stack walker can resort to
/// stack scanning, it can wind up with dubious frames.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum FrameTrust {
/// Unknown
None,
/// Scanned the stack, found this.
Scan,
/// Found while scanning stack using call frame info.
CfiScan,
/// Derived from frame pointer.
FramePointer,
/// Derived from call frame info.
CallFrameInfo,
/// Explicitly provided by some external stack walker.
PreWalked,
/// Given as instruction pointer in a context.
Context,
}
impl FrameTrust {
/// Return a string describing how a stack frame was found
/// by the stackwalker.
pub fn description(&self) -> &'static str {
match *self {
FrameTrust::Context => "given as instruction pointer in context",
FrameTrust::PreWalked => "recovered by external stack walker",
FrameTrust::CallFrameInfo => "call frame info",
FrameTrust::CfiScan => "call frame info with scanning",
FrameTrust::FramePointer => "previous frame's frame pointer",
FrameTrust::Scan => "stack scanning",
FrameTrust::None => "unknown",
}
}
pub fn as_str(&self) -> &'static str {
match *self {
FrameTrust::Context => "context",
FrameTrust::PreWalked => "prewalked",
FrameTrust::CallFrameInfo => "cfi",
FrameTrust::CfiScan => "cfi_scan",
FrameTrust::FramePointer => "frame_pointer",
FrameTrust::Scan => "scan",
FrameTrust::None => "non",
}
}
}
/// The calling convention of a function.
#[derive(Debug, Clone)]
pub enum CallingConvention {
Cdecl,
WindowsThisCall,
OtherThisCall,
}
/// Arguments for this function
#[derive(Debug, Clone)]
pub struct FunctionArgs {
/// What we assumed the calling convention was.
pub calling_convention: CallingConvention,
/// The actual arguments.
pub args: Vec<FunctionArg>,
}
/// A function argument.
#[derive(Debug, Clone)]
pub struct FunctionArg {
/// The name of the argument (usually actually just the type).
pub name: String,
/// The value of the argument.
pub value: Option<u64>,
}
/// A stack frame for an inlined function.
///
/// See [`StackFrame::inlines`][] for more details.
#[derive(Debug, Clone)]
pub struct InlineFrame {
/// The name of the function
pub function_name: String,
/// The file name of the stack frame
pub source_file_name: Option<String>,
/// The line number of the stack frame
pub source_line: Option<u32>,
}
/// A single stack frame produced from unwinding a thread's stack.
#[derive(Debug, Clone)]
pub struct StackFrame {
/// The program counter location as an absolute virtual address.
///
/// - For the innermost called frame in a stack, this will be an exact
/// program counter or instruction pointer value.
///
/// - For all other frames, this address is within the instruction that
/// caused execution to branch to this frame's callee (although it may
/// not point to the exact beginning of that instruction). This ensures
/// that, when we look up the source code location for this frame, we
/// get the source location of the call, not of the point at which
/// control will resume when the call returns, which may be on the next
/// line. (If the compiler knows the callee never returns, it may even
/// place the call instruction at the very end of the caller's machine
/// code, such that the "return address" (which will never be used)
/// immediately after the call instruction is in an entirely different
/// function, perhaps even from a different source file.)
///
/// On some architectures, the return address as saved on the stack or in
/// a register is fine for looking up the point of the call. On others, it
/// requires adjustment.
pub instruction: u64,
/// The instruction address (program counter) that execution of this function
/// would resume at, if the callee returns.
///
/// This is exactly **the return address of the of the callee**. We use this
/// nonstandard terminology because just calling this "return address"
/// would be ambiguous and too easy to mix up.
///
/// **Note:** you should strongly prefer using [`StackFrame::instruction`][], which should
/// be the address of the instruction before this one which called the callee.
/// That is the instruction that this function was logically "executing" when the
/// program's state was captured, and therefore what people expect from
/// backtraces.
///
/// This is more than a matter of user expections: **there are situations
/// where this value is nonsensical but the [`StackFrame::instruction`][] is valid.**
///
/// Specifically, if the callee is "noreturn" then *this function should
/// never resume execution*. The compiler has no obligation to emit any
/// instructions after such a CALL, but CALL still implicitly pushes the
/// instruction after itself to the stack. Such a return address may
/// therefore be outside the "bounds" of this function!!!
///
/// Yes, compilers *can* just immediately jump into the callee for
/// noreturn calls, but it's genuinely very helpful for them to emit a
/// CALL because it keeps the stack reasonable for backtraces and
/// debuggers, which are more interested in [`StackFrame::instruction`][] anyway!
///
/// (If this is the top frame of the call stack, then `resume_address`
/// and `instruction` are exactly equal and should reflect the actual
/// program counter of this thread.)
pub resume_address: u64,
/// The module in which the instruction resides.
pub module: Option<MinidumpModule>,
/// Any unloaded modules which overlap with this address.
///
/// This is currently only populated if `module` is None.
///
/// Since unloaded modules may overlap, there may be more than
/// one module. Since a module may be unloaded and reloaded at
/// multiple positions, we keep track of all the offsets that
/// apply. BTrees are used to produce a more stable output.
///
/// So this is a `BTreeMap<module_name, Set<offsets>>`.
pub unloaded_modules: BTreeMap<String, BTreeSet<u64>>,
/// The function name, may be omitted if debug symbols are not available.
pub function_name: Option<String>,
/// The start address of the function, may be omitted if debug symbols
/// are not available.
pub function_base: Option<u64>,
/// The size, in bytes, of the arguments pushed on the stack for this function.
/// WIN STACK unwinding needs this value to work; it's otherwise uninteresting.
pub parameter_size: Option<u32>,
/// The source file name, may be omitted if debug symbols are not available.
pub source_file_name: Option<String>,
/// The (1-based) source line number, may be omitted if debug symbols are
/// not available.
pub source_line: Option<u32>,
/// The start address of the source line, may be omitted if debug symbols
/// are not available.
pub source_line_base: Option<u64>,
/// Any inline frames that cover the frame address, ordered "inside to outside",
/// or "deepest callee to shallowest callee". This is the same order that StackFrames
/// appear in.
///
/// These frames are "fake" in that they don't actually exist at runtime, and are only
/// known because the compiler added debuginfo saying they exist.
///
/// As a result, many properties of these frames either don't exist or are
/// in some sense "inherited" from the parent real frame. For instance they
/// have the same instruction/module by definiton.
///
/// If you were to print frames you would want to do something like:
///
/// ```ignore
/// let mut frame_num = 0;
/// for frame in &thread.frames {
/// // Inlines come first
/// for inline in &frame.inlines {
/// print_inline(frame_num, frame, inline);
/// frame_num += 1;
/// }
/// print_frame(frame_num, frame);
/// frame_num += 1;
/// }
/// ```
pub inlines: Vec<InlineFrame>,
/// Amount of trust the stack walker has in the instruction pointer
/// of this frame.
pub trust: FrameTrust,
/// The CPU context containing register state for this frame.
pub context: MinidumpContext,
/// Any function args we recovered.
pub arguments: Option<FunctionArgs>,
}
impl StackFrame {
/// Create a `StackFrame` from a `MinidumpContext`.
pub fn from_context(context: MinidumpContext, trust: FrameTrust) -> StackFrame {
StackFrame {
instruction: context.get_instruction_pointer(),
// Initialized the same as `instruction`, but left unmodified during stack walking.
resume_address: context.get_instruction_pointer(),
module: None,
unloaded_modules: BTreeMap::new(),
function_name: None,
function_base: None,
parameter_size: None,
source_file_name: None,
source_line: None,
source_line_base: None,
inlines: Vec::new(),
arguments: None,
trust,
context,
}
}
}
impl FrameSymbolizer for StackFrame {
fn get_instruction(&self) -> u64 {
self.instruction
}
fn set_function(&mut self, name: &str, base: u64, parameter_size: u32) {
self.function_name = Some(String::from(name));
self.function_base = Some(base);
self.parameter_size = Some(parameter_size);
}
fn set_source_file(&mut self, file: &str, line: u32, base: u64) {
self.source_file_name = Some(String::from(file));
self.source_line = Some(line);
self.source_line_base = Some(base);
}
/// This function can be called multiple times, for the inlines that cover the
/// address at various levels of inlining. The call order is from outside to
/// inside.
fn add_inline_frame(&mut self, name: &str, file: Option<&str>, line: Option<u32>) {
self.inlines.push(InlineFrame {
function_name: name.to_string(),
source_file_name: file.map(ToString::to_string),
source_line: line,
})
}
}
/// Information about the results of unwinding a thread's stack.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CallStackInfo {
/// Everything went great.
Ok,
/// No `MinidumpContext` was provided, couldn't do anything.
MissingContext,
/// No stack memory was provided, couldn't unwind past the top frame.
MissingMemory,
/// The CPU type is unsupported.
UnsupportedCpu,
/// This thread wrote the minidump, it was skipped.
DumpThreadSkipped,
}
/// A stack of `StackFrame`s produced as a result of unwinding a thread.
#[derive(Debug, Clone)]
pub struct CallStack {
/// The stack frames.
/// By convention, the stack frame at index 0 is the innermost callee frame,
/// and the frame at the highest index in a call stack is the outermost
/// caller.
pub frames: Vec<StackFrame>,
/// Information about this `CallStack`.
pub info: CallStackInfo,
/// The identifier of the thread.
pub thread_id: u32,
/// The name of the thread, if known.
pub thread_name: Option<String>,
/// The GetLastError() value stored in the TEB.
pub last_error_value: Option<CrashReason>,
}
impl CallStack {
/// Construct a CallStack that just has the unsymbolicated context frame.
///
/// This is the desired input for the stack walker.
pub fn with_context(context: MinidumpContext) -> Self {
Self {
frames: vec![StackFrame::from_context(context, FrameTrust::Context)],
info: CallStackInfo::Ok,
thread_id: 0,
thread_name: None,
last_error_value: None,
}
}
/// Create a `CallStack` with `info` and no frames.
pub fn with_info(id: u32, info: CallStackInfo) -> CallStack {
CallStack {
info,
frames: vec![],
thread_id: id,
thread_name: None,
last_error_value: None,
}
}
/// Write a human-readable description of the call stack to `f`.
///
/// This is very verbose, it implements the output format used by
/// minidump_stackwalk.
pub fn print<T: Write>(&self, f: &mut T) -> io::Result<()> {
fn print_registers<T: Write>(f: &mut T, ctx: &MinidumpContext) -> io::Result<()> {
let registers: Cow<HashSet<&str>> = match ctx.valid {
MinidumpContextValidity::All => {
let gpr = ctx.general_purpose_registers();
let set: HashSet<&str> = gpr.iter().cloned().collect();
Cow::Owned(set)
}
MinidumpContextValidity::Some(ref which) => Cow::Borrowed(which),
};
// Iterate over registers in a known order.
let mut output = String::new();
for reg in ctx.general_purpose_registers() {
if registers.contains(reg) {
let reg_val = ctx.format_register(reg);
let next = format!(" {reg: >6} = {reg_val}");
if output.chars().count() + next.chars().count() > 80 {
// Flush the buffer.
writeln!(f, " {output}")?;
output.truncate(0);
}
output.push_str(&next);
}
}
if !output.is_empty() {
writeln!(f, " {output}")?;
}
Ok(())
}
if self.frames.is_empty() {
writeln!(f, "<no frames>")?;
}
let mut frame_count = 0;
for frame in &self.frames {
// First print out inlines
for inline in &frame.inlines {
// Frame number
let frame_idx = frame_count;
frame_count += 1;
write!(f, "{frame_idx:2} ")?;
// Module name
if let Some(ref module) = frame.module {
write!(f, "{}", basename(&module.code_file()))?;
}
// Function name
write!(f, "!{}", inline.function_name)?;
// Source file and line
if let (Some(source_file), Some(source_line)) =
(&inline.source_file_name, &inline.source_line)
{
write!(f, " [{} : {}]", basename(source_file), source_line,)?;
}
writeln!(f)?;
// A fake `trust`
writeln!(f, " Found by: inlining")?;
}
// Now print out the "real frame"
let frame_idx = frame_count;
frame_count += 1;
let addr = frame.instruction;
// Frame number
write!(f, "{frame_idx:2} ")?;
if let Some(module) = &frame.module {
// Module name
write!(f, "{}", basename(&module.code_file()))?;
if let (Some(func_name), Some(func_base)) =
(&frame.function_name, &frame.function_base)
{
// Function name
write!(f, "!{func_name}")?;
if let (Some(src_file), Some(src_line), Some(src_base)) = (
&frame.source_file_name,
&frame.source_line,
&frame.source_line_base,
) {
// Source file, line, and offset
write!(
f,
" [{} : {} + {:#x}]",
basename(src_file),
src_line,
addr - src_base
)?;
} else {
// We didn't have source info, so just give a byte offset from the func
write!(f, " + {:#x}", addr - func_base)?;
}
} else {
// We didn't have a function name, so just give a byte offset from the module
write!(f, " + {:#x}", addr - module.base_address())?;
}
} else {
// We didn't even find a module, so just print the raw address
write!(f, "{addr:#x}")?;
// List off overlapping unloaded modules.
// First we need to collect them up by name so that we can print
// all the overlaps from one module together and dedupe them.
// (!!! was that code deleted?)
for (name, offsets) in &frame.unloaded_modules {
write!(f, " (unloaded {name}@")?;
let mut first = true;
for offset in offsets {
if first {
write!(f, "{offset:#x}")?;
} else {
// `|` is our separator for multiple entries
write!(f, "|{offset:#x}")?;
}
first = false;
}
write!(f, ")")?;
}
}
// Print the valid registers
writeln!(f)?;
print_registers(f, &frame.context)?;
// And the trust we have of this result
writeln!(f, " Found by: {}", frame.trust.description())?;
// Now print out recovered args
if let Some(args) = &frame.arguments {
use MinidumpRawContext::*;
let pointer_width = match &frame.context.raw {
X86(_) | Ppc(_) | Sparc(_) | Arm(_) | Mips(_) => 4,
Ppc64(_) | Amd64(_) | Arm64(_) | OldArm64(_) => 8,
};
let cc_summary = match args.calling_convention {
CallingConvention::Cdecl => "cdecl [static function]",
CallingConvention::WindowsThisCall => "windows thiscall [C++ member function]",
CallingConvention::OtherThisCall => {
"non-windows thiscall [C++ member function]"
}
};
writeln!(f, " Arguments (assuming {cc_summary})")?;
for (idx, arg) in args.args.iter().enumerate() {
if let Some(val) = arg.value {
if pointer_width == 4 {
writeln!(f, " arg {} ({}) = 0x{:08x}", idx, arg.name, val)?;
} else {
writeln!(f, " arg {} ({}) = 0x{:016x}", idx, arg.name, val)?;
}
} else {
writeln!(f, " arg {} ({}) = <unknown>", idx, arg.name)?;
}
}
// Add an extra new-line between frames when there's function arguments to make
// it more readable.
writeln!(f)?;
}
}
Ok(())
}
}
struct CfiStackWalker<'a, C: CpuContext> {
instruction: u64,
has_grand_callee: bool,
grand_callee_parameter_size: u32,
callee_ctx: &'a C,
callee_validity: &'a MinidumpContextValidity,
caller_ctx: C,
caller_validity: HashSet<&'static str>,
module: &'a MinidumpModule,
stack_memory: UnifiedMemory<'a, 'a>,
}
impl<'a, C> CfiStackWalker<'a, C>
where
C: CpuContext + Clone,
{
fn from_ctx_and_args<P, R>(
ctx: &'a C,
args: &'a GetCallerFrameArgs<'a, P>,
callee_forwarded_regs: R,
) -> Option<Self>
where
R: Fn(&MinidumpContextValidity) -> HashSet<&'static str>,
{
let module = args
.modules
.module_at_address(args.callee_frame.instruction)?;
let grand_callee = args.grand_callee_frame;
Some(Self {
instruction: args.callee_frame.instruction,
has_grand_callee: grand_callee.is_some(),
grand_callee_parameter_size: grand_callee.and_then(|f| f.parameter_size).unwrap_or(0),
callee_ctx: ctx,
callee_validity: args.valid(),
// Default to forwarding all callee-saved regs verbatim.
// The CFI evaluator may clear or overwrite these values.
// The stack pointer and instruction pointer are not included.
caller_ctx: ctx.clone(),
caller_validity: callee_forwarded_regs(args.valid()),
module,
stack_memory: args.stack_memory,
})
}
}
impl<'a, C> FrameWalker for CfiStackWalker<'a, C>
where
C: CpuContext,
C::Register: TryFrom<u64>,
u64: TryFrom<C::Register>,
C::Register: TryFromCtx<'a, Endian, [u8], Error = scroll::Error> + SizeWith<Endian>,
{
fn get_instruction(&self) -> u64 {
self.instruction
}
fn has_grand_callee(&self) -> bool {
self.has_grand_callee
}
fn get_grand_callee_parameter_size(&self) -> u32 {
self.grand_callee_parameter_size
}
fn get_register_at_address(&self, address: u64) -> Option<u64> {
let result: Option<C::Register> = self.stack_memory.get_memory_at_address(address);
result.and_then(|val| u64::try_from(val).ok())
}
fn get_callee_register(&self, name: &str) -> Option<u64> {
self.callee_ctx
.get_register(name, self.callee_validity)
.and_then(|val| u64::try_from(val).ok())
}
fn set_caller_register(&mut self, name: &str, val: u64) -> Option<()> {
let memoized = self.caller_ctx.memoize_register(name)?;
let val = C::Register::try_from(val).ok()?;
self.caller_validity.insert(memoized);
self.caller_ctx.set_register(name, val)
}
fn clear_caller_register(&mut self, name: &str) {
self.caller_validity.remove(name);
}
fn set_cfa(&mut self, val: u64) -> Option<()> {
// NOTE: some things have alluded to architectures where this isn't
// how the CFA should be handled, but we apparently don't support them yet?
let stack_pointer_reg = self.caller_ctx.stack_pointer_register_name();
let val = C::Register::try_from(val).ok()?;
self.caller_validity.insert(stack_pointer_reg);
self.caller_ctx.set_register(stack_pointer_reg, val)
}
fn set_ra(&mut self, val: u64) -> Option<()> {
let instruction_pointer_reg = self.caller_ctx.instruction_pointer_register_name();
let val = C::Register::try_from(val).ok()?;
self.caller_validity.insert(instruction_pointer_reg);
self.caller_ctx.set_register(instruction_pointer_reg, val)
}
}
#[tracing::instrument(name = "unwind_frame", level = "trace", skip_all, fields(idx = _frame_idx, fname = args.callee_frame.function_name.as_deref().unwrap_or("")))]
async fn get_caller_frame<P>(
_frame_idx: usize,
args: &GetCallerFrameArgs<'_, P>,
) -> Option<StackFrame>
where
P: SymbolProvider + Sync,
{
match args.callee_frame.context.raw {
/*
MinidumpRawContext::PPC(ctx) => ctx.get_caller_frame(stack_memory),
MinidumpRawContext::PPC64(ctx) => ctx.get_caller_frame(stack_memory),
MinidumpRawContext::SPARC(ctx) => ctx.get_caller_frame(stack_memory),
*/
MinidumpRawContext::Arm(ref ctx) => arm::get_caller_frame(ctx, args).await,
MinidumpRawContext::Arm64(ref ctx) => arm64::get_caller_frame(ctx, args).await,
MinidumpRawContext::OldArm64(ref ctx) => arm64_old::get_caller_frame(ctx, args).await,
MinidumpRawContext::Amd64(ref ctx) => amd64::get_caller_frame(ctx, args).await,
MinidumpRawContext::X86(ref ctx) => x86::get_caller_frame(ctx, args).await,
MinidumpRawContext::Mips(ref ctx) => mips::get_caller_frame(ctx, args).await,
_ => None,
}
}
async fn fill_source_line_info<P>(
frame: &mut StackFrame,
modules: &MinidumpModuleList,
symbol_provider: &P,
) where
P: SymbolProvider + Sync,
{
// Find the module whose address range covers this frame's instruction.
if let Some(module) = modules.module_at_address(frame.instruction) {
// FIXME: this shouldn't need to clone, we should be able to use
// the same lifetime as the module list that's passed in.
frame.module = Some(module.clone());
// This is best effort, so ignore any errors.
let _ = symbol_provider.fill_symbol(module, frame).await;
// If we got any inlines, reverse them! The symbol format makes it simplest to
// emit inlines from the shallowest callee to the deepest one ("inner to outer"),
// but we want inlines to be in the same order as the stackwalk itself, which means
// we want the deepest frame first (the callee-est frame).
frame.inlines.reverse();
}
}
/// An optional callback when walking frames.
///
/// One may convert from other types to this callback type:
/// `FnMut(frame_idx: usize, frame: &StackFrame)` types can be converted to a
/// callback, and `()` can be converted to no callback (do nothing).
pub enum OnWalkedFrame<'a> {
None,
#[allow(clippy::type_complexity)]
Some(Box<dyn FnMut(usize, &StackFrame) + Send + 'a>),
}
impl From<()> for OnWalkedFrame<'_> {
fn from(_: ()) -> Self {
Self::None
}
}
impl<'a, F: FnMut(usize, &StackFrame) + Send + 'a> From<F> for OnWalkedFrame<'a> {
fn from(f: F) -> Self {
Self::Some(Box::new(f))
}
}
#[tracing::instrument(name = "unwind_thread", level = "trace", skip_all, fields(idx = _thread_idx, tid = stack.thread_id, tname = stack.thread_name.as_deref().unwrap_or("")))]
pub async fn walk_stack<P>(
_thread_idx: usize,
on_walked_frame: impl Into<OnWalkedFrame<'_>>,
stack: &mut CallStack,
stack_memory: Option<UnifiedMemory<'_, '_>>,
modules: &MinidumpModuleList,
system_info: &SystemInfo,
symbol_provider: &P,
) where
P: SymbolProvider + Sync,
{
trace!(
"starting stack unwind of thread {} {}",
stack.thread_id,
stack.thread_name.as_deref().unwrap_or(""),
);
// All the unwinder code down below in `get_caller_frame` requires a valid `stack_memory`,
// where _valid_ means that we can actually read something from it. A call to `memory_range` will validate that,
// as it will reject empty stack memory or one with an overflowing `size`.
let stack_memory =
stack_memory.and_then(|stack_memory| stack_memory.memory_range().map(|_| stack_memory));
// Begin with the context frame, and keep getting callers until there are no more.
let mut has_new_frame = !stack.frames.is_empty();
let mut on_walked_frame = on_walked_frame.into();
while has_new_frame {
// Symbolicate the new frame
let frame_idx = stack.frames.len() - 1;
let frame = stack.frames.last_mut().unwrap();
fill_source_line_info(frame, modules, symbol_provider).await;
// Report the frame as walked and symbolicated
if let OnWalkedFrame::Some(on_walked_frame) = &mut on_walked_frame {
on_walked_frame(frame_idx, frame);
}
let Some(stack_memory) = stack_memory else {
break;
};
// Walk the new frame
let callee_frame = &stack.frames.last().unwrap();
let grand_callee_frame = stack
.frames
.len()
.checked_sub(2)
.and_then(|idx| stack.frames.get(idx));
match callee_frame.function_name.as_ref() {
Some(name) => trace!("unwinding {}", name),
None => trace!("unwinding 0x{:016x}", callee_frame.instruction),
}
let new_frame = get_caller_frame(
frame_idx,
&GetCallerFrameArgs {
callee_frame,
grand_callee_frame,
stack_memory,
modules,
system_info,
symbol_provider,
},
)
.await;
// Check if we're done
if let Some(new_frame) = new_frame {
stack.frames.push(new_frame);
} else {
has_new_frame = false;
}
}
trace!(
"finished stack unwind of thread {} {}\n",
stack.thread_id,
stack.thread_name.as_deref().unwrap_or(""),
);
}
/// Checks if we can dismiss the validity of an instruction based on our symbols,
/// to refine the quality of each unwinder's instruction_seems_valid implementation.
async fn instruction_seems_valid_by_symbols<P>(
instruction: u64,
modules: &MinidumpModuleList,
symbol_provider: &P,
) -> bool
where
P: SymbolProvider + Sync,
{
// Our input is a candidate return address, but we *really* want to validate the address
// of the call instruction *before* the return address. In theory this symbol-based
// analysis shouldn't *care* whether we're looking at the call or the instruction
// after it, but there is one corner case where the return address can be invalid
// but the instruction before it isn't: noreturn.
//
// If the *callee* is noreturn, then the caller has no obligation to have any instructions
// after the call! So e.g. on x86 if you CALL a noreturn function, the return address
// that's implicitly pushed *could* be one-past-the-end of the "function".
//
// This has been observed in practice with `+[NSThread exit]`!
//
// We don't otherwise need the instruction pointer to be terribly precise, so
// subtracting 1 from the address should be sufficient to handle this corner case.
let instruction = instruction.saturating_sub(1);
// NULL pointer is definitely not valid
if instruction == 0 {
return false;
}
if let Some(module) = modules.module_at_address(instruction) {
// Create a dummy frame symbolizing implementation to feed into
// our symbol provider with the address we're interested in. If
// it tries to set a non-empty function name, then we can reasonably
// assume the instruction address is valid.
//use crate::FrameSymbolizer;
struct DummyFrame {
instruction: u64,
has_name: bool,
}
impl FrameSymbolizer for DummyFrame {
fn get_instruction(&self) -> u64 {
self.instruction
}
fn set_function(&mut self, name: &str, _base: u64, _parameter_size: u32) {
self.has_name = !name.is_empty();
}
fn set_source_file(&mut self, _file: &str, _line: u32, _base: u64) {
// Do nothing
}
}
let mut frame = DummyFrame {
instruction,
has_name: false,
};
if symbol_provider
.fill_symbol(module, &mut frame)
.await
.is_ok()
{
frame.has_name
} else {
// If the symbol provider returns an Error, this means that we
// didn't have any symbols for the *module*. Just assume the
// instruction is valid in this case so that scanning works
// when we have no symbols.
true
}
} else {
// We couldn't even map this address to a module. Reject the pointer
// so that we have *some* way to distinguish "normal" pointers
// from instruction address.
//
// FIXME: this will reject any pointer into JITed code which otherwise
// isn't part of a normal well-defined module. We can potentially use
// MemoryInfoListStream (windows) and /proc/self/maps (linux) to refine
// this analysis and allow scans to walk through JITed code.
false
}
}
#[cfg(test)]
mod amd64_unittest;
#[cfg(test)]
mod arm64_unittest;
#[cfg(test)]
mod arm_unittest;
#[cfg(test)]
mod x86_unittest;