diff --git a/README.md b/README.md index a270092..3743532 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,37 @@ # vex-libunwind -> Idiomatic Rust bindings for libunwind on VEX V5 robots +> Idiomatic Rust bindings for LLVM libunwind on VEX V5 robots + +## Install + +``` +cargo add --git https://github.com/vexide/vex-libunwind.git +``` + +## 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`. + +```rs +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; + } +} +``` + +### Further Reading + +Documentation for LLVM-flavored libunwind: + +Documentation for similar but distinct libunwind/libunwind project: + +- +- diff --git a/packages/vex-libunwind-sys/Cargo.toml b/packages/vex-libunwind-sys/Cargo.toml index decdf16..c8a75cd 100644 --- a/packages/vex-libunwind-sys/Cargo.toml +++ b/packages/vex-libunwind-sys/Cargo.toml @@ -3,7 +3,7 @@ name = "vex-libunwind-sys" version = "0.1.0" edition = "2021" license = "MIT" -description = "FFI bindings to libunwind for VEX V5 robots" +description = "FFI bindings to LLVM libunwind for VEX V5 robots" keywords = ["vex", "v5", "unwind", "libunwind"] categories = [ "external-ffi-bindings", diff --git a/packages/vex-libunwind/Cargo.toml b/packages/vex-libunwind/Cargo.toml index 22d9449..0288d0d 100644 --- a/packages/vex-libunwind/Cargo.toml +++ b/packages/vex-libunwind/Cargo.toml @@ -3,7 +3,7 @@ name = "vex-libunwind" version = "0.1.0" edition = "2021" license = "MIT" -description = "Idiomatic Rust bindings for libunwind on VEX V5 robots" +description = "Idiomatic Rust bindings for LLVM libunwind on VEX V5 robots" keywords = ["vex", "v5", "unwind", "libunwind", "backtrace"] categories = ["api-bindings", "embedded", "science::robotics", "no-std"] authors = [ diff --git a/packages/vex-libunwind/src/lib.rs b/packages/vex-libunwind/src/lib.rs index 3f200ce..33848c2 100644 --- a/packages/vex-libunwind/src/lib.rs +++ b/packages/vex-libunwind/src/lib.rs @@ -1,13 +1,16 @@ -//! Idiomatic Rust bindings for `libunwind` on VEX V5 robots +//! Idiomatic Rust bindings for LLVM `libunwind` on VEX V5 robots //! //! ```no_run //! # use vex_libunwind::*; //! let context = UnwindContext::new().unwrap(); -//! let mut cursor = UnwindCursor::new(); +//! 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; //! } //! }