compiler.cfg.*: random doc updates

basis/compiler/cfg/def-use/def-use-docs.factor

@@ -10,6 +10,9 @@ HELP: compute-insns
 { $values { "cfg" cfg } }
 { $description "Computes a mapping from vregs to the instructions that define them and store the result in the " { $link insns } " variable. The " { $link insn-of } " word can then be used to access the assoc." } ;
 
+HELP: defs
+{ $var-description "Mapping from vreg to " { $link basic-block } " which introduces it." } ;
+
 HELP: defs-vregs
 { $values { "insn" insn } { "seq" sequence } }
 { $description "Returns the sequence of vregs defined, or introduced, by this instruction." }
@@ -19,7 +22,8 @@ HELP: defs-vregs
     "T{ ##peek f 37 D: 0 0 } defs-vregs ."
     "{ 37 }"
   }
-} ;
+}
+{ $see-also defs } ;
 
 HELP: insns
 { $var-description { $link assoc } " mapping vreg integers to defining instructions." }
@@ -57,6 +61,10 @@ $nl
   defs-vregs
   temp-vregs
   uses-vregs
+}
+"Dynamic variables:"
+{ $subsections
+  defs
 } ;
 
 ABOUT: "compiler.cfg.def-use"

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

@@ -9,7 +9,14 @@ HELP: ##alien-invoke
 { $class-description
   "An instruction for calling a function in a dynamically linked library. It has the following slots:"
   { $table
-    { { $slot "reg-inputs" } { "Registers to use for the arguments to the function call." } }
+    {
+        { $slot "gc-map" }
+        { "If the invoked c-function calls Factor code which triggers a gc, then a " { $link gc-map } " might be necessary." }
+    }
+    {
+        { $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." }
+    }
     {
         { $slot "stack-inputs" }
         { "Stack slots used for the arguments to the function call." }
@@ -21,8 +28,9 @@ HELP: ##alien-invoke
     { { $slot "symbols" } { "Name of the function to call." } }
     { { $slot "dll" } { "A dll handle." } }
   }
-  "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" } " but on " { $link x86.64 } " the first six arguments are passed in registers and only then are the stack used."
+  "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" } " but on " { $link x86.64 } " the first six arguments are passed in registers and only then is the stack used."
-} ;
+}
+{ $see-also %alien-invoke } ;
 
 HELP: ##allot
 { $class-description
@@ -107,7 +115,7 @@ HELP: ##load-double
 { $see-also %load-double } ;
 
 HELP: ##load-memory-imm
-{ $class-description "Instruction for loading data from memory into an MMS register." }
+{ $class-description "Instruction for loading data from memory into a register. Either a General Purpose or an SSE register." }
 { $see-also %load-memory-imm } ;
 
 HELP: ##load-reference
@@ -160,7 +168,7 @@ HELP: ##phi
 { $class-description
   "A special kind of instruction used to mark control flow. It is inserted by the " { $vocab-link "compiler.cfg.ssa.construction" } " vocab. It has the following slots:"
   { $table
-    { { $slot "inputs" } { "An assoc containing as keys the blocks where the vreg was defined and as values the vreg." } }
+    { { $slot "inputs" } { "An assoc containing as keys the blocks/block numbers where the vreg was defined and as values the vreg. Why care about the blocks?" } }
     { { $slot "dst" } { "A merged vreg for the value." } }
   }
 } ;
@@ -258,6 +266,18 @@ HELP: ##store-memory-imm
 }
 { $see-also %store-memory-imm } ;
 
+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
+    { { $slot "dst" } { "Destination register." } }
+    { { $slot "src" } { "Source register." } }
+  }
+}
+{ $see-also %unbox-any-c-ptr } ;
+
+HELP: ##unbox-long-long
+{ $class-description "Instruction that unboxes a 64-bit integer to two 32-bit registers. Only used on 32 bit architectures." } ;
+
 HELP: ##vector>scalar
 { $class-description
   "This instruction is very similar to " { $link ##copy } "."

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

@@ -1,11 +1,18 @@
-USING: compiler.tree help.markup help.syntax ;
+USING: byte-arrays compiler.tree help.markup help.syntax ;
 IN: compiler.cfg.intrinsics.allot
 
+HELP: emit-<byte-array>
+{ $values { "node" node } }
+{ $description "Emits optimized cfg instructions for allocating a " { $link byte-array } "." } ;
+
 HELP: emit-<tuple-boa>
 { $values { "node" node } }
 { $description "Emits optimized cfg instructions for building and allocating tuples." } ;
 
 ARTICLE: "compiler.cfg.intrinsics.allot" "Generating instructions for inline memory allocation"
-"Generating instructions for inline memory allocation" ;
+"Generating instructions for inline memory allocation"
+$nl
+"Emitters:"
+{ $subsections emit-<byte-array> emit-<tuple-boa> } ;
 
 ABOUT: "compiler.cfg.intrinsics.allot"

basis/compiler/cfg/linear-scan/allocation/allocation-docs.factor

@@ -51,4 +51,12 @@ HELP: spill-at-sync-point?
   { "live-interval" live-interval-state }
   { "?" boolean }
 }
-{ $description "If the live interval has a definition at a keep-dst? sync-point, don't spill." } ;
+{ $description "Whether the given live interval must be spilled at the sync point. If the instruction for the given sync point is a " { $link hairy-clobber-insn } ", such as a (" { $link ##call-gc } " instruction) then the interval is always spilled." } ;
+
+ARTICLE: "compiler.cfg.linear-scan.allocation" "Allocating registers for live intervals"
+"This vocab implements the step in the linear scan algorithm in which virtual registers are allocated physical registers. It also takes decisions on when to spill registers."
+$nl
+"Main entry point:"
+{ $subsections allocate-registers } ;
+
+ABOUT: "compiler.cfg.linear-scan.allocation"

basis/compiler/cfg/linear-scan/allocation/spilling/spilling-docs.factor

@@ -1,6 +1,6 @@
 USING: compiler.cfg.linear-scan
 compiler.cfg.linear-scan.allocation.state
-compiler.cfg.linear-scan.live-intervals help.markup help.syntax ;
+compiler.cfg.linear-scan.live-intervals help.markup help.syntax math ;
 IN: compiler.cfg.linear-scan.allocation.spilling
 
 HELP: assign-spill
@@ -28,6 +28,14 @@ HELP: spill-before
 { $description "If the interval does not have any usages before the spill location, then it is the second child of an interval that was split. We reload the value and let the resolve pass insert a spill later." }
 { $see-also spill-after } ;
 
+HELP: split-for-spill
+{ $values
+  { "live-interval" live-interval }
+  { "n" integer }
+  { "before" live-interval }
+  { "after" live-interval }
+} { $description "During register allocation an interval needs to be split so that the 'after' part of it can be placed in a spill slot." } ;
+
 HELP: spill-intersecting
 { $values { "new" live-interval-state } { "reg" "register" } }
 { $description "Split and spill all active and inactive intervals which intersect 'new' and use 'reg'." } ;
@@ -53,6 +61,9 @@ HELP: trim-before-ranges
 { $description "Extends the last intervals range to one after the last use point and removes all intervals beyond that." } ;
 
 ARTICLE: "compiler.cfg.linear-scan.allocation.spilling" "Spill slot assignment"
-"Words and dynamic variables for assigning spill slots to spilled registers during the " { $link linear-scan } " compiler pass." ;
+"Words and dynamic variables for assigning spill slots to spilled registers during the " { $link linear-scan } " compiler pass."
+$nl
+"Splitting live intervals:"
+{ $subsections split-for-spill } ;
 
 ABOUT: "compiler.cfg.linear-scan.allocation.spilling"

basis/compiler/cfg/linear-scan/live-intervals/live-intervals-docs.factor

@@ -28,6 +28,14 @@ HELP: compute-live-intervals
 { $description "Computes the live intervals and sync points of a cfg." }
 { $notes "The instructions must be numbered." } ;
 
+HELP: find-use
+{ $values
+  { "insn#" integer }
+  { "live-interval" live-interval }
+  { "vreg-use/f" vreg-use }
+}
+{ $description "Finds the live intervals " { $link vreg-use } " at the given instruction number, if it has one." } ;
+
 HELP: finish-live-intervals
 { $values { "live-intervals" sequence } }
 { $description "Since live intervals are computed in a backward order, we have to reverse some sequences, and compute the start and end." } ;
@@ -85,6 +93,7 @@ HELP: sync-point
 { $class-description "A location where all registers have to be spilled. For example when garbage collection is run or an alien ffi call is invoked. Figuring out where in the " { $link cfg } " the sync points are is done in the " { $link compute-live-intervals } " step. The tuple has the following slots:"
   { $table
     { { $slot "n" } { "Set from an instructions sequence number." } }
+    { { $slot "keep-dst?" } { "Boolean that determines whether registers are spilled around this sync point." } }
   }
 }
 { $see-also insn } ;

basis/compiler/cfg/ssa/destruction/destruction-docs.factor

@@ -5,7 +5,11 @@ IN: compiler.cfg.ssa.destruction
 
 HELP: cleanup-cfg
 { $values { "cfg" cfg } }
-{ $description "In this step, " { $link ##parallel-copy } " instructions are substituted with more concreete " { $link ##copy } " instructions. " { $link ##phi } " instructions are removed here." } ;
+{ $description "In this pass, useless copies are eliminated. " { $link ##phi } " instructions are removed and " { $link ##parallel-copy } " are transformed into regular " { $link ##copy } " instructions. Then for the copy instructions, which are ##copy and " { $link ##tagged>integer } " it is checked to see if the copy is useful. If it is not, the instruction is removed from the cfg." } ;
+
+HELP: destruct-ssa
+{ $values { "cfg" cfg } }
+{ $description "Main entry point for the SSA destruction compiler pass." } ;
 
 ARTICLE: "compiler.cfg.ssa.destruction" "SSA Destruction"
 "Because of the design of the register allocator, this pass has three peculiar properties."