From 48559b18574b44e2de879a5c641ab602ec22f0d8 Mon Sep 17 00:00:00 2001
From: iximeow <me@iximeow.net>
Date: Sun, 4 Jul 2021 12:20:13 -0700
Subject: fix several incorrect tests and docs in 64- and 32-bit modes

---
 src/lib.rs | 34 ++++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

(limited to 'src/lib.rs')

diff --git a/src/lib.rs b/src/lib.rs
index cb879fd..057c125 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -84,8 +84,8 @@ mod real_mode;
 pub use real_mode::Arch as x86_16;
 
 const MEM_SIZE_STRINGS: [&'static str; 64] = [
-    "byte", "word", "BUG", "dword", "far", "ptr", "BUG", "qword",
-    "far", "mword", "BUG", "BUG", "BUG", "BUG", "BUG", "xmmword",
+    "byte", "word", "BUG", "dword", "ptr", "far", "BUG", "qword",
+    "BUG", "mword", "BUG", "BUG", "BUG", "BUG", "BUG", "xmmword",
     "BUG", "BUG", "BUG", "BUG", "BUG", "BUG", "BUG", "BUG",
     "BUG", "BUG", "BUG", "BUG", "BUG", "BUG", "BUG", "ymmword",
     "BUG", "BUG", "BUG", "BUG", "BUG", "BUG", "BUG", "BUG",
@@ -98,6 +98,11 @@ pub struct MemoryAccessSize {
     size: u8,
 }
 impl MemoryAccessSize {
+    /// return the number of bytes referenced by this memory access.
+    ///
+    /// if the number of bytes cannot be confidently known by the instruction in isolation (as is
+    /// the case for `xsave`/`xrstor`-style "operate on all processor state" instructions), this
+    /// function will return `None`.
     pub fn bytes_size(&self) -> Option<u8> {
         if self.size == 63 {
             None
@@ -106,6 +111,31 @@ impl MemoryAccessSize {
         }
     }
 
+    /// a human-friendly label for the number of bytes this memory access references.
+    ///
+    /// there are some differences from size names that may be expected elsewhere; `yaxpeax-x86`
+    /// prefers to use consistent names for a width even if the way those bytes are used varies.
+    ///
+    /// the sizes `yaxpeax-x86` knows are as follows:
+    /// | size (bytes) | name       |
+    /// |--------------|------------|
+    /// | 1            | `byte`     |
+    /// | 2            | `word`     |
+    /// | 4            | `dword`    |
+    /// | 6            | `far`      |
+    /// | 8            | `qword`    |
+    /// | 10           | `mword`    |
+    /// | 16           | `xmmword`  |
+    /// | 32           | `ymmword`  |
+    /// | 64           | `zmmword`  |
+    /// | variable     | `ptr`      |
+    ///
+    /// "mword" refers to an mmx-sized access - 80 bits, or 10 bytes. `mword` is also used for
+    /// 64-bit far calls, because they reference a contiguous ten bytes; two bytes of segment
+    /// selector and eight bytes of address.
+    ///
+    /// "variable" accesses access a number of bytes dependent on the physical processor and its
+    /// operating mode. this is particularly relevant for `xsave`/`xrstor`-style instructions.
     pub fn size_name(&self) -> &'static str {
         MEM_SIZE_STRINGS[self.size as usize - 1]
     }
-- 
cgit v1.1