Struct gimli::read::UnwindTable

pub struct UnwindTable<'a, 'ctx, R: Reader> { /* private fields */ }

The UnwindTable iteratively evaluates a FrameDescriptionEntry’s CallFrameInstruction program, yielding the each row one at a time.

6.4.1 Structure of Call Frame Information

DWARF supports virtual unwinding by defining an architecture independent basis for recording how procedures save and restore registers during their lifetimes. This basis must be augmented on some machines with specific information that is defined by an architecture specific ABI authoring committee, a hardware vendor, or a compiler producer. The body defining a specific augmentation is referred to below as the “augmenter.”

Abstractly, this mechanism describes a very large table that has the following structure:

LOC	CFA	R0	R1	...	RN
L0
L1
...
LN

The first column indicates an address for every location that contains code in a program. (In shared objects, this is an object-relative offset.) The remaining columns contain virtual unwinding rules that are associated with the indicated location.

The CFA column defines the rule which computes the Canonical Frame Address value; it may be either a register and a signed offset that are added together, or a DWARF expression that is evaluated.

The remaining columns are labeled by register number. This includes some registers that have special designation on some architectures such as the PC and the stack pointer register. (The actual mapping of registers for a particular architecture is defined by the augmenter.) The register columns contain rules that describe whether a given register has been saved and the rule to find the value for the register in the previous frame.

…

This table would be extremely large if actually constructed as described. Most of the entries at any point in the table are identical to the ones above them. The whole table can be represented quite compactly by recording just the differences starting at the beginning address of each subroutine in the program.

Implementations

impl<'a, 'ctx, R: Reader> UnwindTable<'a, 'ctx, R>

Signal Safe Methods

These methods are guaranteed not to allocate, acquire locks, or perform any other signal-unsafe operations.

pub fn new<Section: UnwindSection<R>>(
    section: &'a Section,
    bases: &'a BaseAddresses,
    ctx: &'ctx mut UninitializedUnwindContext<R>,
    fde: &FrameDescriptionEntry<R>
) -> Result<UnwindTable<'a, 'ctx, R>>

Construct a new UnwindTable for the given FrameDescriptionEntry’s CFI unwinding program.

pub fn next_row(&mut self) -> Result<Option<&UnwindTableRow<R>>>

Evaluate call frame instructions until the next row of the table is completed, and return it.

Unfortunately, this cannot be used with FallibleIterator because of the restricted lifetime of the yielded item.

pub fn into_current_row(self) -> Option<&'ctx UnwindTableRow<R>>

Returns the current row with the lifetime of the context.

Trait Implementations

impl<'a, 'ctx, R: Debug + Reader> Debug for UnwindTable<'a, 'ctx, R>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.