diff options
| -rw-r--r-- | CHANGELOG | 4 | ||||
| -rw-r--r-- | Cargo.toml | 4 | ||||
| -rw-r--r-- | README.md | 4 | ||||
| -rw-r--r-- | src/lib.rs | 46 |
4 files changed, 51 insertions, 7 deletions
@@ -1,3 +1,7 @@ +## 1.0.3 + +* fix a few broken doc links, added example of yaxpeax-x86 usage through yaxpeax-arch traits + ## 1.0.2 * remove a stale line from README @@ -1,7 +1,7 @@ [package] name = "yaxpeax-x86" -version = "1.0.2" +version = "1.0.3" authors = [ "iximeow <me@iximeow.net>" ] license = "0BSD" repository = "http://git.iximeow.net/yaxpeax-x86/" @@ -10,7 +10,7 @@ readme = "README.md" edition = "2018" [dependencies] -yaxpeax-arch = { version = "0.2.0", default-features = false, features = [] } +yaxpeax-arch = { version = "0.2.2", default-features = false, features = [] } "num-traits" = { version = "0.2", default-features = false } "serde" = { version = "1.0", optional = true } "serde_json" = { version = "1.0", optional = true } @@ -5,7 +5,7 @@ x86 decoders implemented as part of the yaxpeax project, implementing traits provided by `yaxpeax-arch`. -Rust users of this library will either want to use the [quick and dirty APIs], or more generic decode interfaces from `yaxpeax-arch` - appropriate when mixing `yaxpeax-x86` usage with other `yaxpeax` decoders, such as `yaxpeax-arm`. examples of both styles are provided [in the documentation](https://docs.rs/yaxpeax-x86/). +Rust users of this library will either want to use the [quick and dirty APIs](https://docs.rs/yaxpeax-x86/latest/yaxpeax_x86/long_mode/struct.InstDecoder.html#method.decode_slice), or more [generic decode interfaces](https://docs.rs/yaxpeax-arch/latest/yaxpeax_arch/trait.Decoder.html#method.decode) from `yaxpeax-arch` - appropriate when mixing `yaxpeax-x86` usage with other `yaxpeax` decoders, such as `yaxpeax-arm`. examples of both styles are provided [in the documentation](https://docs.rs/yaxpeax-x86/). the `ffi/` directory provides a repackaging of `yaxpeax-x86` suitable for use by non-Rust callers, such as C or C++. see the `examples` directory for FFI usage of this library. @@ -17,7 +17,7 @@ the `ffi/` directory provides a repackaging of `yaxpeax-x86` suitable for use by * pretty small? ### `#[no_std]` -the decoders provided by `yaxpeax-x86` are designed to be usable in a `no_std` setting, and does so by default. to build `yaxpeax_x86` without `std`, add the parameter `default-features = false` to your `yaxpeax-x86` dependency; the [ffi packaging] of `yaxpeax_x86` does this and builds without the Rust standard library as well. serde can be enabled without `std`, but json serialization/deserialization [need some careful attention](https://serde.rs/no-std.html) in that mode. as well as the `colors` feature to render instructions with default (eg terminal-friendly) syntax highlighting. +the decoders provided by `yaxpeax-x86` are designed to be usable in a `no_std` setting, and does so by default. to build `yaxpeax_x86` without `std`, add the parameter `default-features = false` to your `yaxpeax-x86` dependency; the [ffi packaging](https://git.iximeow.net/yaxpeax-x86/tree/ffi) of `yaxpeax_x86` does this and builds without the Rust standard library as well. serde can be enabled without `std`, but json serialization/deserialization [need some careful attention](https://serde.rs/no-std.html) in that mode. as well as the `colors` feature to render instructions with default (eg terminal-friendly) syntax highlighting. ### instruction set extensions `yaxpeax-x86` decoders provide the option to specify what [instruction set extensions](http://git.iximeow.net/yaxpeax-x86/tree/src/long_mode/mod.rs#n1297) are eligible when decoding, to support decoding x86 instructions as understood by a particular microarchitecture. the default impls of decoders in `yaxpeax_x86` take an optimistsic approach to decoding and assumes all feature sets are available, as well as accepting both intel-specific and amd-specific quirks around undefined encodings. @@ -17,9 +17,9 @@ //! //! instructions, operands, registers, and generally all decoding structures, are in their mode's //! repsective submodule: -//! * `x86_64`/`amd64` decoding is under [`yaxpeax_x86::long_mode`] -//! * `x86_32`/`x86` decoding is under [`yaxpeax_x86::protected_mode`] -//! * `x86_16`/`8086` decoding is under [`yaxpeax_x86::real_mode`] +//! * `x86_64`/`amd64` decoding is under [`long_mode`] +//! * `x86_32`/`x86` decoding is under [`protected_mode`] +//! * `x86_16`/`8086` decoding is under [`real_mode`] //! //! all modes have equivalent data available in a decoded instruction. for example, all modes have //! library-friendly `Operand` and `RegSpec` types: @@ -48,6 +48,46 @@ //! assert_eq!("dword", mem_size.to_string()); //! ``` //! +//! `yaxpeax-x86` can also be used to decode instructions generically through the `yaxpeax-arch` +//! traits: +//! ``` +//! mod decoder { +//! use yaxpeax_arch::{Arch, AddressDisplay, Decoder, Reader, ReaderBuilder}; +//! +//! pub fn decode_stream< +//! 'data, +//! A: yaxpeax_arch::Arch, +//! U: ReaderBuilder<A::Address, A::Word>, +//! >(data: U) where +//! A::Instruction: std::fmt::Display, +//! { +//! let mut reader = ReaderBuilder::read_from(data); +//! let mut address: A::Address = reader.total_offset(); +//! +//! let decoder = A::Decoder::default(); +//! let mut decode_res = decoder.decode(&mut reader); +//! loop { +//! match decode_res { +//! Ok(ref inst) => { +//! println!("{}: {}", address.show(), inst); +//! decode_res = decoder.decode(&mut reader); +//! address = reader.total_offset(); +//! } +//! Err(e) => { +//! println!("{}: decode error: {}", address.show(), e); +//! break; +//! } +//! } +//! } +//! } +//! } +//! +//! use yaxpeax_x86::amd64::{Arch as x86_64}; +//! use yaxpeax_arch::{ReaderBuilder, U8Reader}; +//! let data: &[u8] = &[0x55, 0x33, 0xc0, 0x48, 0x8b, 0x02, 0x5d, 0xc3]; +//! decoder::decode_stream::<x86_64, _>(data); +//! ``` +//! //! ## `#![no_std]` //! //! `yaxpeax-x86` supports `no_std` usage. to be built `no_std`, `yaxpeax-x86` only needs |