compiler.cfg.*: new and improved docs

basis/compiler/cfg/branch-splitting/branch-splitting-docs.factor

@@ -0,0 +1,6 @@
+USING: compiler.cfg compiler.cfg.utilities help.markup help.syntax ;
+IN: compiler.cfg.branch-splitting
+
+HELP: clone-basic-block
+{ $values { "bb" basic-block } { "bb'" basic-block } }
+{ $description "The new block temporarily gets the same RPO number as the old one, until the next time RPO is computed. This is just to make " { $link back-edge? } " work." } ;

basis/compiler/cfg/branch-splitting/branch-splitting.factor

@@ -11,9 +11,6 @@ IN: compiler.cfg.branch-splitting
     [ clone dup rename-insn-temps ] map ;
 
 : clone-basic-block ( bb -- bb' )
-    ! The new block temporarily gets the same RPO number as the
-    ! old one, until the next time RPO is computed. This is just
-    ! to make 'back-edge?' work.
     <basic-block>
         swap
         {

basis/compiler/cfg/dataflow-analysis/dataflow-analysis-docs.factor

@@ -25,7 +25,8 @@ HELP: join-sets
   { "dfa" class }
   { "set" "merged state" }
 }
-{ $description "Generic word which merges multiple states into one. A block in the cfg might have multiple predecessors and then this word is used to compute the merged input state to use to analyze the block." } ;
+{ $description "Generic word which merges multiple states into one. A block in the cfg might have multiple predecessors and then this word is used to compute the merged input state to use to analyze the block." }
+{ $see-also transfer-set } ;
 
 
 <PRIVATE

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

@@ -23,3 +23,5 @@ HELP: next-vreg-rep
 
 HELP: loc
 { $class-description "Represents a location on the stack. 'n' is an index starting from the top of the stack going down. So 0 is the top of the stack, 1 is what would be the top of the stack after a 'drop', and so on. It has two subclasses, " { $link ds-loc } " for data stack location and " { $link rs-loc } " for locations on the retain stack." } ;
+
+ABOUT: "compiler.cfg.registers"

basis/compiler/cfg/representations/peephole/peephole-docs.factor

@@ -0,0 +1,12 @@
+USING: compiler.cfg.instructions help.markup help.syntax ;
+IN: compiler.cfg.representations.peephole
+
+HELP: convert-to-zero-vector?
+{ $values { "insn" insn } }
+{ $description "When a literal zeroes/ones vector is unboxed, we replace the " { $link ##load-reference } " with a " { $link ##zero-vector } " or " { $link ##fill-vector } " instruction since this is more efficient." } ;
+
+
+ARTICLE: "compiler.cfg.representations.peephole" "Peephole optimizations"
+"Representation selection performs some peephole optimizations when inserting conversions to optimize for a few common cases." ;
+
+ABOUT: "compiler.cfg.representations.peephole"

basis/compiler/cfg/representations/peephole/peephole.factor

@@ -7,9 +7,6 @@ compiler.cfg.representations.selection cpu.architecture kernel
 layouts locals make math namespaces sequences ;
 IN: compiler.cfg.representations.peephole
 
-! Representation selection performs some peephole optimizations
-! when inserting conversions to optimize for a few common cases
-
 GENERIC: optimize-insn ( insn -- )
 
 SYMBOL: insn-index
@@ -65,8 +62,6 @@ M: ##load-integer optimize-insn
         [ obj>> byte-array? ]
     } 1&& ;
 
-! When a literal zeroes/ones vector is unboxed, we replace the ##load-reference
-! with a ##zero-vector or ##fill-vector instruction since this is more efficient.
 : convert-to-zero-vector? ( insn -- ? )
     {
         [ dst>> rep-of vector-rep? ]

basis/compiler/cfg/stacks/map/map-docs.factor

@@ -0,0 +1,6 @@
+USING: assocs compiler.cfg help.markup help.syntax ;
+IN: compiler.cfg.stacks.map
+
+HELP: trace-stack-state
+{ $values { "cfg" cfg } { "assoc" assoc } }
+{ $description "Outputs an assoc with the instruction numbers as keys and as values two tuples of the data and retain stacks shapes before that instruction. All instructions in the cfg gets numbered as a side-effect." } ;

basis/compiler/cfg/stacks/map/map.factor

@@ -41,8 +41,10 @@ M: ##replace-imm visit-insn mark-location ;
 M: ##replace visit-insn mark-location ;
 
 M: ##call visit-insn ( state insn -- state' )
-    ! After a word call, we can't trust any overinitialized locations
+    ! A call instruction may increase the stack height. Then issue a
-    ! to contain valid pointers anymore.
+    ! minor-gc with some of the stack locations scrubbed which would
+    ! overwrite the overinitialized locations we're tracking. That is
+    ! why they need to be cleared here.
     drop [ first2 [ 0 >= ] filter 2array ] map ;
 
 ERROR: vacant-peek insn ;

basis/compiler/constants/constants-docs.factor

@@ -0,0 +1,15 @@
+USING: compiler.codegen.relocation help.markup help.syntax ;
+IN: compiler.constants
+
+HELP: rt-cards-offset
+{ $description "Relocation offset type for the cards table." }
+{ $see-also rel-cards-offset } ;
+
+HELP: rt-decks-offset
+{ $description "Relocation offset type for the decks table." }
+{ $see-also rel-decks-offset } ;
+
+
+ARTICLE: "compiler.constants" "VM memory layout constants" "Common constants" ;
+
+ABOUT: "compiler.constants"