mikros/unwinding
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Describe baremetal

Browse Source
This commit is contained in:
Gary Guo 2021-08-26 22:48:44 +01:00
parent c970b0d1fb
commit 10dccf7dc4
1 changed files with 17 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
README.md
View File

@ -16,6 +16,7 @@ the unwinder:
| unwinder | Yes | The primary feature gate to enable the unwinder |
| fde-phdr | Yes | Use `dl_iterator_phdr` to retrieve frame unwind table. Depends on libc. |
| fde-registry | Yes | Provide `__register__frame` and others for dynamic registration |
| 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. |
| dwarf-expr | Yes | Enable the dwarf expression evaluator. Usually not necessary for Rust |
| hide-trace | Yes | Hide unwinder frames in back trace |
@ -34,7 +35,7 @@ extern crate unwind;
## Personality and other utilities
The library also provides Rust personality function. This can be handy if you are working on a `#![no_std]` binary/staticlib/cdylib and you still want unwinding support.
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 |
@ -47,6 +48,21 @@ Here are the feature gates related:
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 [`example/`](example).
## 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
```ld
/* 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 `unwind::panic::begin_panic` to initiate an unwing and catch using `unwind::panic::catch_unwind`, as if you have a `std`.
If you have your own version of `thread_local` and `println!` working, you can port [`panic_handler.rs`](src/panic_handler.rs) for double-panic protection and stack traces!
## TODO
* A better project name!