From 160df8b3f1f75d3db1ada92ae98156c3fe058c1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= Date: Thu, 22 May 2014 19:01:57 +0200 Subject: [PATCH] Docs: for compiler.cfg.* vocabs --- .../cfg/builder/blocks/blocks-docs.factor | 19 +++++- .../compiler/cfg/builder/builder-docs.factor | 59 ++++++++++++++++++- .../cfg/stacks/height/height-docs.factor | 12 ++++ basis/compiler/cfg/stacks/stacks-docs.factor | 14 +++++ 4 files changed, 102 insertions(+), 2 deletions(-) create mode 100644 basis/compiler/cfg/stacks/height/height-docs.factor create mode 100644 basis/compiler/cfg/stacks/stacks-docs.factor diff --git a/basis/compiler/cfg/builder/blocks/blocks-docs.factor b/basis/compiler/cfg/builder/blocks/blocks-docs.factor index 7a03dd4499..fd7a0a752d 100644 --- a/basis/compiler/cfg/builder/blocks/blocks-docs.factor +++ b/basis/compiler/cfg/builder/blocks/blocks-docs.factor @@ -1,5 +1,22 @@ -USING: compiler.cfg help.markup help.syntax ; +USING: compiler.cfg compiler.tree help.markup help.syntax math ; IN: compiler.cfg.builder.blocks +HELP: initial-basic-block +{ $description "Creates an initial empty " { $link basic-block } " and stores it in the basic-block dynamic variable." } ; + +HELP: begin-basic-block +{ $description "Terminates the current block and initializes a new " { $link basic-block } " to begin outputting instructions to. The new block is included in the old blocks " { $slot "successors" } "." } ; + HELP: make-kill-block { $description "Marks the current " { $link basic-block } " being processed as a kill block." } ; + +HELP: call-height +{ $values { "#call" #call } { "n" number } } +{ $description "Calculates how many items a " { $link #call } " will add or remove from the data stack." } +{ $examples + { $example + "USING: compiler.cfg.builder.blocks prettyprint ;" + "[ 3append ] build-tree second call-height ." + "-2" + } +} ; diff --git a/basis/compiler/cfg/builder/builder-docs.factor b/basis/compiler/cfg/builder/builder-docs.factor index 60c4052d9f..842bd332b7 100644 --- a/basis/compiler/cfg/builder/builder-docs.factor +++ b/basis/compiler/cfg/builder/builder-docs.factor @@ -1,6 +1,63 @@ -USING: compiler.tree help.markup help.syntax sequences words ; +USING: assocs compiler.cfg compiler.cfg.builder.blocks +compiler.cfg.stacks.local compiler.tree help.markup help.syntax literals math +multiline sequences words ; IN: compiler.cfg.builder +<< +STRING: ex-emit-call +USING: compiler.cfg.builder kernel make prettyprint ; +begin-stack-analysis initial-basic-block \ dummy 3 [ emit-call ] { } make drop +current-height basic-block [ get . ] bi@ . +T{ current-height { d 3 } } +T{ basic-block + { id 134 } + { successors + V{ + T{ basic-block + { id 135 } + { instructions + V{ + T{ ##call { word dummy } } + T{ ##branch } + } + } + { successors V{ T{ basic-block { id 136 } } } } + { kill-block? t } + } + } + } +} +; + +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 } } +} +; +>> + +HELP: procedures +{ $var-description "Used as a temporary storage for the current cfg during construction of all cfgs." } ; + +HELP: make-input-map +{ $values { "#call" #call } { "assoc" assoc } } +{ $description "Creates an " { $link assoc } " that maps input values to the shuffle operation to stack locations." } +{ $examples { $unchecked-example $[ ex-make-input-map ] } } ; + + +HELP: emit-call +{ $values { "word" word } { "height" number } } +{ $description "Emits a call to the given word to the " { $link cfg } " being constructed. \"height\" is the number of items being added to or removed from the data stack. Side effects of the word is that it modifies the \"basic-block\" and " { $link current-height } " variables." } +{ $examples + "In this example, a call to a dummy word is emitted which pushes three items onto the stack." + { $unchecked-example $[ ex-emit-call ] } +} +{ $see-also call-height } ; + HELP: emit-node { $values { "node" node } } { $description "Emits some kind of code for the node." } ; diff --git a/basis/compiler/cfg/stacks/height/height-docs.factor b/basis/compiler/cfg/stacks/height/height-docs.factor new file mode 100644 index 0000000000..59f53706b6 --- /dev/null +++ b/basis/compiler/cfg/stacks/height/height-docs.factor @@ -0,0 +1,12 @@ +USING: compiler.cfg compiler.cfg.registers help.markup help.syntax math ; +IN: compiler.cfg.stacks.height + +HELP: record-stack-heights +{ $values { "ds-height" number } { "rs-height" number } { "bb" basic-block } } +{ $description "Does something." } ; + +HELP: ds-heights +{ $var-description "Assoc that records the data stacks height at the entry of each " { $link basic-block } "." } ; + +HELP: rs-heights +{ $var-description "Assoc that records the retain stacks height at the entry of each " { $link basic-block } "." } ; diff --git a/basis/compiler/cfg/stacks/stacks-docs.factor b/basis/compiler/cfg/stacks/stacks-docs.factor new file mode 100644 index 0000000000..aea74b9fcc --- /dev/null +++ b/basis/compiler/cfg/stacks/stacks-docs.factor @@ -0,0 +1,14 @@ +USING: compiler.cfg.stacks.local help.markup help.syntax math sequences ; +IN: compiler.cfg.stacks + +HELP: begin-stack-analysis +{ $description "Initializes a set of variables related to stack analysis of Factor words." } +{ $see-also current-height } ; + +HELP: adjust-d +{ $values { "n" number } } +{ $description "Changes the height of the current data stack." } ; + +HELP: rs-store +{ $values { "vregs" "a " { $link sequence } " of vregs." } } +{ $description "Stores one or more virtual register values on the retain stack. This modifies the " { $link current-height } " dynamic variable." } ;