Docs: initial docs for the compiler.cfg.* vocabs

basis/compiler/cfg/cfg-docs.factor

@@ -0,0 +1,10 @@
+USING: compiler.cfg help.markup help.syntax ;
+
+HELP: basic-block
+{ $class-description
+  "Factors representation of a basic block in the cfg. A basic block is a sequence of instructions that always are executed sequentially and doesn't contain any branching."
+} ;
+
+HELP: <basic-block>
+{ $values { "bb" basic-block } }
+{ $description "Creates a new empty basic block." } ;

basis/compiler/cfg/instructions/instructions-doc.factor

@@ -0,0 +1,49 @@
+USING: help.markup help.syntax kernel layouts slots.private ;
+IN: compiler.cfg.instructions
+
+HELP: vreg-insn
+{ $class-description
+  "Base class for instructions that uses vregs."
+} ;
+
+HELP: ##inc-d
+{ $class-description
+  "An instruction that increases or decreases the data stacks size by n. For example, " { $link 2drop } " decreases it by two and pushing an item increases it by one."
+} ;
+
+HELP: ##set-slot
+{ $class-description
+  "An instruction for non-primitive non-immediate variant of " { $link set-slot } ". It has the following slots:"
+  { $table
+    { { $slot "src" } { "Object to put in the slot." } }
+    { { $slot "obj" } { "Object to set the slot on." } }
+    { { $slot "slot" } { "Slot index." } }
+    { { $slot "tag" } { "Type tag for obj." } }
+  }
+}
+{ $see-also ##set-slot-imm } ;
+
+HELP: ##replace-imm
+{ $class-description
+  "An instruction that replaces an item on the data or register stack with an " { $link immediate } " value." } ;
+
+HELP: ##replace
+{ $class-description
+  "Copies a value from a machine register to a stack location." }
+{ $see-also ##peek ##replace-imm } ;
+
+
+HELP: ##jump
+{ $class-description
+  "An uncondiation jump instruction. It has the following slots:"
+  { $table
+    { { $slot "word" } { "Word whose address the instruction is jumping to." } }
+  }
+  "Note that the optimizer is sometimes able to optimize away a " { $link ##call } " and " { $link ##return } " pair into one ##jump instruction."
+} ;
+
+HELP: ##peek
+{ $class-description
+  "Copies a value from a stack location to a machine register."
+}
+{ $see-also ##replace } ;

basis/compiler/cfg/instructions/instructions.factor

@@ -16,7 +16,6 @@ V{ } clone insn-classes set-global
 ! Virtual CPU instructions, used by CFG IR
 TUPLE: insn ;
 
-! Instructions which use vregs
 TUPLE: vreg-insn < insn ;
 
 ! Instructions which do not have side effects; used for

basis/compiler/cfg/instructions/syntax/syntax-docs.factor

@@ -0,0 +1,29 @@
+USING: help.markup help.syntax literals multiline sequences ;
+IN: compiler.cfg.instructions.syntax
+
+<<
+STRING: parse-insn-slot-specs-ex
+USING: compiler.cfg.instructions.syntax prettyprint splitting ;
+"use: src/int-rep temp: temp/int-rep" " " split parse-insn-slot-specs .
+{
+    T{ insn-slot-spec
+        { type use }
+        { name "src" }
+        { rep int-rep }
+    }
+    T{ insn-slot-spec
+        { type temp }
+        { name "temp" }
+        { rep int-rep }
+    }
+}
+;
+>>
+
+HELP: parse-insn-slot-specs
+{ $values
+  { "seq" "a " { $link sequence } " of tokens" }
+  { "specs" "a " { $link sequence } " of " { $link insn-slot-spec } " items." }
+}
+{ $description "Parses a sequence of tokens into a sequence of instruction slot specifiers." }
+{ $examples { $example $[ parse-insn-slot-specs-ex ] } } ;

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

@@ -0,0 +1,5 @@
+USING: compiler.tree help.markup help.syntax words ;
+IN: compiler.cfg.intrinsics
+HELP: emit-intrinsic
+{ $values { "node" node } { "word" word } }
+{ $description "Emit optimized intrinsic code for a word instead of merely calling it. The \"intrinsic\" property of the word (which is expected to be a quotation) is called with the node as input." } ;

basis/compiler/cfg/intrinsics/slots/slots-docs.factor

@@ -0,0 +1,39 @@
+USING: classes classes.builtin compiler.tree compiler.tree.propagation.info
+help.markup help.syntax math layouts sequences slots.private words ;
+IN: compiler.cfg.intrinsics.slots
+
+HELP: class-tag
+{ $values { "class" class } { "tag/f" "a number or f" } }
+{ $description "Finds the class number for this class if it is a subclass of a builtin class, or " { $link f } " if it isn't." }
+{ $examples
+  { $example
+    "USING: compiler.cfg.intrinsics.slots math prettyprint ;"
+    "complex class-tag ."
+    "7"
+  }
+} ;
+
+HELP: immediate-slot-offset?
+{ $values { "value-info" value-info-state } { "?" "true or false" } }
+{ $description
+  { $link t } " if the value info is a literal " { $link fixnum } " that is small enough to fit into a machine register." }
+{ $examples
+  { $example
+    "USING: compiler.cfg.intrinsics.slots compiler.tree.propagation.info prettyprint ;"
+    "33 <literal-info> immediate-slot-offset? ."
+    "t"
+  }
+} ;
+
+HELP: value-tag
+{ $values { "info" value-info-state } { "n" number } }
+{ $description "Finds the class number for this value-info-states class (an index in the " { $link builtins } " list), or " { $link f } " if it hasn't one." } ;
+
+HELP: emit-write-barrier?
+{ $values { "infos" "a " { $link sequence } " of " { $link value-info-state } " tuples." } { "?" "true or false" } }
+{ $description
+  "Whether a given call to " { $link set-slot } " requires a write barrier to be emitted or not. Write barriers are always needed except when the element to set in the slot is known by the compiler to be " { $link immediate } "." } ;
+
+HELP: emit-set-slot
+{ $values { "node" node } }
+{ $description "Emits intrinsic code for a " { $link set-slot } " call." } ;