From a3c2c7486ef6830751fd0a5e2a6cb91b432f28a5 Mon Sep 17 00:00:00 2001 From: iximeow Date: Tue, 6 Jul 2021 15:23:11 -0700 Subject: fix doc items, add example for use of yaxpeax_x86 by yaxpeax_arch traits --- CHANGELOG | 4 ++++ Cargo.toml | 4 ++-- README.md | 4 ++-- src/lib.rs | 46 +++++++++++++++++++++++++++++++++++++++++++--- 4 files changed, 51 insertions(+), 7 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index d7461cb..5ae5dba 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -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 diff --git a/Cargo.toml b/Cargo.toml index f3150a8..86cbe2b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "yaxpeax-x86" -version = "1.0.2" +version = "1.0.3" authors = [ "iximeow " ] 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 } diff --git a/README.md b/README.md index 21d7769..bdda414 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/src/lib.rs b/src/lib.rs index 2bee840..84353ba 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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, +//! >(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::(data); +//! ``` +//! //! ## `#![no_std]` //! //! `yaxpeax-x86` supports `no_std` usage. to be built `no_std`, `yaxpeax-x86` only needs -- cgit v1.1