From 63a1e90af879f7c8b071ce45a1c45eb7638c010c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= <bjourne@gmail.com>
Date: Sat, 18 Apr 2015 13:08:09 +0200
Subject: [PATCH] compiler.cfg.ssa.cssa, compiler.cfg.ssa.destruction,
 compiler.utilities: docs & tests

---
 basis/compiler/cfg/ssa/cssa/cssa-docs.factor       |  7 +++++++
 basis/compiler/cfg/ssa/cssa/cssa.factor            |  4 ----
 .../cfg/ssa/destruction/destruction-docs.factor    | 12 ++++++++++++
 .../cfg/ssa/destruction/destruction.factor         | 14 --------------
 basis/compiler/utilities/utilities-docs.factor     |  7 +++++++
 basis/compiler/utilities/utilities-tests.factor    |  9 +++++++++
 6 files changed, 35 insertions(+), 18 deletions(-)
 create mode 100644 basis/compiler/cfg/ssa/cssa/cssa-docs.factor
 create mode 100644 basis/compiler/cfg/ssa/destruction/destruction-docs.factor
 create mode 100644 basis/compiler/utilities/utilities-docs.factor
 create mode 100644 basis/compiler/utilities/utilities-tests.factor

diff --git a/basis/compiler/cfg/ssa/cssa/cssa-docs.factor b/basis/compiler/cfg/ssa/cssa/cssa-docs.factor
new file mode 100644
index 0000000000..b516256508
--- /dev/null
+++ b/basis/compiler/cfg/ssa/cssa/cssa-docs.factor
@@ -0,0 +1,7 @@
+USING: compiler.cfg.representations help.markup help.syntax ;
+IN: compiler.cfg.ssa.cssa
+
+ARTICLE: "compiler.cfg.ssa.cssa" "Conventional SSA Form"
+"Convert SSA to conventional SSA. This pass runs after representation selection (see " { $link select-representations } "), so it must keep track of representations when introducing new values." ;
+
+ABOUT: "compiler.cfg.ssa.cssa"
diff --git a/basis/compiler/cfg/ssa/cssa/cssa.factor b/basis/compiler/cfg/ssa/cssa/cssa.factor
index ce472c8536..9b08c217c3 100644
--- a/basis/compiler/cfg/ssa/cssa/cssa.factor
+++ b/basis/compiler/cfg/ssa/cssa/cssa.factor
@@ -7,10 +7,6 @@ namespaces sequences ;
 FROM: assocs => change-at ;
 IN: compiler.cfg.ssa.cssa
 
-! Convert SSA to conventional SSA. This pass runs after representation
-! selection, so it must keep track of representations when introducing
-! new values.
-
 SYMBOLS: edge-copies phi-copies ;
 
 : init-copies ( bb -- )
diff --git a/basis/compiler/cfg/ssa/destruction/destruction-docs.factor b/basis/compiler/cfg/ssa/destruction/destruction-docs.factor
new file mode 100644
index 0000000000..b773447035
--- /dev/null
+++ b/basis/compiler/cfg/ssa/destruction/destruction-docs.factor
@@ -0,0 +1,12 @@
+USING: compiler.cfg.instructions help.markup help.syntax ;
+IN: compiler.cfg.ssa.destruction
+
+ARTICLE: "compiler.cfg.ssa.destruction" "SSA Destruction"
+"Because of the design of the register allocator, this pass has three peculiar properties."
+{ $list
+  "Instead of renaming vreg usages in the CFG, a map from vregs to canonical representatives is computed. This allows the register allocator to use the original SSA names to get reaching definitions."
+  { "Useless " { $link ##copy } " instructions, and all " { $link ##phi } " instructions, are eliminated, so the register allocator does not have to remove any redundant operations." }
+  { "This pass computes live sets and fills out the " { $slot "gc-roots" } " slots of GC maps with " { $vocab-link "compiler.cfg.liveness" } ", so the linear scan register allocator does not need to compute liveness again." }
+} ;
+
+ABOUT: "compiler.cfg.ssa.destruction"
diff --git a/basis/compiler/cfg/ssa/destruction/destruction.factor b/basis/compiler/cfg/ssa/destruction/destruction.factor
index c017578cf0..1c53e53c70 100644
--- a/basis/compiler/cfg/ssa/destruction/destruction.factor
+++ b/basis/compiler/cfg/ssa/destruction/destruction.factor
@@ -11,20 +11,6 @@ kernel locals make namespaces sequences sets ;
 FROM: namespaces => set ;
 IN: compiler.cfg.ssa.destruction
 
-! Because of the design of the register allocator, this pass
-! has three peculiar properties.
-!
-! 1) Instead of renaming vreg usages in the CFG, a map from
-! vregs to canonical representatives is computed. This allows
-! the register allocator to use the original SSA names to get
-! reaching definitions.
-! 2) Useless ##copy instructions, and all ##phi instructions,
-! are eliminated, so the register allocator does not have to
-! remove any redundant operations.
-! 3) This pass computes live sets and fills out GC maps with
-! compiler.cfg.liveness, so the linear scan register allocator
-! does not need to compute liveness again.
-
 ! Maps leaders to equivalence class elements.
 SYMBOL: class-element-map
 
diff --git a/basis/compiler/utilities/utilities-docs.factor b/basis/compiler/utilities/utilities-docs.factor
new file mode 100644
index 0000000000..66b2d77955
--- /dev/null
+++ b/basis/compiler/utilities/utilities-docs.factor
@@ -0,0 +1,7 @@
+USING: assocs compiler.cfg.ssa.destruction.leaders help.markup help.syntax math
+sequences ;
+IN: compiler.utilities
+
+HELP: compress-path
+{ $values { "source" integer } { "assoc" assoc } { "destination" integer } }
+{ $description "Gets the original definer for a vreg number. Then inserts a direct path from 'source' to that definer. For example if the assoc is " { $code "{ { 1 2 } { 2 3 } { 3 4 } { 4 4 } }" } "then the original definer of 1 is 4. The word is used by " { $link leader } " to figure out what the top leader of a vreg is." } ;
diff --git a/basis/compiler/utilities/utilities-tests.factor b/basis/compiler/utilities/utilities-tests.factor
new file mode 100644
index 0000000000..6e4d2d510c
--- /dev/null
+++ b/basis/compiler/utilities/utilities-tests.factor
@@ -0,0 +1,9 @@
+USING: compiler.utilities kernel tools.test ;
+IN: compiler.utilities.tests
+
+{
+    9
+    H{ { 9 9 } { 44 9 } { 7 9 } }
+} [
+    7 H{ { 7 44 } { 44 9 } { 9 9 } } [ compress-path ] keep
+] unit-test