docs, cleanupinst-behavior

1 files changed, 172 insertions, 21 deletions

diff --git a/src/long_mode/behavior.rs b/src/long_mode/behavior.rs
index dd9ec3e..97ae3fd 100644
--- a/src/long_mode/behavior.rs
+++ b/src/long_mode/behavior.rs
@@ -1,9 +1,41 @@
+//! behavior information for x86-64 instructions.
+//!
+//! this module allows users of yaxpeax-x86 to collect operand read/write information about
+//! instructions ([`InstBehavior::get_operand()`]), as well as allowed execution level
+//! ([`InstBehavior::privilege_level()`]), potential exceptions ([`InstBehavior::exceptions()`]),
+//! and iterating all explicit and implicit operands ([`InstBehavior::all_operands()`]).
+//!
+//! additionally, [`ComplexOp`] enumerates instructions that may be considered "complex" - either
+//! involving architectural state not expressed in yaxpeax-x86' API or otherwise affecting machine
+//! state in a way that simply considering the operands as-presented would be inaccurate. where
+//! possible, `ComplexOp` tries to guide users towards how to handle such instructions.
+//!
+//! some behavior information in this module is "unstable", meaning it must be opted into with
+//! `feature = ["unstable"]` on yaxpeax-x86; information from "unstable" interfaces may be
+//! less-tested and change across semver-compatible releases! if you want to use unstable
+//! interfaces here, first: thank you!! please report any issues, and second: consider pinning to a
+//! specific minor version while setting `feature = ["unstable"]` if instruction behavior becoming
+//! more correct might present an issue in your application.
+
+#![deny(missing_docs)]
+
+// a lot of people have told me that we don't need to read code anymore, just like we "never look at
+// machine code anymore". sit with me and have a sad laugh for a moment. if we weren't here, reading
+// and thinking and talking about how to model the computer, where would the training data come
+// from? "you're not being left behind, it's a personal choice!", i've heard. a year later this has
+// evolved into "it is an abdication of your responsibility as an engineer to not pay Anthropic".
+// it is our moral responsibility to build the highest quality software in service of furthering
+// the rot? it is an abdication of ethics to claim all works are good.
+
 use super::{Instruction, Opcode, Operand, OperandSpec};
 use super::RegSpec;
 
 /// an accessor for run-time characteristics of instructions.
 ///
-/// ... TODO words ...
+/// generally, behavior accessors across architectures are expected to have a `behavior()`
+/// entrypoint on a decoded instruction. it is not clear which properties of `behavior()`
+/// generalize across architectures (yet!) but presumably something like `all_operands()` and
+/// `Access` do.
 ///
 /// additionally, of note for x86:
 ///
@@ -15,11 +47,10 @@ use super::RegSpec;
 ///   operation (consider `call qword [rcx]`; `qword [rcx]` is one memory access, but the implied
 ///   push of a return address is a second memory operation).
 /// * `{,e,r}flags` is often written and sometimes read, but almost never as an explicit source or
-///   destination operand. this can be queried with `flags_access()`, in addition to its inclusion
-///   as an implicit operand.
+///   destination operand. this can be queried with [`flags_access()`].
 ///
 /// it's also useful to know if implicit and explicit operands are reads, writes, or both, such as
-/// when diagnosing a run-time fault. to iterate over this information, `operands().accesses()`. or
+/// when diagnosing a run-time fault. to iterate over this information, `all_operands().iter()`. or
 /// `visit_accesses(&mut ..)` to collect all operand/access information for this instruction.
 #[derive(Copy, Clone)]
 pub struct InstBehavior<'inst> {
@@ -28,6 +59,14 @@ pub struct InstBehavior<'inst> {
 }
 
 impl Instruction {
+    /// get a struct to query behaviors of an instruction.
+    ///
+    /// "behaviors" is broad! as of writing, "behavior" covers "implicit and explicit operand
+    /// reads/writes", "possible exceptions", "allowed privilege levels", and "instruction has
+    /// additional semantics not easily expressed by this library".
+    ///
+    /// see the documentation for [`InstBehavior`] as well as the
+    /// [`behavior`][yaxpeax_x86::long_mode::behavior] module for more information.
     pub fn behavior<'inst>(&'inst self) -> InstBehavior<'inst> {
         let mut behavior = opcode2behavior(&self.opcode);
 
@@ -252,6 +291,10 @@ impl Exception {
     /// Control Protection Exception
     pub const CP: Exception = Exception::vector(21);
 
+    /// construct an `Exception` for the provided exception vector number.
+    ///
+    /// this is provided for convenience when converting (for example) the number in an x86
+    /// exception handler to the kinds of `Exception` in this library.
     pub const fn vector(vector: u8) -> Self {
         Self { vector }
     }
@@ -262,6 +305,11 @@ impl Exception {
     }
 
     #[cfg(feature = "fmt")]
+    /// get the typical mnemonic for this `Exception`, if one is documented.
+    ///
+    /// the names returned by helper do not include a leading `#`. they come from the Intel SDM
+    /// chapter 7.3 "SOURCES OF INTERRUPTS" table 7-1 "Protected-Mode Exceptions and Interrupts".
+    /// similar descriptions can be found in the AMD APM.
     pub fn name(&self) -> Option<&'static str> {
         static NAMES: [Option<&'static str>; 22] = [
             Some("DE"), Some("DB"), Some("NMI"), Some("BP"),
@@ -294,20 +342,24 @@ impl fmt::Debug for Exception {
 }
 
 impl ExceptionInfo {
+    /// construct an empty set of possible exception vectors.
     pub fn empty() -> Self {
         Self {
             possible_vectors: 0,
         }
     }
 
+    /// test if this `ExceptionInfo` has any possible vector set.
     pub fn any(&self) -> bool {
         self.possible_vectors != 0
     }
 
+    /// test if this `ExceptionInfo` has no vector set.
     pub fn none(&self) -> bool {
         !self.any()
     }
 
+    /// test if this `ExceptionInfo` indicates that exception `e` may be raised.
     pub fn may(&self, e: Exception) -> bool {
         (self.possible_vectors & (1 << e.vector)) != 0
     }
@@ -323,6 +375,8 @@ impl ExceptionInfo {
         self.possible_vectors |= bit;
     }
 
+    /// record that exception `e` is or is not (`b`) possible in this `ExceptionInfo` record, but
+    /// in a more chaining-friendly way.
     pub const fn with(mut self, e: Exception, b: bool) -> Self {
         self.set(e, b);
         self
@@ -351,13 +405,25 @@ fn test_exception_info() {
     assert_eq!(info.possible_vectors, 0x12000);
 }
 
+/// a description of the privilege level (that is, value of `CPL` in the current code selector)
+/// that allows executing the corresponding instruction.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum PrivilegeLevel {
+    /// the corresponding instruction can run at any privilege level.
     Any = 0b00,
+    /// the corresponding instruction can only run when `CPL=0` (aka "in ring 0").
     PL0 = 0b01,
+    /// the corresponding instruction has more complex rule for when it is allowed.
+    ///
+    /// this may mean the instruction is either "Any" or "PL0" depending on other processor state
+    /// (such as `rdtsc`), or it may mean the instruction simply does not relate directly to
+    /// `CPL=3`/`CPL=0` (such as for `iret`).
     Special = 0b10,
 }
 
+/// a handle for an instruction, its behavior, and any related implicit operands.
+///
+/// this is only useful for [`InstOperands::iter()`].
 #[derive(Copy, Clone)]
 pub struct InstOperands<'inst> {
     inst: InstBehavior<'inst>,
@@ -365,11 +431,17 @@ pub struct InstOperands<'inst> {
 }
 
 impl<'inst> InstOperands<'inst> {
+    /// establish an iterator over the operands described in this `InstOperands`.
     pub fn iter(self) -> AccessIter<'inst> {
         AccessIter::new(self)
     }
 }
 
+/// this struct implements [`Iterator`] to allow library users to walk all explicit and implicit
+/// operands for the corresponding instruction, along with if they are used for reading or for
+/// writing.
+///
+/// implicit operands are always walked first, explicit operands are walked last.
 pub struct AccessIter<'inst> {
     operands: InstOperands<'inst>,
     explicit: bool,
@@ -385,6 +457,8 @@ impl<'inst> AccessIter<'inst> {
         }
     }
 
+    /// weaken this iterator to only returning the operands corresponding to this instruction,
+    /// without specific access information.
     pub fn operands(self) -> OperandIter<'inst> {
         OperandIter { inner: self }
     }
@@ -437,7 +511,8 @@ impl<'inst> Iterator for AccessIter<'inst> {
 
         if self.next < self.operands.inst.inst.operand_count() {
             let op = self.operands.inst.inst.operand(self.next);
-            let access = self.operands.inst.operand_access(self.next).expect("defined operand has defined access");
+            let access = self.operands.inst.operand_access(self.next)
+                .expect("defined operand has defined access");
             debug_assert!(
                 access != Access::None || (
                     self.operands.inst.inst.opcode == Opcode::NOP ||
@@ -454,6 +529,11 @@ impl<'inst> Iterator for AccessIter<'inst> {
     }
 }
 
+/// a reduced-strength iterator of an instruction's implicit and explicit operands.
+///
+/// unlike `AccessIter`, this iterator does not provide read/write information, simply that
+/// operands are or are not present. this is more likely useful for some kinds of instruction
+/// printing than automated instruction analysis.
 pub struct OperandIter<'inst> {
     inner: AccessIter<'inst>,
 }
@@ -512,6 +592,11 @@ impl<'inst> Iterator for OperandIter<'inst> {
 }
 
 impl<'inst> InstBehavior<'inst> {
+    #[cfg(feature = "unstable")]
+    /// get the [`PrivilegeLevel`] for this instruction.
+    ///
+    /// returns `None` if no privilege level information is recorded for the instruction. such
+    /// cases are a bug, please report if you see them.
     pub fn privilege_level(&self) -> Option<PrivilegeLevel> {
         let pl_bits = self.behavior.behavior & 0b11;
         const LUT: [Option<PrivilegeLevel>; 4] = [
@@ -522,8 +607,11 @@ impl<'inst> InstBehavior<'inst> {
         LUT[pl_bits as usize]
     }
 
-    /// 
-//    #[cfg(feature = "unstable")]
+    #[cfg(feature = "unstable")]
+    /// get the [`ExceptionInfo`] for this instruction.
+    ///
+    /// this is very much best-effort and poorly tested. it is behind the `unstable` feature for a
+    /// reason!
     pub fn exceptions(&self) -> ExceptionInfo {
         let mut exceptions = ExceptionInfo::empty();
         if self.privilege_level() != Some(PrivilegeLevel::Any) {
@@ -545,15 +633,21 @@ impl<'inst> InstBehavior<'inst> {
         exceptions
     }
 
-    fn as_complex_op(&self) -> Option<ComplexOp> {
-        // if the behavior is not complex, it is *definitely* not complex. if the behavior is
+    /// transform this instruction's [`Opcode`] into a [`ComplexOp`], if the instruction is
+    /// "complex".
+    ///
+    /// documentation on [`ComplexOp`] covers what instructions are considered "complex" by
+    /// yaxpeax-x86 and why in more detail. correct analysis of a function (or program!) in the
+    /// presence of complex instructions may require consulting the Intel Software Developer's
+    /// Manual or AMD Architecture Programmer's Manual.
+    pub fn as_complex_op(&self) -> Option<ComplexOp> {
+        // if the behavior is not complex, it is *definitely* not a complex op. if the behavior is
         // complex, it's really a "depending on the specific instruction and operands it might
         // be"...
         if !self.behavior.is_complex() {
             return None;
         }
 
-        // TODO: all of these should be a `set_complex` bit.
         if self.inst.opcode == Opcode::BT {
             if self.inst.operands[0] != OperandSpec::RegMMM {
                 Some(ComplexOp::BT)
@@ -614,12 +708,17 @@ impl<'inst> InstBehavior<'inst> {
         })
     }
 
+    /// get the `Access` behavior this instruction has for `rflags`.
+    ///
+    /// note that as the documentation for [`Access`] describes, "read" and "write" have slightly
+    /// different meanings for the flags register than other locations.
+    // this implies that `rflags` must never appear in an implicit operand list.
     pub fn flags_access(&self) -> Option<Access> {
         let flag_acc = (self.behavior.behavior >> 2) & 0b11;
         Access::from_bits(flag_acc)
     }
 
-    pub fn implicit_oplist(&self) -> Option<&'static [ImplicitOperand]> {
+    fn implicit_oplist(&self) -> Option<&'static [ImplicitOperand]> {
         let ops_idx = self.behavior.extra;
         if ops_idx == 0 {
             return None;
@@ -629,8 +728,13 @@ impl<'inst> InstBehavior<'inst> {
         Some(&IMPLICIT_OPS_LIST[ops_idx as usize])
     }
 
+    /// get the `Access` behavor for an explicit operand of this instruction.
+    ///
+    /// `None` means that there is no operand at the given index, while `Some(Access::None)` means
+    /// there is an operand, and the instruction does not actually access it (as for `nop`, `ud0`,
+    /// and `ud1`)
     pub fn operand_access(&self, idx: u8) -> Option<Access> {
-        if idx >= 4 {
+        if idx >= self.inst.operand_count {
             return None;
         }
 
@@ -638,13 +742,24 @@ impl<'inst> InstBehavior<'inst> {
         Access::from_bits(op_acc)
     }
 
+    /// iterate all operands in the instruction and report them to the provided `AccessVisitor`.
+    ///
+    /// this is a more informative, but somewhat more specialized, interface than simply iterating
+    /// [`InstBehavior::all_operands()`]. for memory operands, address calculations are reported to
+    /// the access visitor as reads of the relevant registers. if all dependent values are
+    /// available, the resulting effective address is computed and reported as part of the memory
+    /// access.
+    ///
+    /// `visit_accesses()` is slightly more efficient in this than iterating `all_operands()` as
+    /// well, as it uses unstable internal representations directly, rather than converting to API
+    /// types and back for every operand.
     pub fn visit_accesses<T: AccessVisitor>(&self, v: &mut T) -> Result<(), ComplexOp> {
         if let Some(op) = self.as_complex_op() {
             return Err(op);
         }
 
         fn compute_addr<T: AccessVisitor>(v: &mut T, inst: &Instruction, op_spec: OperandSpec) -> Option<u64> {
-            // TODO: test assertions feature?
+            #[cfg(feature = "_debug_internal_asserts")]
             if !op_spec.is_memory() {
                 panic!("expected memory operand but got {:?}", op_spec);
             }
@@ -753,6 +868,8 @@ impl<'inst> InstBehavior<'inst> {
                     Some(inst.disp as u32 as u64)
                 }
                 other => {
+                    // this could be `_debug_internal_assertions`-gated, but i'm not quite that
+                    // confident yet..
                     panic!("not-yet-handled memory operand: {:?}", other);
                 }
             }
@@ -776,7 +893,11 @@ impl<'inst> InstBehavior<'inst> {
                         OperandSpec::Deref_edi => RegSpec::edi(),
                         OperandSpec::Deref_esi => RegSpec::esi(),
                         OperandSpec::Deref => self.inst.regs[1],
-                        other => { panic!("TODO: unreachable {:?}", other); }
+                        other => {
+                            // this could be `_debug_internal_assertions`-gated, but i'm not quite
+                            // that confident yet..
+                            panic!("TODO: unreachable {:?}", other);
+                        }
                     };
                     if op.write {
                         v.register_write(reg);
@@ -796,7 +917,9 @@ impl<'inst> InstBehavior<'inst> {
                             }
                         }
                         OperandSpec::MemIndexScale => {
-                            // HACK HACK HACK
+                            // HACK HACK HACK this is just how i've decided to interpret
+                            // `MemIndexScale` as an operand spec; it's only for xlat. adding
+                            // another field to implicit operands just for this is a little silly..
                             let base = v.get_register(op.reg);
                             let index = v.get_register(RegSpec::al());
                             if let (Some(base), Some(index)) = (base, index) {
@@ -806,6 +929,8 @@ impl<'inst> InstBehavior<'inst> {
                             }
                         }
                         other => {
+                            // this could be `_debug_internal_assertions`-gated, but i'm not quite
+                            // that confident yet..
                             panic!("impossible operand spec {:?}", other);
                         }
                     };
@@ -969,7 +1094,7 @@ impl<'inst> InstBehavior<'inst> {
                         if other.is_masked() && self.inst.prefixes.evex_unchecked().mask_reg() != 0 {
                             v.register_read(RegSpec::mask(self.inst.prefixes.evex_unchecked().mask_reg()));
                         }
-                        // no lea check necessary: the memory access is coded as a read and no
+                        // no lea check necessary: its memory access is coded as a read and no
                         // instruction has a similar "fake" memory write.
                         v.memory_write(addr, size as u32);
                     }
@@ -1045,17 +1170,23 @@ impl Access {
         LUT[bits as usize]
     }
 
+    /// is this access a read?
+    ///
+    /// if it is `ReadWrite`, this will be `true` as will `is_write`.
     pub fn is_read(&self) -> bool {
         *self as u8 & 0b01 != 0
     }
 
+    /// is this access a write?
+    ///
+    /// if it is `ReadWrite`, this will be `true` as will `is_read`.
     pub fn is_write(&self) -> bool {
         *self as u8 & 0b10 != 0
     }
 }
 
 #[derive(Copy, Clone, PartialEq, Debug)]
-pub struct BehaviorDigest {
+struct BehaviorDigest {
     // laid out like:
     //
     // |7 6|5 4|3 2|1 0|
@@ -1081,7 +1212,6 @@ pub struct BehaviorDigest {
     extra: u16,
 }
 
-// TODO: the various `set_pl*()` are not actually used yet..
 #[allow(dead_code)]
 impl BehaviorDigest {
     const fn empty() -> BehaviorDigest {
@@ -1457,9 +1587,13 @@ impl BehaviorDigest {
 ///
 /// TDX-related instructions are considered complex because they are not more precisely tested and
 /// are assumed as-complex-as-VMX in the first place.
+// TODO: this could be declared through a macro that does something like:
+// "declare_opcode_subset! { }" which gets a list of identifiers and generates the
+// `Opcode::<ident> as u32` rhs. but a vim macro will do for now.
 #[non_exhaustive]
 #[repr(u32)] // same repr as `Opcode`
 #[derive(Copy, Clone, Debug)]
+#[allow(missing_docs)]
 pub enum ComplexOp {
     /// rdmsr/wrmsr are considered "complex" for reasons in the enum doc comment.
     RDMSR = (Opcode::RDMSR as u32),
@@ -1765,13 +1899,30 @@ pub trait AccessVisitor {
     /// if any `get_register()` returns `None` in an address calculation, the subsequent
     /// `memory_read()` or `memory_write()` for that operand will be given an `address` of `None`.
     ///
-    /// if `get_register` is implemented withhout calling `register_read`, the 
-    /// if `get_register()` is given a custom implementation, be sure to either call `
+    /// `get_register()` may be implemented withhout calling `register_read()`, in which case when
+    /// used with `visit_accesses` the register/memory read/writes will all correspond directly to
+    /// implicit and explicit operands.
     fn get_register(&mut self, reg: RegSpec) -> Option<u64> {
         self.register_read(reg);
         None
     }
+    /// record that the instruction reads a memory location.
+    ///
+    /// when used with `visit_accesses`, an address is only provided when yaxpeax-x86 can calculate
+    /// an effective address (i.e. `get_register()` calls for all dependent registers return a
+    /// value). all non-`ComplexOp` instructions have a known memory access size, so this is always
+    /// reported regardless of if *where* is not known.
+    ///
+    /// some instructions can both read and write memory (consider `call [addr]`).
     fn memory_read(&mut self, address: Option<u64>, size: u32);
+    /// record that the instruction writes a memory location.
+    ///
+    /// when used with `visit_accesses`, an address is only provided when yaxpeax-x86 can calculate
+    /// an effective address (i.e. `get_register()` calls for all dependent registers return a
+    /// value). all non-`ComplexOp` instructions have a known memory access size, so this is always
+    /// reported regardless of if *where* is not known.
+    ///
+    /// some instructions can both read and write memory (consider `call [addr]`).
     fn memory_write(&mut self, address: Option<u64>, size: u32);
 }
 
@@ -4038,7 +4189,7 @@ static TABLE: [BehaviorDigest; 1413] = [
             .set_operand(0, Access::Read)
             .set_complex(true),
     /* VERR => */ GENERAL_R_FLAGWRITE,
-    /* VERW => */  GENERAL_R_FLAGWRITE,
+    /* VERW => */ GENERAL_R_FLAGWRITE,
     /* CMC => */ GENERAL_FLAGRW,
     /* CLC => */ GENERAL_FLAGRW,
     /* STC => */ GENERAL_FLAGRW,