compiler.*: more docs

diff --git a/basis/compiler/cfg/cfg-docs.factor b/basis/compiler/cfg/cfg-docs.factor
index 8e8e3ad7845291b8ed340eb92e1cdb14d13e9d45..4586423d426f31b8642ad0ef6ecd2c2e0ef79a61 100644 (file)
--- a/basis/compiler/cfg/cfg-docs.factor
+++ b/basis/compiler/cfg/cfg-docs.factor
@@ -78,3 +78,10 @@ HELP: cfg-changed
 HELP: spill-offset
 { $values { "n" integer } { "offset" integer } }
 { $description "Offset in the current " { $link stack-frame } " to byte at index 'n' in the spill area." } ;
+
+ARTICLE: "compiler.cfg" "Control Flow Graph IR"
+"The compiler.cfg vocab and subvocabs implements the part of the optimizing compiler that analyzes code in the CFG format. The vocab " { $vocab-link "compiler.cfg.builder" } " defines words for building the CFG from SSA IR and the rest of the vocabs in the hierarchy optimization steps that are then applied to it. The graph is then passed to the " { $vocab-link "compiler.codegen" } " vocab which emits machine code."
+$nl
+"The main datatype in the vocab is the " { $link cfg } " tuple. It represents the CFG of a Factor word. The cfg tuple has a slot 'entry' pointing to a " { $link basic-block } ". This block in turn points to other basic blocks, and together they form the call flow graph of the word." ;
+
+ABOUT: "compiler.cfg"

diff --git a/basis/compiler/cfg/instructions/instructions-docs.factor b/basis/compiler/cfg/instructions/instructions-docs.factor
index 3846ec846e58c86d8dd800717079fe01fabb4c07..d4a6793d0f7da12cf5ec711a291d26b0e65dc1f1 100644 (file)
--- a/basis/compiler/cfg/instructions/instructions-docs.factor
+++ b/basis/compiler/cfg/instructions/instructions-docs.factor
@@ -62,6 +62,10 @@ HELP: ##allot
   }
 } ;
 
+HELP: ##bit-count
+{ $class-description "Specialized instruction for counting the number of lit bits in an integer." }
+{ $see-also %bit-count } ;
+
 HELP: ##box
 { $class-description
   "This instruction boxes a value into a tagged pointer."
@@ -521,6 +525,7 @@ $nl
 { $subsections
   ##add-vector
   ##add-sub-vector
+  ##bit-count
   ##compare-float-ordered-branch
   ##div-vector
   ##horizontal-add-vector

diff --git a/basis/compiler/cfg/representations/conversion/conversion-docs.factor b/basis/compiler/cfg/representations/conversion/conversion-docs.factor
index 29031e98c0f083612a4af41bbb6afa50aa563dd5..af9d184676087fea54f062f51f19d47d01fb99df 100644 (file)
--- a/basis/compiler/cfg/representations/conversion/conversion-docs.factor
+++ b/basis/compiler/cfg/representations/conversion/conversion-docs.factor
@@ -1,6 +1,14 @@
 USING: cpu.architecture help.markup help.syntax make ;
 IN: compiler.cfg.representations.conversion
 
+HELP: emit-conversion
+{ $values
+  { "dst" "vreg" }
+  { "src" "vreg" }
+  { "dst-rep" representation }
+  { "src-rep" representation }
+} { $description "Emits an instruction converting a virtual register from one representation to another." } ;
+
 HELP: tagged>rep
 { $values { "dst" "vreg" } { "src" "vreg" } { "rep" representation } }
 { $description "Emits an instruction to the current " { $link make }

diff --git a/basis/compiler/codegen/labels/labels.factor b/basis/compiler/codegen/labels/labels.factor
index ab5e79e9575788de1617272ad20ffd6b457d8a4b..9bfa82c97f77ad222e154fb4f565b70abc0012d5 100644 (file)
--- a/basis/compiler/codegen/labels/labels.factor
+++ b/basis/compiler/codegen/labels/labels.factor
@@ -37,7 +37,6 @@ TUPLE: label-fixup-state { label label } { class integer } { offset integer } ;
     [ [ compute-relative-label ] map concat ]
     bi* ;
 
-! Binary literals
 SYMBOL: binary-literal-table
 
 : add-binary-literal ( obj -- label )

diff --git a/basis/compiler/crossref/crossref-docs.factor b/basis/compiler/crossref/crossref-docs.factor
index 5415ad0ca77f6dbc443285c407b928acf7ab3c3d..578f182dbc6c4b96cd164a76e197bce0ce711c56 100644 (file)
--- a/basis/compiler/crossref/crossref-docs.factor
+++ b/basis/compiler/crossref/crossref-docs.factor
@@ -1,4 +1,4 @@
-USING: assocs help.markup help.syntax sequences words ;
+USING: assocs help.markup help.syntax kernel sequences words ;
 IN: compiler.crossref
 
 HELP: compiled-crossref
@@ -8,6 +8,10 @@ HELP: delete-compiled-xref
 { $values { "word" word } }
 { $description "Deletes cross-referencing data for a word. Used when the optimizing compiler forgets a word." } ;
 
+HELP: dependencies-satisfied?
+{ $values { "word" word } { "cache" assoc } { "?" boolean } }
+{ $description "Checks if all the words dependencies are satisfied or not." } ;
+
 HELP: load-dependencies
 { $values { "word" word } { "seq" sequence } }
 { $description "Outputs a sequence of the words dependencies." } ;
@@ -19,3 +23,8 @@ HELP: remove-xref
 HELP: store-dependencies
 { $values { "word" word } { "assoc" assoc } }
 { $description "Stores the dependencies in 'assoc' in the word attribute \"dependencies\"." } ;
+
+ARTICLE: "compiler.crossref"  "Crossreferencing word dependencies."
+"A vocab that keeps track on how words depends on each other and their dependence types." ;o
+
+ABOUT: "compiler.crossref"

diff --git a/basis/compiler/tree/propagation/branches/branches-docs.factor b/basis/compiler/tree/propagation/branches/branches-docs.factor
new file mode 100644 (file)
index 0000000..ebaf803
--- /dev/null
+++ b/basis/compiler/tree/propagation/branches/branches-docs.factor
@@ -0,0 +1,18 @@
+USING: compiler.tree help.markup help.syntax sequences ;
+IN: compiler.tree.propagation.branches
+
+HELP: child-constraints
+{ $values { "node" node } { "seq" sequence } }
+{ $description "For conditionals, an assoc of child node # --> constraint." } ;
+
+HELP: condition-value
+{ $var-description "When propagating an " { $link #if } " node, this variable holds the value that is being dispatched on." } ;
+
+HELP: live-branches
+{ $values { "#branch" #branch } { "indices" sequence } }
+{ $description "Outputs a sequence of true and false values indicating which of the branches that are possibly live." } ;
+
+ARTICLE: "compiler.tree.propagation.branches" "Sparse propagation for branches"
+"Sparse propagation for branches" ;
+
+ABOUT: "compiler.tree.propagation.branches"

diff --git a/basis/compiler/tree/propagation/branches/branches.factor b/basis/compiler/tree/propagation/branches/branches.factor
index 79bc065bd63ef24af0482c3cc3ef8613dd7d54d5..a4479520ca38fb1a7d453bcfd684f198490b9588 100644 (file)
--- a/basis/compiler/tree/propagation/branches/branches.factor
+++ b/basis/compiler/tree/propagation/branches/branches.factor
@@ -8,7 +8,6 @@ namespaces sequences stack-checker.branches ;
 FROM: sets => union ;
 IN: compiler.tree.propagation.branches
 
-! For conditionals, an assoc of child node # --> constraint
 GENERIC: child-constraints ( node -- seq )
 
 M: #if child-constraints

diff --git a/basis/compiler/tree/propagation/simple/simple-docs.factor b/basis/compiler/tree/propagation/simple/simple-docs.factor
index 083c291fb88c03001c9e6e02c43425c359d26e1f..5903c116a4510e4b7df7889f4f3d5bc2f8f78099 100644 (file)
--- a/basis/compiler/tree/propagation/simple/simple-docs.factor
+++ b/basis/compiler/tree/propagation/simple/simple-docs.factor
@@ -1,5 +1,6 @@
-USING: compiler.tree compiler.tree.propagation.info help.markup
-help.syntax quotations sequences words ;
+USING: classes compiler.tree compiler.tree.propagation.info
+help.markup help.syntax quotations sequences
+stack-checker.dependencies words ;
 IN: compiler.tree.propagation.simple
 
 HELP: call-outputs-quot
@@ -15,8 +16,7 @@ HELP: propagate-predicate
 { $values { "#call" #call } { "word" word } { "infos" sequence } }
 { $description "We need to force the caller word to recompile when the class is redefined, since now we're making assumptions but the class definition itself." } ;
 
-ARTICLE: "compiler.tree.propagation.simple"
-"Propagation for straight-line code"
+ARTICLE: "compiler.tree.propagation.simple" "Propagation for straight-line code"
 "Propagation for straight-line code" ;
 
 ABOUT: "compiler.tree.propagation.simple"

diff --git a/basis/compiler/tree/tree-docs.factor b/basis/compiler/tree/tree-docs.factor
index 9f19de329e3acab42b8ddba1b17dd015fdf16851..fcaf8b9352a1b40b55d0122d019cb5d4c1e130c4 100644 (file)
--- a/basis/compiler/tree/tree-docs.factor
+++ b/basis/compiler/tree/tree-docs.factor
@@ -33,7 +33,11 @@ HELP: #call-recursive
 { $see-also #recursive } ;
 
 HELP: #declare
-{ $class-description "SSA tree node emitted when " { $link declare } " declarations are encountered." } ;
+{ $class-description "SSA tree node emitted when " { $link declare } " declarations are encountered. It has the following slots:"
+  { $table
+    { { $slot "declaration" } { { $link assoc } " that maps values to the types they are declared as." } }
+  }
+} ;
 
 HELP: #enter-recursive
 { $class-description "This node works is placed first in the 'child' " { $link sequence } " for " { $link #recursive } " nodes and works like a header for it." }
@@ -99,6 +103,21 @@ ARTICLE: "compiler.tree" "High-level optimizer operating on lexical tree SSA IR"
   #enter-recursive
   #recursive
   #return-recursive
+  #terminate
+}
+"Nodes for alien ffi:"
+{ $subsections
+  #alien-node
+  #alien-invoke
+  #alien-indirect
+  #alien-assembly
+  #alien-callback
+}
+"Nodes for branching:"
+{ $subsections
+  #dispatch
+  #if
+  #phi
 } ;
 
 ABOUT: "compiler.tree"