Docs: docs for compiler.* and cpu.* words

basis/compiler/codegen/codegen-docs.factor

@@ -1,4 +1,5 @@
-USING: alien byte-arrays compiler.cfg help.markup help.syntax literals
+USING: alien byte-arrays compiler.cfg compiler.codegen.labels
+compiler.codegen.relocation hashtables help.markup help.syntax literals make
 multiline sequences ;
 IN: compiler.codegen
 
@@ -49,13 +50,24 @@ USING: compiler.cfg.debugger io prettyprint ;
 ;
 >>
 
+HELP: labels
+{ $description { $link hashtable } " of mappings from " { $link basic-block } " to " { $link label } "." } ;
+
+HELP: lookup-label
+{ $values { "bb" basic-block } }
+{ $description "Sets and gets a " { $link label } " for the " { $link basic-block } ". The labels are used to generate branch instructions from one block to another." } ;
+
+HELP: generate-block
+{ $values { "bb" basic-block } }
+{ $description "Emits machine code to the current " { $link make } " sequence for one basic block." } ;
+
 HELP: generate
 { $values { "cfg" cfg } { "code" sequence } }
 { $description "Generates assembly code for the given cfg. The output " { $link sequence } " has six items with the following interpretations:"
   { $list
     { "The first element is a sequence of alien function symbols and " { $link dll } "s used by the cfg interleaved." }
     "The second item is the parameter table."
-    "The third item is the literal table."
+    { "The third item is the " { $link literal-table } "." }
     { "The third item is the relocation table as a " { $link byte-array } "." }
     "The fourth item is the label table."
     { "The fifth item is the generated assembly code as a " { $link byte-array } ". It still contains unresolved crossreferences." }
@@ -74,3 +86,10 @@ HELP: useless-branch?
   { "?" "A boolean value" }
 }
 { $description "If successor immediately follows bb in the linearization order, then a branch is is not needed." } ;
+
+HELP: init-fixup
+{ $description "Initializes variables needed for fixup." } ;
+
+HELP: check-fixup
+{ $values { "seq" "a " { $link sequence } " of generated machine code." } }
+{ $description "Used by " { $link with-fixup } " to ensure that the generated machine code is properly aligned." } ;

basis/compiler/codegen/labels/labels-docs.factor

@@ -0,0 +1,6 @@
+USING: help.markup help.syntax strings ;
+IN: compiler.codegen.labels
+
+HELP: define-label
+{ $values { "name" string } }
+{ $description "Defines a new label with the given name. The " { $slot "offset" } " slot is filled in later." } ;

basis/compiler/codegen/relocation/relocation-docs.factor

@@ -0,0 +1,26 @@
+USING: compiler.codegen.labels cpu.architecture help.markup help.syntax make
+strings ;
+IN: compiler.codegen.relocation
+
+HELP: add-literal
+{ $values { "obj" "a symbol" } }
+{ $description "Adds a symbol to the " { $link literal-table } "." } ;
+
+HELP: rel-safepoint
+{ $values { "class" "a relocation class" } }
+{ $description "Adds a safe point to the " { $link relocation-table } " for the current code offset. This word is used by the " { $link %safepoint } " generator." } ;
+
+HELP: compiled-offset
+{ $values { "n" "offset of the code being constructed in the current " { $link make } " sequence." } }
+{ $description "The current compiled code offset. Used for (among other things) calculating jump labels." }
+{ $examples
+  { $example
+    "USING: compiler.codegen.relocation cpu.x86.assembler cpu.x86.assembler.operands make prettyprint ;"
+    "[ init-relocation RAX 0 MOV compiled-offset ] B{ } make . ."
+    "B{ 72 184 0 0 0 0 0 0 0 0 }\n10"
+  }
+} ;
+
+HELP: resolve-label
+{ $values { "label/name" { $link label } " or " { $link string } } }
+{ $description "Assigns the current " { $link compiled-offset } " to the given label." } ;

basis/cpu/architecture/architecture-docs.factor

@@ -1,6 +1,31 @@
-USING: assocs cpu.x86.assembler help.markup help.syntax math system words ;
+USING: assocs cpu.x86.assembler help.markup help.syntax literals math
+multiline system words ;
 IN: cpu.architecture
 
+<<
+STRING: ex-%box-alien
+USING: compiler.codegen compiler.codegen.relocation cpu.architecture make ;
+init-fixup init-relocation [ RAX RBX RCX %box-alien ] B{ } make disassemble
+000000e9fcc720a0: 48b80100000000000000  mov rax, 0x1
+000000e9fcc720aa: 4885db                test rbx, rbx
+000000e9fcc720ad: 0f8400000000          jz dword 0xe9fcc720b3
+000000e9fcc720b3: 498d4d10              lea rcx, [r13+0x10]
+000000e9fcc720b7: 488b01                mov rax, [rcx]
+000000e9fcc720ba: 48c70018000000        mov qword [rax], 0x18
+000000e9fcc720c1: 4883c806              or rax, 0x6
+000000e9fcc720c5: 48830130              add qword [rcx], 0x30
+000000e9fcc720c9: 48c7400201000000      mov qword [rax+0x2], 0x1
+000000e9fcc720d1: 48c7400a01000000      mov qword [rax+0xa], 0x1
+000000e9fcc720d9: 48895812              mov [rax+0x12], rbx
+000000e9fcc720dd: 4889581a              mov [rax+0x1a], rbx
+;
+>>
+
+
+HELP: signed-rep
+{ $values { "rep" representation } { "rep'" representation } }
+{ $description "Maps any representation to its signed counterpart, if it has one." } ;
+
 HELP: immediate-arithmetic?
 { $values { "n" number } { "?" "a boolean" } }
 { $description
@@ -9,12 +34,15 @@ HELP: immediate-arithmetic?
 } ;
 
 HELP: machine-registers
+{ $values { "assoc" assoc } }
 { $description "Mapping from register class to machine registers." } ;
 
 HELP: vm-stack-space
+{ $values { "n" number } }
 { $description "Parameter space to reserve in anything making VM calls." } ;
 
 HELP: complex-addressing?
+{ $values { "?" "a boolean" } }
 { $description "Specifies if " { $link %slot } ", " { $link %set-slot } " and " { $link %write-barrier } " accept the 'scale' and 'tag' parameters, and if %load-memory and %store-memory work." } ;
 
 HELP: param-regs
@@ -29,6 +57,11 @@ HELP: %call
 { $values { "word" word } }
 { $description "Emits code for calling a word in Factor." } ;
 
+HELP: %box-alien
+{ $values { "dst" "destination register" } { "src" "source register" } { "temp" "temporary register" } }
+{ $description "Emits machine code for boxing an alien value." }
+{ $examples { $unchecked-example $[ ex-%box-alien ] } } ;
+
 HELP: fused-unboxing?
 { $values { "?" "a boolean" } }
 { $description "Whether this architecture support " { $link %load-float } ", " { $link %load-double } ", and " { $link %load-vector } "." } ;

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

@@ -0,0 +1,13 @@
+USING: compiler.codegen.labels cpu.x86.assembler help.markup help.syntax ;
+IN: cpu.x86.assembler
+
+HELP: JE
+{ $values { "dst" "destination address or " { $link label } } }
+{ $description "Emits a conditional jump instruction to the given address relative to the current code offset." }
+{ $examples
+  { $unchecked-example
+    "USING: cpu.x86.assembler make ;"
+    "[ 0x0 JE ] B{ } make disassemble"
+    "000000e9fcc71fe0: 0f8400000000  jz dword 0xe9fcc71fe6"
+  }
+} ;