From 75a3e191b2721fd25b3e337175bb0241e43ad3c7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= <bjourne@gmail.com>
Date: Tue, 21 Jun 2016 23:15:20 +0200
Subject: [PATCH] compiler.*: a bunch of random doc additions

---
 .../build-stack-frame-docs.factor             |  9 ++++-
 .../compiler/cfg/builder/builder-docs.factor  | 11 ++++++
 basis/compiler/cfg/builder/builder.factor     |  2 +-
 .../cfg/instructions/instructions-docs.factor | 36 ++++++++++++++-----
 .../cfg/stacks/local/local-docs.factor        | 20 ++++++++---
 basis/compiler/cfg/stacks/stacks-docs.factor  |  2 +-
 .../codegen/relocation/relocation-docs.factor |  4 +++
 basis/compiler/compiler-docs.factor           |  2 +-
 .../compiler/constants/constants-docs.factor  |  4 +++
 9 files changed, 72 insertions(+), 18 deletions(-)

diff --git a/basis/compiler/cfg/build-stack-frame/build-stack-frame-docs.factor b/basis/compiler/cfg/build-stack-frame/build-stack-frame-docs.factor
index 17828cf663..d798bef6ae 100644
--- a/basis/compiler/cfg/build-stack-frame/build-stack-frame-docs.factor
+++ b/basis/compiler/cfg/build-stack-frame/build-stack-frame-docs.factor
@@ -2,6 +2,10 @@ USING: assocs compiler.cfg compiler.cfg.instructions compiler.cfg.stack-frame
 help.markup help.syntax kernel ;
 IN: compiler.cfg.build-stack-frame
 
+HELP: build-stack-frame
+{ $values { "cfg" cfg } }
+{ $description "Main word of the " { $vocab-link "compiler.cfg.build-stack-frame" } " compiler pass." } ;
+
 HELP: compute-stack-frame
 { $values { "cfg" cfg } { "stack-frame/f" stack-frame } }
 { $description "Initializes a stack frame for a cfg, if it needs one." }
@@ -20,6 +24,9 @@ HELP: finalize-stack-frame
 { $description "Calculates and stores the " { $slot "allot-area-base" } ", " { $slot "spill-area-base" } " and " { $slot "total-size" } " slots of a stack frame." } ;
 
 ARTICLE: "compiler.cfg.build-stack-frame" "Computing stack frame size and layout"
-"The " { $vocab-link "compiler.cfg.build-stack-frame" } " vocab builds stack frames for cfg:s." ;
+"The " { $vocab-link "compiler.cfg.build-stack-frame" } " vocab builds stack frames for cfg:s."
+$nl
+"Main word:"
+{ $subsections build-stack-frame } ;
 
 ABOUT: "compiler.cfg.build-stack-frame"
diff --git a/basis/compiler/cfg/builder/builder-docs.factor b/basis/compiler/cfg/builder/builder-docs.factor
index 1fa34fb88a..246e61ae15 100644
--- a/basis/compiler/cfg/builder/builder-docs.factor
+++ b/basis/compiler/cfg/builder/builder-docs.factor
@@ -107,6 +107,10 @@ HELP: end-word
 }
 { $description "Ends the word by adding a basic block containing a " { $link ##return } " instructions to the " { $link cfg } "." } ;
 
+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." } ;
+
 HELP: trivial-branch?
 { $values
   { "nodes" "a " { $link sequence } " of " { $link node } " instances" }
@@ -130,6 +134,8 @@ ARTICLE: "compiler.cfg.builder"
 "Final stage of compilation generates machine code from dataflow IR"
 "The compiler first builds an SSA IR tree of the word to be compiled (see " { $vocab-link "compiler.tree.builder" } ") then this vocab converts it to a CFG IR tree. The result is not in SSA form; this is constructed later by calling compiler.cfg.ssa.construction:construct-ssa."
 $nl
+"Each tree node type has its own implementation of the " { $link emit-node } " generic. In that word, cfg instructions (tuples prefixed with ##) are outputted to basic blocks and the cfg constructed."
+$nl
 "Main word:"
 { $subsections
   build-cfg
@@ -161,6 +167,11 @@ $nl
     emit-loop
     emit-recursive
     end-branch
+}
+"Helpers for " { $link #shuffle } ":"
+{
+    $subsections
+    height-changes
 } ;
 
 ABOUT: "compiler.cfg.builder"
diff --git a/basis/compiler/cfg/builder/builder.factor b/basis/compiler/cfg/builder/builder.factor
index 66a1e25d62..e9a8768f86 100644
--- a/basis/compiler/cfg/builder/builder.factor
+++ b/basis/compiler/cfg/builder/builder.factor
@@ -158,7 +158,7 @@ M: #push emit-node ( block node -- block' )
     [ make-input-map ] [ mapping>> ] [ extract-outputs ] tri
     [ first2 [ [ of of peek-loc ] 2with map ] dip 2array ] 2with map ;
 
-M: #shuffle emit-node ( block node -- block' )
+M: #shuffle emit-node ( block node -- block )
     [ out-vregs/stack ] keep store-height-changes
     [ first2 store-vregs ] each ;
 
diff --git a/basis/compiler/cfg/instructions/instructions-docs.factor b/basis/compiler/cfg/instructions/instructions-docs.factor
index fc19684ed6..fd29601c75 100644
--- a/basis/compiler/cfg/instructions/instructions-docs.factor
+++ b/basis/compiler/cfg/instructions/instructions-docs.factor
@@ -1,8 +1,9 @@
-USING: alien arrays assocs byte-arrays classes combinators compiler.cfg
-compiler.cfg.intrinsics.fixnum compiler.cfg.linear-scan.assignment
-compiler.cfg.liveness compiler.cfg.ssa.destruction compiler.cfg.value-numbering
-compiler.codegen.gc-maps cpu.architecture help.markup help.syntax kernel
-layouts math sequences slots.private system vm ;
+USING: alien arrays assocs byte-arrays classes combinators
+compiler.cfg compiler.cfg.builder compiler.cfg.intrinsics.fixnum
+compiler.cfg.linear-scan.assignment compiler.cfg.liveness
+compiler.cfg.ssa.destruction compiler.cfg.value-numbering
+compiler.codegen.gc-maps cpu.architecture help.markup help.syntax
+kernel layouts math sequences slots.private system vm ;
 IN: compiler.cfg.instructions
 
 HELP: ##alien-invoke
@@ -11,7 +12,7 @@ HELP: ##alien-invoke
   { $table
     {
         { $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." }
+        { "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." }
     }
     {
         { $slot "stack-inputs" }
@@ -83,8 +84,15 @@ HELP: ##compare-float-ordered-branch
   }
 } ;
 
+HELP: ##compare-imm
+{ $class-description "Instruction used to implement trivial ifs and not ifs." }
+{ $see-also emit-trivial-if emit-trivial-not-if } ;
+
+HELP: ##compare-imm-branch
+{ $class-description "The instruction used to implement branching for the " { $link if } " word." } ;
+
 HELP: ##compare-integer
-{ $class-description "This instruction is emitted for integer (" { $link fixnum } ") comparisons." }
+{ $class-description "This instruction is emitted for " { $link fixnum } " comparisons." }
 { $see-also emit-fixnum-comparison } ;
 
 HELP: ##copy
@@ -132,6 +140,9 @@ HELP: ##load-reference
   }
 } ;
 
+HELP: ##load-tagged
+{ $class-description "Loads a tagged value into a register." } ;
+
 HELP: ##load-vector
 { $class-description
   "Loads a " { $link byte-array } " into an SSE register."
@@ -245,14 +256,14 @@ HELP: ##shuffle-vector-imm
 
 HELP: ##slot-imm
 { $class-description
-  "Instruction for reading a slot value from an object."
+  "Instruction for reading a slot with a given index from an object."
   { $table
     { { $slot "dst" } { "Register to read the slot value into." } }
     { { $slot "obj" } { "Register containing the object with the slot." } }
     { { $slot "slot" } { "Slot index." } }
     { { $slot "tag" } { "Type tag for obj." } }
   }
-} ;
+} { $see-also %slot-imm } ;
 
 HELP: ##spill
 { $class-description "Instruction that copies a value from a register to a " { $link spill-slot } "." } ;
@@ -270,6 +281,10 @@ HELP: ##store-memory-imm
 }
 { $see-also %store-memory-imm } ;
 
+HELP: ##test-branch
+{ $class-description "Instruction inserted by the " { $vocab-link "compiler.cfg.value-numbering" } " compiler pass." }
+{ $see-also ##compare-integer-imm-branch } ;
+
 HELP: ##unbox-any-c-ptr
 { $class-description "Instruction that unboxes a pointer in a register so that it can be fed to a C FFI function. For example, if 'src' points to a " { $link byte-array } ", then in 'dst' will be put a pointer to the first byte of that byte array."
   { $table
@@ -384,6 +399,7 @@ $nl
 }
 "Control flow:"
 { $subsections
+  ##branch
   ##call
   ##jump
   ##no-tco
@@ -423,6 +439,7 @@ $nl
 { $subsections
   ##compare
   ##compare-imm
+  ##compare-imm-branch
   ##compare-integer
   ##compare-integer-branch
   ##compare-integer-imm-branch
@@ -435,6 +452,7 @@ $nl
 { $subsections
   ##load-integer
   ##load-reference
+  ##load-tagged
 }
 "Floating point SIMD instructions:"
 { $subsections
diff --git a/basis/compiler/cfg/stacks/local/local-docs.factor b/basis/compiler/cfg/stacks/local/local-docs.factor
index a6e3580633..e030bcd0ab 100644
--- a/basis/compiler/cfg/stacks/local/local-docs.factor
+++ b/basis/compiler/cfg/stacks/local/local-docs.factor
@@ -1,6 +1,6 @@
 USING: assocs compiler.cfg compiler.cfg.instructions
-compiler.cfg.registers hash-sets hashtables help.markup help.syntax
-sequences ;
+compiler.cfg.registers compiler.cfg.stacks hash-sets hashtables
+help.markup help.syntax math sequences ;
 IN: compiler.cfg.stacks.local
 
 HELP: emit-changes
@@ -37,12 +37,22 @@ HELP: loc>vreg
 { $values { "loc" loc } { "vreg" "virtual register" } }
 { $description "Maps a stack location to a virtual register." } ;
 
+HELP: local-kill-set
+{ $values
+  { "ds-height" integer }
+  { "rs-height" integer }
+  { "state" sequence }
+  { "set" hash-set }
+}
+{ $description "The set of stack locations that was killed." }
+{ $see-also compute-local-kill-set } ;
+
 HELP: local-peek-set
 { $var-description "A " { $link hash-set } " used during local block analysis to keep track of peeked stack locations." } ;
 
 HELP: peek-loc
-{ $values { "loc" loc } { "vreg" "virtaul register" } }
-{ $description "Retrieves the virtual register at the given stack location." } ;
+{ $values { "loc" loc } { "vreg" "virtual register" } }
+{ $description "Retrieves the virtual register at the given stack location. If no register has been stored at that location, then a new vreg is returned." } ;
 
 HELP: replace-loc
 { $values { "vreg" "virtual register" } { "loc" loc } }
@@ -53,7 +63,7 @@ HELP: replace-sets
 { $var-description "An " { $link assoc } " in which each key is a " { $link basic-block } " and each value a " { $link hash-set } " with locations that were replaced in that block." } ;
 
 HELP: replaces
-{ $var-description "An " { $link assoc } " that maps from stack locations to virtual registers that were put on the stack." }
+{ $var-description "An " { $link assoc } " that maps from stack locations to virtual registers that were put on the stack during the local analysis phase. " { $link ds-push } " and similar words writes to it." }
 { $see-also replace-loc } ;
 
 HELP: translate-local-loc
diff --git a/basis/compiler/cfg/stacks/stacks-docs.factor b/basis/compiler/cfg/stacks/stacks-docs.factor
index 0b212e3b21..21fef15880 100644
--- a/basis/compiler/cfg/stacks/stacks-docs.factor
+++ b/basis/compiler/cfg/stacks/stacks-docs.factor
@@ -5,7 +5,7 @@ IN: compiler.cfg.stacks
 
 HELP: ds-push
 { $values { "vreg" "a virtual register" } }
-{ $description "Used when translating the " { $link #push } " SSA node to CFG form for pushing a literal value onto the data stack." } ;
+{ $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." }
diff --git a/basis/compiler/codegen/relocation/relocation-docs.factor b/basis/compiler/codegen/relocation/relocation-docs.factor
index f6abdc85b5..6f90b55740 100644
--- a/basis/compiler/codegen/relocation/relocation-docs.factor
+++ b/basis/compiler/codegen/relocation/relocation-docs.factor
@@ -49,6 +49,10 @@ 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-literal
+{ $values { "literal" "a literal" } { "class" "a relocation class" } }
+{ $description "Adds a refrence to a literal value to the current code offset." } ;
+
 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." } ;
diff --git a/basis/compiler/compiler-docs.factor b/basis/compiler/compiler-docs.factor
index d961674282..930c858e7f 100644
--- a/basis/compiler/compiler-docs.factor
+++ b/basis/compiler/compiler-docs.factor
@@ -64,7 +64,7 @@ HELP: backend
 { $see-also generate } ;
 
 HELP: compiled
-{ $var-description { "An " { $link assoc } " used by the optimizing compiler for intermediate storage of generated code. The keys are the labels to the CFG:s and the values the generated code as given by the " { $link generate } " word." } } ;
+{ $var-description { "An " { $link assoc } " used by the optimizing compiler for intermediate storage of generated code. The keys are the labels to the CFG:s and the values the generated code as described by the " { $link generate } " word." } } ;
 
 HELP: compile-word
 { $values { "word" word } }
diff --git a/basis/compiler/constants/constants-docs.factor b/basis/compiler/constants/constants-docs.factor
index 80bfaea655..1552d37e4c 100644
--- a/basis/compiler/constants/constants-docs.factor
+++ b/basis/compiler/constants/constants-docs.factor
@@ -19,6 +19,10 @@ HELP: rt-decks-offset
 { $description "Relocation offset type for the decks table." }
 { $see-also rel-decks-offset } ;
 
+HELP: rt-literal
+{ $description "Relocation type for a literal. The literal can be either an immediate such as a fixnum or " { $link f } " or an object reference." }
+{ $see-also rel-literal } ;
+
 HELP: string-offset
 { $values { "n" integer } }
 { $description "hm" } ;