From 584150cb446fa9f672b11c5d6ca76cf4b335b1f8 Mon Sep 17 00:00:00 2001 From: Ionel-Cristinel ANICHITEI Date: Wed, 20 Oct 2021 10:03:16 +0300 Subject: [PATCH] Move rsbddisasm to the bindings directory --- .github/workflows/rust.yml | 10 +- .gitignore | 4 +- .../rsbddisasm}/Cargo.toml | 0 {rsbddisasm => bindings/rsbddisasm}/README.md | 4 +- .../rsbddisasm}/bddisasm-sys/Cargo.toml | 1 + bindings/rsbddisasm/bddisasm-sys/LICENSE | 1 + bindings/rsbddisasm/bddisasm-sys/README.md | 9 ++ .../rsbddisasm}/bddisasm-sys/build.rs | 0 .../rsbddisasm/bddisasm-sys/csrc/bddisasm | 1 + .../bddisasm-sys/csrc/bddisasm_wrapper.h | 0 bindings/rsbddisasm/bddisasm-sys/csrc/inc | 1 + .../rsbddisasm}/bddisasm-sys/src/lib.rs | 9 ++ .../rsbddisasm}/bddisasm/Cargo.toml | 0 bindings/rsbddisasm/bddisasm/README.md | 136 ++++++++++++++++++ .../rsbddisasm}/bddisasm/src/cpu_modes.rs | 0 .../rsbddisasm}/bddisasm/src/cpuid.rs | 0 .../rsbddisasm}/bddisasm/src/decode_error.rs | 0 .../bddisasm/src/decoded_instruction.rs | 0 .../rsbddisasm}/bddisasm/src/decoder.rs | 0 .../rsbddisasm}/bddisasm/src/fpu_flags.rs | 0 .../bddisasm/src/instruction_category.rs | 0 .../rsbddisasm}/bddisasm/src/isa_set.rs | 0 .../rsbddisasm}/bddisasm/src/lib.rs | 4 +- .../rsbddisasm}/bddisasm/src/mnemonic.rs | 0 .../rsbddisasm}/bddisasm/src/operand.rs | 0 .../rsbddisasm}/bddisasm/src/rflags.rs | 0 .../rsbddisasm}/bddisasm/src/tuple.rs | 0 rsbddisasm/bddisasm-sys/LICENSE | 1 - rsbddisasm/bddisasm-sys/csrc/bddisasm | 1 - rsbddisasm/bddisasm-sys/csrc/inc | 1 - 30 files changed, 171 insertions(+), 12 deletions(-) rename {rsbddisasm => bindings/rsbddisasm}/Cargo.toml (100%) rename {rsbddisasm => bindings/rsbddisasm}/README.md (83%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm-sys/Cargo.toml (96%) create mode 120000 bindings/rsbddisasm/bddisasm-sys/LICENSE create mode 100644 bindings/rsbddisasm/bddisasm-sys/README.md rename {rsbddisasm => bindings/rsbddisasm}/bddisasm-sys/build.rs (100%) create mode 120000 bindings/rsbddisasm/bddisasm-sys/csrc/bddisasm rename {rsbddisasm => bindings/rsbddisasm}/bddisasm-sys/csrc/bddisasm_wrapper.h (100%) create mode 120000 bindings/rsbddisasm/bddisasm-sys/csrc/inc rename {rsbddisasm => bindings/rsbddisasm}/bddisasm-sys/src/lib.rs (85%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/Cargo.toml (100%) create mode 100644 bindings/rsbddisasm/bddisasm/README.md rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/cpu_modes.rs (100%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/cpuid.rs (100%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/decode_error.rs (100%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/decoded_instruction.rs (100%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/decoder.rs (100%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/fpu_flags.rs (100%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/instruction_category.rs (100%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/isa_set.rs (100%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/lib.rs (96%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/mnemonic.rs (100%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/operand.rs (100%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/rflags.rs (100%) rename {rsbddisasm => bindings/rsbddisasm}/bddisasm/src/tuple.rs (100%) delete mode 120000 rsbddisasm/bddisasm-sys/LICENSE delete mode 120000 rsbddisasm/bddisasm-sys/csrc/bddisasm delete mode 120000 rsbddisasm/bddisasm-sys/csrc/inc diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 6d6093b..92e8d66 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -24,16 +24,16 @@ jobs: run: echo "LIBCLANG_PATH=$((gcm clang).source -replace "clang.exe")" >> $env:GITHUB_ENV if: matrix.os == 'windows-latest' - name: Debug Build - run: cargo build --verbose --manifest-path rsbddisasm/Cargo.toml + run: cargo build --verbose --manifest-path bindings/rsbddisasm/Cargo.toml - name: Release build - run: cargo build --release --verbose --manifest-path rsbddisasm/Cargo.toml + run: cargo build --release --verbose --manifest-path bindings/rsbddisasm/Cargo.toml - name: Run tests - run: cargo test --verbose --manifest-path rsbddisasm/Cargo.toml + run: cargo test --verbose --manifest-path bindings/rsbddisasm/Cargo.toml - name: Run clippy - run: cargo clippy --manifest-path rsbddisasm/Cargo.toml + run: cargo clippy --manifest-path bindings/rsbddisasm/Cargo.toml - name: Run format checks run: | - cd rsbddisasm + cd bindings/rsbddisasm cargo fmt -- --check cd .. diff --git a/.gitignore b/.gitignore index 68c2033..815b04d 100644 --- a/.gitignore +++ b/.gitignore @@ -64,6 +64,6 @@ libbddisasm.pc build/ .vscode disasmtool_lix/_build -rsbddisasm/target -rsbddisasm/Cargo.lock +bindings/rsbddisasm/target +bindings/rsbddisasm/Cargo.lock bindings/pybddisasm/pybddisasm.egg-info diff --git a/rsbddisasm/Cargo.toml b/bindings/rsbddisasm/Cargo.toml similarity index 100% rename from rsbddisasm/Cargo.toml rename to bindings/rsbddisasm/Cargo.toml diff --git a/rsbddisasm/README.md b/bindings/rsbddisasm/README.md similarity index 83% rename from rsbddisasm/README.md rename to bindings/rsbddisasm/README.md index a74141e..312d5ca 100644 --- a/rsbddisasm/README.md +++ b/bindings/rsbddisasm/README.md @@ -12,7 +12,7 @@ This crate uses the [*-sys crate convention](https://doc.rust-lang.org/cargo/ref ### bddisasm -This crate aims to offer a higher-level interface over [bddisasm-sys](#bddisasm-sys). It is currently held back by the fact that I don't really know Rust. +This crate aims to offer a higher-level interface over [bddisasm-sys](#bddisasm-sys). Parts of it are auto-generated, with slight manual changes (for example, the `Mnemonic` enum and related functions). @@ -24,3 +24,5 @@ Parts of it are auto-generated, with slight manual changes (for example, the `Mn - [ ] more examples for `cpu_modes` - [ ] an API to check if an instruction is supported with certain CPU modes on or off (currently a user has to manually check the `CpuModes` structure) - [ ] implement `Display` for more types (especially those in `operand`) +- [ ] remove the `bindgen` dev dependency? See [this issue](https://github.com/rust-lang/rust-bindgen/issues/918) as to why we may want to do that +- [ ] better directory structure diff --git a/rsbddisasm/bddisasm-sys/Cargo.toml b/bindings/rsbddisasm/bddisasm-sys/Cargo.toml similarity index 96% rename from rsbddisasm/bddisasm-sys/Cargo.toml rename to bindings/rsbddisasm/bddisasm-sys/Cargo.toml index 547410f..93001ea 100644 --- a/rsbddisasm/bddisasm-sys/Cargo.toml +++ b/bindings/rsbddisasm/bddisasm-sys/Cargo.toml @@ -6,6 +6,7 @@ edition = "2018" links = "bddisasm" build = "build.rs" license = "Apache-2.0" +readme = "README.md" repository = "https://github.com/bitdefender/bddisasm" documentation = "https://docs.rs/bddisasm-sys" description = """ diff --git a/bindings/rsbddisasm/bddisasm-sys/LICENSE b/bindings/rsbddisasm/bddisasm-sys/LICENSE new file mode 120000 index 0000000..5853aae --- /dev/null +++ b/bindings/rsbddisasm/bddisasm-sys/LICENSE @@ -0,0 +1 @@ +../../../LICENSE \ No newline at end of file diff --git a/bindings/rsbddisasm/bddisasm-sys/README.md b/bindings/rsbddisasm/bddisasm-sys/README.md new file mode 100644 index 0000000..48c8fb5 --- /dev/null +++ b/bindings/rsbddisasm/bddisasm-sys/README.md @@ -0,0 +1,9 @@ +# bddisasm-sys + +Rust bindings for [bddisasm](https://github.com/bitdefender/bddisasm). + +See [bddisasm](https://crates.io/crates/bddisasm) if you're looking for a Rust wrapper for these bindings. + +## Requirements + +[bindgen](https://crates.io/crates/bindgen) is used to generate the bindings at build time. Because of this, users need to have `clang` installed. Check the [bindgen documentation](https://rust-lang.github.io/rust-bindgen/requirements.html) for more information. diff --git a/rsbddisasm/bddisasm-sys/build.rs b/bindings/rsbddisasm/bddisasm-sys/build.rs similarity index 100% rename from rsbddisasm/bddisasm-sys/build.rs rename to bindings/rsbddisasm/bddisasm-sys/build.rs diff --git a/bindings/rsbddisasm/bddisasm-sys/csrc/bddisasm b/bindings/rsbddisasm/bddisasm-sys/csrc/bddisasm new file mode 120000 index 0000000..efbda44 --- /dev/null +++ b/bindings/rsbddisasm/bddisasm-sys/csrc/bddisasm @@ -0,0 +1 @@ +../../../../bddisasm/ \ No newline at end of file diff --git a/rsbddisasm/bddisasm-sys/csrc/bddisasm_wrapper.h b/bindings/rsbddisasm/bddisasm-sys/csrc/bddisasm_wrapper.h similarity index 100% rename from rsbddisasm/bddisasm-sys/csrc/bddisasm_wrapper.h rename to bindings/rsbddisasm/bddisasm-sys/csrc/bddisasm_wrapper.h diff --git a/bindings/rsbddisasm/bddisasm-sys/csrc/inc b/bindings/rsbddisasm/bddisasm-sys/csrc/inc new file mode 120000 index 0000000..0906712 --- /dev/null +++ b/bindings/rsbddisasm/bddisasm-sys/csrc/inc @@ -0,0 +1 @@ +../../../../inc/ \ No newline at end of file diff --git a/rsbddisasm/bddisasm-sys/src/lib.rs b/bindings/rsbddisasm/bddisasm-sys/src/lib.rs similarity index 85% rename from rsbddisasm/bddisasm-sys/src/lib.rs rename to bindings/rsbddisasm/bddisasm-sys/src/lib.rs index ecc197f..24750f5 100644 --- a/rsbddisasm/bddisasm-sys/src/lib.rs +++ b/bindings/rsbddisasm/bddisasm-sys/src/lib.rs @@ -2,6 +2,15 @@ * Copyright (c) 2021 Bitdefender * SPDX-License-Identifier: Apache-2.0 */ +//! Rust bindings for [bddisasm](https://github.com/bitdefender/bddisasm). +//! +//! See [bddisasm](https://crates.io/crates/bddisasm) if you're looking for a Rust wrapper for these bindings. +//! +//! # Requirements +//! +//! [bindgen](https://crates.io/crates/bindgen) is used to generate the bindings at build time. Because of this, users +//! need to have `clang` installed. +//! Check the [bindgen documentation](https://rust-lang.github.io/rust-bindgen/requirements.html) for more information. #![allow(non_camel_case_types)] #![allow(non_snake_case)] #![allow(non_upper_case_globals)] diff --git a/rsbddisasm/bddisasm/Cargo.toml b/bindings/rsbddisasm/bddisasm/Cargo.toml similarity index 100% rename from rsbddisasm/bddisasm/Cargo.toml rename to bindings/rsbddisasm/bddisasm/Cargo.toml diff --git a/bindings/rsbddisasm/bddisasm/README.md b/bindings/rsbddisasm/bddisasm/README.md new file mode 100644 index 0000000..d4d258b --- /dev/null +++ b/bindings/rsbddisasm/bddisasm/README.md @@ -0,0 +1,136 @@ +# bddisasm + +Rust bindings for the [bddisasm](https://github.com/bitdefender/bddisasm) x86/x64 decoder library, built on top +of [bddisasm-sys](https://crates.io/crates/bddisasm-sys). + +It supports all existing x86 instruction, offering a wide range of information about each one, including: + +- operands (implicit and explicit) +- access mode for each operand +- CPUID feature flags +- CPU modes in which an instruction is valid + +## Usage + +Add `bddisasm` to your `Cargo.toml`: + +```toml +[dependencies] +bddisasm = "0.1.0" +``` + +## Examples + +### Decoding one instruction + +```rust +use bddisasm::decoded_instruction::{DecodedInstruction, DecodeMode, Mnemonic}; + +let code = vec![0x31, 0xc0]; +match DecodedInstruction::decode(&code, DecodeMode::Bits32) { + Ok(ins) => { + assert_eq!(ins.mnemonic(), Mnemonic::Xor); + println!("{}", ins); + }, + Err(err) => println!("Unable to decode: {}", err), +} +``` + +### Decoding multiple instructions + +```rust +use bddisasm::decoder::{Decoder, DecodeMode}; + +let code = [ + // ENCLS + 0x0f, 0x01, 0xcf, + // MOV rax, qword ptr [rbx+rcx*4+0x1234] + 0x48, 0x8b, 0x84, 0x8b, 0x34, 0x12, 0x00, 0x00, + // Not a valid instruction + 0x0f, + // WRMSR + 0x0f, 0x30, +]; +let decoder = Decoder::new(&code, DecodeMode::Bits64, 0x1234); + +for ins in decoder { + match ins { + Ok(ins) => println!("{}", ins), + Err(e) => println!("{}", e), + } +} +``` + +This will print: + +```text +ENCLS +MOV rax, qword ptr [rbx+rcx*4+0x1234] +the provided input buffer is too small +WRMSR +``` + +### Working with instruction operands + +Rich informaion is offered for each type of operand. Bellow is a minimal example that looks at a memory operand. + +```rust +# use bddisasm::decode_error::DecodeError; +# fn test() -> Result<(), DecodeError> { +use bddisasm::decoded_instruction::{DecodedInstruction, DecodeMode}; +use bddisasm::operand::OpInfo; + +// ` MOV rax, qword ptr [rcx+r15*2]` +let code = b"\x4a\x8b\x04\x79"; +let ins = DecodedInstruction::decode(code, DecodeMode::Bits64).unwrap(); +// Get the operands +let operands = ins.operands(); +// Get the second operand which is the source (`[rcx+r15*2]`) +let src = operands[1]; + +println!("Source operand type: {}", src.info); +match src.info { + OpInfo::Mem(mem) => { + if let Some(base) = mem.base { + println!("Base register: {}", base); + } else { + println!("No base register"); + } + + if let Some(index) = mem.index { + println!("Index register: {}", index); + } else { + println!("No index register"); + } + + if let Some(scale) = mem.scale { + println!("Scale: {}", scale); + } else { + println!("No scale"); + } + + if let Some(displacement) = mem.disp { + println!("Displacement: {}", displacement); + } else { + println!("No displacement"); + } + }, + _ => unreachable!(), +} +# Ok(()) +# } +``` + +Will print: + +```text +Source operand type: memory +Base register: 1 +Index register: 15 +Scale: 2 +No displacement +``` + +## Requirements + +Because [bddisasm-sys](https://crates.io/crates/bddisasm-sys) uses [bindgen](https://crates.io/crates/bindgen) to generate the bindings at build time, users need to have `clang` installed. Check the [bindgen documentation](https://rust-lang.github.io/rust-bindgen/requirements.html) for more information. diff --git a/rsbddisasm/bddisasm/src/cpu_modes.rs b/bindings/rsbddisasm/bddisasm/src/cpu_modes.rs similarity index 100% rename from rsbddisasm/bddisasm/src/cpu_modes.rs rename to bindings/rsbddisasm/bddisasm/src/cpu_modes.rs diff --git a/rsbddisasm/bddisasm/src/cpuid.rs b/bindings/rsbddisasm/bddisasm/src/cpuid.rs similarity index 100% rename from rsbddisasm/bddisasm/src/cpuid.rs rename to bindings/rsbddisasm/bddisasm/src/cpuid.rs diff --git a/rsbddisasm/bddisasm/src/decode_error.rs b/bindings/rsbddisasm/bddisasm/src/decode_error.rs similarity index 100% rename from rsbddisasm/bddisasm/src/decode_error.rs rename to bindings/rsbddisasm/bddisasm/src/decode_error.rs diff --git a/rsbddisasm/bddisasm/src/decoded_instruction.rs b/bindings/rsbddisasm/bddisasm/src/decoded_instruction.rs similarity index 100% rename from rsbddisasm/bddisasm/src/decoded_instruction.rs rename to bindings/rsbddisasm/bddisasm/src/decoded_instruction.rs diff --git a/rsbddisasm/bddisasm/src/decoder.rs b/bindings/rsbddisasm/bddisasm/src/decoder.rs similarity index 100% rename from rsbddisasm/bddisasm/src/decoder.rs rename to bindings/rsbddisasm/bddisasm/src/decoder.rs diff --git a/rsbddisasm/bddisasm/src/fpu_flags.rs b/bindings/rsbddisasm/bddisasm/src/fpu_flags.rs similarity index 100% rename from rsbddisasm/bddisasm/src/fpu_flags.rs rename to bindings/rsbddisasm/bddisasm/src/fpu_flags.rs diff --git a/rsbddisasm/bddisasm/src/instruction_category.rs b/bindings/rsbddisasm/bddisasm/src/instruction_category.rs similarity index 100% rename from rsbddisasm/bddisasm/src/instruction_category.rs rename to bindings/rsbddisasm/bddisasm/src/instruction_category.rs diff --git a/rsbddisasm/bddisasm/src/isa_set.rs b/bindings/rsbddisasm/bddisasm/src/isa_set.rs similarity index 100% rename from rsbddisasm/bddisasm/src/isa_set.rs rename to bindings/rsbddisasm/bddisasm/src/isa_set.rs diff --git a/rsbddisasm/bddisasm/src/lib.rs b/bindings/rsbddisasm/bddisasm/src/lib.rs similarity index 96% rename from rsbddisasm/bddisasm/src/lib.rs rename to bindings/rsbddisasm/bddisasm/src/lib.rs index 7ec0c85..a5cb822 100644 --- a/rsbddisasm/bddisasm/src/lib.rs +++ b/bindings/rsbddisasm/bddisasm/src/lib.rs @@ -4,7 +4,9 @@ */ //! bddisasm x86/x64 instruction decoder //! -//! This crate contains bindings for the [bddisasm](https://github.com/bitdefender/bddisasm) x86/x64 decoder library. +//! Rust bindings for the [bddisasm](https://github.com/bitdefender/bddisasm) x86/x64 decoder library, built on top +//! of [bddisasm-sys](https://crates.io/crates/bddisasm-sys). +//! //! It supports all existing x86 instruction, offering a wide range of information about each one, including: //! //! - operands (implicit and explicit) diff --git a/rsbddisasm/bddisasm/src/mnemonic.rs b/bindings/rsbddisasm/bddisasm/src/mnemonic.rs similarity index 100% rename from rsbddisasm/bddisasm/src/mnemonic.rs rename to bindings/rsbddisasm/bddisasm/src/mnemonic.rs diff --git a/rsbddisasm/bddisasm/src/operand.rs b/bindings/rsbddisasm/bddisasm/src/operand.rs similarity index 100% rename from rsbddisasm/bddisasm/src/operand.rs rename to bindings/rsbddisasm/bddisasm/src/operand.rs diff --git a/rsbddisasm/bddisasm/src/rflags.rs b/bindings/rsbddisasm/bddisasm/src/rflags.rs similarity index 100% rename from rsbddisasm/bddisasm/src/rflags.rs rename to bindings/rsbddisasm/bddisasm/src/rflags.rs diff --git a/rsbddisasm/bddisasm/src/tuple.rs b/bindings/rsbddisasm/bddisasm/src/tuple.rs similarity index 100% rename from rsbddisasm/bddisasm/src/tuple.rs rename to bindings/rsbddisasm/bddisasm/src/tuple.rs diff --git a/rsbddisasm/bddisasm-sys/LICENSE b/rsbddisasm/bddisasm-sys/LICENSE deleted file mode 120000 index 30cff74..0000000 --- a/rsbddisasm/bddisasm-sys/LICENSE +++ /dev/null @@ -1 +0,0 @@ -../../LICENSE \ No newline at end of file diff --git a/rsbddisasm/bddisasm-sys/csrc/bddisasm b/rsbddisasm/bddisasm-sys/csrc/bddisasm deleted file mode 120000 index 00ffb24..0000000 --- a/rsbddisasm/bddisasm-sys/csrc/bddisasm +++ /dev/null @@ -1 +0,0 @@ -../../../bddisasm \ No newline at end of file diff --git a/rsbddisasm/bddisasm-sys/csrc/inc b/rsbddisasm/bddisasm-sys/csrc/inc deleted file mode 120000 index 3e5b14c..0000000 --- a/rsbddisasm/bddisasm-sys/csrc/inc +++ /dev/null @@ -1 +0,0 @@ -../../../inc \ No newline at end of file