compiler.cfg.stacks.*: more docs

diff --git a/basis/compiler/cfg/stacks/clearing/clearing-docs.factor b/basis/compiler/cfg/stacks/clearing/clearing-docs.factor
new file mode 100644 (file)
index 0000000..4b2e912
--- /dev/null
+++ b/basis/compiler/cfg/stacks/clearing/clearing-docs.factor
@@ -0,0 +1,35 @@
+USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax sequences strings ;
+IN: compiler.cfg.stacks.clearing
+
+ARTICLE: "compiler.cfg.stacks.clearing" "Uninitialized stack location clearing"
+"A compiler pass that inserts " { $link ##replace-imm } " instructions front of unsafe " { $link ##peek } " instructions in the " { $link cfg } ". Consider the following sequence of instructions."
+{ $code
+  "##inc-d 2"
+  "##peek RCX D 2"
+}
+"The ##peek can cause a stack underflow and then there will be two uninitialized locations on the data stack that can't be traced. To counteract that, this pass modifies the instruction sequence so that it becomes:"
+{ $code
+  "##inc-d 2"
+  "##replace-imm 17 D 0"
+  "##replace-imm 17 D 1"
+  "##peek RCX D 2"
+} ;
+
+HELP: dangerous-insn?
+{ $values { "state" "a stack state" } { "insn" insn } }
+{ $description "Checks if the instruction is dangerous (can cause a stack underflow). " }
+{ $examples
+  { $example
+    "USING: compiler.cfg.instructions compiler.cfg.registers prettyprint ;"
+    "{ { 0 { } } { 0 { } } } T{ ##peek { loc D 0 } } dangerous-insn? ."
+    "t"
+  }
+  { $example
+    "USING: compiler.cfg.instructions compiler.cfg.registers prettyprint ;"
+    "{ { 0 { } } { 2 { 0 1 } } } T{ ##peek { loc R 0 } } dangerous-insn? ."
+    "f"
+  }
+} ;
+
+
+ABOUT: "compiler.cfg.stacks.clearing"

diff --git a/basis/compiler/cfg/stacks/vacant/vacant-docs.factor b/basis/compiler/cfg/stacks/vacant/vacant-docs.factor
index fefe1d0d8ee07f5ce6305903ab3215b7c14b0d4b..4fb717357f69549a78c50844caf18acef1fcca67 100644 (file)
--- a/basis/compiler/cfg/stacks/vacant/vacant-docs.factor
+++ b/basis/compiler/cfg/stacks/vacant/vacant-docs.factor
@@ -1,4 +1,5 @@
-USING: compiler.cfg.instructions help.markup help.syntax sequences strings ;
+USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax sequences
+strings ;
 IN: compiler.cfg.stacks.vacant
 
 ARTICLE: "compiler.cfg.stacks.vacant" "Uninitialized/overinitialized stack location analysis"
@@ -36,4 +37,8 @@ HELP: overinitialized>bits
 }
 { $description "Converts a sequence of overinitialized stack locations to the pattern of 1:s and 0:s that can be put in the " { $slot "check-d" } " and " { $slot "check-r" } " slots of a " { $link gc-map } ". 0:s are initialized locations and 0:s are empty ones. First element is stack location -1,second -2 and so on." } ;
 
+HELP: fill-gc-maps
+{ $values { "cfg" cfg } }
+{ $description "Populates the scrub-d, check-d, scrub-r and check-r slots of all gc maps in the cfg." } ;
+
 ABOUT: "compiler.cfg.stacks.vacant"