compiler.cfg.*: new and improved docs

diff --git a/basis/compiler/cfg/branch-splitting/branch-splitting-docs.factor b/basis/compiler/cfg/branch-splitting/branch-splitting-docs.factor
new file mode 100644 (file)
index 0000000..fe777f1
--- /dev/null
+++ b/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." } ;

diff --git a/basis/compiler/cfg/branch-splitting/branch-splitting.factor b/basis/compiler/cfg/branch-splitting/branch-splitting.factor
index bcb0a74ed23f2e7de9d7c5c0e2a286490295a7a9..40826a921c1d2df02261a135b79b488dba4e6b97 100644 (file)
--- a/basis/compiler/cfg/branch-splitting/branch-splitting.factor
+++ b/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
         {

diff --git a/basis/compiler/cfg/dataflow-analysis/dataflow-analysis-docs.factor b/basis/compiler/cfg/dataflow-analysis/dataflow-analysis-docs.factor
index 4f7081b4da936592a928d335fab0516f5767c880..74fa8fd8aef21b63beba98f3372a60618e2e8cff 100644 (file)
--- a/basis/compiler/cfg/dataflow-analysis/dataflow-analysis-docs.factor
+++ b/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

diff --git a/basis/compiler/cfg/registers/registers-docs.factor b/basis/compiler/cfg/registers/registers-docs.factor
index dddba48334039c92acba466bfa068113d41959d5..bf15b4e637c8c9a02449277b63181dcb64a12969 100644 (file)
--- a/basis/compiler/cfg/registers/registers-docs.factor
+++ b/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"

diff --git a/basis/compiler/cfg/representations/peephole/peephole-docs.factor b/basis/compiler/cfg/representations/peephole/peephole-docs.factor
new file mode 100644 (file)
index 0000000..982230d
--- /dev/null
+++ b/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"

diff --git a/basis/compiler/cfg/representations/peephole/peephole.factor b/basis/compiler/cfg/representations/peephole/peephole.factor
index eaa1535801d1f29fc82bc8bc7e86011f02c3e94a..f505cb7b8aa24a27866bdd9e6fd43a9ec54832e0 100644 (file)
--- a/basis/compiler/cfg/representations/peephole/peephole.factor
+++ b/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? ]

diff --git a/basis/compiler/cfg/stacks/map/map-docs.factor b/basis/compiler/cfg/stacks/map/map-docs.factor
new file mode 100644 (file)
index 0000000..bb0a172
--- /dev/null
+++ b/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." } ;

diff --git a/basis/compiler/cfg/stacks/map/map.factor b/basis/compiler/cfg/stacks/map/map.factor
index 10f62d4dc10b941cb894e4990a34c1692f9564cd..fb458431e82b9b8768230b9774954f4efcab99da 100644 (file)
--- a/basis/compiler/cfg/stacks/map/map.factor
+++ b/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
-    ! to contain valid pointers anymore.
+    ! A call instruction may increase the stack height. Then issue a
+    ! 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 ;

diff --git a/basis/compiler/constants/constants-docs.factor b/basis/compiler/constants/constants-docs.factor
new file mode 100644 (file)
index 0000000..567dcfb
--- /dev/null
+++ b/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"