vex-libunwind

Idiomatic Rust bindings for LLVM libunwind on VEX V5 robots

Install

cargo add vex-libunwind

Usage

To unwind from the current execution point, also known as "local" unwinding, capture the current CPU state with UnwindContext and then step through each stack frame with an UnwindCursor.

let context = UnwindContext::new().unwrap();
let mut cursor = UnwindCursor::new(&context);

loop {
    // Print instruction pointer (i.e. "program counter")
    println!("{:?}", cursor.register(registers::UNW_REG_IP));

    if !cursor.step().unwrap() {
        // End of stack reached
        break;
    }
}

Prerequisites

Libunwind will not find stack frames unless you add unwind tables to your program and show it where to find them.

Add unwind tables by updating your target file or using the -Cforce-unwind-tables=on rust flag:

{
    ...,
    "default-uwtable": true
}

Then update your target file to include the unwind tables and the symbols libunwind uses to find them:

SECTIONS {
    /* ... */

    .eh_frame : {
        __eh_frame_start = .;
       *(.eh_frame)
        __eh_frame_end = .;
    } > RAM

    .eh_framehdr : {
       __eh_frame_hdr_start = .;
       *(.eh_framehdr)
       __eh_frame_hdr_end = .;
    } > RAM

    .ARM.exidx : {
        __exidx_start = .;
        *(.ARM.exidx*)
        *(.gnu.linkonce.armexidix.*.*)
        __exidx_end = .;
    } > RAM

    /* ... */
}

Further Reading

Documentation for LLVM-flavored libunwind: https://github.com/llvm/llvm-project/blob/main/libunwind/docs/index.rst

Documentation for similar but distinct libunwind/libunwind project:

• https://www.nongnu.org/libunwind/man/libunwind(3).html
• https://github.com/libunwind/libunwind

lib.rs:

Bindings to the low-level unw_* LLVM libunwind APIs which are an interface defined by the HP libunwind project.