compiler.cfg.*: smaller doc improvements

basis/compiler/cfg/cfg-docs.factor

@@ -36,4 +36,5 @@ HELP: cfg
 
 HELP: cfg-changed
 { $values { "cfg" cfg } }
-{ $description "Resets all \"calculated\" slots in the cfg which forces them to be recalculated." } ;
+{ $description "Resets all \"calculated\" slots in the cfg which forces them to be recalculated." }
+{ $see-also predecessors-changed } ;

basis/compiler/cfg/instructions/instructions-docs.factor

@@ -1,6 +1,6 @@
-USING: alien arrays assocs classes compiler.cfg compiler.codegen.gc-maps
+USING: alien arrays assocs classes compiler.cfg compiler.cfg.value-numbering
-cpu.architecture help.markup help.syntax kernel layouts sequences
+compiler.codegen.gc-maps cpu.architecture help.markup help.syntax kernel
-slots.private system ;
+layouts sequences slots.private system ;
 IN: compiler.cfg.instructions
 
 HELP: new-insn
@@ -87,6 +87,24 @@ HELP: ##call
   "An instruction for calling a Factor word."
 } ;
 
+HELP: ##check-nursery-branch
+{ $class-description
+  "Instruction that inserts a conditional branch to a " { $link basic-block } " that garbage collects the nursery. The " { $vocab-link "compiler.cfg.gc-checks" } " vocab goes through each block in the " { $link cfg } " and checks if it allocates memory. If it does, then this instruction is inserted in the cfg before that block and checks if there is enough available space in the nursery. If it isn't, then a basic block containing code for garbage collecting the nursery is executed."
+  $nl
+  "It has the following slots:"
+  { $table
+    { { $slot "size" } { "Number of bytes the next block in the cfg will allocate." } }
+    { { $slot "cc" } { "A comparison symbol." } }
+    { { $slot "temp1" } { "First register that will be clobbered." } }
+    { { $slot "temp2" } { "Second register that will be clobbered." } }
+  }
+}
+{ $see-also %check-nursery-branch } ;
+
+HELP: ##mul-vector
+{ $class-description
+  "SIMD instruction." } ;
+
 HELP: ##set-slot
 { $class-description
   "An instruction for the non-primitive, non-immediate variant of " { $link set-slot } ". It has the following slots:"
@@ -169,19 +187,6 @@ HELP: ##peek
 HELP: ##safepoint
 { $class-description "Instruction that inserts a safe point in the generated code." } ;
 
-HELP: ##check-nursery-branch
-{ $class-description
-  "Instruction that inserts a conditional branch to a " { $link basic-block } " that garbage collects the nursery. The " { $vocab-link "compiler.cfg.gc-checks" } " vocab goes through each block in the " { $link cfg } " and checks if it allocates memory. If it does, then this instruction is inserted in the cfg before that block and checks if there is enough available space in the nursery. If it isn't, then a basic block containing code for garbage collecting the nursery is executed."
-  $nl
-  "It has the following slots:"
-  { $table
-    { { $slot "size" } { "Number of bytes the next block in the cfg will allocate." } }
-    { { $slot "cc" } { "A comparison symbol." } }
-    { { $slot "temp1" } { "Register symbol." } }
-    { { $slot "temp2" } { "Register symbol." } }
-  }
-} ;
-
 HELP: ##return
 { $class-description "Instruction that returns from a procedure call." } ;
 
@@ -197,6 +202,9 @@ HELP: ##compare-integer
 HELP: ##spill
 { $class-description "Instruction that copies a value from a register to a " { $link spill-slot } "." } ;
 
+HELP: ##store-memory-imm
+{ $class-description "Instruction that copies an 8 byte value from a XMM register to a memory location addressed by a normal register. This instruction is often turned into a cheaper " { $link ##store-memory } " instruction in the " { $link value-numbering } " pass." } ;
+
 HELP: gc-map-insn
 { $class-description "Union class of all instructions that contain subroutine calls to functions which allocate memory. Each of the instances has a " { $snippet "gc-map" } " slot." } ;
 
@@ -229,18 +237,6 @@ $nl
   ##phi
   ##return
 }
-"Comparison instructions:"
-{ $subsections
-  ##compare
-  ##compare-imm
-  ##compare-integer
-  ##compare-integer-branch
-  ##compare-integer-imm-branch
-  ##test
-  ##test-branch
-  ##test-imm
-  ##test-imm-branch
-}
 "Alien calls and FFI:"
 { $subsections
   ##alien-assembly
@@ -268,10 +264,29 @@ $nl
   gc-map-insn
   <gc-map>
 }
+"Comparison instructions:"
+{ $subsections
+  ##compare
+  ##compare-imm
+  ##compare-integer
+  ##compare-integer-branch
+  ##compare-integer-imm-branch
+  ##test
+  ##test-branch
+  ##test-imm
+  ##test-imm-branch
+}
 "Constant loading:"
 { $subsections
   ##load-integer
   ##load-reference
+}
+"Floating point instructions:"
+{ $subsections
+  ##add-float
+  ##div-float
+  ##mul-float
+  ##sub-float
 }
  "Integer arithmetic and bit operations:"
 { $subsections
@@ -304,6 +319,15 @@ $nl
   ##set-slot-imm
   ##write-barrier
 }
+"SIMD instructions"
+{ $subsections
+  ##add-vector
+  ##add-sub-vector
+  ##div-vector
+  ##mul-vector
+  ##store-memory-imm
+  ##sub-vector
+}
 "Stack height manipulation:"
 { $subsections
   ##inc

basis/compiler/cfg/linear-scan/assignment/assignment-docs.factor

@@ -1,33 +1,46 @@
-USING: assocs compiler.cfg compiler.cfg.instructions heaps help.markup
+USING: assocs compiler.cfg compiler.cfg.instructions
+compiler.cfg.linear-scan.live-intervals compiler.cfg.registers heaps help.markup
 help.syntax math ;
 IN: compiler.cfg.linear-scan.assignment
 
+HELP: add-pending
+{ $values { "live-interval" live-interval-state } }
+{ $description "Adds a live interval to the pending interval set." } ;
+
+HELP: assign-derived-roots
+{ $values { "gc-map" gc-map } }
+{ $description "Assigns pairs of spill slots for all derived roots in a gc map." } ;
+{ assign-gc-roots assign-derived-roots } related-words
+
+HELP: assign-gc-roots
+{ $values { "gc-map" gc-map } }
+{ $description "Assigns spill slots for all gc roots in a gc map." } ;
+
+HELP: assign-registers-in-insn
+{ $values { "insn" insn } }
+{ $description "Assigns physical registers and spill slots for the virtual registers used by the instruction." } ;
+
+HELP: machine-edge-live-ins
+{ $var-description "Mapping from basic blocks to predecessors to values which are live on a particular incoming edge." } ;
+
 HELP: machine-live-ins
 { $var-description "Mapping from basic blocks to values which are live at the start on all incoming CFG edges." } ;
 
 HELP: machine-live-outs
 { $var-description "Mapping from " { $link basic-block } " to an " { $link assoc } " of pairs which are the values that are live at the end. The keys of the pairs are virtual registers and the values are either real registers or spill slots." } ;
 
+HELP: remove-pending
+{ $values { "live-interval" live-interval-state } }
+{ $description "Removes a pending live interval." } ;
+
 HELP: unhandled-intervals
 { $var-description { $link min-heap } " of live intervals which still need a register allocation." } ;
 
-HELP: assign-registers-in-insn
-{ $values { "insn" insn } }
-{ $description "Assigns physical registers and spill slots for the virtual registers used by the instruction." } ;
-
-HELP: assign-gc-roots
-{ $values { "gc-map" gc-map } }
-{ $description "Assigns spill slots for all gc roots in a gc map." } ;
-
-HELP: assign-derived-roots
-{ $values { "gc-map" gc-map } }
-{ $description "Assigns pairs of spill slots for all derived roots in a gc map." } ;
-
-{ assign-gc-roots assign-derived-roots } related-words
-
 HELP: vreg>reg
 { $values { "vreg" "virtual register" } { "reg" "register" } }
-{ $description "If a live vreg is not in the pending set, then it must have been spilled." } ;
+{ $description "If a live vreg is not in the pending set, then it must have been spilled." }
+{ $errors "Can throw a " { $link bad-vreg } " error." }
+{ $see-also pending-interval-assoc } ;
 
 HELP: vregs>regs
 { $values { "vregs" "a sequence of virtual registers" } { "assoc" assoc } }
@@ -39,7 +52,9 @@ HELP: vreg>spill-slot
 
 ARTICLE: "compiler.cfg.linear-scan.assignment" "Assigning registers to live intervals"
 "The " { $vocab-link "compiler.cfg.linear-scan.assignment" } " assigns registers to live intervals." $nl
+"Pending intervals:"
+{ $subsections add-pending pending-interval-assoc remove-pending }
 "Vreg transformations:"
-{ $subsections vreg>reg vreg>spill-slot } ;
+{ $subsections vreg>reg vreg>spill-slot vregs>regs } ;
 
 ABOUT: "compiler.cfg.linear-scan.assignment"

basis/compiler/cfg/linear-scan/assignment/assignment.factor

@@ -34,11 +34,10 @@ ERROR: not-spilled-error vreg ;
     dup vreg>reg dup spill-slot? [ nip ] [ drop leader not-spilled-error ] if ;
 
 : vregs>regs ( vregs -- assoc )
-    [ f ] [ [ dup vreg>reg ] H{ } map>assoc ] if-empty ;
+    [ dup vreg>reg ] H{ } map>assoc ;
 
 SYMBOL: unhandled-intervals
 
-! Liveness info is used by resolve pass
 SYMBOL: machine-live-ins
 
 : machine-live-in ( bb -- assoc )
@@ -47,8 +46,6 @@ SYMBOL: machine-live-ins
 : compute-live-in ( bb -- )
     [ live-in keys vregs>regs ] keep machine-live-ins get set-at ;
 
-! Mapping from basic blocks to predecessors to values which are
-! live on a particular incoming edge
 SYMBOL: machine-edge-live-ins
 
 : machine-edge-live-in ( predecessor bb -- assoc )

basis/compiler/cfg/liveness/liveness-docs.factor

@@ -1,10 +1,18 @@
-USING: compiler.cfg.instructions help.markup help.syntax ;
+USING: assocs compiler.cfg compiler.cfg.instructions help.markup help.syntax ;
 IN: compiler.cfg.liveness
 
 HELP: fill-gc-map
 { $values { "live-set" "no idea" } { "insn" insn } }
 { $description "Assigns values to the " { $slot "gc-roots" } " and " { $slot "derived-roots" } " slots of an instructions " { $link gc-map } "." } ;
 
+HELP: live-in
+{ $values { "bb" basic-block } { "set" assoc } }
+{ $description "All the virtual registers that are live in a basic block." } ;
+
+HELP: live-in?
+{ $values { "vreg" "virtual register" } { "bb" basic-block } { "?" "a boolean" } }
+{ $description "Whether the vreg is live in the block or not." } ;
+
 HELP: edge-live-ins
 { $var-description "Assoc mapping basic blocks to sequences of sets of vregs; each sequence is in correspondence with a predecessor." } ;
 

basis/compiler/cfg/liveness/liveness-tests.factor

@@ -6,6 +6,13 @@ tools.test vectors alien math compiler.cfg.comparisons
 cpu.x86.assembler.operands assocs ;
 IN: compiler.cfg.liveness.tests
 
+! visit-insn
+{
+    H{ }
+} [
+    H{ } clone T{ ##peek f 0 D 0 } visit-insn
+] unit-test
+
 : test-liveness ( -- )
     1 get block>cfg compute-live-sets ;
 

basis/compiler/cfg/ssa/destruction/leaders/leaders-docs.factor

@@ -0,0 +1,9 @@
+USING: help.markup help.syntax math ;
+IN: compiler.cfg.ssa.destruction.leaders
+
+HELP: leader-map
+{ $var-description "A map from vregs to canonical representatives due to coalescing done by SSA destruction. Used by liveness analysis and the register allocator, so we can use the original SSA names to get certain info (reaching definitions, representations)." } ;
+
+ARTICLE: "compiler.cfg.ssa.destruction.leaders" "Leader book-keeping" "This vocab defines words for getting the leaders of vregs." ;
+
+ABOUT: "compiler.cfg.ssa.destruction.leaders"

basis/compiler/cfg/ssa/destruction/leaders/leaders.factor

@@ -3,11 +3,6 @@
 USING: compiler.utilities kernel namespaces ;
 IN: compiler.cfg.ssa.destruction.leaders
 
-! A map from vregs to canonical representatives due to
-! coalescing done by SSA destruction.  Used by liveness
-! analysis and the register allocator, so we can use the
-! original SSA names to get certain info (reaching definitions,
-! representations).
 SYMBOL: leader-map
 
 : leader ( vreg -- vreg' ) leader-map get compress-path ;