From c76a994f27aca61a81749b7d19b5419232419a6b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= <bjourne@gmail.com>
Date: Sun, 11 May 2014 13:01:13 +0200
Subject: [PATCH] Docs: new stub documentation for vocabs in compiler.cfg

---
 .../cfg/builder/alien/alien-docs.factor       |  6 +++
 .../builder/alien/boxing/boxing-docs.factor   | 34 +++++++++++++++
 .../cfg/gc-checks/gc-checks-docs.factor       | 41 +++++++++++++++++++
 .../save-contexts/save-contexts-docs.factor   | 10 +++++
 4 files changed, 91 insertions(+)
 create mode 100644 basis/compiler/cfg/builder/alien/alien-docs.factor
 create mode 100644 basis/compiler/cfg/builder/alien/boxing/boxing-docs.factor
 create mode 100644 basis/compiler/cfg/gc-checks/gc-checks-docs.factor
 create mode 100644 basis/compiler/cfg/save-contexts/save-contexts-docs.factor

diff --git a/basis/compiler/cfg/builder/alien/alien-docs.factor b/basis/compiler/cfg/builder/alien/alien-docs.factor
new file mode 100644
index 0000000000..0dee4a3d81
--- /dev/null
+++ b/basis/compiler/cfg/builder/alien/alien-docs.factor
@@ -0,0 +1,6 @@
+USING: help.markup help.syntax make stack-checker.alien ;
+IN: compiler.cfg.builder.alien
+
+HELP: caller-return
+{ $values { "params" alien-node-params } }
+{ $description "If the last alien call returns a value, then this word will emit an instruction to the current sequence being constructed by " { $link make } " which boxes it." } ;
diff --git a/basis/compiler/cfg/builder/alien/boxing/boxing-docs.factor b/basis/compiler/cfg/builder/alien/boxing/boxing-docs.factor
new file mode 100644
index 0000000000..d78554063e
--- /dev/null
+++ b/basis/compiler/cfg/builder/alien/boxing/boxing-docs.factor
@@ -0,0 +1,34 @@
+USING: alien.c-types compiler.cfg.instructions help.markup help.syntax make
+math ;
+IN: compiler.cfg.builder.alien.boxing
+
+HELP: box
+{ $values
+  { "vregs" "a one-element sequence containing a virtual register indentifier" }
+  { "reps" "a one-element sequence containing a representation symbol" }
+  { "c-type" c-type }
+}
+{ $description "Emits a " { $link ##box-alien } " instruction which boxes an alien value contained in the given register." }
+{ $examples
+  { $unchecked-example
+    "USING: compiler.cfg.builder.alien.boxing make prettyprint ;"
+    "{ 71 } { int-rep } void* base-type [ box ] { } make nip ."
+    "{ T{ ##box-alien { dst 105 } { src 71 } { temp 104 } } }"
+  }
+}
+{ $see-also ##box-alien } ;
+
+HELP: stack-size
+{ $values
+  { "c-type" c-type }
+  { "n" number }
+}
+{ $description "Calculates how many bytes of stack space an instance of the C type requires." }
+{ $examples
+  { $unchecked-example
+    "USING: compiler.cfg.builder.alien.boxing prettyprint vm ;"
+    "context base-type stack-size ."
+    "144"
+  }
+}
+{ $see-also heap-size } ;
diff --git a/basis/compiler/cfg/gc-checks/gc-checks-docs.factor b/basis/compiler/cfg/gc-checks/gc-checks-docs.factor
new file mode 100644
index 0000000000..8e5260d509
--- /dev/null
+++ b/basis/compiler/cfg/gc-checks/gc-checks-docs.factor
@@ -0,0 +1,41 @@
+USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax kernel
+layouts math sequences slots.private ;
+IN: compiler.cfg.gc-checks
+
+<PRIVATE
+
+HELP: insert-gc-checks
+{ $values { "cfg" cfg } { "cfg'" cfg } }
+{ $description "Inserts gc checks in each " { $link basic-block } " in the cfg where they are needed." } ;
+
+HELP: insert-gc-check?
+{ $values { "bb" basic-block } { "?" "a boolean" } }
+{ $description "Whether to insert a gc check in the block or not." } ;
+
+HELP: blocks-with-gc
+{ $values { "cfg" cfg } { "bbs" "a " { $link sequence } " of " { $link basic-block } } }
+{ $description "Lists all basic blocks in the cfg that needs gc checks." } ;
+
+HELP: allocation-size*
+{ $values { "insn" insn } { "n" number } }
+{ $description "Number of bytes allocated by the given instruction." } ;
+
+HELP: allocation-size
+{ $values { "insns" { $link sequence } " of " { $link insn } } { "n" number } }
+{ $description "Calculates the total number of bytes allocated by the block." }
+{ $examples
+  { $example
+    "USING: accessors compiler.cfg.debugger compiler.cfg.gc-checks.private kernel prettyprint sequences ;"
+    "[ V{ } clone ] test-ssa first entry>> successors>> first instructions>> allocation-size ."
+    "32"
+  }
+} ;
+
+PRIVATE>
+
+ARTICLE: "compiler.cfg.gc-checks" "Garbage collection check insertion"
+"This pass runs after representation selection, since it needs to know which vregs can contain tagged pointers." ;
+
+HELP: process-block
+{ $values { "bb" basic-block } }
+{ $description "Process a block that needs a gc check. New blocks are allocated and connected for the gc branches." } ;
diff --git a/basis/compiler/cfg/save-contexts/save-contexts-docs.factor b/basis/compiler/cfg/save-contexts/save-contexts-docs.factor
new file mode 100644
index 0000000000..9255ec94d1
--- /dev/null
+++ b/basis/compiler/cfg/save-contexts/save-contexts-docs.factor
@@ -0,0 +1,10 @@
+USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax ;
+IN: compiler.cfg.save-contexts
+
+HELP: insert-save-contexts
+{ $values { "cfg" cfg } { "cfg'" cfg } }
+{ $description "Inserts " { $link ##save-context } " instructions in each " { $link basic-block } " in the cfg that needs them. Save contexts are needed after instructions that modify the context, or instructions that read parameter registers." } ;
+
+HELP: bb-needs-save-context?
+{ $values { "bb" basic-block } { "?" "a boolean" } }
+{ $description "Whether to insert a " { $link ##save-context } " instruction in the block or not." } ;