Move rsbddisasm to the bindings directory

.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 ..
 

.gitignore

@@ -64,6 +64,6 @@ libbddisasm.pc
 build/
 .vscode
 disasmtool_lix/_build
-rsbddisasm/target
+bindings/rsbddisasm/target
-rsbddisasm/Cargo.lock
+bindings/rsbddisasm/Cargo.lock
 bindings/pybddisasm/pybddisasm.egg-info

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

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 = """

bindings/rsbddisasm/bddisasm-sys/LICENSE

@@ -0,0 +1 @@
+../../../LICENSE

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.

bindings/rsbddisasm/bddisasm-sys/csrc/bddisasm

@@ -0,0 +1 @@
+../../../../bddisasm/

bindings/rsbddisasm/bddisasm-sys/csrc/inc

@@ -0,0 +1 @@
+../../../../inc/

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)]

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.

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)

rsbddisasm/bddisasm-sys/LICENSE

@@ -1 +0,0 @@
-../../LICENSE

rsbddisasm/bddisasm-sys/csrc/bddisasm

@@ -1 +0,0 @@
-../../../bddisasm

rsbddisasm/bddisasm-sys/csrc/inc

@@ -1 +0,0 @@
-../../../inc