compiler.*: more compiler docs

diff --git a/basis/compiler/cfg/cfg-docs.factor b/basis/compiler/cfg/cfg-docs.factor
index 33db978d4e38c262bbc957c13021dc5a86ae748f..ae45d1c12cac334715d84a5cb1c6a193b664e768 100644 (file)
--- a/basis/compiler/cfg/cfg-docs.factor
+++ b/basis/compiler/cfg/cfg-docs.factor
@@ -1,6 +1,7 @@
 USING: compiler.cfg.instructions compiler.cfg.rpo
-compiler.cfg.stack-frame compiler.tree help.markup help.syntax kernel
-math namespaces sequences vectors words ;
+compiler.cfg.stack-frame compiler.tree cpu.x86.assembler.operands
+help.markup help.syntax kernel math namespaces sequences vectors words
+;
 IN: compiler.cfg
 
 HELP: basic-block
@@ -33,7 +34,7 @@ HELP: cfg
     { { $slot "word" } { "The " { $link word } " the cfg is produced from." } }
     { { $slot "post-order" } { "The blocks of the cfg in a post order traversal " { $link sequence } "." } }
     { { $slot "stack-frame" } { { $link stack-frame } " of the cfg." } }
-    { { $slot "frame-pointer?" } { "Whether the cfg needs a frame pointer. Only cfgs generated for " { $link #alien-callback } " nodes does need it." } }
+    { { $slot "frame-pointer?" } { "Whether the cfg needs a frame pointer. Only cfgs generated for " { $link #alien-callback } " nodes does need it. If the slot is " { $link t } ", then the frame pointer register (" { $link RBP } " on x86.64 archs) will not be clobbered by register allocation. See " { $vocab-link "compiler.cfg.linear-scan" } " for details." } }
   }
 }
 { $see-also <cfg> post-order } ;

diff --git a/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor b/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor
index 8c4f31c4684263660774f854330161259cd23373..8146c9a5a0814d9bc0d21a2520eb6bfe3653bffc 100644 (file)
--- a/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor
+++ b/basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor
@@ -1,7 +1,7 @@
-USING: assocs compiler.cfg compiler.cfg.instructions
-compiler.cfg.linear-scan.allocation compiler.cfg.linear-scan.allocation.state
-compiler.cfg.linear-scan.live-intervals cpu.architecture hashtables help.markup
-help.syntax kernel sequences ;
+USING: assocs compiler.cfg.instructions
+compiler.cfg.linear-scan.allocation.state
+compiler.cfg.linear-scan.live-intervals cpu.architecture hashtables
+help.markup help.syntax kernel sequences ;
 IN: compiler.cfg.linear-scan.allocation
 
 HELP: (allocate-registers)
@@ -25,7 +25,11 @@ HELP: assign-register
 { $description "Assigns a processor register to the live interval." } ;
 
 HELP: free-positions
-{ $values { "registers" assoc } { "reg-class" { $or int-regs float-regs } } { "avail-registers" assoc } }
+{ $values
+  { "registers" assoc }
+  { "reg-class" { $or int-regs float-regs } }
+  { "avail-registers" assoc }
+}
 { $description "Creates an alist mapping registers to their desirability for allocation. 'avail-registers' is an alist and not a " { $link hashtable } " because the register allocation order is significant." }
 { $see-also register-status } ;
 

diff --git a/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor b/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor
index 00728c7521cd89a80f84316ff2938315f6eed700..b3c23bc51b1547962db5fceb4e7fef7d69ac0770 100644 (file)
--- a/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor
+++ b/basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor
@@ -58,7 +58,7 @@ HELP: next-spill-slot
 { $description "Creates a new " { $link spill-slot } " of the given size and also allocates space in the " { $link cfg } " in the cfg for it." } ;
 
 HELP: progress
-{ $var-description "Start index of current live interval. We ensure that all live intervals added to the unhandled set have a start index strictly greater than this one. This ensures that we can catch infinite loop situations. We also ensure that all live intervals added to the handled set have an end index strictly smaller than this one. This helps catch bugs." }
+{ $var-description "Start index of current live interval. We ensure that all live intervals added to the unhandled set have a start index greater than or equal to this one. This ensures that we can catch infinite loop situations. We also ensure that all live intervals added to the handled set have an end index strictly smaller than this one. This helps catch bugs." }
 { $see-also check-handled check-unhandled } ;
 
 HELP: register-available?

diff --git a/basis/compiler/cfg/linear-scan/linear-scan-docs.factor b/basis/compiler/cfg/linear-scan/linear-scan-docs.factor
index fb1710f9b66f4c84501f13069da83ba590ab2940..765a1de8758f5211a7324bdc8df9d13f7e933246 100644 (file)
--- a/basis/compiler/cfg/linear-scan/linear-scan-docs.factor
+++ b/basis/compiler/cfg/linear-scan/linear-scan-docs.factor
@@ -11,7 +11,7 @@ HELP: allocate-and-assign-registers
 
 HELP: linear-scan
 { $values { "cfg" cfg } }
-{ $description "Entry point for the linear scan register alloation pass." } ;
+{ $description "Entry point for the linear scan register allocation pass." } ;
 
 ARTICLE: "compiler.cfg.linear-scan" "Linear-scan register allocation"
 "Linear scan to assign physical registers. SSA liveness must have been computed already. It also spills registers that are live during gc calls."

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 1c7058bf45eaf74f049936b91d4801f375833cd5..fe486c7cf1b7ef71b4d9ed820a95dabfb30d9023 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
@@ -32,9 +32,6 @@ HELP: compute-live-intervals
 { $description "Computes the live intervals and sync points of a cfg." }
 { $notes "The instructions must be numbered." } ;
 
-HELP: hairy-clobber-insn
-{ $class-description "Instructions that clobber registers. They receive inputs and  produce outputs in spill slots." } ;
-
 HELP: find-use
 { $values
   { "insn#" integer }
@@ -50,6 +47,13 @@ HELP: finish-live-interval
 HELP: from
 { $var-description "An integer representing a sequence number one lower than all numbers in the currently processed block." } ;
 
+HELP: hairy-clobber-insn
+{ $class-description "Instructions that clobber registers. They receive inputs and produce outputs in spill slots." } ;
+
+HELP: insn>sync-point
+{ $values { "insn" insn } { "sync-point/f" { $maybe sync-point } } }
+{ $description "If the instruction clobbers arbitrary registers, then a sync point for it is emitted. Most instructions don't so then " { $link f } " is returned instead." } ;
+
 HELP: intervals-intersect?
 { $values
   { "interval1" live-interval-state }
@@ -127,6 +131,11 @@ $nl
   record-def
   record-use
   record-temp
+}
+"Sync point handling:"
+{ $subsections
+  cfg>sync-points
+  insn>sync-point
 } ;
 
 

diff --git a/basis/compiler/cfg/liveness/liveness-docs.factor b/basis/compiler/cfg/liveness/liveness-docs.factor
index ce1c70fb0df1d191b16ff2c07e50efe477069462..1e8df96e625c19dc03eeebb246aca1cdbb17cbc3 100644 (file)
--- a/basis/compiler/cfg/liveness/liveness-docs.factor
+++ b/basis/compiler/cfg/liveness/liveness-docs.factor
@@ -1,5 +1,6 @@
-USING: assocs compiler.cfg compiler.cfg.def-use compiler.cfg.instructions
-compiler.cfg.representations hash-sets help.markup help.syntax kernel
+USING: assocs compiler.cfg compiler.cfg.def-use
+compiler.cfg.instructions compiler.cfg.representations
+cpu.architecture hash-sets help.markup help.syntax kernel math
 sequences ;
 IN: compiler.cfg.liveness
 
@@ -12,7 +13,7 @@ HELP: compute-live-sets
 { $description "Main entry point for vocab. Pass must only be run after representation selection. In this pass " { $slot "gc-roots" } " are set." } ;
 
 HELP: edge-live-ins
-{ $var-description "Assoc mapping basic blocks to sequences of sets of vregs; each sequence is in correspondence with a predecessor." } ;
+{ $var-description { $link assoc } " mapping basic blocks to sequences of sets of vregs; each sequence is in correspondence with a predecessor." } ;
 
 HELP: fill-gc-map
 { $values { "live-set" assoc } { "gc-map" gc-map } }
@@ -50,6 +51,21 @@ HELP: lookup-base-pointer
 { $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" }
 { $see-also base-pointers } ;
 
+HELP: visit-gc-root
+{ $values
+  { "vreg" integer }
+  { "derived-roots" assoc }
+  { "gc-roots" sequence }
+}
+{ $description "Handles a vreg that is live at a gc point. The vreg is handled in three ways depending on its representation:"
+  { $list
+    { "If it is " { $link tagged-rep } ", then the vreg contains a pointer to an object and it is added to the 'gc-roots' sequence." }
+    { "If it is " { $link int-rep } " and the vreg has a base pointer, then it is added to the 'derived-roots' assoc along with that base pointer." }
+    "Otherwise the vreg does not contain an object reference and nothing is done with it."
+  }
+}
+{ $see-also lookup-base-pointer } ;
+
 ARTICLE: "compiler.cfg.liveness" "Liveness analysis"
 "Similar to http://en.wikipedia.org/wiki/Liveness_analysis, with three additions:"
 $nl
@@ -63,6 +79,11 @@ $nl
 { $subsections
   live-in live-in? live-ins
   live-out live-out? live-outs
+}
+"Filling GC maps:"
+{ $subsections
+  lookup-base-pointer
+  visit-gc-root
 } ;
 
 ABOUT: "compiler.cfg.liveness"

diff --git a/basis/compiler/cfg/ssa/destruction/destruction-docs.factor b/basis/compiler/cfg/ssa/destruction/destruction-docs.factor
index ac231653708748de214fda4468c7416839f5951e..b19f894a99c2637941a24b6b9f8ac71fcf042ec0 100644 (file)
--- a/basis/compiler/cfg/ssa/destruction/destruction-docs.factor
+++ b/basis/compiler/cfg/ssa/destruction/destruction-docs.factor
@@ -12,6 +12,8 @@ HELP: destruct-ssa
 { $description "Main entry point for the SSA destruction compiler pass." } ;
 
 ARTICLE: "compiler.cfg.ssa.destruction" "SSA Destruction"
+"SSA destruction compiler pass. It is preceeded by " { $vocab-link "compiler.cfg.save-contexts" } " and followed by " { $vocab-link "compiler.cfg.linear-scan" } "."
+$nl
 "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. See " { $link leader-map } "." }