Struct DebugInfo

pub struct DebugInfo { /* private fields */ }

Available on crate feature debug only.

Debug information which is parsed from DWARF debugging information.

Implementations

impl DebugInfo

pub fn from_file<P: AsRef<Path>>(path: P) -> Result<DebugInfo, DebugError>

Read debug info directly from a ELF file.

pub fn from_raw(data: &[u8]) -> Result<Self, DebugError>

Parse debug information directly from a buffer containing an ELF file.

pub fn get_source_location(&self, address: u64) -> Option<SourceLocation>

Try get the SourceLocation for a given address.

pub fn create_static_scope_cache(&self) -> VariableCache

We do not actually resolve the children of [VariableName::StaticScope] automatically, and only create the necessary header in the VariableCache. This allows us to resolve the [VariableName::StaticScope] on demand/lazily, when a user requests it from the debug client. This saves a lot of overhead when a user only wants to see the [VariableName::LocalScope] or [VariableName::Registers] while stepping through code (the most common use cases)

pub fn cache_deferred_variables( &self, cache: &mut VariableCache, memory: &mut dyn MemoryInterface, parent_variable: &mut Variable, frame_info: StackFrameInfo<'_>, ) -> Result<(), DebugError>

This effects the on-demand expansion of lazy/deferred load of all the ‘child’ Variables for a given ‘parent’.

pub fn unwind( &self, core: &mut impl MemoryInterface, initial_registers: DebugRegisters, exception_handler: &dyn ExceptionInterface, instruction_set: Option<InstructionSet>, ) -> Result<Vec<StackFrame>, Error>

Performs the logical unwind of the stack and returns a Vec<StackFrame>

• The first ‘StackFrame’ represents the frame at the current PC (program counter), and …
• Each subsequent StackFrame represents the previous or calling StackFrame in the call stack.
• The majority of the work happens in the 'unwind: while loop, where each iteration will create a StackFrame where possible, and update the unwind_registers to prepare for the next iteration.

The unwind loop will continue until we meet one of the following conditions:

• We can no longer unwind a valid PC value to be used for the next frame.
• We encounter a LR register value of 0x0 or 0xFFFFFFFF (Arm ‘Reset’ value for that register).
• We can not intelligently calculate a valid LR register value from the other registers, or the gimli::RegisterRule result is a value of 0x0. Note: DWARF 6.4.4 - CIE defines the return register address used in the gimli::RegisterRule tables for unwind operations. Theoretically, if we encounter a function that has Undefined gimli::RegisterRule for the return register address, it means we have reached the bottom of the stack OR the function is a ‘no return’ type of function. I have found actual examples (e.g. local functions) where we get Undefined for register rule when we cannot apply this logic. Example 1: local functions in main.rs will have LR rule as Undefined. Example 2: main()-> ! that is called from a trampoline will have a valid LR rule.
• Similarly, certain error conditions encountered in StackFrameIterator will also break out of the unwind loop.

Note: In addition to populating the StackFrames, this function will also populate the DebugInfo::VariableCache with Variables for available Registers as well as static and function variables. TODO: Separate logic for stackframe creation and cache population

pub fn get_breakpoint_location( &self, path: TypedPath<'_>, line: u64, column: Option<u64>, ) -> Result<VerifiedBreakpoint, DebugError>

Find the program counter where a breakpoint should be set, given a source file, a line and optionally a column.