From 26d53f90193f5851553be24717c27dd1c8d9ae97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= Date: Thu, 1 Sep 2016 02:16:30 +0200 Subject: [PATCH] compiler.cfg.*: compiler doc updates --- .../cfg/builder/blocks/blocks-docs.factor | 2 +- .../compiler/cfg/builder/builder-docs.factor | 20 +++++++++++++------ .../cfg/instructions/instructions-docs.factor | 19 +++++++++++++----- .../cfg/intrinsics/misc/misc-docs.factor | 6 +++++- .../cfg/stack-frame/stack-frame-docs.factor | 1 + basis/compiler/cfg/stacks/stacks-docs.factor | 15 ++++++++++++-- basis/compiler/tree/tree-docs.factor | 8 ++++---- 7 files changed, 52 insertions(+), 19 deletions(-) diff --git a/basis/compiler/cfg/builder/blocks/blocks-docs.factor b/basis/compiler/cfg/builder/blocks/blocks-docs.factor index 6e16abcf29..476e96d78b 100644 --- a/basis/compiler/cfg/builder/blocks/blocks-docs.factor +++ b/basis/compiler/cfg/builder/blocks/blocks-docs.factor @@ -76,7 +76,7 @@ HELP: end-branch HELP: set-basic-block { $values { "basic-block" basic-block } } -{ $description "Sets the given blocks as the current one by storing it in the basic-block dynamic variable. If it has any " { $slot "instructions" } " the current " { $link building } " is set to those." } ; +{ $description "Sets the given blocks as the current one. If it has any " { $slot "instructions" } " the current " { $link building } " is set to those." } ; HELP: with-branch { $values diff --git a/basis/compiler/cfg/builder/builder-docs.factor b/basis/compiler/cfg/builder/builder-docs.factor index 246e61ae15..f57320b4b5 100644 --- a/basis/compiler/cfg/builder/builder-docs.factor +++ b/basis/compiler/cfg/builder/builder-docs.factor @@ -37,11 +37,7 @@ T{ basic-block STRING: ex-make-input-map USING: compiler.cfg.builder prettyprint ; T{ #shuffle { in-d { 37 81 92 } } } make-input-map . -H{ - { 81 T{ ds-loc { n 1 } } } - { 37 T{ ds-loc { n 2 } } } - { 92 T{ ds-loc } } -} +{ { 37 D: 2 } { 81 D: 1 } { 92 D: 0 } } ; >> @@ -109,7 +105,18 @@ HELP: end-word HELP: height-changes { $values { "#shuffle" #shuffle } { "height-changes" sequence } } -{ $description "Returns a two-tuple which represents how much the " { $link #shuffle } " node increases or decreases the data and retainstacks." } ; +{ $description "Returns a two-tuple which represents how much the " { $link #shuffle } " node increases or decreases the data and retainstacks." } +{ $examples + { $example + "USING: compiler.cfg.builder compiler.tree prettyprint ;" + "T{ #shuffle { in-d { 37 81 92 } } { out-d { 20 } } } height-changes ." + "{ -2 0 }" + } +} ; + +HELP: out-vregs/stack +{ $values { "#shuffle" #shuffle } { "seq" sequence } } +{ $description "Returns a sequence of what vregs are on which stack locations after the shuffle instruction." } ; HELP: trivial-branch? { $values @@ -172,6 +179,7 @@ $nl { $subsections height-changes + out-vregs/stack } ; ABOUT: "compiler.cfg.builder" diff --git a/basis/compiler/cfg/instructions/instructions-docs.factor b/basis/compiler/cfg/instructions/instructions-docs.factor index 34dae02d4e..44f399f3b7 100644 --- a/basis/compiler/cfg/instructions/instructions-docs.factor +++ b/basis/compiler/cfg/instructions/instructions-docs.factor @@ -10,6 +10,10 @@ HELP: ##alien-invoke { $class-description "An instruction for calling a function in a dynamically linked library. It has the following slots:" { $table + { + { $slot "dead-outputs" } + { "A sequence of return values from the function that the compiler.cfg.dce pass has figured out are not used." } + } { { $slot "reg-inputs" } { "Registers to use for the arguments to the function call. Each sequence item is a 3-tuple consisting of a " { $link spill-slot } ", register representation and a register. When the function is called, the parameter is copied from the spill slot to the given register." } @@ -22,14 +26,18 @@ HELP: ##alien-invoke { $slot "reg-outputs" } { "If the called function returns a value, then this slot is a one-element sequence containing a 3-tuple describing which register is used for the return value." } } - { - { $slot "gc-map" } - { "If the invoked C function calls Factor code which triggers a GC, then a " { $link gc-map } " is necessary to find the roots." } - } { { $slot "symbols" } { "Name of the function to call." } } { { $slot "dll" } { "A dll handle or " { $link f } "." } } + { + { $slot "gc-map" } + { + "If the invoked C function calls Factor code which triggers a GC, then a " + { $link gc-map } + " is necessary to find the roots." + } + } } - "Which function arguments that goes in " { $slot "reg-inputs" } " and which goes in " { $slot "stack-inputs" } " depend on the calling convention. In " { $link cdecl } " on " { $link x86.32 } ", all arguments goes in " { $slot "stack-inputs" } ", in " { $link x86.64 } " the first six arguments are passed in registers and then stack parameters are used for the remainder." + "Which function arguments that goes in " { $slot "reg-inputs" } " and which goes in " { $slot "stack-inputs" } " depend on the calling convention. In " { $link cdecl } " on " { $link x86.32 } ", all arguments goes in " { $slot "stack-inputs" } ", in " { $link x86.64 } " on " { $link unix } ", the first six arguments are passed in registers and then stack parameters are used for the remainder." } { $see-also #alien-invoke %alien-invoke } ; @@ -286,6 +294,7 @@ HELP: ##store-memory-imm { $slot "offset" } { "Offset in bytes from the address to where the data should be written." } } + { { $slot "rep" } { "Value representation in the vector register." } } { { $slot "src" } { "Vreg that contains the item to set." } } } } diff --git a/basis/compiler/cfg/intrinsics/misc/misc-docs.factor b/basis/compiler/cfg/intrinsics/misc/misc-docs.factor index 0e2fecd558..2716b78c9d 100644 --- a/basis/compiler/cfg/intrinsics/misc/misc-docs.factor +++ b/basis/compiler/cfg/intrinsics/misc/misc-docs.factor @@ -1,4 +1,4 @@ -USING: compiler.cfg compiler.tree help.markup help.syntax +USING: compiler.cfg compiler.tree help.markup help.syntax kernel kernel.private ; IN: compiler.cfg.intrinsics.misc @@ -9,3 +9,7 @@ HELP: emit-context-object { "block'" basic-block } } { $description "Emits intrinsic code for a call to the " { $link context-object } " primitive." } ; + +HELP: emit-eq +{ $values { "node" node } } +{ $description "Intrinsic emitter for the " { $link eq? } " word." } ; diff --git a/basis/compiler/cfg/stack-frame/stack-frame-docs.factor b/basis/compiler/cfg/stack-frame/stack-frame-docs.factor index 008a73eb3b..7c71945818 100644 --- a/basis/compiler/cfg/stack-frame/stack-frame-docs.factor +++ b/basis/compiler/cfg/stack-frame/stack-frame-docs.factor @@ -13,6 +13,7 @@ HELP: stack-frame "The stack frame is also aligned to a 16 byte boundary. It has the following slots:" { $table { { $slot "total-size" } { "Total size of the stack frame." } } + { { $slot "params" } { "Reserved parameter space." } } { { $slot "allot-area-base" } { "Base offset of the allocation area." } } { { $slot "allot-area-size" } { "Number of bytes requires for the allocation area." } } { { $slot "allot-area-align" } { "This slot is always at least " { $link cell } " bytes." } } diff --git a/basis/compiler/cfg/stacks/stacks-docs.factor b/basis/compiler/cfg/stacks/stacks-docs.factor index 21fef15880..c2ff2131f8 100644 --- a/basis/compiler/cfg/stacks/stacks-docs.factor +++ b/basis/compiler/cfg/stacks/stacks-docs.factor @@ -8,8 +8,8 @@ HELP: ds-push { $description "Used when translating the " { $link #push } " SSA node to CFG form. The node pushes a literal value onto the data stack." } ; HELP: begin-stack-analysis -{ $description "Initializes a set of variables related to stack analysis of Factor words." } -{ $see-also height-state } ; +{ $description "Initializes a set of variables related to global stack analysis of Factor words." } +{ $see-also begin-local-analysis height-state } ; HELP: end-stack-analysis { $values { "cfg" cfg } } @@ -36,3 +36,14 @@ HELP: 2inputs HELP: 3inputs { $values { "vreg1" "a vreg" } { "vreg2" "a vreg" } { "vreg3" "a vreg" } } { $description "Lifts the three topmost values from the datastack and stores them in virtual registers. The datastacks height is adjusted afterwards." } ; + +ARTICLE: "compiler.cfg.stacks" "Generating instructions for accessing the data and retain stacks" "This vocab contains utility words for manipulating the analysis data and retain stacks." +$nl +"When nodes in the dataflow IR pushes or pops items from the stacks, instructions for performing those actions aren't immediately emitted. Instead the analysis stacks are manipulated and when the stack analysis phase is complete, optimal stack shuffling code is emitted. This way, exactly the same instructions are emitted for equivalent qutations such as [ dup drop ] and [ ]." +$nl +"Popping from the datastack:" +{ $subsections 2inputs 3inputs ds-drop } +"Pushing to the datastack:" +{ $subsections ds-push store-vregs } ; + +ABOUT: "compiler.cfg.stacks" diff --git a/basis/compiler/tree/tree-docs.factor b/basis/compiler/tree/tree-docs.factor index e918964508..9f19de329e 100644 --- a/basis/compiler/tree/tree-docs.factor +++ b/basis/compiler/tree/tree-docs.factor @@ -1,6 +1,6 @@ -USING: alien assocs help.markup help.syntax kernel kernel.private quotations -sequences stack-checker.alien stack-checker.inlining stack-checker.values -stack-checker.visitor words ; +USING: alien assocs help.markup help.syntax kernel kernel.private +quotations sequences stack-checker.alien stack-checker.inlining +stack-checker.values stack-checker.visitor words ; IN: compiler.tree HELP: node @@ -14,7 +14,7 @@ HELP: #alien-invoke { $see-also alien-invoke } ; HELP: #alien-callback -{ $class-description "SSA tree node that constructs an alien callback." } ; +{ $class-description "SSA tree node that constructs an alien callback. It is not a subclass of " { $link #alien-node } ". " } ; HELP: #call { $class-description "SSA tree node that calls a word. It has the following slots:"