rs: expose CS_OPT_MNEMONIC option via Capstone::set_mnemonic

Fixes #64.

Since the library expects a NUL-terminated string, an extra step is
added to append NUL character using std::ffi::CString. However, it
requires std environment, so set_mnemonic_cstr is provided for non-std
environment.

Author: jiegec

.github/workflows/main.yml

@@ -41,4 +41,4 @@ jobs:
         run: env ${{ matrix.rust.env }} ALL_FEATURES=1 ./capstone-rs/ci/test.sh
 
       - name: test (only enable x86 and arm64)
-        run: env ${{ matrix.rust.env }} FEATURES=full,arch_x86,arch_arm64 NO_DEFAULT_FEATURES=1 ./capstone-rs/ci/test.sh
+        run: env ${{ matrix.rust.env }} FEATURES=std,full,arch_x86,arch_arm64 NO_DEFAULT_FEATURES=1 ./capstone-rs/ci/test.sh

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Make RegAccessType available for ARM64
 - Rename RegAccessType to AccessType while keeping type alias
 - Expose `CS_OPT_UNSIGNED` via `Capstone::set_unsigned`
+- Expose `CS_OPT_MNEMONIC` via `Capstone::set_mnemonic`
 
 ### Changed
 - `InsnDetail::regs_read()`/`InsnDetail::regs_write()` return more of the accessed registers

capstone-rs/src/capstone.rs

@@ -1,8 +1,11 @@
 use alloc::boxed::Box;
 use alloc::string::String;
 use core::convert::From;
+use core::ffi::CStr;
 use core::marker::PhantomData;
 use core::mem::MaybeUninit;
+#[cfg(feature = "std")]
+use std::ffi::CString;
 
 use libc::{c_int, c_void};
 
@@ -386,6 +389,44 @@ impl Capstone {
         result
     }
 
+    /// Customize mnemonic for instructions with alternative name.
+    ///
+    /// Pass `Some(mnemonic)` to enable custom mnemonic or `None` to revert to default.
+    #[cfg(feature = "std")]
+    pub fn set_mnemonic(&mut self, insn_id: InsnId, mnemonic: Option<&str>) -> CsResult<()> {
+        let mnemonic_cstr = match mnemonic {
+            Some(s) => Some(CString::new(s).map_err(|_err| {
+                Error::CustomError(
+                    "Failed to convert mnemonic to C-String due to internal NUL characters",
+                )
+            })?),
+            None => None,
+        };
+        self.set_mnemonic_cstr(insn_id, mnemonic_cstr.as_ref().map(CString::as_c_str))
+    }
+
+    /// Customize mnemonic for instructions with alternative name, passing a core::ffi::CStr.
+    ///
+    /// Pass `Some(mnemonic)` to enable custom mnemonic or `None` to revert to default.
+    pub fn set_mnemonic_cstr(
+        &mut self,
+        insn_id: InsnId,
+        mnemonic_cstr: Option<&CStr>,
+    ) -> CsResult<()> {
+        let option_value: cs_opt_mnem = cs_opt_mnem {
+            id: insn_id.0,
+            mnemonic: mnemonic_cstr
+                .map(|s| s.as_ptr())
+                .unwrap_or(core::ptr::null()),
+        };
+        let result = self._set_cs_option(
+            cs_opt_type::CS_OPT_MNEMONIC,
+            &option_value as *const cs_opt_mnem as usize,
+        );
+
+        result
+    }
+
     /// Converts a register id `reg_id` to a `String` containing the register name.
     /// Unavailable in Diet mode
     pub fn reg_name(&self, reg_id: RegId) -> Option<String> {

capstone-rs/src/test.rs

@@ -208,6 +208,69 @@ fn test_unsigned() {
     assert_eq!(insns[0].op_str(), Some("x0, [x1, #0xffffffffffffffff]"));
 }
 
+#[cfg(feature = "arch_x86")]
+#[test]
+fn test_mnemonic() {
+    use capstone_sys::x86_insn;
+
+    let x86_code: &[u8] = b"\x6c";
+
+    // default mnemonic
+    let cs = Capstone::new()
+        .x86()
+        .mode(x86::ArchMode::Mode64)
+        .build()
+        .unwrap();
+    let insns = cs.disasm_all(x86_code, 0x1000).unwrap();
+    let insns: Vec<_> = insns.iter().collect();
+    assert_eq!(insns.len(), 1);
+    assert_eq!(insns[0].id().0, x86_insn::X86_INS_INSB as u32);
+    assert_eq!(insns[0].mnemonic(), Some("insb"));
+
+    // override mnemonic
+    let mut cs = Capstone::new()
+        .x86()
+        .mode(x86::ArchMode::Mode64)
+        .build()
+        .unwrap();
+    cs.set_mnemonic(InsnId(x86_insn::X86_INS_INSB as InsnIdInt), Some("abcd"))
+        .unwrap();
+    let insns = cs.disasm_all(x86_code, 0x1000).unwrap();
+    let insns: Vec<_> = insns.iter().collect();
+    assert_eq!(insns.len(), 1);
+    assert_eq!(insns[0].id().0, x86_insn::X86_INS_INSB as u32);
+    assert_eq!(insns[0].mnemonic(), Some("abcd"));
+
+    // revert override
+    let mut cs = Capstone::new()
+        .x86()
+        .mode(x86::ArchMode::Mode64)
+        .build()
+        .unwrap();
+    cs.set_mnemonic(InsnId(x86_insn::X86_INS_INSB as InsnIdInt), Some("abcd"))
+        .unwrap();
+    cs.set_mnemonic(InsnId(x86_insn::X86_INS_INSB as InsnIdInt), None)
+        .unwrap();
+    let insns = cs.disasm_all(x86_code, 0x1000).unwrap();
+    let insns: Vec<_> = insns.iter().collect();
+    assert_eq!(insns.len(), 1);
+    assert_eq!(insns[0].id().0, x86_insn::X86_INS_INSB as u32);
+    assert_eq!(insns[0].mnemonic(), Some("insb"));
+
+    // override with invalid mnemonic should fail
+    let mut cs = Capstone::new()
+        .x86()
+        .mode(x86::ArchMode::Mode64)
+        .build()
+        .unwrap();
+    assert!(cs
+        .set_mnemonic(
+            InsnId(x86_insn::X86_INS_INSB as InsnIdInt),
+            Some("\x00abcd")
+        )
+        .is_err());
+}
+
 #[cfg(all(feature = "full", feature = "arch_x86"))]
 #[test]
 fn test_detail_true() {