From d2c0ae9fd98968709d15933c6dfb7162eb416fb2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= <bjourne@gmail.com>
Date: Mon, 19 Jan 2015 13:08:37 +0000
Subject: [PATCH] compiler.cfg.stacks.*: more docs

---
 .../cfg/stacks/clearing/clearing-docs.factor  | 35 +++++++++++++++++++
 .../cfg/stacks/vacant/vacant-docs.factor      |  7 +++-
 2 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 basis/compiler/cfg/stacks/clearing/clearing-docs.factor

diff --git a/basis/compiler/cfg/stacks/clearing/clearing-docs.factor b/basis/compiler/cfg/stacks/clearing/clearing-docs.factor
new file mode 100644
index 0000000000..4b2e912504
--- /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 fefe1d0d8e..4fb717357f 100644
--- 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"