From 6a8336047d1e3c5949401d025327532d2dadd744 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= Date: Mon, 5 May 2014 01:12:41 +0200 Subject: [PATCH] Docs: initial docs for the compiler.cfg.* vocabs --- basis/compiler/cfg/cfg-docs.factor | 10 ++++ .../cfg/instructions/instructions-doc.factor | 49 +++++++++++++++++++ .../cfg/instructions/instructions.factor | 1 - .../instructions/syntax/syntax-docs.factor | 29 +++++++++++ .../cfg/intrinsics/intrinsics-docs.factor | 5 ++ .../cfg/intrinsics/slots/slots-docs.factor | 39 +++++++++++++++ 6 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 basis/compiler/cfg/cfg-docs.factor create mode 100644 basis/compiler/cfg/instructions/instructions-doc.factor create mode 100644 basis/compiler/cfg/instructions/syntax/syntax-docs.factor create mode 100644 basis/compiler/cfg/intrinsics/intrinsics-docs.factor create mode 100644 basis/compiler/cfg/intrinsics/slots/slots-docs.factor diff --git a/basis/compiler/cfg/cfg-docs.factor b/basis/compiler/cfg/cfg-docs.factor new file mode 100644 index 0000000000..bda3118f28 --- /dev/null +++ b/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: +{ $values { "bb" basic-block } } +{ $description "Creates a new empty basic block." } ; diff --git a/basis/compiler/cfg/instructions/instructions-doc.factor b/basis/compiler/cfg/instructions/instructions-doc.factor new file mode 100644 index 0000000000..962dfb9767 --- /dev/null +++ b/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 } ; diff --git a/basis/compiler/cfg/instructions/instructions.factor b/basis/compiler/cfg/instructions/instructions.factor index 0fc8763a01..f73d10c960 100644 --- a/basis/compiler/cfg/instructions/instructions.factor +++ b/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 diff --git a/basis/compiler/cfg/instructions/syntax/syntax-docs.factor b/basis/compiler/cfg/instructions/syntax/syntax-docs.factor new file mode 100644 index 0000000000..c24e43850f --- /dev/null +++ b/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 ] } } ; diff --git a/basis/compiler/cfg/intrinsics/intrinsics-docs.factor b/basis/compiler/cfg/intrinsics/intrinsics-docs.factor new file mode 100644 index 0000000000..53d268d216 --- /dev/null +++ b/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." } ; diff --git a/basis/compiler/cfg/intrinsics/slots/slots-docs.factor b/basis/compiler/cfg/intrinsics/slots/slots-docs.factor new file mode 100644 index 0000000000..5847e73dcf --- /dev/null +++ b/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 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." } ;