compiler.cfg.*: bunch of doc updates

basis/compiler/cfg/loop-detection/loop-detection-docs.factor

@@ -0,0 +1,6 @@
+USING: compiler.cfg help.markup help.syntax ;
+IN: compiler.cfg.loop-detection
+
+HELP: needs-loops
+{ $values { "cfg" cfg } }
+{ $description "Runs loop detection for the cfg if it isn't valid." } ;

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

@@ -2,33 +2,36 @@ USING: compiler.cfg.instructions cpu.architecture help.markup help.syntax
 math ;
 IN: compiler.cfg.registers
 
-HELP: vreg-counter
-{ $var-description "Virtual registers, used by CFG and machine IRs, are just integers." } ;
+HELP: loc
+{ $class-description "Represents a location on the stack. 'n' is an index starting from the top of the stack going down. So 0 is the top of the stack, 1 is what would be the top of the stack after a 'drop', and so on. It has two subclasses, " { $link ds-loc } " for data stack location and " { $link rs-loc } " for locations on the retain stack." } ;
 
 HELP: next-vreg
 { $values { "vreg" number } }
 { $description "Creates a new virtual register identifier." }
 { $notes "This word cannot be called after representation selection has run; use " { $link next-vreg-rep } " in that case." } ;
 
+HELP: next-vreg-rep
+{ $values { "rep" representation } { "vreg" number } }
+{ $description "Creates a new virtual register identifier and sets its representation." }
+{ $notes "This word cannot be called before representation selection has run; use " { $link next-vreg } " in that case." } ;
+
+
 HELP: rep-of
 { $values { "vreg" number } { "rep" representation } }
 { $description "Gets the representation for a virtual register. This word cannot be called before representation selection has run; use any-rep for " { $link ##copy } " instructions and so on." }
 { $notes "Throws " { $link bad-vreg } " if the representation for the vreg isn't known." } ;
 
 HELP: representations
-{ $var-description "Mapping from vregs to their representations." } ;
+{ $var-description "Mapping from vregs to their representations. This data is set by the "
+  { $vocab-link "compiler.cfg.representations.conversion" } " vocab." }
+{ $see-also rep-of } ;
 
 HELP: set-rep-of
 { $values { "rep" representation } { "vreg" number } }
 { $description "Sets the representation for a virtual register." } ;
 
-HELP: next-vreg-rep
-{ $values { "rep" representation } { "vreg" number } }
-{ $description "Creates a new virtual register identifier and sets its representation." }
-{ $notes "This word cannot be called before representation selection has run; use " { $link next-vreg } " in that case." } ;
-
-HELP: loc
-{ $class-description "Represents a location on the stack. 'n' is an index starting from the top of the stack going down. So 0 is the top of the stack, 1 is what would be the top of the stack after a 'drop', and so on. It has two subclasses, " { $link ds-loc } " for data stack location and " { $link rs-loc } " for locations on the retain stack." } ;
+HELP: vreg-counter
+{ $var-description "Virtual registers, used by CFG and machine IRs, are just integers." } ;
 
 ARTICLE: "compiler.cfg.registers" "Virtual single-assignment registers"
 "Virtual register assignment." ;

basis/compiler/cfg/representations/conversion/conversion-docs.factor

@@ -0,0 +1,7 @@
+USING: cpu.architecture help.markup help.syntax make ;
+IN: compiler.cfg.representations.conversion
+
+HELP: tagged>rep
+{ $values { "dst" "vreg" } { "src" "vreg" } { "rep" representation } }
+{ $description "Emits an instruction to the current " { $link make }
+  " sequence for converting a tagged value of the givern representation to an untagged one." } ;

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

@@ -1,6 +1,9 @@
-USING: help.markup help.syntax ;
+USING: cpu.architecture help.markup help.syntax ;
 IN: compiler.cfg.representations
 
-ARTICLE: "compiler.cfg.representations" "Virtual register representation selection" "Virtual register representation selection. This is where decisions about integer tagging and float and vector boxing are made. The appropriate conversion operations inserted after a cost analysis." ;
+ARTICLE: "compiler.cfg.representations" "Virtual register representation selection"
+"Virtual register representation selection. This is where decisions about integer tagging and float and vector boxing are made. The appropriate conversion operations inserted after a cost analysis."
+$nl
+"Good representation selection is very important for Factor because it uses tagged pointers. If the best representations are selected, then the number of conversions between " { $link int-rep } " and " { $link tagged-rep } " is minimized." ;
 
 ABOUT: "compiler.cfg.representations"

basis/compiler/cfg/representations/rewrite/rewrite-docs.factor

@@ -0,0 +1,14 @@
+USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax
+sequences ;
+IN: compiler.cfg.representations.rewrite
+
+HELP: alternatives
+{ $var-description "Mapping from vreg,rep pairs to vregs." } ;
+
+HELP: conversions-for-block
+{ $values { "insns" sequence } }
+{ $description "Inserts the required conversions in the blocks instruction sequence." } ;
+
+HELP: insert-conversions
+{ $values { "cfg" cfg } }
+{ $description "The last step in " { $vocab-link "compiler.cfg.representations" } ". Here instructions such as " { $link ##shl-imm } " and " { $link ##shr-imm } " are inserted to convert between tagged and untagged value types." } ;

basis/compiler/cfg/representations/rewrite/rewrite.factor

@@ -10,7 +10,6 @@ IN: compiler.cfg.representations.rewrite
 ! Insert conversions. This introduces new temporaries, so we need
 ! to rename opearands too.
 
-! Mapping from vreg,rep pairs to vregs
 SYMBOL: alternatives
 
 :: (emit-def-conversion) ( dst preferred required -- new-dst' )

basis/compiler/cfg/representations/selection/selection-docs.factor

@@ -2,12 +2,15 @@ USING: help.markup help.syntax math sequences ;
 IN: compiler.cfg.representations.selection
 
 HELP: costs
-{ $var-description "Maps vreg to representation to cost." } ;
+{ $var-description "Maps vreg to representation to cost. The costs for each vreg is represented as a hashtable where the keys are representation singletons and the values the costs of using that representation." } ;
 
 HELP: increase-cost
 { $values { "rep" "representation symbol" } { "scc" "?" } { "factor" integer } }
 { $description "Increase cost of keeping vreg in rep, making a choice of rep less likely. If the rep is not in the cost alist, it means this representation is prohibited." } ;
 
+HELP: inert-tag-untag-insn
+{ $class-description "Class of instructions that are binary and inert with respect to tagging. Those instructions often doesn't need untagging and retagging because the operations can be performed on their tagged representations." } ;
+
 HELP: init-costs
 { $description "Initialize cost as 0 for each possibility." } ;
 
@@ -15,5 +18,13 @@ HELP: minimize-costs
 { $values { "costs" sequence } { "representations" sequence } }
 { $description "For every vreg, compute preferred representation, that minimizes costs." } ;
 
+HELP: possibilities
+{ $var-description "Hashtable mapping vregs to to their possible representations." } ;
+
 HELP: tagged-vregs
 { $var-description "Vregs which must be tagged at the definition site because there is at least one usage that is not int-rep. If all usages are int-rep it is safe to untag at the definition site." } ;
+
+ARTICLE: "compiler.cfg.representations.selection" "Assign representations to vregs"
+"This is the second last step in the representation selection compiler pass. Each vreg is assigned a machine representation which is any of the representations in the " { $vocab-link "cpu.architecture" } ;
+
+ABOUT: "compiler.cfg.representations.selection"

basis/compiler/cfg/stack-frame/stack-frame-docs.factor

@@ -2,9 +2,9 @@ USING: compiler.cfg.instructions cpu.x86 help.markup help.syntax layouts math ;
 IN: compiler.cfg.stack-frame
 
 HELP: stack-frame
-{ $class-description "Counts of, among other things, how much stack a compiled word needs. The stack frame is organized in the following fashion:"
+{ $class-description "Counts in bytes of the various sizes of the blocks of the stack frame. The stack frame is organized in the following fashion, from bottom to top:"
   { $list
-    "Parameter space:"
+    "Parameter space: space for parameters to FFI functions "
     "Allocation area: space for local allocations."
     "Spill area: space for register spills."
     { "Reserved stack space: only applicable on Windows x86.64. See " { $link reserved-stack-space } "." }

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

@@ -27,11 +27,11 @@ HELP: store-vregs
 
 HELP: 2inputs
 { $values { "vreg1" "a vreg" } { "vreg2" "a vreg" } }
-{ $description "Lifts the two topmost values from the datastack and stores them in virtual registers. The datastacks height is adjusted afterwards." } ;
+{ $description "Lifts the two topmost values from the datastack and stores them in virtual registers. The datastacks height is decremented by 2." } ;
 
 HELP: 3inputs
 { $values { "vreg1" "a vreg" } { "vreg2" "a vreg" } { "vreg3" "a vreg" } }
-{ $description "Lifts the three topmost values from the datastack and stores them in virtual registers. The datastacks height is adjusted afterwards." } ;
+{ $description "Lifts the three topmost values from the datastack and stores them in virtual registers. The datastacks height is decremented by 3." } ;
 
 ARTICLE: "compiler.cfg.stacks" "Generating instructions for accessing the data and retain stacks" "This vocab contains utility words for manipulating the analysis data and retain stacks."
 $nl

basis/compiler/codegen/gc-maps/gc-maps-docs.factor

@@ -27,7 +27,7 @@ HELP: emit-uint
 } ;
 
 HELP: emit-gc-maps
-{ $description "GC maps are emitted so that the end is aligned to a 16-byte boundary." } ;
+{ $description "One of the last stages in code generation are emitting the GC maps which are placed directly after the generated executable code. They are emitted so that the end is aligned to a 16-byte boundary." } ;
 
 HELP: gc-maps
 { $var-description "Variable that holds a sequence of " { $link gc-map } " tuples. Gc maps are added to the sequence by " { $link gc-map-here } "." } ;