compiler.cfg.*: even more docs

basis/compiler/cfg/block-joining/block-joining-docs.factor

@@ -3,13 +3,19 @@ IN: compiler.cfg.block-joining
 
 HELP: join-block?
 { $values { "bb" basic-block } { "?" boolean } }
-{ $description "Whether the block can be joined with its predecessor or not." } ;
+{ $description "Whether the block can be joined with its predecessor or not. Two blocks can only be joined if:"
+  { $list
+    "Neither of them are kill blocks"
+    "They have only one predecessor and it has only one successor"
+    "The predecessor has a lower block number"
+  }
+} ;
 
 HELP: join-blocks
 { $values { "cfg" cfg } }
 { $description "A compiler pass when optimizing the cfg." } ;
 
 ARTICLE: "compiler.cfg.block-joining" "Block Joining"
-"Joining blocks that are not calls and are connected by a single CFG edge. This pass does not update " { $link ##phi } " nodes and should therefore only run before stack analysis." ;
+"Joining blocks that are not calls and are connected by a single CFG edge. This pass does not update " { $link ##phi } " nodes and should therefore only run before stack analysis or after ##phi node elimination." ;
 
 ABOUT: "compiler.cfg.block-joining"

basis/compiler/cfg/gc-checks/gc-checks-docs.factor

@@ -33,7 +33,8 @@ HELP: gc-check-offsets
 
 HELP: insert-gc-check?
 { $values { "bb" basic-block } { "?" boolean } }
-{ $description "Whether to insert a gc check in the block or not." } ;
+{ $description "Whether to insert a gc check in the block or not. Only blocks with allocation instructions require gc checks." }
+{ $see-also allocation-insn } ;
 
 HELP: insert-gc-checks
 { $values { "cfg" cfg }  }

basis/compiler/cfg/linear-scan/allocation/spilling/spilling-docs.factor

@@ -1,4 +1,5 @@
-USING: compiler.cfg.linear-scan.allocation.state
+USING: compiler.cfg.linear-scan
+compiler.cfg.linear-scan.allocation.state
 compiler.cfg.linear-scan.live-intervals help.markup help.syntax ;
 IN: compiler.cfg.linear-scan.allocation.spilling
 
@@ -7,20 +8,47 @@ HELP: assign-spill
 { $description "Assigns a spill slot for the live interval." }
 { $see-also assign-spill-slot } ;
 
+HELP: spill-after
+{ $values
+  { "after" live-interval-state }
+  { "after/f" { $link live-interval-state } " or " { $link f } }
+}
+{ $description "If the interval has no more usages after the spill location, then it is the first child of an interval that was split.  We spill the value and let the resolve pass insert a reload later. An interval may be split if it overlaps a " { $link sync-point } "." }
+{ $see-also spill-before } ;
+
+HELP: spill-available
+{ $values { "new" live-interval-state } { "pair" "2-tuple of score and register" } }
+{ $description "A register would become fully available if all active and inactive intervals using it were split and spilled." } ;
+
 HELP: spill-before
 { $values
   { "before" live-interval-state }
   { "before/f" { $link live-interval-state } " or " { $link f } }
 }
-{ $description "If the interval does not have any usages before the spill location, then it is the second child of an interval that was split. We reload the value and let the resolve pass insert a spill later." } ;
+{ $description "If the interval does not have any usages before the spill location, then it is the second child of an interval that was split. We reload the value and let the resolve pass insert a spill later." }
+{ $see-also spill-after } ;
+
+HELP: spill-intersecting
+{ $values { "new" live-interval-state } { "reg" "register" } }
+{ $description "Split and spill all active and inactive intervals which intersect 'new' and use 'reg'." } ;
 
 HELP: spill-intersecting-active
 { $values { "new" live-interval-state } { "reg" "register" } }
 { $description "If there is an active interval using 'reg' (there should be at most one) are split and spilled and removed from the inactive set." } ;
 
+HELP: spill-intersecting-inactive
+{ $values { "new" live-interval-state } { "reg" "register" } }
+{ $description "Any inactive intervals using 'reg' are split and spilled and removed from the inactive set." }
+{ $see-also inactive-intervals } ;
+
 HELP: spill-partially-available
 { $values
   { "new" live-interval-state }
   { "pair" "register availability status" }
 }
 { $description "A register would be available for part of the new interval's lifetime if all active and inactive intervals using that register were split and spilled." } ;
+
+ARTICLE: "compiler.cfg.linear-scan.allocation.spilling" "Spill slot assignment"
+"Words and dynamic variables for assigning spill slots to spilled registers during the " { $link linear-scan } " compiler pass." ;
+
+ABOUT: "compiler.cfg.linear-scan.allocation.spilling"

basis/compiler/cfg/linear-scan/allocation/spilling/spilling.factor

@@ -3,8 +3,8 @@
 USING: accessors assocs combinators
 compiler.cfg.linear-scan.allocation.splitting
 compiler.cfg.linear-scan.allocation.state
-compiler.cfg.linear-scan.live-intervals compiler.utilities fry
+compiler.cfg.linear-scan.live-intervals compiler.cfg.registers
-kernel linked-assocs locals math namespaces sequences ;
+compiler.utilities fry kernel linked-assocs locals math namespaces sequences ;
 IN: compiler.cfg.linear-scan.allocation.spilling
 
 ERROR: bad-live-ranges interval ;
@@ -59,9 +59,6 @@ ERROR: bad-live-ranges interval ;
     ] [ 2drop ] if ;
 
 : spill-after ( after -- after/f )
-    ! If the interval has no more usages after the spill location,
-    ! then it is the first child of an interval that was split.  We
-    ! spill the value and let the resolve pass insert a reload later.
     dup uses>> empty? [ drop f ] [
         {
             [ ]
@@ -115,8 +112,6 @@ ERROR: bad-live-ranges interval ;
     '[ _ remove-nth! drop  new start>> spill ] [ 2drop ] if ;
 
 :: spill-intersecting-inactive ( new reg -- )
-    ! Any inactive intervals using 'reg' are split and spilled
-    ! and removed from the inactive set.
     new inactive-intervals-for [
         dup reg>> reg = [
             dup new intervals-intersect? [
@@ -126,16 +121,11 @@ ERROR: bad-live-ranges interval ;
     ] filter! drop ;
 
 : spill-intersecting ( new reg -- )
-    ! Split and spill all active and inactive intervals
-    ! which intersect 'new' and use 'reg'.
     [ spill-intersecting-active ]
     [ spill-intersecting-inactive ]
     2bi ;
 
 : spill-available ( new pair -- )
-    ! A register would become fully available if all
-    ! active and inactive intervals using it were split
-    ! and spilled.
     [ first spill-intersecting ] [ register-available ] 2bi ;
 
 : spill-partially-available ( new pair -- )

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

@@ -30,6 +30,11 @@ HELP: compute-live-in
 { $description "Computes the live in registers for a basic block." }
 { $see-also machine-live-ins } ;
 
+HELP: insert-reload
+{ $values { "live-interval" live-interval-state } }
+{ $description "Inserts a " { $link ##reload } " instruction for a live interval." }
+{ $see-also insert-spill } ;
+
 HELP: machine-edge-live-ins
 { $var-description "Mapping from basic blocks to predecessors to values which are live on a particular incoming edge." } ;
 

basis/compiler/cfg/ssa/interference/interference-docs.factor

@@ -1,11 +1,16 @@
-USING: help.markup help.syntax ;
+USING: compiler.cfg help.markup help.syntax sequences ;
 IN: compiler.cfg.ssa.interference
 
+HELP: sets-interfere?
+{ $values { "seq1" sequence } { "seq2" sequence } }
+{ $description "Checks if two sets consisting of " { $link vreg-info } " instances interfere with each other. If they interfere, then copies can not be eliminated." } ;
+
 HELP: vreg-info
 { $class-description
   "Slots:"
   { $table
     { { $slot "vreg" } { "The vreg the vreg-info is the info for." } }
+    { { $slot "bb" } { "The " { $link basic-block } " in which the vreg is defined." } }
   }
 } ;