[Rust] Remove `UnusedRegisterStackInfo` and update architecture documentation

3 files changed, 117 insertions, 29 deletions

diff --git a/rust/src/architecture/branches.rs b/rust/src/architecture/branches.rs
index 80baa1b6..a6810b34 100644
--- a/rust/src/architecture/branches.rs
+++ b/rust/src/architecture/branches.rs
@@ -22,7 +22,7 @@ pub enum BranchKind {
 
 #[derive(Default, Copy, Clone, PartialEq, Eq, Hash, Debug)]
 pub struct BranchInfo {
-    /// If `None` the target architecture is the same as the branch instruction.
+    /// If `None`, the target architecture is the same as the branching instruction.
     pub arch: Option<CoreArchitecture>,
     pub kind: BranchKind,
 }
diff --git a/rust/src/architecture/intrinsic.rs b/rust/src/architecture/intrinsic.rs
index 4ad5ee2a..5d9827a1 100644
--- a/rust/src/architecture/intrinsic.rs
+++ b/rust/src/architecture/intrinsic.rs
@@ -32,7 +32,7 @@ pub trait Intrinsic: Debug + Sized + Clone + Copy {
     fn outputs(&self) -> Vec<Conf<Ref<Type>>>;
 }
 
-/// Type for architrectures that do not use intrinsics. Will panic if accessed as an intrinsic.
+/// Type for architectures that do not use intrinsics. Will panic if accessed as an intrinsic.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct UnusedIntrinsic;
 
diff --git a/rust/src/architecture/register.rs b/rust/src/architecture/register.rs
index 50bb38ba..1f17c785 100644
--- a/rust/src/architecture/register.rs
+++ b/rust/src/architecture/register.rs
@@ -6,8 +6,6 @@ use std::ffi::CStr;
 use std::fmt::{Debug, Formatter};
 use std::hash::Hash;
 
-pub use binaryninjacore_sys::BNImplicitRegisterExtend as ImplicitRegisterExtend;
-
 crate::new_id_type!(RegisterId, u32);
 
 impl RegisterId {
@@ -18,59 +16,133 @@ impl RegisterId {
 
 crate::new_id_type!(RegisterStackId, u32);
 
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
+pub enum ImplicitRegisterExtend {
+    /// The upper bits of the parent register are preserved (untouched).
+    ///
+    /// # Example (x86-64)
+    ///
+    /// Executing `inc al` only modifies the lowest 8 bits of `rax`. The upper 56 bits of `rax` remain
+    /// completely unchanged.
+    NoExtend = 0,
+    /// The upper bits of the parent register are zeroed out.
+    ///
+    /// # Example (x86-64)
+    ///
+    /// Executing `mov eax, 1` writes `1` to the lower 32 bits of `rax`, but implicitly **clears** the
+    /// upper 32 bits of `rax` to zero.
+    ZeroExtendToFullWidth,
+    /// The upper bits of the parent register are filled with the sign bit (MSB) of the value written.
+    SignExtendToFullWidth,
+}
+
+impl From<BNImplicitRegisterExtend> for ImplicitRegisterExtend {
+    fn from(value: BNImplicitRegisterExtend) -> Self {
+        match value {
+            BNImplicitRegisterExtend::NoExtend => Self::NoExtend,
+            BNImplicitRegisterExtend::ZeroExtendToFullWidth => Self::ZeroExtendToFullWidth,
+            BNImplicitRegisterExtend::SignExtendToFullWidth => Self::SignExtendToFullWidth,
+        }
+    }
+}
+
+impl From<ImplicitRegisterExtend> for BNImplicitRegisterExtend {
+    fn from(value: ImplicitRegisterExtend) -> Self {
+        match value {
+            ImplicitRegisterExtend::NoExtend => Self::NoExtend,
+            ImplicitRegisterExtend::ZeroExtendToFullWidth => Self::ZeroExtendToFullWidth,
+            ImplicitRegisterExtend::SignExtendToFullWidth => Self::SignExtendToFullWidth,
+        }
+    }
+}
+
+/// Information about a register.
 pub trait RegisterInfo: Sized {
     type RegType: Register<InfoType = Self>;
 
+    /// The register that this register is an alias of.
+    ///
+    /// # Example (x86-64)
+    ///
+    /// The register `rax` is a parent of the register `eax`.
     fn parent(&self) -> Option<Self::RegType>;
+
+    /// Size of the register in bytes.
     fn size(&self) -> usize;
+
+    /// Offset of the register in bytes from the start of the containing [`RegisterInfo::parent`].
     fn offset(&self) -> usize;
+
+    /// Used when this register aliases a logical register to determine what happens to the upper bits.
     fn implicit_extend(&self) -> ImplicitRegisterExtend;
 }
 
 pub trait Register: Debug + Sized + Clone + Copy + Hash + Eq {
     type InfoType: RegisterInfo<RegType = Self>;
 
+    /// The displayed name of the register, such as "eax".
     fn name(&self) -> Cow<'_, str>;
+
     fn info(&self) -> Self::InfoType;
 
     /// Unique identifier for this `Register`.
     ///
-    /// *MUST* be in the range [0, 0x7fff_ffff]
+    /// NOTE: *MUST* be in the range [0, 0x7fff_ffff]
     fn id(&self) -> RegisterId;
 }
 
+/// Information about a register stack.
 pub trait RegisterStackInfo: Sized {
     type RegStackType: RegisterStack<InfoType = Self>;
     type RegType: Register<InfoType = Self::RegInfoType>;
     type RegInfoType: RegisterInfo<RegType = Self::RegType>;
 
+    // TODO: Return a list of the registers instead?
+    /// The sequence of physical registers that back this stack.
+    ///
+    /// This defines the absolute storage locations in the hardware, ignoring the current stack pointer.
+    ///
+    /// Return the start of the "fake" registers defined. The core requires that the id's be contiguous
+    /// as you only return the **first** storage register and the count.
+    ///
+    /// # Example (x87 FPU)
+    ///
+    /// [`RegisterStackInfo::top_relative_regs`] with (REG_ST0, 8) and then define here (REG_PHYSICAL_0, 8).
     fn storage_regs(&self) -> (Self::RegType, usize);
-    fn top_relative_regs(&self) -> Option<(Self::RegType, usize)>;
-    fn stack_top_reg(&self) -> Self::RegType;
-}
-
-/// Type for architectures that do not use register stacks. Will panic if accessed as a register stack.
-#[derive(Clone, Copy, PartialEq, Eq, Hash)]
-pub struct UnusedRegisterStackInfo<R: Register> {
-    _reg: std::marker::PhantomData<R>,
-}
 
-impl<R: Register> RegisterStackInfo for UnusedRegisterStackInfo<R> {
-    type RegStackType = UnusedRegisterStack<R>;
-    type RegType = R;
-    type RegInfoType = R::InfoType;
+    // TODO: Return a list of the registers instead?
+    /// The sequence of registers used to access the stack relative to the current top.
+    ///
+    /// Return the start of the relative registers defined. The core requires that the id's be contiguous
+    /// as you only return the **first** relative register and the count.
+    ///
+    /// # Example (x87 FPU)
+    ///
+    /// Returns (REG_ST0, 8), where the id's of all the later relative registers are contiguous.
+    fn top_relative_regs(&self) -> Option<(Self::RegType, usize)>;
 
-    fn storage_regs(&self) -> (Self::RegType, usize) {
-        unreachable!()
-    }
-    fn top_relative_regs(&self) -> Option<(Self::RegType, usize)> {
-        unreachable!()
-    }
-    fn stack_top_reg(&self) -> Self::RegType {
-        unreachable!()
-    }
+    /// The specific register that holds the index of the current stack top.
+    ///
+    /// The value in this register determines which physical `storage_reg` corresponds
+    /// to the first `top_relative_reg`.
+    ///
+    /// # Example (x87 FPU)
+    ///
+    /// Returns the `TOP` as a fake register.
+    ///
+    /// * If `TOP` == 0: `top_relative_regs[0]` maps to `storage_regs[0]`.
+    /// * If `TOP` == 1: `top_relative_regs[0]` maps to `storage_regs[1]`.
+    fn stack_top_reg(&self) -> Self::RegType;
 }
 
+/// Register stacks are used in architectures where registers are accessed relative to a
+/// dynamic stack pointer rather than by fixed names.
+///
+/// For more information see [`RegisterStackInfo`].
+///
+/// # Example
+/// The **x87 FPU** on x86 uses a register stack (`ST(0)` through `ST(7)`).
+/// Pushing a value decrements the stack top pointer; popping increments it.
 pub trait RegisterStack: Debug + Sized + Clone + Copy {
     type InfoType: RegisterStackInfo<
         RegType = Self::RegType,
@@ -96,7 +168,7 @@ pub struct UnusedRegisterStack<R: Register> {
 }
 
 impl<R: Register> RegisterStack for UnusedRegisterStack<R> {
-    type InfoType = UnusedRegisterStackInfo<R>;
+    type InfoType = Self;
     type RegType = R;
     type RegInfoType = R::InfoType;
 
@@ -111,6 +183,22 @@ impl<R: Register> RegisterStack for UnusedRegisterStack<R> {
     }
 }
 
+impl<R: Register> RegisterStackInfo for UnusedRegisterStack<R> {
+    type RegStackType = Self;
+    type RegType = R;
+    type RegInfoType = R::InfoType;
+
+    fn storage_regs(&self) -> (Self::RegType, usize) {
+        unreachable!()
+    }
+    fn top_relative_regs(&self) -> Option<(Self::RegType, usize)> {
+        unreachable!()
+    }
+    fn stack_top_reg(&self) -> Self::RegType {
+        unreachable!()
+    }
+}
+
 #[derive(Debug, Copy, Clone)]
 pub struct CoreRegisterInfo {
     arch: CoreArchitecture,
@@ -147,7 +235,7 @@ impl RegisterInfo for CoreRegisterInfo {
     }
 
     fn implicit_extend(&self) -> ImplicitRegisterExtend {
-        self.info.extend
+        self.info.extend.into()
     }
 }