### Get Module Name Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Returns the name of the module. ```rust pub fn name(&self) -> &str { &self.name } ``` -------------------------------- ### AArch64 Stack Unwinding Example Source: https://docs.rs/framehop/0.16.0/framehop/index.html Demonstrates how to use the `UnwinderAarch64` to iterate through stack frames. Requires explicit module information and a stack read function. ```rust use core::ops::Range; use framehop::aarch64::{CacheAarch64, UnwindRegsAarch64, UnwinderAarch64}; use framehop::{ExplicitModuleSectionInfo, FrameAddress, Module}; let mut cache = CacheAarch64::<_>::new(); let mut unwinder = UnwinderAarch64::new(); let module = Module::new( "mybinary".to_string(), 0x1003fc000..0x100634000, 0x1003fc000, ExplicitModuleSectionInfo { base_svma: 0x100000000, text_svma: Some(0x100000b64..0x1001d2d18), text: Some(vec![/* __text */]), stubs_svma: Some(0x1001d2d18..0x1001d309c), stub_helper_svma: Some(0x1001d309c..0x1001d3438), got_svma: Some(0x100238000..0x100238010), unwind_info: Some(vec![/* __unwind_info */]), eh_frame_svma: Some(0x100237f80..0x100237ffc), eh_frame: Some(vec![/* __eh_frame */]), text_segment_svma: Some(0x1003fc000..0x100634000), text_segment: Some(vec![/* __TEXT */]), ..Default::default() }, ); unwinder.add_module(module); let pc = 0x1003fc000 + 0x1292c0; let lr = 0x1003fc000 + 0xe4830; let sp = 0x10; let fp = 0x20; let stack = [ 1, 2, 3, 4, 0x40, 0x1003fc000 + 0x100dc4, 5, 6, 0x70, 0x1003fc000 + 0x12ca28, 7, 8, 9, 10, 0x0, 0x0, ]; let mut read_stack = |addr| stack.get((addr / 8) as usize).cloned().ok_or(()); use framehop::Unwinder; let mut iter = unwinder.iter_frames( pc, UnwindRegsAarch64::new(lr, sp, fp), &mut cache, &mut read_stack, ); let mut frames = Vec::new(); while let Ok(Some(frame)) = iter.next() { frames.push(frame); } assert_eq!( frames, vec![ FrameAddress::from_instruction_pointer(0x1003fc000 + 0x1292c0), FrameAddress::from_return_address(0x1003fc000 + 0x100dc4).unwrap(), FrameAddress::from_return_address(0x1003fc000 + 0x12ca28).unwrap() ] ); ``` -------------------------------- ### Create a new CacheStats instance Source: https://docs.rs/framehop/0.16.0/framehop/struct.CacheStats.html Initializes a new CacheStats struct with zero counts. Use this when starting to track cache performance. ```rust pub fn new() -> Self ``` -------------------------------- ### UnwindRegsX86_64 Methods Source: https://docs.rs/framehop/0.16.0/framehop/type.UnwindRegsNative.html Provides methods for creating, getting, and setting register values for UnwindRegsX86_64. ```APIDOC ## Implementations for UnwindRegsX86_64 ### `impl UnwindRegsX86_64` #### `pub fn new(ip: u64, sp: u64, bp: u64) -> Self` Creates a new `UnwindRegsX86_64` instance. #### `pub fn get(&self, reg: Reg) -> u64` Retrieves the value of a specific register. #### `pub fn set(&mut self, reg: Reg, value: u64)` Sets the value of a specific register. #### `pub fn ip(&self) -> u64` Gets the instruction pointer (IP). #### `pub fn set_ip(&mut self, ip: u64)` Sets the instruction pointer (IP). #### `pub fn sp(&self) -> u64` Gets the stack pointer (SP). #### `pub fn set_sp(&mut self, sp: u64)` Sets the stack pointer (SP). #### `pub fn bp(&self) -> u64` Gets the base pointer (BP). #### `pub fn set_bp(&mut self, bp: u64)` Sets the base pointer (BP). ``` -------------------------------- ### RuleCache Statistics Retrieval Source: https://docs.rs/framehop/0.16.0/src/framehop/rule_cache.rs.html Provides a method to get a snapshot of the current cache usage statistics. ```rust pub fn stats(&self) -> CacheStats { self.stats } ``` -------------------------------- ### Module Constructor Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Creates a new Module instance with the provided name, address range, base address, and section information. ```APIDOC ## Module::new ### Description Constructs a new `Module` instance. ### Method `pub fn new( name: String, avma_range: core::ops::Range, base_avma: u64, section_info: impl ModuleSectionInfo, ) -> Self` ### Parameters - **name** (`String`) - The name of the module. - **avma_range** (`core::ops::Range`) - The address range of the module. - **base_avma** (`u64`) - The base absolute virtual memory address of the module. - **section_info** (`impl ModuleSectionInfo`) - An object providing module section information. ``` -------------------------------- ### Get Type ID Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwindRegsAarch64.html Gets the TypeId of the current type, used for dynamic type checking. ```rust fn type_id(&self) -> TypeId ``` -------------------------------- ### Provided Methods Source: https://docs.rs/framehop/0.16.0/framehop/trait.ModuleSectionInfo.html These methods have default implementations but can be overridden. ```APIDOC fn segment_svma_range(&mut self, _name: &[u8]) -> Option> Get the given segment’s memory range, as stated in the module. ``` ```APIDOC fn segment_data(&mut self, _name: &[u8]) -> Option Get the given segment’s data. This will only be called once per segment. ``` -------------------------------- ### Get Module Base AVMA Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Returns the base AVMA of the module. ```rust pub fn base_avma(&self) -> u64 { self.base_avma } ``` -------------------------------- ### Module Implementations Source: https://docs.rs/framehop/0.16.0/framehop/struct.Module.html Provides methods for creating and accessing information about a Module instance. ```APIDOC ## Implementations ### impl> Module #### `new` Constructor ```rust pub fn new( name: String, avma_range: Range, base_avma: u64, section_info: impl ModuleSectionInfo, ) -> Self ``` Creates a new `Module` instance. #### `avma_range` Method ```rust pub fn avma_range(&self) -> Range ``` Returns the address range of the module. #### `base_avma` Method ```rust pub fn base_avma(&self) -> u64 ``` Returns the base absolute virtual memory address of the module. #### `name` Method ```rust pub fn name(&self) -> &str ``` Returns the name of the module. ``` -------------------------------- ### Get Link Register Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwindRegsAarch64.html Retrieves the link register (lr) value. ```rust pub fn lr(&self) -> u64 ``` -------------------------------- ### CloneToUninit Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.PtrAuthMask.html Experimental API for performing copy-assignment to uninitialized memory. This is a nightly-only feature. ```APIDOC ## unsafe fn clone_to_uninit(&self, dest: *mut u8) Performs copy-assignment from `self` to `dest`. ``` -------------------------------- ### UnwinderAarch64::remove_module Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwinderAarch64.html Removes a module from the unwinder, keyed by its starting address. ```APIDOC ## UnwinderAarch64::remove_module ### Description Remove a module that was added before using `add_module`, keyed by the start address of that module’s address range. If no match is found, the call is ignored. This should be called whenever a module is unloaded from the process. ### Parameters - `module_address_range_start` (`u64`): The starting address of the module's address range. ``` -------------------------------- ### UnwinderAarch64::new Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwinderAarch64.html Creates a new UnwinderAarch64 instance for a process. ```APIDOC ## UnwinderAarch64::new ### Description Create an unwinder for a process. ### Returns - `Self`: A new instance of `UnwinderAarch64`. ``` -------------------------------- ### UnwindRegsX86_64 get method Source: https://docs.rs/framehop/0.16.0/framehop/type.UnwindRegsNative.html Retrieves the value of a specified register from the UnwindRegsX86_64 instance. ```rust pub fn get(&self, reg: Reg) -> u64 ``` -------------------------------- ### Get Frame Pointer Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwindRegsAarch64.html Retrieves the frame pointer (fp), which is register x29. ```rust pub fn fp(&self) -> u64 ``` -------------------------------- ### Implement Default for CacheX86_64 Source: https://docs.rs/framehop/0.16.0/src/framehop/x86_64/cache.rs.html Provides a default implementation for `CacheX86_64`, allowing it to be created using `Default::default()`. It uses `new_in` to create the cache. ```rust impl Default for CacheX86_64

{ fn default() -> Self { Self::new_in() } } ``` -------------------------------- ### Get Stack Pointer Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwindRegsAarch64.html Retrieves the current stack pointer (sp) value. ```rust pub fn sp(&self) -> u64 ``` -------------------------------- ### CacheX86_64::new_in Source: https://docs.rs/framehop/0.16.0/framehop/x86_64/struct.CacheX86_64.html Creates a new instance of CacheX86_64 with a specified allocation policy. ```APIDOC ## CacheX86_64::new_in() ### Description Creates a new cache with a specified allocation policy. ### Method `new_in()` ### Type Parameters - `P`: An `AllocationPolicy` trait bound. ### Returns - `Self`: A new instance of `CacheX86_64`. ``` -------------------------------- ### new_in() - CacheX86_64 Source: https://docs.rs/framehop/0.16.0/framehop/type.CacheNative.html Creates a new instance of the CacheX86_64 cache. ```APIDOC ### impl CacheX86_64

#### pub fn new_in() -> Self Create a new cache. ``` -------------------------------- ### Get PtrAuthMask for LR Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwindRegsAarch64.html Retrieves the PtrAuthMask that is applied to the link register (lr) value. ```rust pub fn lr_mask(&self) -> PtrAuthMask ``` -------------------------------- ### Try Convert From Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwindRegsAarch64.html Attempts to perform a conversion from one type to another. Returns a `Result` which is `Ok` on success or `Err` if the conversion fails. ```rust type Error = Infallible ``` ```rust fn try_from(value: U) -> Result>::Error> ``` -------------------------------- ### Initialize Module with Unwind Data Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Creates a new Module instance, initializing it with name, address range, base address, and unwind data derived from section information. ```rust pub fn new( name: String, avma_range: core::ops::Range, base_avma: u64, mut section_info: impl ModuleSectionInfo, ) -> Self { let unwind_data = ModuleUnwindDataInternal::new(&mut section_info); Self { name, avma_range, base_avma, base_svma: section_info.base_svma(), unwind_data: Arc::new(unwind_data), } } ``` -------------------------------- ### Get Module AVMA Range Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Returns the AVMA (Absolute Virtual Memory Address) range of the module. ```rust pub fn avma_range(&self) -> core::ops::Range { self.avma_range.clone() } ``` -------------------------------- ### new() - UnwinderX86_64 Source: https://docs.rs/framehop/0.16.0/framehop/x86_64/struct.UnwinderX86_64.html Creates a new instance of the UnwinderX86_64 for a process. ```APIDOC ## `new()` ```rust pub fn new() -> Self ``` Create an unwinder for a process. ``` -------------------------------- ### PartialEq Implementation Source: https://docs.rs/framehop/0.16.0/framehop/struct.ExplicitModuleSectionInfo.html Methods for comparing two ExplicitModuleSectionInfo instances for equality. ```APIDOC ## fn eq(&self, other: &ExplicitModuleSectionInfo) -> bool ### Description Tests for `self` and `other` values to be equal, and is used by `==`. ### Method GET (conceptual) ### Endpoint N/A (SDK method) ### Parameters - **other** (&ExplicitModuleSectionInfo) - Required - The other instance to compare against. ### Response - **equal** (bool) - True if the instances are equal, false otherwise. ``` ```APIDOC ## fn ne(&self, other: &Rhs) -> bool ### Description Tests for `!=`. The default implementation is almost always sufficient, and should not be overridden without very good reason. ### Method GET (conceptual) ### Endpoint N/A (SDK method) ### Parameters - **other** (&Rhs) - Required - The other instance to compare against. ### Response - **not_equal** (bool) - True if the instances are not equal, false otherwise. ``` -------------------------------- ### Get Segment Data by Name Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Retrieves segment data based on its name. Currently only supports the '__TEXT' segment. ```rust fn segment_data(&mut self, name: &[u8]) -> Option { match name { b"__TEXT" => self.text_segment.take(), _ => None, } } ``` -------------------------------- ### Module Constructor Source: https://docs.rs/framehop/0.16.0/framehop/struct.Module.html Creates a new Module instance. Requires the module's name, its virtual address range, base virtual address, and section information. ```rust pub fn new( name: String, avma_range: Range, base_avma: u64, section_info: impl ModuleSectionInfo, ) -> Self ``` -------------------------------- ### Get total cache hits Source: https://docs.rs/framehop/0.16.0/framehop/struct.CacheStats.html Returns the total number of successful cache lookups. This is a direct count of `hit_count`. ```rust pub fn hits(&self) -> u64 ``` -------------------------------- ### UnwinderX86_64::new Source: https://docs.rs/framehop/0.16.0/src/framehop/x86_64/unwinder.rs.html Creates a new unwinder instance for the x86_64 architecture. ```APIDOC /// Create an unwinder for a process. pub fn new() -> Self { Self(UnwinderInternal::new()) } ``` -------------------------------- ### Get Cache Statistics Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.CacheAarch64.html Retrieves a snapshot of the current cache usage statistics. This can be useful for monitoring and performance analysis. ```rust pub fn stats(&self) -> CacheStats ``` -------------------------------- ### Get minimum of two PtrAuthMask values Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.PtrAuthMask.html Implements the min method for PtrAuthMask, returning the lesser of two mask values. ```rust fn min(self, other: Self) -> Self where Self: Sized, ``` -------------------------------- ### CacheX86_64::new Source: https://docs.rs/framehop/0.16.0/src/framehop/x86_64/cache.rs.html Creates a new instance of CacheX86_64 with a default allocation policy that may allocate during unwinding. ```APIDOC ## CacheX86_64::new ### Description Creates a new cache for the x86_64 unwinder. This constructor is specific to caches that may allocate memory during the unwinding process. ### Signature ```rust pub fn new() -> Self ``` ### Returns A new `CacheX86_64` instance. ``` -------------------------------- ### Get maximum of two PtrAuthMask values Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.PtrAuthMask.html Implements the max method for PtrAuthMask, returning the greater of two mask values. ```rust fn max(self, other: Self) -> Self where Self: Sized, ``` -------------------------------- ### RuleCache Initialization Source: https://docs.rs/framehop/0.16.0/src/framehop/rule_cache.rs.html The `new` function initializes a RuleCache with a boxed array of `None` entries and default statistics. ```rust pub fn new() -> Self { Self { entries: Box::new([None; CACHE_ENTRY_COUNT]), stats: CacheStats::new(), } } ``` -------------------------------- ### AArch64 PtrAuthMask Initialization and Usage Source: https://docs.rs/framehop/0.16.0/src/framehop/aarch64/unwindregs.rs.html Demonstrates the initialization of PtrAuthMask with different bit configurations and its use with maximum known addresses. These assertions verify the correct masking behavior for pointer authentication. ```rust assert_eq!(PtrAuthMask::new_24_40().0, u64::MAX >> 24); assert_eq!(PtrAuthMask::new_24_40().0, (1 << 40) - 1); assert_eq!( PtrAuthMask::from_max_known_address(0x0000aaaab54f7000).0, 0x0000ffffffffffff ); assert_eq!( PtrAuthMask::from_max_known_address(0x0000ffffa3206000).0, 0x0000ffffffffffff ); assert_eq!( PtrAuthMask::from_max_known_address(0xffffffffc05a9000).0, 0xffffffffffffffff ); assert_eq!( PtrAuthMask::from_max_known_address(0x000055ba9f07e000).0, 0x00007fffffffffff ); assert_eq!( PtrAuthMask::from_max_known_address(0x00007f76b8019000).0, 0x00007fffffffffff ); assert_eq!( PtrAuthMask::from_max_known_address(0x000000022a3ccff7).0, 0x00000003ffffffff ); ``` -------------------------------- ### Get Raw Address Source: https://docs.rs/framehop/0.16.0/framehop/enum.FrameAddress.html Retrieves the raw 64-bit unsigned integer address (AVMA) stored within the FrameAddress enum. ```rust pub fn address(self) -> u64> ``` -------------------------------- ### UnwinderX86_64::new Source: https://docs.rs/framehop/0.16.0/framehop/type.UnwinderNative.html Creates a new unwinder instance for a process. ```APIDOC ## UnwinderX86_64::new ```rust pub fn new() -> Self; ``` Create an unwinder for a process. ``` -------------------------------- ### Remove Module from UnwinderAarch64 Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwinderAarch64.html Removes a previously added module from the unwinder, keyed by its starting address. This should be called when a module is unloaded. ```rust fn remove_module(&mut self, module_address_range_start: u64) ``` -------------------------------- ### Get Section Data by Name Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Retrieves specific section data based on its name. Supports common unwind and debug sections. ```rust fn section_data(&mut self, name: &[u8]) -> Option { match name { b"__text" | b".text" => self.text.take(), b"__unwind_info" => self.unwind_info.take(), b"__eh_frame" | b".eh_frame" => self.eh_frame.take(), b"__eh_frame_hdr" | b".eh_frame_hdr" => self.eh_frame_hdr.take(), b"__debug_frame" | b".debug_frame" => self.debug_frame.take(), _ => None, } } ``` -------------------------------- ### Get Raw Address (AVMA) Source: https://docs.rs/framehop/0.16.0/src/framehop/code_address.rs.html Retrieves the raw virtual memory address (AVMA) from a FrameAddress. For ReturnAddress, it converts the NonZeroU64 to u64. ```rust pub fn address(self) -> u64 { match self { FrameAddress::InstructionPointer(address) => address, FrameAddress::ReturnAddress(address) => address.into(), } } ``` -------------------------------- ### UnwinderAarch64 Methods Source: https://docs.rs/framehop/0.16.0/src/framehop/aarch64/unwinder.rs.html Provides methods for creating, cloning, and managing the Aarch64 unwinder, including adding and removing modules, and retrieving the maximum known code address. ```APIDOC impl Default for UnwinderAarch64 fn default() -> Self { Self::new() } impl Clone for UnwinderAarch64 fn clone(&self) -> Self { Self(self.0.clone()) } impl UnwinderAarch64 { /// Create an unwinder for a process. pub fn new() -> Self { Self(UnwinderInternal::new()) } } ``` -------------------------------- ### Get CacheX86_64 statistics Source: https://docs.rs/framehop/0.16.0/src/framehop/x86_64/cache.rs.html Retrieves the cache usage statistics for the `CacheX86_64`. This method accesses the underlying rule cache's statistics. ```rust /// Returns a snapshot of the cache usage statistics. pub fn stats(&self) -> CacheStats { self.0.rule_cache.stats() } } ``` -------------------------------- ### Get Unwind Rule from Sequence Source: https://docs.rs/framehop/0.16.0/framehop/x86_64/enum.UnwindRuleX86_64.html Attempts to construct an UnwindRuleX86_64 from an iterator of operations. Returns None if the sequence cannot be represented by a single rule. ```rust pub fn for_sequence_of_offset_or_pop(iter: I) -> Option where I: Iterator, T: Into, ``` -------------------------------- ### Unwinding with PE Unwind Info Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Handles unwinding for PE (Portable Executable) binaries using unwind information from `.pdata`, `.rdata`, and `.xdata` sections. ```rust ModuleUnwindDataInternal::PeUnwindInfo { pdata, rdata, xdata, text, } => ::unwind_frame( crate::pe::PeSections { pdata, rdata: rdata.as_ref(), xdata: xdata.as_ref(), text: text.as_ref(), }, rel_lookup_address, regs, is_first_frame, read_stack, )?, ``` -------------------------------- ### Get total cache lookups Source: https://docs.rs/framehop/0.16.0/framehop/struct.CacheStats.html Calculates the sum of all cache hits and misses. This represents the total number of times the cache was consulted. ```rust pub fn total(&self) -> u64 ``` -------------------------------- ### CacheX86_64::new Source: https://docs.rs/framehop/0.16.0/framehop/x86_64/struct.CacheX86_64.html Creates a new instance of CacheX86_64 with the default allocation policy (MayAllocateDuringUnwind). ```APIDOC ## CacheX86_64::new() ### Description Creates a new cache for x86_64 unwinding. ### Method `new()` ### Returns - `Self`: A new instance of `CacheX86_64`. ``` -------------------------------- ### From Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.PtrAuthMask.html Enables conversion from one type to another. ```APIDOC ## fn from(t: T) -> T Returns the argument unchanged. ``` -------------------------------- ### UnwindIterator Struct Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html The UnwindIterator provides a way to iterate through the stack frames of a process, starting from an initial program counter and register state. ```APIDOC ## UnwindIterator Struct ### Description An iterator for unwinding the entire stack, starting from the initial register values. The first yielded frame is the instruction pointer, and subsequent addresses are return addresses. This iterator attempts to detect if stack unwinding completed successfully or was truncated. ### Lifetimes - `'u`: The lifetime of the `Unwinder`. - `'c`: The lifetime of the unwinder cache. - `'r`: The lifetime of the exclusive access to the `read_stack` callback. ### Fields - `unwinder`: A reference to the `Unwinder` implementation being used. - `state`: The current state of the `UnwindIterator`. - `regs`: The unwind registers for the current frame. - `cache`: A mutable reference to the unwind cache. - `read_stack`: A mutable reference to the closure used for reading stack memory. ``` -------------------------------- ### Create FrameAddress from Return Address Source: https://docs.rs/framehop/0.16.0/framehop/enum.FrameAddress.html Attempts to create a FrameAddress::ReturnAddress variant from a 64-bit unsigned integer. Returns None if the provided address is zero. ```rust pub fn from_return_address(return_address: u64) -> Option ``` -------------------------------- ### Get Maximum Known Code Address Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Returns the end address of the last module in the unwinder's list, or 0 if no modules are present. ```rust pub fn max_known_code_address(&self) -> u64 { self.modules.last().map_or(0, |m| m.avma_range.end) } ``` -------------------------------- ### Create FrameAddress::ReturnAddress Source: https://docs.rs/framehop/0.16.0/src/framehop/code_address.rs.html Creates a FrameAddress::ReturnAddress from a u64 value. Returns None if the provided address is zero, as NonZeroU64 cannot represent zero. ```rust pub fn from_return_address(return_address: u64) -> Option { Some(FrameAddress::ReturnAddress(NonZeroU64::new( return_address, )?)) } ``` -------------------------------- ### Get Owned Version Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwindRegsAarch64.html Creates owned data from borrowed data, usually by cloning. The `Owned` type alias specifies the owned type. ```rust type Owned = T ``` ```rust fn to_owned(&self) -> T ``` -------------------------------- ### Clone to Uninitialized Memory (Nightly) Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwindRegsAarch64.html This is a nightly-only experimental API. It performs copy-assignment from self to the provided uninitialized memory destination. ```rust unsafe fn clone_to_uninit(&self, dest: *mut u8) ``` -------------------------------- ### Get Return Address from Stack - x86_64 Source: https://docs.rs/framehop/0.16.0/src/framehop/x86_64/pe.rs.html Reads the return address from the stack at the current RSP and increments RSP. This is a fallback for uncacheable unwind results. ```rust let rsp = regs.get(Reg::RSP); let ra = read_stack_err(read_stack, rsp)?; regs.set(Reg::RSP, rsp + 8); Ok(UnwindResult::Uncacheable(ra)) ``` -------------------------------- ### Module Name Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Returns the name of the module. ```APIDOC ## Module::name ### Description Returns the name of the module. ### Method `pub fn name(&self) -> &str` ### Returns - `&str` - The name of the module. ``` -------------------------------- ### pub fn for_sequence_of_offset_or_pop Source: https://docs.rs/framehop/0.16.0/framehop/x86_64/enum.UnwindRuleX86_64.html Attempts to construct an UnwindRuleX86_64 from a sequence of operations. ```APIDOC ## impl UnwindRuleX86_64 ### pub fn for_sequence_of_offset_or_pop(iter: I) -> Option **Description**: Get the rule which represents the given operations, if possible. **Parameters**: * `iter`: An iterator yielding items that can be converted into `OffsetOrPop`. ``` -------------------------------- ### UnwinderInternal::remove_module Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Removes a module from the unwinder's list based on the starting address of its range. If the module is found, the module generation counter is updated. ```APIDOC ## UnwinderInternal::remove_module ### Description Removes a module from the unwinder's list based on the starting address of its range. If the module is found, the module generation counter is updated. ### Signature ```rust pub fn remove_module(&mut self, module_address_range_start: u64) ``` ### Parameters - **module_address_range_start** (`u64`): The starting address of the module's range to identify it for removal. ``` -------------------------------- ### Into Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.PtrAuthMask.html Enables conversion into another type, leveraging the `From` trait. ```APIDOC ## fn into(self) -> U Calls `U::from(self)`. ``` -------------------------------- ### UnwindRegsX86_64 Struct and Methods Source: https://docs.rs/framehop/0.16.0/src/framehop/x86_64/unwindregs.rs.html Provides the definition for UnwindRegsX86_64, a structure to hold register state for x86_64 unwinding, and its associated methods for initialization, getting, and setting registers. ```APIDOC ## Struct: UnwindRegsX86_64 ### Description Represents the register state for x86_64 architecture during stack unwinding. It stores the instruction pointer (IP) and an array of 16 general-purpose registers. ### Fields - `ip`: `u64` - The instruction pointer. - `regs`: `[u64; 16]` - An array holding the 16 general-purpose registers. ## Enum: Reg ### Description An enumeration representing the 16 general-purpose registers available on the x86_64 architecture. ### Variants - `RAX`, `RDX`, `RCX`, `RBX`, `RSI`, `RDI`, `RBP`, `RSP`, `R8`, `R9`, `R10`, `R11`, `R12`, `R13`, `R14`, `R15` ## Methods for UnwindRegsX86_64 ### `new(ip: u64, sp: u64, bp: u64) -> Self` #### Description Constructs a new `UnwindRegsX86_64` instance, initializing the instruction pointer, stack pointer (RSP), and base pointer (RBP). #### Parameters - `ip` (u64): The initial value for the instruction pointer. - `sp` (u64): The initial value for the stack pointer (RSP). - `bp` (u64): The initial value for the base pointer (RBP). ### `get(&self, reg: Reg) -> u64` #### Description Retrieves the value of a specified register. #### Parameters - `reg` (Reg): The register to retrieve the value from. #### Returns - `u64`: The value of the specified register. ### `set(&mut self, reg: Reg, value: u64)` #### Description Sets the value of a specified register. #### Parameters - `reg` (Reg): The register to set. - `value` (u64): The new value for the register. ### `ip(&self) -> u64` #### Description Gets the current value of the instruction pointer. #### Returns - `u64`: The instruction pointer value. ### `set_ip(&mut self, ip: u64)` #### Description Sets the instruction pointer to a new value. #### Parameters - `ip` (u64): The new instruction pointer value. ### `sp(&self) -> u64` #### Description Gets the current value of the stack pointer (RSP). #### Returns - `u64`: The stack pointer value. ### `set_sp(&mut self, sp: u64)` #### Description Sets the stack pointer (RSP) to a new value. #### Parameters - `sp` (u64): The new stack pointer value. ### `bp(&self) -> u64` #### Description Gets the current value of the base pointer (RBP). #### Returns - `u64`: The base pointer value. ### `set_bp(&mut self, bp: u64)` #### Description Sets the base pointer (RBP) to a new value. #### Parameters - `bp` (u64): The new base pointer value. ## `impl Debug for UnwindRegsX86_64` ### Description Implements the `Debug` trait for `UnwindRegsX86_64`, providing a formatted string representation of the register state, with values displayed in hexadecimal. ``` -------------------------------- ### CloneToUninit Trait Implementation (Nightly) Source: https://docs.rs/framehop/0.16.0/framehop/enum.FrameAddress.html An experimental nightly-only API for performing copy-assignment from a cloned value to uninitialized memory. ```rust unsafe fn clone_to_uninit(&self, dest: *mut u8)> ``` -------------------------------- ### Get Chained Unwind Info - x86_64 Source: https://docs.rs/framehop/0.16.0/src/framehop/x86_64/pe.rs.html Collects chained unwind information by following links from the initial unwind info. It resolves errors during the collection process. ```rust let chained_info = core::iter::successors(Some(Ok(unwind_info)), |info| { let Ok(info) = info else { return None; }; if let Some(UnwindInfoTrailer::ChainedUnwindInfo { chained }) = info.trailer() { let unwind_info_address = chained.unwind_info_address.get(); Some( sections .unwind_info_memory_at_rva(unwind_info_address) .and_then(|data| { UnwindInfo::parse(data).ok_or(PeUnwinderError::UnwindInfoParseError) }), ) } else { None } }) .collect::, _>>()?; ``` -------------------------------- ### Clone Implementation for Module Source: https://docs.rs/framehop/0.16.0/framehop/struct.Module.html Provides functionality to create a duplicate of a Module instance. This is useful for creating independent copies of module information. ```rust fn clone(&self) -> Self ``` -------------------------------- ### Get Maximum Known Code Address Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwinderAarch64.html Returns the highest known code address in the process based on loaded modules. Returns 0 if no modules are loaded. ```rust fn max_known_code_address(&self) -> u64 ``` -------------------------------- ### TryFrom Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.PtrAuthMask.html Enables fallible conversion from one type to another. ```APIDOC ## type Error = Infallible The type returned in the event of a conversion error. ``` ```APIDOC ## fn try_from(value: U) -> Result>::Error> Performs the conversion. ``` -------------------------------- ### Get total cache misses Source: https://docs.rs/framehop/0.16.0/framehop/struct.CacheStats.html Calculates the sum of all types of cache misses. This represents the total number of times the cache failed to provide a valid entry. ```rust pub fn misses(&self) -> u64 ``` -------------------------------- ### Create new CacheX86_64 with MayAllocateDuringUnwind Source: https://docs.rs/framehop/0.16.0/src/framehop/x86_64/cache.rs.html Creates a new instance of `CacheX86_64` specifically for `MayAllocateDuringUnwind` policy. ```rust impl CacheX86_64 { /// Create a new cache. pub fn new() -> Self { Self(Cache::new()) } } ``` -------------------------------- ### CacheStats Helper Methods Source: https://docs.rs/framehop/0.16.0/src/framehop/rule_cache.rs.html Provides utility methods for CacheStats, such as calculating total lookups, hits, and misses. ```rust impl CacheStats { /// Create a new instance. pub fn new() -> Self { Default::default() } /// The number of total lookups. pub fn total(&self) -> u64 { self.hits() + self.misses() } /// The number of total hits. pub fn hits(&self) -> u64 { self.hit_count } /// The number of total misses. pub fn misses(&self) -> u64 { self.miss_empty_slot_count + self.miss_wrong_modules_count + self.miss_wrong_address_count } } ``` -------------------------------- ### Remove Module from Unwinder Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Removes a module from the unwinder's list based on its start address. Updates the modules generation counter if the module is found and removed. ```rust pub fn remove_module(&mut self, module_address_range_start: u64) { if let Ok(index) = self .modules .binary_search_by_key(&module_address_range_start, |module| { module.avma_range.start }) { self.modules.remove(index); self.modules_generation = next_global_modules_generation(); }; } ``` -------------------------------- ### Add Module to Unwinder Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Inserts a new module into the unwinder's sorted list of modules based on its start address. Updates the modules generation counter. ```rust pub fn add_module(&mut self, module: Module) { let insertion_index = match self .modules .binary_search_by_key(&module.avma_range.start, |module| module.avma_range.start) { Ok(i) => i, // unexpected Err(i) => i, }; self.modules.insert(insertion_index, module); self.modules_generation = next_global_modules_generation(); } ``` -------------------------------- ### ExplicitModuleSectionInfo Methods Source: https://docs.rs/framehop/0.16.0/framehop/struct.ExplicitModuleSectionInfo.html Methods for retrieving information about sections and segments within a module. ```APIDOC ## fn base_svma(&self) -> u64 ### Description Return the base address stated in the module. ### Method GET (conceptual) ### Endpoint N/A (SDK method) ### Parameters None ### Response - **base_svma** (u64) - The base memory address of the module. ``` ```APIDOC ## fn section_svma_range(&mut self, name: &[u8]) -> Option> ### Description Get the given section’s memory range, as stated in the module. ### Method GET (conceptual) ### Endpoint N/A (SDK method) ### Parameters - **name** (&[u8]) - Required - The name of the section. ### Response - **svma_range** (Option>) - The memory range of the section, if found. ``` ```APIDOC ## fn section_data(&mut self, name: &[u8]) -> Option ### Description Get the given section’s data. This will only be called once per section. ### Method GET (conceptual) ### Endpoint N/A (SDK method) ### Parameters - **name** (&[u8]) - Required - The name of the section. ### Response - **data** (Option) - The data of the section, if found. ``` ```APIDOC ## fn segment_svma_range(&mut self, name: &[u8]) -> Option> ### Description Get the given segment’s memory range, as stated in the module. ### Method GET (conceptual) ### Endpoint N/A (SDK method) ### Parameters - **name** (&[u8]) - Required - The name of the segment. ### Response - **svma_range** (Option>) - The memory range of the segment, if found. ``` ```APIDOC ## fn segment_data(&mut self, name: &[u8]) -> Option ### Description Get the given segment’s data. This will only be called once per segment. ### Method GET (conceptual) ### Endpoint N/A (SDK method) ### Parameters - **name** (&[u8]) - Required - The name of the segment. ### Response - **data** (Option) - The data of the segment, if found. ``` -------------------------------- ### Get Segment SVMA Range by Name Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Returns the SVMA (Static Virtual Memory Address) range for a given segment name. Currently only supports the '__TEXT' segment. ```rust fn segment_svma_range(&mut self, name: &[u8]) -> Option> { match name { b"__TEXT" => self.text_segment_svma.clone(), _ => None, } } ``` -------------------------------- ### Create new CacheX86_64 with generic AllocationPolicy Source: https://docs.rs/framehop/0.16.0/src/framehop/x86_64/cache.rs.html Creates a new instance of `CacheX86_64` with a generic `AllocationPolicy`. This is useful when a specific allocation policy is not required at compile time. ```rust impl CacheX86_64

{ /// Create a new cache. pub fn new_in() -> Self { Self(Cache::new()) } ``` -------------------------------- ### new() - CacheX86_64 for MayAllocateDuringUnwind Source: https://docs.rs/framehop/0.16.0/framehop/type.CacheNative.html Creates a new instance of CacheX86_64 specifically for the MayAllocateDuringUnwind policy. ```APIDOC ### impl CacheX86_64 #### pub fn new() -> Self Create a new cache. ``` -------------------------------- ### UnwinderAarch64 implementation of Unwinder trait Source: https://docs.rs/framehop/0.16.0/src/framehop/aarch64/unwinder.rs.html Implements the `Unwinder` trait for `UnwinderAarch64`. This includes methods for adding/removing modules, getting the max code address, and performing the actual frame unwinding. ```rust impl, P: AllocationPolicy> Unwinder for UnwinderAarch64 { type UnwindRegs = UnwindRegsAarch64; type Cache = CacheAarch64

; type Module = Module; fn add_module(&mut self, module: Module) { self.0.add_module(module); } fn remove_module(&mut self, module_address_range_start: u64) { self.0.remove_module(module_address_range_start); } fn max_known_code_address(&self) -> u64 { self.0.max_known_code_address() } fn unwind_frame( &self, address: FrameAddress, regs: &mut UnwindRegsAarch64, cache: &mut CacheAarch64

, read_stack: &mut F, ) -> Result, Error> where F: FnMut(u64) -> Result, { self.0.unwind_frame(address, regs, &mut cache.0, read_stack) } } ``` -------------------------------- ### Try Convert Into Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/struct.UnwindRegsAarch64.html Attempts to convert the value into another type using `TryFrom`. Returns a `Result` which is `Ok` on success or `Err` if the conversion fails. ```rust type Error = >::Error ``` ```rust fn try_into(self) -> Result>::Error> ``` -------------------------------- ### Unwinder Trait - remove_module Method Source: https://docs.rs/framehop/0.16.0/framehop/trait.Unwinder.html Removes a previously added module from the unwinder, keyed by its starting address. This call is ignored if no matching module is found and should be used when a module is unloaded. ```rust fn remove_module(&mut self, module_avma_range_start: u64); ``` -------------------------------- ### TryInto for T Implementation Source: https://docs.rs/framehop/0.16.0/framehop/aarch64/enum.UnwindRuleAarch64.html Provides the ability to attempt a conversion from type `T` into type `U`, with a potential error. ```APIDOC ## impl TryInto for T ### Associated Type `type Error = >::Error` The type returned in the event of a conversion error. ### Method `fn try_into(self) -> Result>::Error>` Performs the conversion. ``` -------------------------------- ### UnwinderInternal::unwind_frame Source: https://docs.rs/framehop/0.16.0/src/framehop/unwinder.rs.html Initiates the unwinding process for a single call frame starting from the given address. This method utilizes caching and registered unwinding rules to determine the caller's frame. ```APIDOC ## UnwinderInternal::unwind_frame ### Description Initiates the unwinding process for a single call frame starting from the given address. This method utilizes caching and registered unwinding rules to determine the caller's frame. It requires a mutable reference to the unwinder's registers, a cache for unwind rules, and a function to read stack memory. ### Signature ```rust pub fn unwind_frame( &self, address: FrameAddress, regs: &mut A::UnwindRegs, cache: &mut Cache, read_stack: &mut F, ) -> Result, Error> where F: FnMut(u64) -> Result, ``` ### Parameters - **address** (`FrameAddress`): The address of the current frame to start unwinding from. - **regs** (`&mut A::UnwindRegs`): Mutable reference to the unwinder's registers. - **cache** (`&mut Cache`): Mutable reference to the cache for unwind rules. - **read_stack** (`&mut F`): A mutable closure or function pointer used to read data from the stack. It takes a stack address (`u64`) and returns a `Result`. ### Returns A `Result` containing `Option` which represents the return address of the caller frame, or `Error` if an issue occurred during unwinding. ``` -------------------------------- ### TryInto for T Source: https://docs.rs/framehop/0.16.0/framehop/enum.FrameAddress.html Provides a way to attempt a conversion into another type, returning a Result. ```APIDOC ## impl TryInto for T ### Description Provides a way to attempt a conversion into another type, returning a Result. #### type Error = >::Error ### Description The type returned in the event of a conversion error. #### fn try_into(self) -> Result>::Error> ### Description Performs the conversion. ``` -------------------------------- ### Get Address for Lookup Source: https://docs.rs/framehop/0.16.0/src/framehop/code_address.rs.html Determines the appropriate address for lookup, adjusting return addresses by subtracting one byte. This is crucial for correctly identifying call instructions when searching for unwind or debug information. ```rust pub fn address_for_lookup(self) -> u64 { match self { FrameAddress::InstructionPointer(address) => address, FrameAddress::ReturnAddress(address) => u64::from(address) - 1, } } ``` -------------------------------- ### Get Address for Lookup Source: https://docs.rs/framehop/0.16.0/framehop/enum.FrameAddress.html Provides the appropriate address for lookups, adjusting return addresses by subtracting one byte to point within the call instruction. This is useful for retrieving unwind or debug information. ```rust pub fn address_for_lookup(self) -> u64> ``` -------------------------------- ### Basic Unwind Rule Execution Test Source: https://docs.rs/framehop/0.16.0/src/framehop/x86_64/unwind_rule.rs.html Tests the execution of different unwind rules, including OffsetSp, UseFramePointer, and JustReturn, with assertions for the resulting register values and return addresses. ```rust let stack = [ 1, 2, 0x100300, 4, 0x40, 0x100200, 5, 6, 0x70, 0x100100, 7, 8, 9, 10, 0x0, 0x0, ]; let mut read_stack = |addr| Ok(stack[(addr / 8) as usize]); let mut regs = UnwindRegsX86_64::new(0x100400, 0x10, 0x20); let res = UnwindRuleX86_64::OffsetSp { sp_offset_by_8: 1 }.exec(true, &mut regs, &mut read_stack); assert_eq!(res, Ok(Some(0x100300))); assert_eq!(regs.ip(), 0x100300); assert_eq!(regs.sp(), 0x18); assert_eq!(regs.bp(), 0x20); let res = UnwindRuleX86_64::UseFramePointer.exec(true, &mut regs, &mut read_stack); assert_eq!(res, Ok(Some(0x100200))); assert_eq!(regs.ip(), 0x100200); assert_eq!(regs.sp(), 0x30); assert_eq!(regs.bp(), 0x40); let res = UnwindRuleX86_64::UseFramePointer.exec(false, &mut regs, &mut read_stack); assert_eq!(res, Ok(Some(0x100100))); assert_eq!(regs.ip(), 0x100100); assert_eq!(regs.sp(), 0x50); assert_eq!(regs.bp(), 0x70); let res = UnwindRuleX86_64::UseFramePointer.exec(false, &mut regs, &mut read_stack); assert_eq!(res, Ok(None)) ``` -------------------------------- ### UnwinderAarch64 new function Source: https://docs.rs/framehop/0.16.0/src/framehop/aarch64/unwinder.rs.html Creates a new instance of `UnwinderAarch64` for a process. This is the primary way to initialize the unwinder. ```rust pub fn new() -> Self { Self(UnwinderInternal::new()) } ```