compiler.cfg.*: a bunch of docs updates

basis/compiler/cfg/cfg-docs.factor

@@ -20,7 +20,8 @@ HELP: <basic-block>
 
 HELP: <cfg>
 { $values { "word" word } { "label" "label" } { "entry" basic-block } { "cfg" cfg } }
-{ $description "Constructor for " { $link cfg } ". " { $slot "spill-area-size" } " and " { $slot "spill-area-align" } " are set to default values." } ;
+{ $description "Constructor for " { $link cfg } ". " { $slot "spill-area-size" } " and " { $slot "spill-area-align" } " are set to default values." }  ;
+
 
 HELP: cfg
 { $class-description
@@ -33,7 +34,7 @@ HELP: cfg
     { { $slot "frame-pointer?" } { "Whether the cfg needs a frame pointer. Only cfgs generated for " { $link #alien-callback } " nodes does need it." } }
   }
 }
-{ $see-also post-order } ;
+{ $see-also <cfg> post-order } ;
 
 HELP: cfg-changed
 { $values { "cfg" cfg } }

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

@@ -1,8 +1,8 @@
-USING: alien arrays assocs classes compiler.cfg compiler.cfg.intrinsics.fixnum
+USING: alien arrays assocs byte-arrays classes combinators compiler.cfg
-compiler.cfg.linear-scan.assignment compiler.cfg.liveness
+compiler.cfg.intrinsics.fixnum compiler.cfg.linear-scan.assignment
-compiler.cfg.ssa.destruction compiler.cfg.value-numbering
+compiler.cfg.liveness compiler.cfg.ssa.destruction compiler.cfg.value-numbering
-compiler.codegen.gc-maps cpu.architecture help.markup help.syntax kernel layouts
+compiler.codegen.gc-maps cpu.architecture help.markup help.syntax kernel
-math sequences slots.private system ;
+layouts math sequences slots.private system vm ;
 IN: compiler.cfg.instructions
 
 HELP: ##alien-invoke
@@ -81,6 +81,9 @@ HELP: ##copy
   }
 } ;
 
+HELP: ##dispatch
+{ $class-description "Special instruction for implementing " { $link case } " blocks." } ;
+
 HELP: ##fixnum-add
 { $class-description "Instruction for adding two fixnums together." }
 { $see-also emit-fixnum+ } ;
@@ -100,7 +103,8 @@ HELP: ##jump
 } ;
 
 HELP: ##load-double
-{ $class-description "I dont know." } ;
+{ $class-description "Loads a " { $link float } " into a SIMD register." }
+{ $see-also %load-double } ;
 
 HELP: ##load-memory-imm
 { $class-description "Instruction for loading data from memory into an MMS register." }
@@ -115,6 +119,23 @@ HELP: ##load-reference
   }
 } ;
 
+HELP: ##load-vector
+{ $class-description
+  "Loads a " { $link byte-array } " into an SSE register."
+}
+{ $see-also %load-vector } ;
+
+HELP: ##local-allot
+{ $class-description
+  "An instruction for allocating memory in the words own stack frame. It's mostly used for receiving data from alien calls. It has the following slots:"
+  { $table
+    { { $slot "dst" } { "Register into which a pointer to the stack allocated memory is put." } }
+    { { $slot "size" } { "Number of bytes to allocate." } }
+    { { $slot "offset" } { } }
+  }
+}
+{ $see-also ##allot } ;
+
 HELP: ##mul-vector
 { $class-description
   "SIMD instruction." } ;
@@ -167,6 +188,10 @@ HELP: ##return
 HELP: ##safepoint
 { $class-description "Instruction that inserts a safe point in the generated code." } ;
 
+HELP: ##save-context
+{ $class-description "The ##save-context instructions saves the state of the data, retain and callstacks in the threads " { $link context } " struct." }
+{ $see-also %save-context } ;
+
 HELP: ##set-slot
 { $class-description
   "An instruction for the non-primitive, non-immediate variant of " { $link set-slot } ". It has the following slots:"
@@ -196,6 +221,16 @@ HELP: ##set-slot-imm
 HELP: ##single>double-float
 { $class-description "Converts a single precision value (32-bit usually) stored in a SIMD register to a double precision one (64-bit usually)." } ;
 
+HELP: ##shuffle-vector-imm
+{ $class-description "Shuffles the vector in a SSE register according to the given shuffle pattern. It is used to extract a given element of the vector."
+  { $table
+    { { $slot "dst" } { "Destination register to shuffle the vector to." } }
+    { { $slot "src" } { "Source register." } }
+    { { $slot "shuffle" } { "Shuffling pattern." } }
+  }
+}
+{ $see-also %shuffle-vector-imm } ;
+
 HELP: ##slot-imm
 { $class-description
   "Instruction for reading a slot value from an object."
@@ -351,6 +386,7 @@ $nl
   ##call-gc
   ##check-nursery-branch
   ##local-allot
+  ##save-context
   allocation-insn
   gc-map
   gc-map-insn
@@ -421,7 +457,10 @@ $nl
   ##div-vector
   ##horizontal-add-vector
   ##horizontal-sub-vector
+  ##load-double
+  ##load-vector
   ##mul-vector
+  ##shuffle-vector-imm
   ##single>double-float
   ##store-memory-imm
   ##sub-vector

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

@@ -5,14 +5,17 @@ HELP: admissible-registers
 { $values { "cfg" cfg } { "regs" assoc } }
 { $description "Lists all registers usable by the cfg by register class. In general, that's all registers except the frame pointer register that might be used by the cfg for other purposes." } ;
 
+HELP: allocate-and-assign-registers
+{ $values { "cfg" cfg } }
+{ $description "Allocates and assigns registers and spill slots to SSA values in the cfg." } ;
+
 HELP: linear-scan
 { $values { "cfg" cfg } }
 { $description "Entry point for the linear scan register alloation pass." } ;
 
 ARTICLE: "compiler.cfg.linear-scan" "Linear-scan register allocation"
-"Linear scan to assign physical registers. SSA liveness must have been computed already."
+"Linear scan to assign physical registers. SSA liveness must have been computed already. It also spills registers that are live during gc calls."
-$nl
+{ $heading "References" }
-"References:"
 { $list
   "Linear Scan Register Allocation by Massimiliano Poletto and Vivek Sarkar http://www.cs.ucla.edu/~palsberg/course/cs132/linearscan.pdf"
   "Linear Scan Register Allocation for the Java HotSpot Client Compiler by Christian Wimmer and http://www.ssw.uni-linz.ac.at/Research/Papers/Wimmer04Master/"

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

@@ -1,5 +1,6 @@
 USING: assocs compiler.cfg compiler.cfg.def-use compiler.cfg.instructions
-compiler.cfg.representations help.markup help.syntax kernel ;
+compiler.cfg.representations hash-sets help.markup help.syntax kernel
+sequences ;
 IN: compiler.cfg.liveness
 
 HELP: base-pointers
@@ -17,6 +18,10 @@ HELP: fill-gc-map
 { $values { "live-set" assoc } { "gc-map" gc-map } }
 { $description "Assigns values to the " { $slot "gc-roots" } " and " { $slot "derived-roots" } " slots of the " { $link gc-map } ". Does nothing if the " { $link select-representations } " pass hasn't ran." } ;
 
+HELP: gc-roots
+{ $values { "live-set" assoc } { "derived-roots" hash-set } { "gc-roots" sequence } }
+{ $description "" } ;
+
 HELP: gen-uses
 { $values { "live-set" assoc } { "insn" insn } }
 { $description "Adds the vregs the instruction uses to the live set." }

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

@@ -1,10 +1,15 @@
-USING: compiler.cfg.instructions compiler.cfg.ssa.interference
+USING: compiler.cfg compiler.cfg.instructions
+compiler.cfg.ssa.destruction.leaders compiler.cfg.ssa.interference
 help.markup help.syntax kernel make sequences ;
 IN: compiler.cfg.ssa.destruction.coalescing
 
 HELP: class-element-map
 { $var-description "Maps leaders to equivalence class elements which are sequences of " { $link vreg-info } " instances." } ;
 
+HELP: coalesce-cfg
+{ $values { "cfg" cfg } }
+{ $description "In this step, " { $link leader-map } " info is calculated." } ;
+
 HELP: coalesce-elements
 { $values { "merged" "??" } { "follower" "vreg" } { "leader" "vreg" } }
 { $description "Delete follower's class, and set leaders's class to merged." } ;

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

@@ -10,7 +10,7 @@ HELP: cleanup-cfg
 ARTICLE: "compiler.cfg.ssa.destruction" "SSA Destruction"
 "Because of the design of the register allocator, this pass has three peculiar properties."
 { $list
-  "Instead of renaming vreg usages in the CFG, a map from vregs to canonical representatives is computed. This allows the register allocator to use the original SSA names to get reaching definitions."
+  { "Instead of renaming vreg usages in the CFG, a map from vregs to canonical representatives is computed. This allows the register allocator to use the original SSA names to get reaching definitions. See " { $link leader-map } "." }
   { "Useless " { $link ##copy } " instructions, and all " { $link ##phi } " instructions, are eliminated, so the register allocator does not have to remove any redundant operations." }
   { "This pass computes live sets and fills out the " { $slot "gc-roots" } " slots of GC maps with " { $vocab-link "compiler.cfg.liveness" } ", so the linear scan register allocator does not need to compute liveness again." }
 }

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

@@ -6,7 +6,7 @@ HELP: ?leader
 { $description "The leader of the vreg or the register itself if it has no other leader." } ;
 
 HELP: leader-map
-{ $var-description "A map from vregs to canonical representatives due to coalescing done by SSA destruction. Used by liveness analysis and the register allocator, so we can use the original SSA names to get certain info (reaching definitions, representations). By default, each vreg is its own leader." }
+{ $var-description "A map from vregs to canonical representatives due to coalescing done by SSA destruction. Used by liveness analysis and the register allocator, so we can use the original SSA names to get certain info (reaching definitions, representations). By default, each vreg is its own leader. The data is computed in the " { $vocab-link "compiler.cfg.ssa.destruction" } " compiler pass." }
 { $see-also init-coalescing } ;
 
 ARTICLE: "compiler.cfg.ssa.destruction.leaders" "Leader book-keeping" "This vocab defines words for getting the leaders of vregs." ;

basis/compiler/cfg/stack-frame/stack-frame-docs.factor

@@ -1,4 +1,4 @@
-USING: cpu.x86 help.markup help.syntax layouts math ;
+USING: compiler.cfg.instructions cpu.x86 help.markup help.syntax layouts math ;
 IN: compiler.cfg.stack-frame
 
 HELP: stack-frame
@@ -25,7 +25,7 @@ HELP: stack-frame
 
 HELP: (stack-frame-size)
 { $values { "stack-frame" stack-frame } { "n" integer } }
-{ $description "Base stack frame size, without padding and alignment." } ;
+{ $description "Base stack frame size, without padding and alignment. If the size is zero, then no " { $link ##epilogue } " and " { $link ##prologue } " needs to be emitted for the word." } ;
 
 HELP: spill-offset
 { $values { "n" integer } { "offset" integer } }