compiler.cfg.*: compiler doc updates

basis/compiler/cfg/builder/blocks/blocks-docs.factor

@@ -76,7 +76,7 @@ HELP: end-branch
 
 HELP: set-basic-block
 { $values { "basic-block" basic-block } }
-{ $description "Sets the given blocks as the current one by storing it in the basic-block dynamic variable. If it has any " { $slot "instructions" } " the current " { $link building } " is set to those." } ;
+{ $description "Sets the given blocks as the current one. If it has any " { $slot "instructions" } " the current " { $link building } " is set to those." } ;
 
 HELP: with-branch
 { $values

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

@@ -37,11 +37,7 @@ T{ basic-block
 STRING: ex-make-input-map
 USING: compiler.cfg.builder prettyprint ;
 T{ #shuffle { in-d { 37 81 92 } } } make-input-map .
-H{
+{ { 37 D: 2 } { 81 D: 1 } { 92 D: 0 } }
-    { 81 T{ ds-loc { n 1 } } }
-    { 37 T{ ds-loc { n 2 } } }
-    { 92 T{ ds-loc } }
-}
 ;
 >>
 
@@ -109,7 +105,18 @@ HELP: end-word
 
 HELP: height-changes
 { $values { "#shuffle" #shuffle } { "height-changes" sequence } }
-{ $description "Returns a two-tuple which represents how much the " { $link #shuffle } " node increases or decreases the data and retainstacks." } ;
+{ $description "Returns a two-tuple which represents how much the " { $link #shuffle } " node increases or decreases the data and retainstacks." }
+{ $examples
+  { $example
+    "USING: compiler.cfg.builder compiler.tree prettyprint ;"
+    "T{ #shuffle { in-d { 37 81 92 } } { out-d { 20 } } } height-changes ."
+    "{ -2 0 }"
+  }
+} ;
+
+HELP: out-vregs/stack
+{ $values { "#shuffle" #shuffle } { "seq" sequence } }
+{ $description "Returns a sequence of what vregs are on which stack locations after the shuffle instruction." } ;
 
 HELP: trivial-branch?
 { $values
@@ -172,6 +179,7 @@ $nl
 {
     $subsections
     height-changes
+    out-vregs/stack
 } ;
 
 ABOUT: "compiler.cfg.builder"

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

@@ -10,6 +10,10 @@ HELP: ##alien-invoke
 { $class-description
   "An instruction for calling a function in a dynamically linked library. It has the following slots:"
   { $table
+    {
+        { $slot "dead-outputs" }
+        { "A sequence of return values from the function that the compiler.cfg.dce pass has figured out are not used." }
+    }
     {
         { $slot "reg-inputs" }
         { "Registers to use for the arguments to the function call. Each sequence item is a 3-tuple consisting of a " { $link spill-slot } ", register representation and a register. When the function is called, the parameter is copied from the spill slot to the given register." }
@@ -22,14 +26,18 @@ HELP: ##alien-invoke
         { $slot "reg-outputs" }
         { "If the called function returns a value, then this slot is a one-element sequence containing a 3-tuple describing which register is used for the return value." }
     }
-    {
-        { $slot "gc-map" }
-        { "If the invoked C function calls Factor code which triggers a GC, then a " { $link gc-map } " is necessary to find the roots." }
-    }
     { { $slot "symbols" } { "Name of the function to call." } }
     { { $slot "dll" } { "A dll handle or " { $link f } "." } }
+    {
+        { $slot "gc-map" }
+        {
+            "If the invoked C function calls Factor code which triggers a GC, then a "
+            { $link gc-map }
+            " is necessary to find the roots."
         }
-  "Which function arguments that goes in " { $slot "reg-inputs" } " and which goes in " { $slot "stack-inputs" } " depend on the calling convention. In " { $link cdecl } " on " { $link x86.32 } ", all arguments goes in " { $slot "stack-inputs" } ", in " { $link x86.64 } " the first six arguments are passed in registers and then stack parameters are used for the remainder."
+    }
+  }
+  "Which function arguments that goes in " { $slot "reg-inputs" } " and which goes in " { $slot "stack-inputs" } " depend on the calling convention. In " { $link cdecl } " on " { $link x86.32 } ", all arguments goes in " { $slot "stack-inputs" } ", in " { $link x86.64 } " on " { $link unix } ", the first six arguments are passed in registers and then stack parameters are used for the remainder."
 }
 { $see-also #alien-invoke %alien-invoke } ;
 
@@ -286,6 +294,7 @@ HELP: ##store-memory-imm
         { $slot "offset" }
         { "Offset in bytes from the address to where the data should be written." }
     }
+    { { $slot "rep" } { "Value representation in the vector register." } }
     { { $slot "src" } { "Vreg that contains the item to set." } }
   }
 }

basis/compiler/cfg/intrinsics/misc/misc-docs.factor

@@ -1,4 +1,4 @@
-USING: compiler.cfg compiler.tree help.markup help.syntax
+USING: compiler.cfg compiler.tree help.markup help.syntax kernel
 kernel.private ;
 IN: compiler.cfg.intrinsics.misc
 
@@ -9,3 +9,7 @@ HELP: emit-context-object
   { "block'" basic-block }
 }
 { $description "Emits intrinsic code for a call to the " { $link context-object } " primitive." } ;
+
+HELP: emit-eq
+{ $values { "node" node } }
+{ $description "Intrinsic emitter for the " { $link eq? } " word." } ;

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

@@ -13,6 +13,7 @@ HELP: stack-frame
   "The stack frame is also aligned to a 16 byte boundary. It has the following slots:"
   { $table
     { { $slot "total-size" } { "Total size of the stack frame." } }
+    { { $slot "params" } { "Reserved parameter space." } }
     { { $slot "allot-area-base" } { "Base offset of the allocation area." } }
     { { $slot "allot-area-size" } { "Number of bytes requires for the allocation area." } }
     { { $slot "allot-area-align" } { "This slot is always at least " { $link cell } " bytes." } }

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

@@ -8,8 +8,8 @@ HELP: ds-push
 { $description "Used when translating the " { $link #push } " SSA node to CFG form. The node pushes a literal value onto the data stack." } ;
 
 HELP: begin-stack-analysis
-{ $description "Initializes a set of variables related to stack analysis of Factor words." }
+{ $description "Initializes a set of variables related to global stack analysis of Factor words." }
-{ $see-also height-state } ;
+{ $see-also begin-local-analysis height-state } ;
 
 HELP: end-stack-analysis
 { $values { "cfg" cfg } }
@@ -36,3 +36,14 @@ HELP: 2inputs
 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." } ;
+
+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
+"When nodes in the dataflow IR pushes or pops items from the stacks, instructions for performing those actions aren't immediately emitted. Instead the analysis stacks are manipulated and when the stack analysis phase is complete, optimal stack shuffling code is emitted. This way, exactly the same instructions are emitted for equivalent qutations such as [ dup drop ] and [ ]."
+$nl
+"Popping from the datastack:"
+{ $subsections 2inputs 3inputs ds-drop }
+"Pushing to the datastack:"
+{ $subsections ds-push store-vregs } ;
+
+ABOUT: "compiler.cfg.stacks"

basis/compiler/tree/tree-docs.factor

@@ -1,6 +1,6 @@
-USING: alien assocs help.markup help.syntax kernel kernel.private quotations
+USING: alien assocs help.markup help.syntax kernel kernel.private
-sequences stack-checker.alien stack-checker.inlining stack-checker.values
+quotations sequences stack-checker.alien stack-checker.inlining
-stack-checker.visitor words ;
+stack-checker.values stack-checker.visitor words ;
 IN: compiler.tree
 
 HELP: node
@@ -14,7 +14,7 @@ HELP: #alien-invoke
 { $see-also alien-invoke } ;
 
 HELP: #alien-callback
-{ $class-description "SSA tree node that constructs an alien callback." } ;
+{ $class-description "SSA tree node that constructs an alien callback. It is not a subclass of " { $link #alien-node } ". " } ;
 
 HELP: #call
 { $class-description "SSA tree node that calls a word. It has the following slots:"