cpu.*: docs and tests for words in the assembler

basis/cpu/architecture/architecture-docs.factor

@@ -67,7 +67,7 @@ HELP: immediate-arithmetic?
 
 HELP: machine-registers
 { $values { "assoc" assoc } }
-{ $description "Mapping from register class to machine registers." } ;
+{ $description "Mapping from register class to machine registers. Only registers not reserved by the Factor VM are included." } ;
 
 HELP: vm-stack-space
 { $values { "n" number } }
@@ -147,7 +147,7 @@ HELP: stack-cleanup
 } ;
 
 ARTICLE: "cpu.architecture" "CPU architecture description model"
-"The " { $vocab-link "cpu.architecture" } " vocab generic words and hooks that serves as an api for the compiler towards the cpu architecture."
+"The " { $vocab-link "cpu.architecture" } " vocab contains generic words and hooks that serves as an api for the compiler towards the cpu architecture."
 $nl
 "Register categories:"
 { $subsections machine-registers param-regs return-regs }

basis/cpu/x86/assembler/operands/operands-docs.factor

@@ -1,6 +1,42 @@
 USING: cpu.x86.assembler.operands.private help.markup help.syntax math ;
 IN: cpu.x86.assembler.operands
 
+HELP: indirect
+{ $class-description "Tuple that represents an indirect addressing operand. It has the following slots:"
+  { $table
+    { { $slot "index" } { "Register for the index value. It must not be " { $link ESP } " or " { $link RSP } "." } }
+    { { $slot "displacement" } { "An integer offset." } }
+  }
+} ;
+
 HELP: [RIP+]
 { $values { "displacement" number } { "indirect" indirect } }
-{ $description "Creates an indirect operand relative to the RIP register." } ;
+{ $description "Creates an indirect operand relative to the RIP register." }
+{ $examples
+  { $unchecked-example
+    "USING: cpu.x86.assembler cpu.x86.assembler.operands make tools.disassembler ;"
+    "[ 0x1234 [RIP+] EAX MOV ] B{ } make disassemble"
+    "00000000015cef50: 890534120000  mov [rip+0x1234], eax"
+  }
+} ;
+
+HELP: []
+{ $values { "base/displacement" "register or an integer" } { "indirect" indirect } }
+{ $description "Creates an indirect operand from a given address or " { $link register } "." } ;
+
+HELP: n-bit-version-of
+{ $values { "register" register } { "n" integer } { "register'" register } }
+{ $description "Returns a less wide version of the given register." } ;
+
+ARTICLE: "cpu.x86.assembler.operands" "x86 registers and memory operands"
+"Indirect operand constructors for various addressing formats:"
+{ $subsections [] [RIP+] [+] [++] [+*2+] [+*4+] [+*8+] }
+"Register correspondances:"
+{ $subsections
+  8-bit-version-of
+  16-bit-version-of
+  32-bit-version-of
+  64-bit-version-of
+  n-bit-version-of
+  native-version-of
+} ;

basis/cpu/x86/assembler/operands/operands-tests.factor

@@ -0,0 +1,14 @@
+USING: cpu.x86.assembler cpu.x86.assembler.operands
+cpu.x86.assembler.operands.private make tools.test ;
+IN: cpu.x86.assembler.operands.tests
+
+[ RCX RSP 2 0 <indirect> ] [ bad-index? ] must-fail-with
+
+{ B{ 72 137 12 153 } } [
+    [ RCX RBX 2 0 <indirect> RCX MOV ] B{ } make
+] unit-test
+
+! No specific encoding for RBP and R13
+{ B{ 73 137 76 157 0 } } [
+    [ R13 RBX 2 f <indirect> RCX MOV ] B{ } make
+] unit-test