From 280620c55ffbf410c41f9434038a10e0a6844981 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= Date: Mon, 26 May 2014 13:26:00 +0200 Subject: [PATCH] Docs: docs for compiler-related words --- basis/compiler/cfg/cfg-docs.factor | 12 +++++++++--- .../cfg/instructions/instructions-doc.factor | 8 +++++++- .../cfg/linearization/linearization-docs.factor | 11 +++++++++++ basis/compiler/cfg/stacks/local/local-docs.factor | 2 +- basis/compiler/codegen/codegen-docs.factor | 7 +++---- basis/compiler/compiler-docs.factor | 7 ++++++- .../cpu/x86/assembler/operands/operands-docs.factor | 6 ++++++ core/compiler/units/units-docs.factor | 2 +- core/words/words-docs.factor | 5 +++++ 9 files changed, 49 insertions(+), 11 deletions(-) create mode 100644 basis/compiler/cfg/linearization/linearization-docs.factor create mode 100644 basis/cpu/x86/assembler/operands/operands-docs.factor diff --git a/basis/compiler/cfg/cfg-docs.factor b/basis/compiler/cfg/cfg-docs.factor index 87257fd00e..0be57bb075 100644 --- a/basis/compiler/cfg/cfg-docs.factor +++ b/basis/compiler/cfg/cfg-docs.factor @@ -1,5 +1,5 @@ -USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax -namespaces vectors words ; +USING: compiler.cfg compiler.cfg.instructions compiler.cfg.rpo help.markup +help.syntax namespaces sequences vectors words ; IN: compiler.cfg HELP: basic-block @@ -21,5 +21,11 @@ HELP: cfg { $table { { $slot "entry" } { "Initial " { $link basic-block } " of the graph." } } { { $slot "word" } { "The " { $link word } " the cfg is produced from." } } + { { $slot "post-order" } { "The blocks of the cfg in a post order traversal " { $link sequence } "." } } } -} ; +} +{ $see-also post-order } ; + +HELP: cfg-changed +{ $values { "cfg" cfg } } +{ $description "Resets all \"calculated\" slots in the cfg which forces them to be recalculated." } ; diff --git a/basis/compiler/cfg/instructions/instructions-doc.factor b/basis/compiler/cfg/instructions/instructions-doc.factor index 04b3cc6a12..888c4c0856 100644 --- a/basis/compiler/cfg/instructions/instructions-doc.factor +++ b/basis/compiler/cfg/instructions/instructions-doc.factor @@ -1,6 +1,12 @@ USING: compiler.cfg help.markup help.syntax kernel layouts slots.private ; IN: compiler.cfg.instructions +HELP: new-insn +{ $values { "class" class } { "insn" insn } } +{ $description + "Boa wrapper for the " { $link insn } " class with " { $slot "insn#" } " set to " { $link f } "." +} ; + HELP: insn { $class-description "Base class for all virtual cpu instructions, used by the CFG IR." @@ -21,7 +27,7 @@ HELP: foldable-insn 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." + "An instruction that increases or decreases the data stacks height by n. For example, " { $link 2drop } " decreases it by two and pushing an item increases it by one." } ; HELP: ##prologue diff --git a/basis/compiler/cfg/linearization/linearization-docs.factor b/basis/compiler/cfg/linearization/linearization-docs.factor new file mode 100644 index 0000000000..cc99891689 --- /dev/null +++ b/basis/compiler/cfg/linearization/linearization-docs.factor @@ -0,0 +1,11 @@ +USING: compiler.cfg compiler.cfg.linearization compiler.codegen help.markup +help.syntax kernel macros sequences ; +IN: compiler.cfg.linearization + +HELP: linearization-order +{ $values + { "cfg" cfg } + { "bb" sequence } +} +{ $description "Lists the basic blocks in linearization order. That is, the order in which they will be written in the generated assembly code." } +{ $see-also generate } ; diff --git a/basis/compiler/cfg/stacks/local/local-docs.factor b/basis/compiler/cfg/stacks/local/local-docs.factor index 89c8580b6e..691b8061e0 100644 --- a/basis/compiler/cfg/stacks/local/local-docs.factor +++ b/basis/compiler/cfg/stacks/local/local-docs.factor @@ -16,7 +16,7 @@ HELP: translate-local-loc } ; HELP: emit-height-changes -{ $description "Emits stack height change instructions to the CFG being built." } +{ $description "Emits stack height change instructions to the CFG being built. This is done when a " { $link basic-block } " is begun or ended." } { $examples { $example "USING: compiler.cfg.stacks.local make namespaces prettyprint ;" diff --git a/basis/compiler/codegen/codegen-docs.factor b/basis/compiler/codegen/codegen-docs.factor index 37ae572db0..0331db601b 100644 --- a/basis/compiler/codegen/codegen-docs.factor +++ b/basis/compiler/codegen/codegen-docs.factor @@ -65,11 +65,10 @@ HELP: generate { $values { "cfg" cfg } { "code" sequence } } { $description "Generates assembly code for the given cfg. The output " { $link sequence } " has six items with the following interpretations:" { $list - { "The first element is a sequence of alien function symbols and " { $link dll } "s used by the cfg interleaved." } - "The second item is the parameter table." - { "The third item is the " { $link literal-table } "." } + { "The first element is a sequence of alien function symbols and " { $link dll } "s used by the cfg interleaved. That is, the " { $link parameter-table } "." } + { "The second item is the " { $link literal-table } "." } { "The third item is the relocation table as a " { $link byte-array } "." } - "The fourth item is the label table." + { "The fourth item is the " { $link label-table } "." } { "The fifth item is the generated assembly code as a " { $link byte-array } ". It still contains unresolved crossreferences." } "The sixth item is the size of the stack frame in bytes." } diff --git a/basis/compiler/compiler-docs.factor b/basis/compiler/compiler-docs.factor index 1a357ddda6..1418e5edae 100644 --- a/basis/compiler/compiler-docs.factor +++ b/basis/compiler/compiler-docs.factor @@ -1,4 +1,4 @@ -USING: assocs compiler.cfg.builder compiler.cfg.optimizer +USING: assocs compiler.cfg compiler.cfg.builder compiler.cfg.optimizer compiler.errors compiler.tree.builder compiler.tree.optimizer compiler.units compiler.codegen help.markup help.syntax io parser quotations sequences words ; @@ -58,6 +58,11 @@ HELP: frontend { $values { "word" word } { "tree" sequence } } { $description "First step of the compilation process. It outputs a high-level tree in SSA form." } ; +HELP: backend +{ $values { "tree" "a " { $link sequence } " of SSA nodes" } { "word" word } } +{ $description "The second last step of the compilation process. A word and its SSA tree is taken as input and a " { $link cfg } " is built from which assembly code is generated." } +{ $see-also generate } ; + HELP: compile-word { $values { "word" word } } { $description "Compile a single word." } diff --git a/basis/cpu/x86/assembler/operands/operands-docs.factor b/basis/cpu/x86/assembler/operands/operands-docs.factor new file mode 100644 index 0000000000..1aa6624bc7 --- /dev/null +++ b/basis/cpu/x86/assembler/operands/operands-docs.factor @@ -0,0 +1,6 @@ +USING: cpu.x86.assembler.operands.private help.markup help.syntax math ; +IN: cpu.x86.assembler.operands + +HELP: [RIP+] +{ $values { "displacement" number } { "indirect" indirect } } +{ $description "Creates an indirect operand relative to the RIP register." } ; diff --git a/core/compiler/units/units-docs.factor b/core/compiler/units/units-docs.factor index c370018c46..35af4a28f1 100644 --- a/core/compiler/units/units-docs.factor +++ b/core/compiler/units/units-docs.factor @@ -85,7 +85,7 @@ $nl "The alist maps words to one of the following:" { $list { "a quotation - in this case, the quotation is compiled with the non-optimizing compiler and the word will call the quotation when executed." } - { "a 5-element array " { $snippet "{ parameters literals relocation labels code }" } " - in this case, a code heap block is allocated with the given data and the word will call the code block when executed. This is used by the optimizing compiler." } + { "a 6-element array " { $snippet "{ parameters literals relocation labels code stack-frame-size }" } " - in this case, a code heap block is allocated with the given data and the word will call the code block when executed. This is used by the optimizing compiler." } } "If any of the redefined words may already be referenced by other words in the code heap, from outside of the compilation unit, then a scan of the code heap must be performed to update all word call sites. Passing " { $link t } " as the " { $snippet "update-existing?" } " parameter enables this code path." $nl diff --git a/core/words/words-docs.factor b/core/words/words-docs.factor index 4006706ffc..1f23d5cbbf 100644 --- a/core/words/words-docs.factor +++ b/core/words/words-docs.factor @@ -345,6 +345,11 @@ HELP: deprecated? { $description "Tests if an object is " { $link POSTPONE: deprecated } "." } { $notes "Outputs " { $link f } " if the object is not a word." } ; +HELP: inline? +{ $values { "obj" object } { "?" "a boolean" } } +{ $description "Tests if an object is " { $link POSTPONE: inline } "." } +{ $notes "Outputs " { $link f } " if the object is not a word." } ; + HELP: subwords { $values { "word" word } { "seq" sequence } } { $description "Lists all specializations for the given word." }