11 releases
| 0.2.3 | Oct 13, 2024 |
|---|---|
| 0.2.2 | Jun 25, 2024 |
| 0.2.1 | Oct 28, 2023 |
| 0.1.7 | May 7, 2023 |
| 0.1.3 | Oct 26, 2021 |
#84 in Rust patterns
67,451 downloads per month
Used in 14 crates
(5 directly)
105KB
3K
SLoC
Unwinding library in Rust and for Rust
This library serves two purposes:
- Provide a pure Rust alternative to libgcc_eh or libunwind.
- Provide easier unwinding support for
#![no_std]targets.
Currently supports x86_64, x86, RV64, RV32 and AArch64.
Unwinder
The unwinder can be enabled with unwinder feature. Here are the feature gates related to the unwinder:
| Feature | Default | Description |
|---|---|---|
| unwinder | Yes | The primary feature gate to enable the unwinder |
| fde-phdr-dl | Yes | Use dl_iterator_phdr to retrieve frame unwind table. Depends on libc. |
| fde-phdr-aux | No | Use ELF auxiliary vector to retrieve frame unwind table. Depends on libc. |
| fde-registry | Yes | Provide __register__frame and others for dynamic registration. Requires either libc or spin for a mutex implementation. |
| fde-gnu-eh-frame-hdr | No | Use __executable_start, __etext and __GNU_EH_FRAME_HDR to retrieve frame unwind table. The former two symbols are usually provided by the linker, while the last one is provided if GNU LD is used and --eh-frame-hdr option is enabled. |
| fde-static | No | Use __executable_start, __etext and __eh_frame to retrieve frame unwind table. The former two symbols are usually provided by the linker, while the last one would need to be provided by the user via linker script. |
| fde-custom | No | Allow the program to provide a custom means of retrieving frame unwind table at runtime via the set_custom_eh_frame_finder function. |
| dwarf-expr | Yes | Enable the dwarf expression evaluator. Usually not necessary for Rust |
| hide-trace | Yes | Hide unwinder frames in back trace |
If you want to use the unwinder for other Rust (C++, or any programs that utilize the unwinder), you can build the unwinding_dyn crate provided, and use LD_PRELOAD to replace the system unwinder with it.
cd cdylib
cargo build --release
# Test the unwinder using rustc. Why not :)
LD_PRELOAD=`../target/release/libunwinding_dyn.so` rustc +nightly -Ztreat-err-as-bug
If you want to link to the unwinder in a Rust binary, simply add
extern crate unwinding;
Personality and other utilities
The library also provides Rust personality function. This can work with the unwinder described above or with a different unwinder. This can be handy if you are working on a #![no_std] binary/staticlib/cdylib and you still want unwinding support.
Here are the feature gates related:
| Feature | Default | Description |
|---|---|---|
| personality | No | Provides #[lang = eh_personality] |
| No | Provides (e)?print(ln)?. This is really only here because panic handler needs to print things. Depends on libc. |
|
| panicking | No | Provides a generic begin_panic and catch_unwind. Only stack unwinding functionality is provided, memory allocation and panic handling is left to the user. |
| panic | No | Provides Rust begin_panic and catch_unwind. Only stack unwinding functionality is provided and no printing is done, because this feature does not depend on libc. |
| panic-handler | No | Provides #[panic_handler]. Provides similar behaviour on panic to std, with RUST_BACKTRACE support as well. Stack trace won't have symbols though. Depends on libc. |
| system-alloc | No | Provides a global allocator which calls malloc and friends. Provided for convience. |
If you are writing a #![no_std] program, simply enable personality, panic-handler and system-alloc in addition to the defaults, you instantly obtains the ability to do unwinding! An example is given in the example/ folder.
Baremetal
To use this library for baremetal projects, disable default features and enable unwinder, fde-static, personality, panic. dwarf-expr and hide-trace are optional. Modify the linker script by
/* Inserting these two lines */
. = ALIGN(8);
PROVIDE(__eh_frame = .);
/* before .eh_frame rule */
.eh_frame : { KEEP (*(.eh_frame)) *(.eh_frame.*) }
And that's it! After you ensured that the global allocator is functional, you can use unwinding::panic::begin_panic to initiate an unwing and catch using unwinding::panic::catch_unwind, as if you have a std.
If your linker supports --eh-frame-hdr you can also try to use fde-gnu-eh-frame-hdr instead of fde-static. GNU LD will provides a __GNU_EH_FRAME_HDR magic symbol so you don't have to provide __eh_frame through linker script.
If you have your own version of thread_local and println! working, you can port panic_handler.rs for double-panic protection and stack traces!
Dependencies
~1–1.5MB
~32K SLoC