compiler.cfg.*: docs for compiler words

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

@@ -1,6 +1,21 @@
-USING: help.markup help.syntax make stack-checker.alien ;
+USING: help.markup help.syntax literals make multiline stack-checker.alien ;
 IN: compiler.cfg.builder.alien
 
+<<
+STRING: ex-caller-return
+USING: compiler.cfg.builder.alien make prettyprint ;
+[
+    T{ ##alien-invoke { reg-outputs { { 1 int-rep RAX } } } } ,
+    T{ alien-invoke-params { return pointer: void } }  caller-return
+] { } make  .
+{
+    T{ ##alien-invoke { reg-outputs { { 1 int-rep RAX } } } }
+    T{ ##box-alien { dst 116 } { src 1 } { temp 115 } }
+}
+;
+>>
+
 HELP: caller-return
 { $values { "params" alien-node-params } }
-{ $description "If the last alien call returns a value, then this word will emit an instruction to the current sequence being constructed by " { $link make } " which boxes it." } ;
+{ $description "If the last alien call returns a value, then this word will emit an instruction to the current sequence being constructed by " { $link make } " that boxes it." }
+{ $examples { $unchecked-example $[ ex-caller-return ] } } ;

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

@@ -19,6 +19,23 @@ HELP: box
 }
 { $see-also ##box-alien } ;
 
+HELP: box-return
+{ $values
+  { "vregs" "vregs that contains the return value of the alien call" }
+  { "reps" "representations of the vregs" }
+  { "c-type" abstract-c-type }
+  { "dst" "vreg in which the boxed value, or a reference to it, will be placed" }
+}
+{ $description "Emits instructions for boxing the return value from an alien function call." }
+{ $examples
+  { $unchecked-example
+    "USING: compiler.cfg.builder.alien.boxing kernel make prettyprint ;"
+    "[ { 10 } { tagged-rep } int base-type box-return drop ] { } make ."
+    "{ T{ ##convert-integer { dst 118 } { src 10 } { c-type int } } }"
+  }
+}
+{ $see-also ##box-alien } ;
+
 HELP: stack-size
 { $values
   { "c-type" c-type }

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

@@ -1,15 +1,37 @@
-USING: compiler.cfg compiler.tree help.markup help.syntax math ;
+USING: compiler.cfg compiler.tree help.markup help.syntax literals math
+multiline quotations ;
 IN: compiler.cfg.builder.blocks
 
-HELP: initial-basic-block
-{ $description "Creates an initial empty " { $link basic-block } " and stores it in the basic-block dynamic variable." } ;
+<<
+STRING: ex-emit-trivial-block
+USING: compiler.cfg.builder.blocks prettyprint ;
+initial-basic-block [ [ gensym ##call, ] emit-trivial-block ] { } make drop
+basic-block get .
+T{ basic-block
+    { id 2040412 }
+    { successors
+        V{
+            T{ basic-block
+                { id 2040413 }
+                { instructions
+                    V{
+                        T{ ##call { word ( gensym ) } }
+                        T{ ##branch }
+                    }
+                }
+                { successors
+                    V{ T{ basic-block { id 2040414 } } }
+                }
+            }
+        }
+    }
+}
+;
+>>
 
 HELP: begin-basic-block
 { $description "Terminates the current block and initializes a new " { $link basic-block } " to begin outputting instructions to. The new block is included in the old blocks " { $slot "successors" } "." } ;
 
-HELP: make-kill-block
-{ $description "Marks the current " { $link basic-block } " being processed as a kill block." } ;
-
 HELP: call-height
 { $values { "#call" #call } { "n" number } }
 { $description "Calculates how many items a " { $link #call } " will add or remove from the data stack." }
@@ -20,3 +42,14 @@ HELP: call-height
     "-2"
   }
 } ;
+
+HELP: emit-trivial-block
+{ $values { "quot" quotation } }
+{ $description "Combinator that emits a trivial block, constructed by calling the supplied quotation." }
+{ $examples { $unchecked-example $[ ex-emit-trivial-block ] } } ;
+
+HELP: initial-basic-block
+{ $description "Creates an initial empty " { $link basic-block } " and stores it in the basic-block dynamic variable." } ;
+
+HELP: make-kill-block
+{ $description "Marks the current " { $link basic-block } " being processed as a kill block." } ;

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

@@ -5,7 +5,8 @@ IN: compiler.cfg.builder
 
 <<
 STRING: ex-emit-call
-USING: compiler.cfg.builder kernel make prettyprint ;
+USING: compiler.cfg.builder compiler.cfg.builder.blocks compiler.cfg.stacks
+kernel make prettyprint ;
 begin-stack-analysis initial-basic-block \ dummy 3 [ emit-call ] { } make drop
 current-height basic-block [ get . ] bi@ .
 T{ current-height { d 3 } }
@@ -59,7 +60,7 @@ HELP: emit-call
 
 HELP: emit-node
 { $values { "node" node } }
-{ $description "Emits some kind of code for the node." } ;
+{ $description "Emits CFG instructions for the given SSA node." } ;
 
 HELP: trivial-branch?
 { $values

basis/compiler/cfg/cfg-docs.factor

@@ -5,9 +5,10 @@ IN: compiler.cfg
 
 HELP: basic-block
 { $class-description
-  "Factors representation of a basic block in the cfg. A basic block is a sequence of instructions that always are executed sequentially and doesn't contain any branching. It has the following slots:"
+  "Factors representation of a basic block in the Call Flow Graph (CFG). A basic block is a sequence of instructions that always are executed sequentially and doesn't contain any branching. It has the following slots:"
   { $table
     { { $slot "successors" } { "A " { $link vector } " of basic blocks that may be executed directly after this block. Most blocks only have one successor but a block that checks where an if-condition should branch to would have two for example." } }
+    { { $slot "predecessors" } { "The opposite of successors -- a " { $link vector } " of basic blocks from which the execution may have arrived into this block." } }
     { { $slot "instructions" } { "A " { $link vector } " of " { $link insn } " tuples which form the instructions of the basic block." } }
   }
 } ;
@@ -20,7 +21,7 @@ HELP: cfg
 { $class-description
   "Call flow graph. It has the following slots:"
   { $table
-    { { $slot "entry" } { "Initial " { $link basic-block } " of the graph." } }
+    { { $slot "entry" } { "Root " { $link basic-block } " of the graph." } }
     { { $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." } }

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

@@ -42,7 +42,10 @@ HELP: ##alien-invoke
   { $table
     { { $slot "reg-inputs" } { "Registers to use for the arguments to the function call." } }
     { { $slot "stack-inputs" } { "Stack slots used for the arguments to the function call. Only used if all register arguments are already filled." } }
-    { { $slot "reg-outputs" } { "Register that wil contain the return value of the function call if any." } }
+    {
+        { $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 "symbols" } { "Name of the function to call." } }
     { { $slot "dll" } { "A dll handle." } }
   }
@@ -74,6 +77,11 @@ HELP: ##replace
   "Copies a value from a machine register to a stack location." }
   { $see-also ##peek ##replace-imm } ;
 
+HELP: ##box-alien
+{ $class-description
+  "An instruction for boxing an alien value."
+} ;
+
 HELP: ##write-barrier
 { $class-description
   "An instruction for inserting a write barrier. This instruction is almost always inserted after a " { $link ##set-slot } " instruction. It has the following slots:"

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

@@ -2,7 +2,14 @@ USING: compiler.cfg compiler.cfg.registers help.markup help.syntax ;
 IN: compiler.cfg.stacks.local
 
 HELP: current-height
-{ $class-description "A tuple used to keep track of the heights of the data and retain stacks in a " { $link basic-block } "." } ;
+{ $class-description "A tuple used to keep track of the heights of the data and retain stacks in a " { $link basic-block } " The idea is that if the stack change instructions are tracked, then multiple changes can be folded into one. It has the following slots:"
+  { $table
+    { { $slot "d" } { "Current datastack height." } }
+    { { $slot "r" } { "Current retainstack height." } }
+    { { $slot "emit-d" } { "Queued up datastack height change." } }
+    { { $slot "emit-r" } { "Queued up retainstack height change." } }
+  }
+} ;
 
 HELP: translate-local-loc
 { $values { "loc" loc } { "loc'" loc } }