significantly improve instruction printing efficiency

CHANGELOG

@@ -1,3 +1,47 @@
+## 2.0.0
+
+* upgrade to `yaxpeax-arch 0.3.1`, which brings with it a deprecation of the
+  `Colorize` and `ShowContextual` traits.
+* because common use of yaxpeax-x86 involves using both this crate and
+  `yaxpeax-arch`, moving to a newer major version of `yaxpeax-arch` is a major
+  version bump of `yaxpeax-x86` as well. so, 2.0.0!
+
+changes:
+
+* `Operand` variants have had their naming made more consistent.
+  - many variants starting with "Reg" actually describe a memory access. they
+    now begin with "Mem" instead.
+  - several variants mentioned "Scale" in their name, but not "Index", even
+    though they use an index register. they now do.
+  - several variants mentioned their constituent parts out of order. for
+    example, "RegIndexBaseScaleDisp", even though the parts were specified as
+    base, then index, then scale, then displacement. these names have been
+    adjusted to reflect the order of their fields, which is roughly the order
+    those fields are shown when printed.
+  - `DisplacementU*` operands have always been access to memory at the absolute
+    address they specify. their names are now `AbsoluteU*`
+* `Operand`, across the board, now uses struct-style enum variants, rather than tuple-style.
+* the two changes together mean an operand that was
+  `RegIndexBaseScaleDisp(reg, reg, u8, i32)`
+  is now
+  `MemBaseIndexScaleDisp { base, index, scale, disp }`
+  and similar for other variants.
+* two operand kinds, and their masked variants, were never actually constructed, and have been deleted.
+  - long ago yaxpeax-x86 returned different Operand variants when an index
+    register was used with scale 1, to hint that no scaling actually occurred.
+    this was eventually changed to return a scaling Operand variant with
+    scale==1, but the old variants remained.
+  - RegIndexBase has been removed
+  - RegIndexBaseDisp has been removed
+* `Prefixes::selects_cs()` has been moved to `Prefixes::cs()`, and the old
+  useless functions are no more. `inst.prefixes().cs()` is finally a reasonable
+  way to determine if an instruction reads or writes through the cs prefix.
+
+fixes:
+
+* fix 32-bit call/jmp not respecting 66 prefix if set - such cases use 16-bit
+  operands, but decoded as if they used 32-bit operands.
+
 ## 1.2.2
 
 * fix `hreset` reporting two operands, with a second operand of `Nothing`.

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 
 name = "yaxpeax-x86"
-version = "1.2.2"
+version = "2.0.0"
 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.7", default-features = false, features = [] }
+yaxpeax-arch = { version = "0.3.1", 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 }
@@ -40,7 +40,13 @@ lto = true
 default = ["std", "colors", "use-serde", "fmt"]
 
 # opt-in for some apis that are really much nicer with String
-std = ["yaxpeax-arch/std"]
+std = ["alloc", "yaxpeax-arch/std"]
+
+# opt-in for some formatting-related helpers that require performing allocation
+#
+# this should only be useful with `fmt` currently, but in the future there could
+# be other `fmt`-independent code gated on `alloc`.
+alloc = ["yaxpeax-arch/alloc"]
 
 # feature for formatting instructions and their components
 fmt = []
@@ -52,3 +58,7 @@ colors = ["yaxpeax-arch/colors"]
 # This enables some capstone benchmarks over the same
 # instruction bytes used to bench this code.
 capstone_bench = []
+
+# this disables a lot of inlining to make it easier for me to measure
+# likelihood of codepaths for typical instruction sequences
+profiling = []

build.rs

@@ -1,5 +1,5 @@
 fn main() {
-    #[cfg(capstone_bench)]
+    #[cfg(feature="capstone_bench")]
     {
         println!("cargo:rustc-link-search=/usr/lib/");
         println!("cargo:rustc-link-lib=capstone");

ffi/long_mode/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2018"
 
 [dependencies]
 yaxpeax-x86 = { path = "../../", default-features = false }
-yaxpeax-arch = { version = "0.2.7", default-features = false }
+yaxpeax-arch = { version = "0.3.1", default-features = false }
 
 [lib]
 name = "yaxpeax_x86_ffi_long_mode"

ffi/multiarch/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2018"
 
 [dependencies]
 yaxpeax-x86 = { path = "../../", default-features = false }
-yaxpeax-arch = { version = "0.2.7", default-features = false }
+yaxpeax-arch = { version = "0.3.1", default-features = false }
 
 [lib]
 name = "yaxpeax_x86_ffi_multiarch"

ffi/protected_mode/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2018"
 
 [dependencies]
 yaxpeax-x86 = { path = "../../", default-features = false }
-yaxpeax-arch = { version = "0.2.7", default-features = false }
+yaxpeax-arch = { version = "0.3.1", default-features = false }
 
 [lib]
 name = "yaxpeax_x86_ffi_protected_mode"

ffi/real_mode/Cargo.toml

@@ -6,9 +6,14 @@ edition = "2018"
 
 [dependencies]
 yaxpeax-x86 = { path = "../../", default-features = false }
-yaxpeax-arch = { version = "0.2.7", default-features = false }
+yaxpeax-arch = { version = "0.3.1", default-features = false }
 
 [lib]
 name = "yaxpeax_x86_ffi_real_mode"
 path = "src/lib.rs"
-crate-type = ["staticlib"]
+crate-type = ["staticlib", "cdylib"]
+
+[features]
+default = ["fmt"]
+
+fmt = ["yaxpeax-x86/fmt"]

fuzz/Cargo.toml

@@ -10,6 +10,8 @@ cargo-fuzz = true
 
 [dependencies.yaxpeax-x86]
 path = ".."
+[dependencies.yaxpeax-arch]
+version = "0.3.1"
 [dependencies.libfuzzer-sys]
 git = "https://github.com/rust-fuzz/libfuzzer-sys.git"
 
@@ -27,6 +29,18 @@ path = "fuzz_targets/display_does_not_panic.rs"
 test = false
 doc = false
 
+[[bin]]
+name = "displaysink_used_correctly"
+path = "fuzz_targets/displaysink_used_correctly.rs"
+test = false
+doc = false
+
+[[bin]]
+name = "instruction_text_buffer_size_ok"
+path = "fuzz_targets/instruction_text_buffer_size_ok.rs"
+test = false
+doc = false
+
 [[bin]]
 name = "display_c_does_not_panic"
 path = "fuzz_targets/display_c_does_not_panic.rs"

fuzz/fuzz_targets/decode_does_not_panic.rs

@@ -6,7 +6,7 @@ fuzz_target!(|data: &[u8]| {
     let x86_64_decoder = yaxpeax_x86::long_mode::InstDecoder::default();
     let x86_32_decoder = yaxpeax_x86::protected_mode::InstDecoder::default();
     let x86_16_decoder = yaxpeax_x86::real_mode::InstDecoder::default();
-    drop(x86_64_decoder.decode_slice(data));
-    drop(x86_32_decoder.decode_slice(data));
-    drop(x86_16_decoder.decode_slice(data));
+    x86_64_decoder.decode_slice(data).expect("is ok");
+    x86_32_decoder.decode_slice(data).expect("is ok");
+    x86_16_decoder.decode_slice(data).expect("is ok");
 });

fuzz/fuzz_targets/display_does_not_panic.rs

@@ -8,14 +8,26 @@ fuzz_target!(|data: &[u8]| {
     let x86_16_decoder = yaxpeax_x86::real_mode::InstDecoder::default();
 
     if let Ok(inst) = x86_64_decoder.decode_slice(data) {
-        inst.write_to(&mut String::new()).expect("format does not panic");
+        let mut out = String::new();
+        inst.write_to(&mut out).expect("format does not panic");
+        let mut text_buf = yaxpeax_x86::long_mode::InstructionTextBuffer::new();
+        text_buf.format_inst(&inst.display_with(yaxpeax_x86::long_mode::DisplayStyle::Intel)).expect("can format");
+        assert_eq!(text_buf.text_str(), out);
     };
 
     if let Ok(inst) = x86_32_decoder.decode_slice(data) {
-        inst.write_to(&mut String::new()).expect("format does not panic");
+        let mut out = String::new();
+        inst.write_to(&mut out).expect("format does not panic");
+        let mut text_buf = yaxpeax_x86::protected_mode::InstructionTextBuffer::new();
+        text_buf.format_inst(&inst.display_with(yaxpeax_x86::protected_mode::DisplayStyle::Intel)).expect("can format");
+        assert_eq!(text_buf.text_str(), out);
     };
 
     if let Ok(inst) = x86_16_decoder.decode_slice(data) {
-        inst.write_to(&mut String::new()).expect("format does not panic");
+        let mut out = String::new();
+        inst.write_to(&mut out).expect("format does not panic");
+        let mut text_buf = yaxpeax_x86::real_mode::InstructionTextBuffer::new();
+        text_buf.format_inst(&inst.display_with(yaxpeax_x86::real_mode::DisplayStyle::Intel)).expect("can format");
+        assert_eq!(text_buf.text_str(), out);
     };
 });

fuzz/fuzz_targets/displaysink_used_correctly.rs

@@ -0,0 +1,24 @@
+#![no_main]
+#[macro_use] extern crate libfuzzer_sys;
+extern crate yaxpeax_x86;
+extern crate yaxpeax_arch;
+
+fuzz_target!(|data: &[u8]| {
+    let x86_64_decoder = yaxpeax_x86::long_mode::InstDecoder::default();
+    let x86_32_decoder = yaxpeax_x86::protected_mode::InstDecoder::default();
+    let x86_16_decoder = yaxpeax_x86::real_mode::InstDecoder::default();
+
+    use yaxpeax_arch::testkit::DisplaySinkValidator;
+
+    if let Ok(inst) = x86_64_decoder.decode_slice(data) {
+        inst.display_into(&mut DisplaySinkValidator::new()).expect("instruction can be displayed");
+    };
+
+    if let Ok(inst) = x86_32_decoder.decode_slice(data) {
+        inst.display_into(&mut DisplaySinkValidator::new()).expect("instruction can be displayed");
+    };
+
+    if let Ok(inst) = x86_16_decoder.decode_slice(data) {
+        inst.display_into(&mut DisplaySinkValidator::new()).expect("instruction can be displayed");
+    };
+});

fuzz/fuzz_targets/instruction_text_buffer_size_ok.rs

@@ -0,0 +1,51 @@
+#![no_main]
+#[macro_use] extern crate libfuzzer_sys;
+extern crate yaxpeax_x86;
+extern crate yaxpeax_arch;
+
+use std::fmt::Write;
+
+fuzz_target!(|data: &[u8]| {
+    let x86_64_decoder = yaxpeax_x86::long_mode::InstDecoder::default();
+    let x86_32_decoder = yaxpeax_x86::protected_mode::InstDecoder::default();
+    let x86_16_decoder = yaxpeax_x86::real_mode::InstDecoder::default();
+
+    if let Ok(inst) = x86_64_decoder.decode_slice(data) {
+        use yaxpeax_x86::long_mode::DisplayStyle;
+
+        let mut s = String::new();
+        write!(s, "{}", inst.display_with(DisplayStyle::Intel)).expect("can write");
+        // MAX_INSTRUCTION_LEN is not a public crate item yet...
+        assert!(s.len() < 512);
+        s.clear();
+        write!(s, "{}", inst.display_with(DisplayStyle::C)).expect("can write");
+        // MAX_INSTRUCTION_LEN is not a public crate item yet...
+        assert!(s.len() < 512);
+    };
+
+    if let Ok(inst) = x86_32_decoder.decode_slice(data) {
+        use yaxpeax_x86::protected_mode::DisplayStyle;
+
+        let mut s = String::new();
+        write!(s, "{}", inst.display_with(DisplayStyle::Intel)).expect("can write");
+        // MAX_INSTRUCTION_LEN is not a public crate item yet...
+        assert!(s.len() < 512);
+        s.clear();
+        write!(s, "{}", inst.display_with(DisplayStyle::C)).expect("can write");
+        // MAX_INSTRUCTION_LEN is not a public crate item yet...
+        assert!(s.len() < 512);
+    };
+
+    if let Ok(inst) = x86_16_decoder.decode_slice(data) {
+        use yaxpeax_x86::real_mode::DisplayStyle;
+
+        let mut s = String::new();
+        write!(s, "{}", inst.display_with(DisplayStyle::Intel)).expect("can write");
+        // MAX_INSTRUCTION_LEN is not a public crate item yet...
+        assert!(s.len() < 512);
+        s.clear();
+        write!(s, "{}", inst.display_with(DisplayStyle::C)).expect("can write");
+        // MAX_INSTRUCTION_LEN is not a public crate item yet...
+        assert!(s.len() < 512);
+    };
+});

fuzz/fuzz_targets/small_reg_is_always_old_bank_if_possible.rs

@@ -12,8 +12,8 @@ extern crate yaxpeax_x86;
 // cases. leaving them in for fuzz targets to match other cases, and In Case Of Future Change.
 fuzz_target!(|data: &[u8]| {
     let x86_64_decoder = yaxpeax_x86::long_mode::InstDecoder::default();
-    let x86_32_decoder = yaxpeax_x86::protected_mode::InstDecoder::default();
-    let x86_16_decoder = yaxpeax_x86::real_mode::InstDecoder::default();
+    // let x86_32_decoder = yaxpeax_x86::protected_mode::InstDecoder::default();
+    // let x86_16_decoder = yaxpeax_x86::real_mode::InstDecoder::default();
 
     if let Ok(inst) = x86_64_decoder.decode_slice(data) {
         for i in 0..inst.operand_count() {

goodfile

@@ -28,7 +28,7 @@ Build.artifact(sopath)
 
 -- now run some perf numbers...
 Step.start("perf")
-Build.run({"git", "clone", "https://github.com/athre0z/disas-bench.git", "disas-bench"})
+Build.run({"git", "clone", "https://github.com/iximeow/disas-bench.git", "disas-bench"})
 Build.run({"git", "submodule", "update", "--recursive", "--init"}, {cwd="disas-bench"})
 Build.run({"git", "remote", "add", "dev", "../../.."}, {cwd="disas-bench/libs/yaxpeax"})
 Build.run({"git", "fetch", "-a", "dev"}, {cwd="disas-bench/libs/yaxpeax"})

src/lib.rs

@@ -35,10 +35,10 @@
 //! #[cfg(features="fmt")]
 //! assert_eq!("xor eax, dword [rcx]", inst.to_string());
 //!
-//! assert_eq!(Operand::Register(RegSpec::eax()), inst.operand(0));
+//! assert_eq!(Operand::Register { reg: RegSpec::eax() }, inst.operand(0));
 //! #[cfg(features="fmt")]
 //! assert_eq!("eax", inst.operand(0).to_string());
-//! assert_eq!(Operand::RegDeref(RegSpec::rcx()), inst.operand(1));
+//! assert_eq!(Operand::MemDeref { base: RegSpec::rcx() }, inst.operand(1));
 //!
 //! // an operand in isolation does not know the size of memory it references, if any
 //! #[cfg(features="fmt")]
@@ -138,9 +138,44 @@ pub use protected_mode::Arch as x86_32;
 pub mod real_mode;
 pub use real_mode::Arch as x86_16;
 
-mod safer_unchecked;
+// this exists to size `InstructionTextBuffer`'s buffer. it ideally would come from an `Arch`
+// impl, or something related to `Arch`, but i'm not yet sure how to wire that up into
+// yaxpeax-arch. so instead calculate an appropriate max size for all of 16-bit/32-bit/64-bit
+// instruction printing that `InstructionTextBuffer` can be used for.
+//
+// `InstructionTextBuffer` prints an `InstructionDisplayer`, which means either intel syntax or
+// pseudo-C. in the future, at&t probably, as well.
+//
+// the pseudo-C syntax's max length would be something like:
+// ```
+// xacquire xrelease lock { repnz qword if /* signed */ greater_or_equal(rflags) then jmp gs:[xmm31 +
+// xmm31 * 8 + 0x12345678]{k7}{z}{rne-sae} }
+// ```
+// (which is nonsensical) or for an unknown opcode,
+// ```
+// xacquire xrelease lock { op0 = op(op0, op1, op2, op3) }
+// ```
+// where `opN` is an operand. the longest operand, same as above, would be something like
+// ```
+// gs:[xmm31 + xmm31 * 8 + 0x12345678]{k7}{z}{rne-sae}
+// ```
+// for a length like 262 bytes of operand, 55 bytes of prefixes and syntax, and another up-to-20
+// bytes of opcode.
+//
+// the longest contextualize_c might write is around 337 bytes. round up to 512 because it's.. not
+// much extra.
+//
+// the same reasoning for intel syntax yields a smaller instruction:
+// ```
+// xacquire xrelease lock op op1, op2, op3, op4
+// ```
+// where the longest operands are the same as above. this comes out to closer to 307 bytes. 512
+// bytes is still the longest of the two options.
+#[allow(dead_code)] // can be an unused constant in some library configurations
+const MAX_INSTRUCTION_LEN: usize = 512;
 
-const MEM_SIZE_STRINGS: [&'static str; 64] = [
+const MEM_SIZE_STRINGS: [&'static str; 65] = [
+    "BUG",
     "byte", "word", "BUG", "dword", "ptr", "far", "BUG", "qword",
     "BUG", "mword", "BUG", "BUG", "BUG", "BUG", "BUG", "xmmword",
     "BUG", "BUG", "BUG", "BUG", "BUG", "BUG", "BUG", "BUG",
@@ -194,7 +229,7 @@ impl MemoryAccessSize {
     /// "variable" accesses access a number of bytes dependent on the physical processor and its
     /// operating mode. this is particularly relevant for `xsave`/`xrstor`-style instructions.
     pub fn size_name(&self) -> &'static str {
-        MEM_SIZE_STRINGS[self.size as usize - 1]
+        MEM_SIZE_STRINGS[self.size as usize]
     }
 }