Docs: more various compiler doc improvements

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

@@ -1,5 +1,6 @@
-USING: arrays classes compiler.cfg compiler.codegen.gc-maps cpu.architecture
-help.markup help.syntax kernel layouts sequences slots.private ;
+USING: arrays assocs classes compiler.cfg compiler.codegen.gc-maps
+cpu.architecture help.markup help.syntax kernel layouts sequences
+slots.private ;
 IN: compiler.cfg.instructions
 
 HELP: new-insn
@@ -74,6 +75,9 @@ HELP: ##alien-invoke
 HELP: alien-call-insn
 { $class-description "Union class of all alien call instructions." } ;
 
+HELP: def-is-use-insn
+{ $class-description "Union class of instructions that have complex expansions and require that the output registers are not equal to any of the input registers." } ;
+
 HELP: ##call
 { $class-description
   "An instruction for calling a Factor word."
@@ -184,6 +188,7 @@ 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 "derived-roots" } { "An " { $link assoc } " of pairs of spill slots." } }
   }
 }
 { $see-also emit-gc-info-bitmaps } ;
@@ -233,6 +238,8 @@ $nl
   ##callback-outputs
   ##local-allot
   ##unbox
+  ##unbox-alien
+  ##unbox-any-c-ptr
   ##unbox-long-long
   alien-call-insn
 }

basis/compiler/cfg/instructions/instructions.factor

@@ -875,8 +875,6 @@ hairy-clobber-insn
 ##box
 ##box-long-long ;
 
-! Instructions that have complex expansions and require that the
-! output registers are not equal to any of the input registers
 UNION: def-is-use-insn
 ##box-alien
 ##box-displaced-alien

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

@@ -4,3 +4,17 @@ IN: compiler.cfg.liveness
 HELP: fill-gc-map
 { $values { "live-set" "no idea" } { "insn" insn } }
 { $description "Assigns values to the " { $slot "gc-roots" } " and " { $slot "derived-roots" } " slots of an instructions " { $link gc-map } "." } ;
+
+HELP: edge-live-ins
+{ $var-description "Assoc mapping basic blocks to sequences of sets of vregs; each sequence is in correspondence with a predecessor." } ;
+
+ARTICLE: "compiler.cfg.liveness" "Liveness analysis"
+"Similar to http://en.wikipedia.org/wiki/Liveness_analysis, with three additions:"
+$nl
+{ $list
+  "With SSA, it is not sufficient to have a single live-in set per block. There is also an edge-live-in set per edge, consisting of phi inputs from each predecessor."
+  "Liveness analysis annotates call sites with GC maps indicating the spill slots in the stack frame that contain tagged pointers, and thus have to be visited if a GC occurs inside the call."
+  { "GC maps can contain derived pointers. A derived pointer is a pointer into the middle of a data heap object. Each derived pointer has a base pointer, to keep it up to date when objects are moved by the garbage collector. This extends live intervals and inserts new " { $link ##phi } " instructions." }
+} ;
+
+ABOUT: "compiler.cfg.liveness"

basis/compiler/cfg/liveness/liveness.factor

@@ -9,21 +9,6 @@ compiler.cfg.rpo cpu.architecture ;
 FROM: namespaces => set ;
 IN: compiler.cfg.liveness
 
-! Similar to http://en.wikipedia.org/wiki/Liveness_analysis,
-! with three additions:
-
-! 1) With SSA, it is not sufficient to have a single live-in set
-! per block. There is also there is an edge-live-in set per
-! edge, consisting of phi inputs from each predecessor.
-! 2) Liveness analysis annotates call sites with GC maps
-! indicating the spill slots in the stack frame that contain
-! tagged pointers, and thus have to be visited if a GC occurs
-! inside the call.
-! 3) GC maps can contain derived pointers. A derived pointer is
-! a pointer into the middle of a data heap object. Each derived
-! pointer has a base pointer, to keep it up to date when objects
-! are moved by the garbage collector. This extends live
-! intervals and inserts new ##phi instructions.
 SYMBOL: live-ins
 
 : live-in ( bb -- set )
@@ -34,8 +19,6 @@ SYMBOL: live-outs
 : live-out ( bb -- set )
     live-outs get at ;
 
-! Assoc mapping basic blocks to sequences of sets of vregs; each
-! sequence is in correspondence with a predecessor
 SYMBOL: edge-live-ins
 
 : edge-live-in ( predecessor basic-block -- set )

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

@@ -23,3 +23,7 @@ HELP: each-basic-block
 HELP: optimize-basic-block
 { $values { "bb" basic-block } { "quot" quotation } }
 { $description "Performs one " { $link simple-optimization } " step. The quotation takes the instructions of the basic block and returns them back in an optimized form." } ;
+
+HELP: simple-analysis
+{ $values { "cfg" cfg } { "quot" quotation } }
+{ $description "Applies a quotation to each sequence of instructions in each " { $link basic-block } " in the cfg." } ;