compiler.cfg.*: docs and more tests

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

@@ -80,3 +80,9 @@ HELP: trivial-branch?
 HELP: build-cfg
 { $values { "nodes" sequence } { "word" word } { "procedures" sequence } }
 { $description "Builds one or more cfgs from the given word." } ;
+
+ARTICLE: "compiler.cfg.builder"
+"Final stage of compilation generates machine code from dataflow IR"
+"Convert tree SSA IR to CFG IR. The result is not in SSA form; this is constructed later by calling compiler.cfg.ssa.construction:construct-ssa." ;
+
+ABOUT: "compiler.cfg.builder"

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

@@ -1,13 +1,12 @@
-USING: tools.test kernel sequences words sequences.private fry
-prettyprint alien alien.accessors math.private
-compiler.tree.builder compiler.tree.optimizer
-compiler.cfg.builder compiler.cfg.debugger
-compiler.cfg.optimizer compiler.cfg.rpo
-compiler.cfg.predecessors compiler.cfg.checker compiler.cfg
-arrays locals byte-arrays kernel.private math slots.private
-vectors sbufs strings math.partial-dispatch hashtables assocs
-combinators.short-circuit strings.private accessors
-compiler.cfg.instructions compiler.cfg.representations ;
+USING: accessors alien alien.accessors arrays assocs byte-arrays
+combinators.short-circuit compiler.cfg compiler.cfg.builder compiler.cfg.checker
+compiler.cfg.debugger compiler.cfg.instructions compiler.cfg.optimizer
+compiler.cfg.predecessors compiler.cfg.registers compiler.cfg.rpo
+compiler.cfg.stacks.local compiler.tree compiler.tree.builder
+compiler.tree.optimizer compiler.cfg.representations fry hashtables kernel
+kernel.private locals make math math.partial-dispatch math.private namespaces
+prettyprint sbufs sequences sequences.private slots.private strings
+strings.private  tools.test vectors words ;
 FROM: alien.c-types => int ;
 IN: compiler.cfg.builder.tests
 
@@ -236,3 +235,44 @@ IN: compiler.cfg.builder.tests
     [ tag 1 swap fixnum-shift-fast ]
     [ ##compare-integer-imm-branch? ] contains-insn?
 ] unit-test
+
+! make-input-map
+{
+    H{
+        { 81 T{ ds-loc { n 1 } } }
+        { 37 T{ ds-loc { n 2 } } }
+        { 92 T{ ds-loc } }
+    }
+} [
+    T{ #shuffle { in-d { 37 81 92 } } } make-input-map
+] unit-test
+
+! emit-node
+{
+    { T{ ##load-integer { dst 78 } { val 0 } } }
+} [
+    77 vreg-counter set-global
+    current-height new current-height set
+    H{ } clone replace-mapping set
+    [
+        T{ #push { literal 0 } { out-d { 8537399 } } } emit-node
+    ] { } make
+] unit-test
+
+{
+    T{ current-height { d 1 } { emit-d 1 } }
+    H{ { D -1 4 } { D 0 4 } }
+} [
+    0 vreg-counter set-global
+    current-height new current-height set
+    H{ } clone replace-mapping set
+    4 D 0 replace-loc
+    T{ #shuffle
+       { mapping { { 2 4 } { 3 4 } } }
+       { in-d V{ 4 } }
+       { out-d V{ 2 3 } }
+    } emit-node
+
+    current-height get
+    replace-mapping get
+] unit-test

basis/compiler/cfg/parallel-copy/parallel-copy-docs.factor

@@ -9,6 +9,10 @@ HELP: parallel-copy
 { $values { "mapping" { $link assoc } " of { dst src } virtual register pairs" } }
 { $description "Creates " { $link ##copy } " instructions." } ;
 
+HELP: parallel-copy-rep
+{ $values { "mapping" { $link assoc } " of { dst src } virtual register pairs" } }
+{ $description "Creates " { $link ##copy } " instructions." } ;
+
 ARTICLE: "compiler.cfg.parallel-copy" "Parallel copy"
 "Revisiting Out-of-SSA Translation for Correctness, Code Quality, and Efficiency http://hal.archives-ouvertes.fr/docs/00/34/99/25/PDF/OutSSA-RR.pdf, Algorithm 1" ;
 

basis/compiler/cfg/stacks/local/local-docs.factor

@@ -1,6 +1,11 @@
-USING: compiler.cfg compiler.cfg.registers help.markup help.syntax ;
+USING: assocs compiler.cfg compiler.cfg.registers help.markup help.syntax math
+sequences ;
 IN: compiler.cfg.stacks.local
 
+HELP: replace-mapping
+{ $var-description "An " { $link assoc } " that maps from stack locations to virtual registers that were put on the stack." }
+{ $see-also replace-loc } ;
+
 HELP: current-height
 { $class-description "A tuple used to keep track of the heights of the data and retain stacks in a " { $link basic-block } " The idea is that if the stack change instructions are tracked, then multiple changes can be folded into one. It has the following slots:"
   { $table
@@ -11,6 +16,18 @@ HELP: current-height
   }
 } ;
 
+HELP: loc>vreg
+{ $values { "loc" loc } { "vreg" "virtual register" } }
+{ $description "Maps a stack location to a virtual register." } ;
+
+HELP: replace-loc
+{ $values { "vreg" "virtual register" } { "loc" loc } }
+{ $description "Registers that the absolute stack location " { $snippet "loc" } " should be overwritten with the contents of the virtual register." } ;
+
+HELP: peek-loc
+{ $values { "loc" loc } { "vreg" "virtaul register" } }
+{ $description "Retrieves the virtual register and the given stack location." } ;
+
 HELP: translate-local-loc
 { $values { "loc" loc } { "loc'" loc } }
 { $description "Translates an absolute stack location to one that is relative to the current stacks height as given in " { $link current-height } "." }
@@ -22,16 +39,24 @@ HELP: translate-local-loc
   }
 } ;
 
-HELP: emit-height-changes
-{ $description "Emits stack height change instructions to the CFG being built. This is done when a " { $link basic-block } " is begun or ended." }
+HELP: height-changes
+{ $values { "current-height" current-height } { "insns" sequence } }
+{ $description "Converts a " { $link current-height } " tuple to 0-2 stack height change instructions." }
 { $examples
   { $example
-    "USING: compiler.cfg.stacks.local make namespaces prettyprint ;"
-    "T{ current-height { emit-d 4 } { emit-r -2 } } current-height set [ emit-height-changes ] { } make ."
+    "USING: compiler.cfg.stacks.local ;"
+    "T{ current-height { emit-d 4 } { emit-r -2 } } height-changes ."
     "{ T{ ##inc-d { n 4 } } T{ ##inc-r { n -2 } } }"
   }
 } ;
 
+HELP: emit-changes
+{ $description "! Insert height and stack changes prior to the last instruction." } ;
+
+HELP: inc-d
+{ $values { "n" number } }
+{ $description "Increases or decreases the current datastacks height." } ;
+
 ARTICLE: "compiler.cfg.stacks.local" "Local stack analysis"
 "Local stack analysis. We build three sets for every basic block in the CFG:"
 { $list

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

@@ -14,6 +14,10 @@ HELP: adjust-d
 { $values { "n" number } }
 { $description "Changes the height of the current data stack." } ;
 
+HELP: ds-store
+{ $values { "vreg" "a " { $link sequence } " of vregs." } }
+{ $description "Registers that a sequence of vregs are stored at at each corresponding index of the data stack." } ;
+
 HELP: rs-store
 { $values { "vregs" "a " { $link sequence } " of vregs." } }
 { $description "Stores one or more virtual register values on the retain stack. This modifies the " { $link current-height } " dynamic variable." } ;

basis/compiler/tests/optimizer.factor

@@ -2,11 +2,11 @@ USING: accessors arrays compiler.units generic hashtables
 stack-checker kernel kernel.private math prettyprint sequences
 sbufs strings tools.test vectors words sequences.private
 quotations classes classes.algebra classes.tuple.private
-continuations growable namespaces hints alien.accessors
+continuations growable memory namespaces hints alien.accessors
 compiler.tree.builder compiler.tree.optimizer sequences.deep
 compiler.test definitions generic.single shuffle math.order
 compiler.cfg.debugger classes.struct alien.syntax alien.data
-alien.c-types ;
+alien.c-types splitting ;
 IN: compiler.tests.optimizer
 
 GENERIC: xyz ( obj -- obj )
@@ -463,3 +463,8 @@ STRUCT: BitmapData { Scan0 void* } ;
         with-out-parameters Scan0>>
     ] compile-call
 ] unit-test
+
+! #1187
+{ } [
+    10 [ [ minor-gc split-slice ] [ drop ] recover ] times
+] unit-test