compiler.cfg.*: lots of more compiler docs

diff --git a/basis/compiler/cfg/def-use/def-use-docs.factor b/basis/compiler/cfg/def-use/def-use-docs.factor
index 949cc9b43a932965e0b15e7b7fd36c0ae3a90406..ab76a277746f38af406969d92714e40f38dc75e1 100644 (file)
--- a/basis/compiler/cfg/def-use/def-use-docs.factor
+++ b/basis/compiler/cfg/def-use/def-use-docs.factor
@@ -1,7 +1,11 @@
-USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax
+USING: assocs compiler.cfg compiler.cfg.instructions help.markup help.syntax
 sequences ;
 IN: compiler.cfg.def-use
 
+HELP: compute-defs
+{ $values { "cfg" cfg } }
+{ $description "Computes a mapping from vregs to " { $link basic-block } " instances in which they are defined. The data is assigned to the " { $link defs } " dynamic variable." } ;
+
 HELP: compute-insns
 { $values { "cfg" cfg } }
 { $description "Computes a mapping from vregs to the instructions that define them and store the result in the " { $link insns } " variable. The " { $link insn-of } " word can then be used to access the assoc." } ;
@@ -17,9 +21,14 @@ HELP: defs-vregs
   }
 } ;
 
+HELP: insns
+{ $var-description { $link assoc } " mapping vreg integers to defining instructions." }
+{ $see-also compute-insns insn-of } ;
+
 HELP: insn-of
 { $values { "vreg" "virtual register" } { "insn" insn } }
-{ $description "Maps the vreg to the instruction that defined it." } ;
+{ $description "Maps the vreg to the instruction that defined it." }
+{ $see-also compute-insns } ;
 
 HELP: temp-vregs
 { $values { "insn" insn } { "seq" sequence } }
@@ -43,7 +52,7 @@ HELP: special-vreg-insns
 ARTICLE: "compiler.cfg.def-use" "Common code used by several passes for def-use analysis"
 "The " { $vocab-link "compiler.cfg.def-use" } " contains tools to correlate SSA instructions with virtual registers defined or used by them."
 $nl
-"Vregs for a given instruction:"
+"The def-use protocol -- vregs for a given instruction:"
 { $subsections
   defs-vregs
   temp-vregs

diff --git a/basis/compiler/cfg/def-use/def-use.factor b/basis/compiler/cfg/def-use/def-use.factor
index de95e5d910b3b5a3c6745b4632e16afbd4ea60d2..c32789eab9f915cdd04695488a65ac4918d059cb 100644 (file)
--- a/basis/compiler/cfg/def-use/def-use.factor
+++ b/basis/compiler/cfg/def-use/def-use.factor
@@ -11,7 +11,6 @@ IN: compiler.cfg.def-use
 
 ! Utilities for iterating over instruction operands
 
-! Def-use protocol
 GENERIC: defs-vregs ( insn -- seq )
 GENERIC: temp-vregs ( insn -- seq )
 GENERIC: uses-vregs ( insn -- seq )

diff --git a/basis/compiler/cfg/instructions/instructions-docs.factor b/basis/compiler/cfg/instructions/instructions-docs.factor
index a2236bcf0d501587173333cc798ae650288a4731..b5dc55065502accd25ff8a7a72dd3399be27d19c 100644 (file)
--- a/basis/compiler/cfg/instructions/instructions-docs.factor
+++ b/basis/compiler/cfg/instructions/instructions-docs.factor
@@ -1,4 +1,5 @@
 USING: alien arrays assocs classes compiler.cfg compiler.cfg.intrinsics.fixnum
+compiler.cfg.linear-scan.assignment compiler.cfg.liveness
 compiler.cfg.ssa.destruction compiler.cfg.value-numbering
 compiler.codegen.gc-maps cpu.architecture help.markup help.syntax kernel layouts
 math sequences slots.private system ;
@@ -136,7 +137,12 @@ HELP: ##peek
 
 HELP: ##phi
 { $class-description
-  "A special kind of instruction used to mark control flow. It is inserted by the " { $vocab-link "compiler.cfg.ssa.construction" } " vocab." } ;
+  "A special kind of instruction used to mark control flow. It is inserted by the " { $vocab-link "compiler.cfg.ssa.construction" } " vocab. It has the following slots:"
+  { $table
+    { { $slot "inputs" } { "An assoc containing as keys the blocks where the vreg was defined and as values the vreg." } }
+    { { $slot "dst" } { "A merged vreg for the value." } }
+  }
+} ;
 
 HELP: ##prologue
 { $class-description
@@ -229,6 +235,15 @@ HELP: ##vector>scalar
 { $notes "The two vregs must not necessarily share the same representation." }
 { $see-also %vector>scalar } ;
 
+HELP: ##vm-field
+{ $class-description "Instruction for loading a pointer to a vm field."
+  { $table
+    { { $slot "dst" } { "Register to load the field into." } }
+    { { $slot "offset" } { "Offset of the field relative to the vm address." } }
+  }
+}
+{ $see-also %vm-field } ;
+
 HELP: ##write-barrier
 { $class-description
   "An instruction for inserting a write barrier. This instruction is almost always inserted after a " { $link ##set-slot } " instruction. If the container object is in an older generation than the item inserted, this instruction guarantees that the item will not be garbage collected. It has the following slots:"
@@ -278,11 +293,14 @@ HELP: gc-map-insn
 HELP: gc-map
 { $class-description "A tuple that holds info necessary for a gc cycle to figure out where the gc root pointers are. It has the following slots:"
   { $table
-    { { $slot "gc-roots" } { "A " { $link sequence } " of " { $link spill-slot } " which will be traced in a gc cycle. " } }
+    {
+        { $slot "gc-roots" }
+        { "First a " { $link sequence } " of vregs that will be spilled during a gc. It is assigned in the " { $vocab-link "compiler.cfg.liveness" } " compiler pass. Then it is converted to a sequence of " { $link spill-slot } "s in " { $link assign-registers } "." }
+    }
     { { $slot "derived-roots" } { "An " { $link assoc } " of pairs of spill slots." } }
   }
 }
-{ $see-also emit-gc-info-bitmaps } ;
+{ $see-also emit-gc-info-bitmaps fill-gc-map } ;
 
 ARTICLE: "compiler.cfg.instructions" "Basic block instructions"
 "The " { $vocab-link "compiler.cfg.instructions" } " vocab contains all instruction classes used for generating CFG:s (Call Flow Graphs)."

diff --git a/basis/compiler/cfg/intrinsics/fixnum/fixnum-docs.factor b/basis/compiler/cfg/intrinsics/fixnum/fixnum-docs.factor
index 948d26d2fab471c69eec8e40cc7219fe02fdd937..c14078d6a3002f42478770bf2a299423c6176a0b 100644 (file)
--- a/basis/compiler/cfg/intrinsics/fixnum/fixnum-docs.factor
+++ b/basis/compiler/cfg/intrinsics/fixnum/fixnum-docs.factor
@@ -1,6 +1,11 @@
-USING: compiler.cfg.instructions help.markup help.syntax ;
+USING: compiler.cfg.instructions help.markup help.syntax layouts math ;
 IN: compiler.cfg.intrinsics.fixnum
 
+HELP: fixnum*overflow
+{ $values { "x" fixnum } { "y" fixnum } { "z" bignum } }
+{ $description "Word called to perform a fixnum multiplication when the product overflows the value storable in " { $link cell } "." }
+{ $see-also most-negative-fixnum most-positive-fixnum } ;
+
 HELP: emit-fixnum-comparison
 { $values { "cc" "comparison symbol" } }
 { $description "Emits a " { $link ##compare-integer } " instruction to the make sequence." } ;

diff --git a/basis/compiler/cfg/linear-scan/linear-scan-docs.factor b/basis/compiler/cfg/linear-scan/linear-scan-docs.factor
index 15ef0e76356342567a89e03dc6056bb9538dc3c4..dbd35011a2cdc9e0b151ab2b2775e9bf7c812dc3 100644 (file)
--- a/basis/compiler/cfg/linear-scan/linear-scan-docs.factor
+++ b/basis/compiler/cfg/linear-scan/linear-scan-docs.factor
@@ -5,6 +5,10 @@ HELP: admissible-registers
 { $values { "cfg" cfg } { "regs" assoc } }
 { $description "Lists all registers usable by the cfg by register class. In general, that's all registers except the frame pointer register that might be used by the cfg for other purposes." } ;
 
+HELP: linear-scan
+{ $values { "cfg" cfg } }
+{ $description "Entry point for the linear scan register alloation pass." } ;
+
 ARTICLE: "compiler.cfg.linear-scan" "Linear-scan register allocation"
 "Linear scan to assign physical registers. SSA liveness must have been computed already."
 $nl
@@ -13,7 +17,8 @@ $nl
   "Linear Scan Register Allocation by Massimiliano Poletto and Vivek Sarkar http://www.cs.ucla.edu/~palsberg/course/cs132/linearscan.pdf"
   "Linear Scan Register Allocation for the Java HotSpot Client Compiler by Christian Wimmer and http://www.ssw.uni-linz.ac.at/Research/Papers/Wimmer04Master/"
   "Quality and Speed in Linear-scan Register Allocation by Omri Traub, Glenn Holloway, Michael D. Smith http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.34.8435"
-} ;
-
+}
+"Optimization pass entry point:"
+{ $subsections linear-scan } ;
 
 ABOUT: "compiler.cfg.linear-scan"

diff --git a/basis/compiler/cfg/linear-scan/live-intervals/live-intervals-docs.factor b/basis/compiler/cfg/linear-scan/live-intervals/live-intervals-docs.factor
index f27e0dced09930ff9ce9b5c8fc18a78ec3d3ef53..b7de4f6b7a24778e17df15119c78be1d88f17a15 100644 (file)
--- a/basis/compiler/cfg/linear-scan/live-intervals/live-intervals-docs.factor
+++ b/basis/compiler/cfg/linear-scan/live-intervals/live-intervals-docs.factor
@@ -19,6 +19,9 @@ HELP: finish-live-intervals
 { $values { "live-intervals" sequence } { "seq" sequence } }
 { $description "Since live intervals are computed in a backward order, we have to reverse some sequences, and compute the start and end." } ;
 
+HELP: from
+{ $var-description "An integer representing a sequence number one lower than all numbers in the currently processed block." } ;
+
 HELP: live-interval-state
 { $class-description "A class encoding the \"liveness\" of a virtual register. It has the following slots:"
   { $table
@@ -58,6 +61,9 @@ HELP: live-interval-state
 HELP: live-intervals
 { $var-description "Mapping from vreg to " { $link live-interval-state } "." } ;
 
+HELP: live-range
+{ $class-description "Represents a range in the " { $link cfg } " in which a vreg is live." } ;
+
 HELP: sync-point
 { $class-description "A location where all registers have to be spilled. For example when garbage collection is run or an alien ffi call is invoked. Figuring out where in the " { $link cfg } " the sync points are is done in the " { $link compute-live-intervals } " step. The tuple has the following slots:"
   { $table
@@ -68,3 +74,20 @@ HELP: sync-point
 
 HELP: sync-points
 { $var-description "Sequence of sync points." } ;
+
+HELP: to
+{ $var-description "An integer representing a sequence number equal to the highest number in the currently processed block." } ;
+
+ARTICLE: "compiler.cfg.linear-scan.live-intervals" "Live interval utilities"
+"This vocab contains words for managing live intervals."
+$nl
+"Liveness classes and constructors:"
+{ $subsections
+  <live-interval>
+  <live-range>
+  live-interval
+  live-range
+} ;
+
+
+ABOUT: "compiler.cfg.linear-scan.live-intervals"

diff --git a/basis/compiler/cfg/liveness/liveness-docs.factor b/basis/compiler/cfg/liveness/liveness-docs.factor
index 43507732414bf640eeaebaf38298b6c1ec318d48..20565ebf4fc12ff85ad780b9649b2fdb96c0539e 100644 (file)
--- a/basis/compiler/cfg/liveness/liveness-docs.factor
+++ b/basis/compiler/cfg/liveness/liveness-docs.factor
@@ -38,6 +38,9 @@ HELP: live-ins
 { $var-description "Hash that maps from basic blocks to vregs that are live in them." }
 { $see-also compute-live-sets } ;
 
+HELP: live-outs
+{ $var-description "Hash that maps from basic blocks to sets of vregs that are live after execution leaves the block." } ;
+
 HELP: lookup-base-pointer
 { $values { "vreg" "vreg" } { "vreg/f" { $maybe "vreg" } } }
 { $description "Tries to figure out what the base pointer for a vreg is. Can't use cache here because of infinite recursion inside the quotation passed to cache" }
@@ -53,6 +56,9 @@ $nl
 }
 $nl
 "Querying liveness data:"
-{ $subsections live-in live-in? live-out live-out? } ;
+{ $subsections
+  live-in live-in? live-ins
+  live-out live-out? live-outs
+} ;
 
 ABOUT: "compiler.cfg.liveness"

diff --git a/basis/compiler/cfg/parallel-copy/parallel-copy-docs.factor b/basis/compiler/cfg/parallel-copy/parallel-copy-docs.factor
index dee440b60988720525c4ae6651e69775c53b4c40..7a4d44dfb0c10b85a5995f3dd6ff63867d144642 100644 (file)
--- a/basis/compiler/cfg/parallel-copy/parallel-copy-docs.factor
+++ b/basis/compiler/cfg/parallel-copy/parallel-copy-docs.factor
@@ -16,6 +16,9 @@ HELP: parallel-copy-rep
 { $description "Creates " { $link ##copy } " instructions. Representation selection must have been run previously." } ;
 
 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" ;
+"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"
+$nl
+"Generating " { $link ##copy } " instructions:"
+{ $subsections parallel-copy parallel-copy-rep } ;
 
 ABOUT: "compiler.cfg.parallel-copy"

diff --git a/basis/compiler/cfg/ssa/construction/construction-docs.factor b/basis/compiler/cfg/ssa/construction/construction-docs.factor
index 16fa879e71bb57cd7e9bdfd97388fd3a23d7550b..60b4a76dd7f019f9bab8b50a301a74aad4c53c3a 100644 (file)
--- a/basis/compiler/cfg/ssa/construction/construction-docs.factor
+++ b/basis/compiler/cfg/ssa/construction/construction-docs.factor
@@ -1,7 +1,11 @@
-USING: compiler.cfg.instructions compiler.cfg.ssa.construction.private
-help.markup help.syntax ;
+USING: compiler.cfg compiler.cfg.instructions
+compiler.cfg.ssa.construction.private help.markup help.syntax ;
 IN: compiler.cfg.ssa.construction
 
+HELP: <##phi>
+{ $values { "vreg" "vreg" } { "bb" basic-block } { "##phi" ##phi } }
+{ $description "Creates a new " { $link ##phi } " instruction given a vreg and a basic block." } ;
+
 HELP: phis
 { $var-description "Maps vregs to " { $link ##phi } " instructions." } ;
 
@@ -17,6 +21,12 @@ HELP: defs-multi
 HELP: inserting-phis
 { $var-description "Maps basic blocks to sequences of " { $link ##phi } " instructions." } ;
 
+HELP: pushed
+{ $var-description "Maps vregs to renaming stacks." } ;
+
+HELP: stacks
+{ $var-description "Maps vregs to renaming stacks." } ;
+
 ARTICLE: "compiler.cfg.ssa.construction" "SSA construction"
 "Iterated dominance frontiers are computed using the DJ Graph method in " { $vocab-link "compiler.cfg.ssa.construction.tdmsc" } "."
 $nl

diff --git a/basis/compiler/cfg/ssa/construction/construction.factor b/basis/compiler/cfg/ssa/construction/construction.factor
index 2cfbf7280cd9194c8c05da9a3d85a1e96181af2a..e8e963b0d8e4b41b127fa8c25f7daa30163a1fe8 100644 (file)
--- a/basis/compiler/cfg/ssa/construction/construction.factor
+++ b/basis/compiler/cfg/ssa/construction/construction.factor
@@ -4,10 +4,10 @@ USING: accessors assocs combinators compiler.cfg
 compiler.cfg.def-use compiler.cfg.dominance
 compiler.cfg.instructions compiler.cfg.registers
 compiler.cfg.renaming.functor compiler.cfg.rpo
-compiler.cfg.ssa.construction.tdmsc deques dlists fry kernel
-math namespaces sequences sets ;
+compiler.cfg.ssa.construction.tdmsc compiler.cfg.utilities deques dlists fry
+kernel math sequences sets ;
 FROM: assocs => change-at ;
-FROM: namespaces => set ;
+FROM: namespaces => set get ;
 IN: compiler.cfg.ssa.construction
 
 <PRIVATE
@@ -36,9 +36,11 @@ M: vreg-insn compute-insn-defs
 
 SYMBOL: inserting-phis
 
+: <##phi> ( vreg bb -- ##phi )
+    predecessors>> over '[ _ ] H{ } map>assoc ##phi new-insn ;
+
 : insert-phi-later ( vreg bb -- )
-    [ predecessors>> over '[ _ ] H{ } map>assoc ##phi new-insn ] keep
-    inserting-phis get push-at ;
+    [ <##phi> ] keep inserting-phis get push-at ;
 
 : compute-phis-for ( vreg bbs -- )
     members merge-set [ insert-phi-later ] with each ;
@@ -52,7 +54,6 @@ SYMBOL: phis
 
 SYMBOL: used-vregs
 
-! Maps vregs to renaming stacks
 SYMBOLS: stacks pushed ;
 
 : init-renaming ( -- )
@@ -124,8 +125,7 @@ M: vreg-insn rename-insn
     pop-stacks ;
 
 : rename ( cfg -- )
-    init-renaming
-    entry>> rename-in-block ;
+    init-renaming entry>> rename-in-block ;
 
 ! Live phis
 SYMBOL: live-phis

diff --git a/basis/compiler/cfg/ssa/destruction/destruction-docs.factor b/basis/compiler/cfg/ssa/destruction/destruction-docs.factor
index 886861693f222ebbc2df85bc1c55e2971675d418..8585c56d104de699f2c045b65e3a11f6542712d7 100644 (file)
--- a/basis/compiler/cfg/ssa/destruction/destruction-docs.factor
+++ b/basis/compiler/cfg/ssa/destruction/destruction-docs.factor
@@ -1,6 +1,6 @@
 USING: compiler.cfg compiler.cfg.instructions
-compiler.cfg.ssa.destruction.private compiler.cfg.ssa.interference help.markup
-help.syntax kernel sequences ;
+compiler.cfg.ssa.destruction.private compiler.cfg.ssa.destruction.leaders
+compiler.cfg.ssa.interference help.markup help.syntax kernel sequences ;
 IN: compiler.cfg.ssa.destruction
 
 HELP: class-element-map

diff --git a/basis/compiler/cfg/ssa/destruction/leaders/leaders-docs.factor b/basis/compiler/cfg/ssa/destruction/leaders/leaders-docs.factor
index cf4cf92a98c79ef11d7dc2b5b07676d82e960966..4cc85b3da6d1b4157c4078e02f198a7c4d616c2a 100644 (file)
--- a/basis/compiler/cfg/ssa/destruction/leaders/leaders-docs.factor
+++ b/basis/compiler/cfg/ssa/destruction/leaders/leaders-docs.factor
@@ -1,8 +1,13 @@
-USING: help.markup help.syntax math ;
+USING: compiler.cfg.ssa.destruction.private help.markup help.syntax math ;
 IN: compiler.cfg.ssa.destruction.leaders
 
+HELP: ?leader
+{ $values { "vreg" "vreg" } { "vreg'" "vreg" } }
+{ $description "The leader of the vreg or the register itself if it has no other leader." } ;
+
 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)." } ;
+{ $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). By default, each vreg is its own leader." }
+{ $see-also init-coalescing perform-coalescing } ;
 
 ARTICLE: "compiler.cfg.ssa.destruction.leaders" "Leader book-keeping" "This vocab defines words for getting the leaders of vregs." ;
 

diff --git a/basis/compiler/cfg/ssa/interference/interference-docs.factor b/basis/compiler/cfg/ssa/interference/interference-docs.factor
new file mode 100644 (file)
index 0000000..8874d58
--- /dev/null
+++ b/basis/compiler/cfg/ssa/interference/interference-docs.factor
@@ -0,0 +1,20 @@
+USING: help.markup help.syntax ;
+IN: compiler.cfg.ssa.interference
+
+HELP: vreg-info
+{ $class-description
+  "Slots:"
+  { $table
+    { { $slot "vreg" } { "The vreg the vreg-info is the info for." } }
+  }
+} ;
+
+
+ARTICLE: "compiler.cfg.ssa.interference" "Interference testing using SSA properties."
+"Interference testing using SSA properties"
+$nl
+"Based on:"
+$nl
+"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" ;
+
+ABOUT: "compiler.cfg.ssa.interference"

diff --git a/basis/compiler/cfg/ssa/interference/interference.factor b/basis/compiler/cfg/ssa/interference/interference.factor
index 722cc3104d54ec1716a896bc8c2bf5b17ef2add8..c6297d76ca725aa2c92dd88b8972185ba996c2b6 100644 (file)
--- a/basis/compiler/cfg/ssa/interference/interference.factor
+++ b/basis/compiler/cfg/ssa/interference/interference.factor
@@ -5,13 +5,6 @@ compiler.cfg.dominance compiler.cfg.ssa.interference.live-ranges
 kernel locals math math.order sequences sorting.slots ;
 IN: compiler.cfg.ssa.interference
 
-! Interference testing using SSA properties.
-!
-! Based on:
-!
-! 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
-
 TUPLE: vreg-info vreg value def-index bb pre-of color equal-anc-in equal-anc-out ;
 
 :: <vreg-info> ( vreg value bb -- info )