compiler.*: more compiler docs

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
+compiler.cfg.stack-frame compiler.tree cpu.x86.assembler.operands
-math namespaces sequences vectors words ;
+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 } ;

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

@@ -1,7 +1,7 @@
-USING: assocs compiler.cfg compiler.cfg.instructions
+USING: assocs compiler.cfg.instructions
-compiler.cfg.linear-scan.allocation compiler.cfg.linear-scan.allocation.state
+compiler.cfg.linear-scan.allocation.state
-compiler.cfg.linear-scan.live-intervals cpu.architecture hashtables help.markup
+compiler.cfg.linear-scan.live-intervals cpu.architecture hashtables
-help.syntax kernel sequences ;
+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 } ;
 

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?

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."

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
 } ;
 
 

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

@@ -1,5 +1,6 @@
-USING: assocs compiler.cfg compiler.cfg.def-use compiler.cfg.instructions
+USING: assocs compiler.cfg compiler.cfg.def-use
-compiler.cfg.representations hash-sets help.markup help.syntax kernel
+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"

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 } "." }