capstone: add cs_regs_access

capstone-rs/src/capstone.rs

@@ -11,7 +11,9 @@ use capstone_sys::*;
 use crate::constants::{Arch, Endian, ExtraMode, Mode, OptValue, Syntax};
 use crate::error::*;
 use crate::ffi::str_from_cstr_ptr;
-use crate::instruction::{Insn, InsnDetail, InsnGroupId, InsnId, Instructions, RegId};
+use crate::instruction::{
+    Insn, InsnDetail, InsnGroupId, InsnId, InsnRegsAccess, Instructions, RegId,
+};
 
 
 /// An instance of the capstone disassembler
@@ -378,6 +380,25 @@ impl Capstone {
         }
     }
 
+    /// Returns `RegsAccess` structure for a given instruction
+    ///
+    /// Requires:
+    ///
+    /// 1. Instruction was created with detail enabled
+    /// 2. Skipdata is disabled
+    /// 3. Capstone was not compiled in diet mode
+    pub fn insn_regs_access<'s, 'i: 's>(&'s self, insn: &'i Insn) -> CsResult<InsnRegsAccess> {
+        if !self.detail_enabled {
+            Err(Error::DetailOff)
+        } else if insn.id().0 == 0 {
+            Err(Error::IrrelevantDataInSkipData)
+        } else if Self::is_diet() {
+            Err(Error::IrrelevantDataInDiet)
+        } else {
+            Ok(unsafe { insn.regs_access(self.csh()) })
+        }
+    }
+
     /// Returns a tuple (major, minor) indicating the version of the capstone C library.
     pub fn lib_version() -> (u32, u32) {
         let mut major: c_int = 0;

capstone-rs/src/instruction.rs

@@ -145,6 +145,14 @@ pub struct Insn<'a> {
 /// `ArchDetail` enum.
 pub struct InsnDetail<'a>(pub(crate) &'a cs_detail, pub(crate) Arch);
 
+/// Contains information about registers accessed by an instruction, either explicitly or implicitly
+pub struct InsnRegsAccess {
+    pub(crate) regs_read: cs_regs,
+    pub(crate) regs_read_count: u8,
+    pub(crate) regs_write: cs_regs,
+    pub(crate) regs_write_count: u8,
+}
+
 impl<'a> Insn<'a> {
     /// The mnemonic for the instruction
     pub fn mnemonic(&self) -> Option<&str> {
@@ -184,6 +192,15 @@ impl<'a> Insn<'a> {
     pub(crate) unsafe fn detail(&self, arch: Arch) -> InsnDetail {
         InsnDetail(&*self.insn.detail, arch)
     }
+
+    /// Returns the `RegsAccess` object, if there is one. It is up to the caller to determine
+    /// the pre-conditions are satisfied.
+    ///
+    /// Be careful this is still in early stages and largely untested with various `cs_option` and
+    /// architecture matrices
+    pub(crate) unsafe fn regs_access(&self, cs: csh) -> InsnRegsAccess {
+        InsnRegsAccess::new(cs, &self.insn)
+    }
 }
 
 impl<'a> Debug for Insn<'a> {
@@ -328,6 +345,64 @@ impl<'a> InsnDetail<'a> {
     }
 }
 
+impl<'a> InsnRegsAccess {
+    fn new(cs: csh, ins: &cs_insn) -> Self {
+        let mut regs_read = [0u16; 64];
+        let mut regs_read_count = 0u8;
+        let mut regs_write = [0u16; 64];
+        let mut regs_write_count = 0u8;
+
+        unsafe {
+            cs_regs_access(
+                cs,
+                ins,
+                regs_read.as_mut_ptr(),
+                &mut regs_read_count,
+                regs_write.as_mut_ptr(),
+                &mut regs_write_count,
+            );
+        }
+
+        Self {
+            regs_read,
+            regs_read_count,
+            regs_write,
+            regs_write_count,
+        }
+    }
+
+    /// Returns the explicit and implicit accessed registers
+    pub fn regs_read(&self) -> RegsIter<RegIdInt> {
+        RegsIter(self.regs_read[..self.regs_read_count as usize].iter())
+    }
+
+    /// Returns the number of explicit and implicit read registers
+    pub fn regs_read_count(&self) -> u8 {
+        self.regs_read_count
+    }
+
+    /// Returns the explicit and implicit write registers
+    pub fn regs_write(&self) -> RegsIter<RegIdInt> {
+        RegsIter(self.regs_write[..self.regs_write_count as usize].iter())
+    }
+
+    /// Returns the number of explicit and implicit write registers
+    pub fn regs_write_count(&self) -> u8 {
+        self.regs_write_count
+    }
+}
+
+impl Debug for InsnRegsAccess {
+    fn fmt(&self, fmt: &mut Formatter) -> fmt::Result {
+        fmt.debug_struct("RegsAccess")
+            .field("regs_read", &self.regs_read())
+            .field("regs_read_count", &self.regs_read_count())
+            .field("regs_write", &self.regs_write())
+            .field("regs_write_count", &self.regs_write_count())
+            .finish()
+    }
+}
+
 impl<'a> Debug for InsnDetail<'a> {
     fn fmt(&self, fmt: &mut Formatter) -> fmt::Result {
         fmt.debug_struct("Detail")

capstone-rs/src/test.rs

@@ -127,6 +127,8 @@ fn test_detail_false_fail() {
 
     assert_eq!(cs.insn_detail(&insns[0]).unwrap_err(), Error::DetailOff);
     assert_eq!(cs.insn_detail(&insns[1]).unwrap_err(), Error::DetailOff);
+    assert_eq!(cs.insn_regs_access(&insns[0]).unwrap_err(), Error::DetailOff);
+    assert_eq!(cs.insn_regs_access(&insns[1]).unwrap_err(), Error::DetailOff);
 }
 
 #[test]