compiler.*: even more compiler docs

basis/compiler/cfg/cfg-docs.factor

@@ -7,6 +7,7 @@ HELP: basic-block
 { $class-description
   "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 "number" } { "The blocks sequence number. Generated by calling " { $link number-blocks } ". " } }
     { { $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." } }

basis/compiler/codegen/codegen-docs.factor

@@ -1,6 +1,6 @@
-USING: alien byte-arrays compiler.cfg compiler.codegen.labels
-compiler.codegen.relocation hashtables help.markup help.syntax literals make
-multiline sequences ;
+USING: alien byte-arrays compiler.cfg compiler.cfg.instructions
+compiler.codegen.labels compiler.codegen.relocation cpu.architecture hashtables
+help.markup help.syntax literals make multiline sequences ;
 IN: compiler.codegen
 
 <<
@@ -53,16 +53,10 @@ STRING: generate-ex-answer
 ;
 >>
 
-HELP: labels
-{ $description { $link hashtable } " of mappings from " { $link basic-block } " to " { $link label } "." } ;
-
-HELP: lookup-label
-{ $values { "bb" basic-block } { "label" label } }
-{ $description "Sets and gets a " { $link label } " for the " { $link basic-block } ". The labels are used to generate branch instructions from one block to another." } ;
-
-HELP: generate-block
-{ $values { "bb" basic-block } }
-{ $description "Emits machine code to the current " { $link make } " sequence for one basic block." } ;
+HELP: emit-branch
+{ $values { "bb" basic-block } { "successor" basic-block } }
+{ $description "Emits a branching instruction for jumping from one block to the next. If the blocks are next to each other, then no jump is needed." }
+{ $see-also %jump-label } ;
 
 HELP: generate
 { $values { "cfg" cfg } { "code" sequence } }
@@ -81,6 +75,23 @@ HELP: generate
   { $unchecked-example $[ generate-ex generate-ex-answer ] }
 } ;
 
+HELP: generate-insn
+{ $values { "insn" insn } }
+{ $description "Generates assembler code for one cfg instruction." }
+{ $see-also generate } ;
+
+HELP: generate-block
+{ $values { "bb" basic-block } }
+{ $description "Emits machine code to the current " { $link make } " sequence for one basic block." } ;
+
+
+HELP: labels
+{ $description { $link hashtable } " of mappings from " { $link basic-block } " to " { $link label } "." } ;
+
+HELP: lookup-label
+{ $values { "bb" basic-block } { "label" label } }
+{ $description "Sets and gets a " { $link label } " for the " { $link basic-block } ". The labels are used to generate branch instructions from one block to another." } ;
+
 HELP: useless-branch?
 { $values
   { "bb" basic-block }

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

@@ -48,7 +48,7 @@ HELP: gc-map-needed?
 
 HELP: gc-root-offsets
 { $values { "gc-map" gc-map } { "offsets" sequence } }
-{ $description "Gets the offets of all roots in a gc-map. The " { $link stack-frame } " variable must have been setup first." } ;
+{ $description "Gets the offets of all roots in a gc-map. The " { $link cfg } " variable must have been set and the stack-frame slot been initialized." } ;
 
 HELP: serialize-gc-maps
 { $values { "byte-array" byte-array } }

basis/compiler/codegen/relocation/relocation-docs.factor

@@ -1,11 +1,14 @@
-USING: byte-vectors compiler.codegen.labels compiler.constants cpu.architecture
-help.markup help.syntax make strings ;
+USING: byte-vectors compiler.constants cpu.architecture help.markup
+help.syntax make vectors ;
 IN: compiler.codegen.relocation
 
 HELP: relocation-table
 { $description "A " { $link byte-vector } " holding the relocations for the current compilation. Each sequence of four bytes in the vector represents one relocation." }
 { $see-also init-relocation } ;
 
+HELP: add-dlsym-parameters
+{ $description "Adds a pair of parameters for a reference to an external C function to the " { $link parameter-table } "." } ;
+
 HELP: add-relocation
 { $values
   { "class" "a relocation class such as " { $link rc-relative } }
@@ -20,14 +23,6 @@ HELP: add-literal
 HELP: init-relocation
 { $description "Initializes the dynamic variables related to code relocation." } ;
 
-HELP: rel-decks-offset
-{ $values { "class" "a relocation class" } }
-{ $description "Adds a decks offset relocation. It is used for marking cards when emitting write barriers." } ;
-
-HELP: rel-safepoint
-{ $values { "class" "a relocation class" } }
-{ $description "Adds a safe point to the " { $link relocation-table } " for the current code offset. This word is used by the " { $link %safepoint } " generator." } ;
-
 HELP: compiled-offset
 { $values { "n" "offset of the code being constructed in the current " { $link make } " sequence." } }
 { $description "The current compiled code offset. Used for (among other things) calculating jump labels." }
@@ -45,10 +40,25 @@ HELP: compiled-offset
   }
 } ;
 
+HELP: parameter-table
+{ $var-description "The parameter table is a " { $link vector } " which contains all the paramters for the word being generated." } ;
+
+HELP: rel-decks-offset
+{ $values { "class" "a relocation class" } }
+{ $description "Adds a decks offset relocation. It is used for marking cards when emitting write barriers." } ;
+
+HELP: rel-safepoint
+{ $values { "class" "a relocation class" } }
+{ $description "Adds a safe point to the " { $link relocation-table } " for the current code offset. This word is used by the " { $link %safepoint } " generator." } ;
+
 ARTICLE: "compiler.codegen.relocation" "Relocatable VM objects"
 "The " { $vocab-link "compiler.codegen.relocation" } " deals with assigning memory addresses to VM objects, such as the card table. Those objects have different addresses during each execution which is why they are \"relocatable\". The vocab is shared by the optimizing and non-optimizing compiler."
 $nl
 "Adding relocations:"
-{ $subsections add-relocation rel-decks-offset rel-safepoint } ;
+{ $subsections add-relocation rel-decks-offset rel-safepoint }
+"Adding parameters:"
+{ $subsections add-dlsym-parameters }
+"Tables used during code generation:"
+{ $subsections literal-table parameter-table relocation-table } ;
 
 ABOUT: "compiler.codegen.relocation"

basis/compiler/codegen/relocation/relocation.factor

@@ -19,7 +19,6 @@ SYMBOL: extra-offset  ! Only used by non-optimizing compiler
 : align-code ( n -- )
     alignment (align-code) ;
 
-! Parameter table
 SYMBOL: parameter-table
 
 : add-parameter ( obj -- ) parameter-table get push ;

basis/compiler/tree/propagation/simple/simple-tests.factor

@@ -139,16 +139,16 @@ cpu x86.64? [
     }
 } [
     { 2 "hello" } [ <literal-info> ] map setup-value-infos { 0 1 } { 2 } \ +
-    <#call> (fold-call2)
+    <#call> dup word>> (fold-call)
 ] unit-test
 
 ! foldable-call?
 { t f f t } [
     { 2 3 "hello" } [ <literal-info> ] map setup-value-infos
-    { 0 1 } { 2 } \ + <#call> foldable-call?
-    { 0 2 } { 2 } \ + <#call> foldable-call?
+    { 0 1 } { 2 } \ + <#call> dup word>> foldable-call?
+    { 0 2 } { 2 } \ + <#call> dup word>> foldable-call?
     number <class-info> 1array setup-value-infos
-    { 0 } { 1 } \ >fixnum <#call> foldable-call?
+    { 0 } { 1 } \ >fixnum <#call> dup word>> foldable-call?
     "mamma mia" <literal-info> 1array setup-value-infos
-    { 0 } { 1 } \ >fixnum <#call> foldable-call?
+    { 0 } { 1 } \ >fixnum <#call> dup word>> foldable-call?
 ] unit-test

basis/cpu/architecture/architecture-docs.factor

@@ -132,7 +132,11 @@ HELP: %box
 { $description "Call a function to convert a value into a tagged pointer, possibly allocating a bignum, float, or alien instance, which is then pushed on the data stack." } ;
 
 HELP: %box-alien
-{ $values { "dst" "destination register" } { "src" "source register" } { "temp" "temporary register" } }
+{ $values
+  { "dst" "destination register" }
+  { "src" "register containing pointer to the alien" }
+  { "temp" "temporary register" }
+}
 { $description "Emits machine code for boxing an alien value. If the alien is not a NULL pointer, then five " { $link cells } " will be allocated in the nursery space to wrap the object. See vm/layouts.hpp for details." }
 { $examples { $unchecked-example $[ ex-%box-alien ] } }
 { $see-also ##box-alien %allot } ;

basis/stack-checker/alien/alien-docs.factor

@@ -7,8 +7,10 @@ HELP: alien-node-params
   { $table
     { { $slot "return" } { "a " { $link c-type-name } " which indicates the type of the functions return value." } }
     { { $slot "parameters" } { "a " { $link sequence } " of " { $link c-type-name } " giving the types of the functions parameters." } }
+    { { $slot "abi" } { "calling convention of the function the node parameters operates on." } }
   }
-} ;
+}
+{ $see-also abi } ;
 
 HELP: alien-callback-params
 { $class-description "Class that holds the parameter types and return value type of an alien callback call." }

basis/stack-checker/backend/backend-docs.factor

@@ -1,5 +1,5 @@
 USING: compiler.tree effects help.markup help.syntax math quotations sequences
-stack-checker.state stack-checker.values stack-checker.visitor ;
+stack-checker.state stack-checker.values stack-checker.visitor words ;
 IN: stack-checker.backend
 
 HELP: consume-d
@@ -51,6 +51,10 @@ HELP: push-literal
 { $description "Pushes a literal onto the " { $link literals } " sequence." }
 { $see-also commit-literals } ;
 
+HELP: required-stack-effect
+{ $values { "word" word } { "effect" effect } }
+{ $description "Gets the stack effect of the word, or throws an error if it doesn't have one." } ;
+
 HELP: with-infer
 { $values { "quot" quotation } { "effect" effect } { "visitor" "a visitor, if any" } }
 { $description "Initializes the inference engine and then runs the given quotation which is supposed to perform the inferencing." } ;

basis/stack-checker/inlining/inlining-docs.factor

@@ -0,0 +1,10 @@
+USING: compiler.tree help.markup help.syntax words ;
+IN: stack-checker.inlining
+
+HELP: inline-recursive-word
+{ $values { "word" word } }
+{ $description "Emits an " { #recursive } " ssa node for a call to the given inline recursive word." } ;
+
+HELP: prepare-stack
+{ $values { "word" word } }
+{ $description "Called when an inline recursive word is compiled." } ;