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

   1 USING: arrays assocs compiler.cfg compiler.cfg.builder.blocks
   2 compiler.cfg.instructions compiler.cfg.stacks.local
   3 compiler.tree help.markup help.syntax kernel literals math
   4 multiline quotations sequences vectors words ;
   5 IN: compiler.cfg.builder
   6
   7 <<
   8 STRING: ex-emit-call
   9 USING: compiler.cfg.builder compiler.cfg.builder.blocks compiler.cfg.stacks
  10 kernel make prettyprint ;
  11 begin-stack-analysis <basic-block> set-basic-block
  12 \ dummy 3 [ emit-call ] { } make drop
  13 height-state basic-block [ get . ] bi@
  14 { { 3 0 } { 0 0 } }
  15 T{ basic-block
  16     { id 1903165 }
  17     { successors
  18         V{
  19             T{ basic-block
  20                 { id 1903166 }
  21                 { instructions
  22                     V{
  23                         T{ ##call { word dummy } }
  24                         T{ ##branch }
  25                     }
  26                 }
  27                 { successors
  28                     V{ T{ basic-block { id 1903167 } } }
  29                 }
  30                 { kill-block? t }
  31             }
  32         }
  33     }
  34 }
  35 ;
  36
  37 STRING: ex-make-input-map
  38 USING: compiler.cfg.builder prettyprint ;
  39 T{ #shuffle { in-d { 37 81 92 } } } make-input-map .
  40 { { 37 D: 2 } { 81 D: 1 } { 92 D: 0 } }
  41 ;
  42 >>
  43
  44 HELP: build-cfg
  45 { $values { "nodes" sequence } { "word" word } { "procedures" sequence } }
  46 { $description "Builds one or more cfgs from the given word." } ;
  47
  48 HELP: procedures
  49 { $var-description "A " { $link vector } " used as temporary storage during cfg construction for all procedures being built." }
  50 { $see-also build-cfg } ;
  51
  52 HELP: make-input-map
  53 { $values { "#shuffle" #shuffle } { "assoc" assoc } }
  54 { $description "Creates an " { $link assoc } " that maps input values to the shuffle operation to stack locations." }
  55 { $examples { $unchecked-example $[ ex-make-input-map ] } } ;
  56
  57 HELP: emit-call
  58 { $values
  59   { "block" basic-block }
  60   { "word" word }
  61   { "height" number }
  62   { "block'" basic-block }
  63 }
  64 { $description
  65   "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."
  66   $nl
  67   "Side effects of the word is that it modifies the \"basic-block\" and " { $link height-state } " variables."
  68 }
  69 { $examples
  70   "In this example, a call to a dummy word is emitted which pushes three items onto the stack."
  71   { $unchecked-example $[ ex-emit-call ] }
  72 }
  73 { $see-also call-height } ;
  74
  75 HELP: emit-loop-call
  76 { $values { "successor-block" basic-block } { "current-block" basic-block } }
  77 { $description "Sets the given block as the successor of the current block. Then ends the block." } ;
  78
  79 HELP: emit-node
  80 { $values { "block" basic-block } { "node" node } { "block'" basic-block } }
  81 { $description "Emits CFG instructions for the given SSA node. The word can add one or more basic blocks to the " { $link cfg } ". The next block to operate on is pushed onto the stack."
  82 $nl
  83 "The following classes emit-node methods does not change the current block:"
  84   { $list
  85     { $link #alien-assembly }
  86     { $link #alien-callback }
  87     { $link #alien-indirect }
  88   }
  89 } ;
  90
  91 HELP: emit-nodes
  92 { $values
  93   { "block" "current " { $link basic-block } }
  94   { "nodes" sequence }
  95   { "block'" basic-block }
  96 }
  97 { $description "Emits all tree nodes to the cfg. The next block to operate on is pushed onto the stack." } ;
  98
  99 HELP: end-word
 100 { $values
 101   { "block" "current " { $link basic-block } }
 102   { "block'" basic-block }
 103 }
 104 { $description "Ends the word by adding a basic block containing a " { $link ##return } " instructions to the " { $link cfg } "." } ;
 105
 106 HELP: height-changes
 107 { $values { "#shuffle" #shuffle } { "height-changes" pair } }
 108 { $description "Returns a two-tuple which represents how much the " { $link #shuffle } " node increases or decreases the data and retainstacks." }
 109 { $examples
 110   { $example
 111     "USING: compiler.cfg.builder compiler.tree prettyprint ;"
 112     "T{ #shuffle { in-d { 37 81 92 } } { out-d { 20 } } } height-changes ."
 113     "{ -2 0 }"
 114   }
 115 } ;
 116
 117 HELP: out-vregs/stack
 118 { $values { "#shuffle" #shuffle } { "pair" sequence } }
 119 { $description "Returns a sequence of what vregs are on which stack locations after the shuffle instruction." } ;
 120
 121 HELP: trivial-branch?
 122 { $values
 123   { "nodes" "a " { $link sequence } " of " { $link node } " instances" }
 124   { "value" { $maybe "the pushed value" } }
 125   { "?" boolean }
 126 }
 127 { $description "Checks whether nodes is a trivial branch or not. The branch is counted as trivial if all it does is push a literal value on the stack." }
 128 { $examples
 129   { $example
 130     "USING: compiler.cfg.builder compiler.tree prettyprint ;"
 131     "{ T{ #push { literal 25 } } } trivial-branch? . ."
 132     "t\n25"
 133   }
 134 } ;
 135
 136 HELP: with-cfg-builder
 137 { $values { "nodes" sequence } { "word" word } { "label" word } { "quot" quotation } }
 138 { $description "Combinator used to begin and end stack analysis so that the given quotation can build the cfg. The quotation is passed the initial basic block on the stack." } ;
 139
 140 ARTICLE: "compiler.cfg.builder"
 141 "Final stage of compilation generates machine code from dataflow IR"
 142 "The compiler first builds an SSA IR tree of the word to be compiled (see " { $vocab-link "compiler.tree.builder" } ") then this vocab converts it to a CFG IR tree. The result is not in SSA form; this is constructed later by calling compiler.cfg.ssa.construction:construct-ssa."
 143 $nl
 144 "Each tree node type has its own implementation of the " { $link emit-node } " generic. In that word, cfg instructions (tuples prefixed with ##) are output to basic blocks and the cfg constructed."
 145 $nl
 146 "Main word:"
 147 { $subsections
 148   build-cfg
 149 }
 150 "Block adders:"
 151 { $subsections
 152   begin-word
 153   end-word
 154 }
 155 "Combinators:"
 156 { $subsections
 157     with-cfg-builder
 158 }
 159 "Emitters for " { $link #call } ":"
 160 { $subsections
 161   emit-call
 162   emit-loop-call
 163 }
 164 "Emitters for " { $link #dispatch } " and " { $link #if } ":"
 165 { $subsections
 166   emit-actual-if
 167   emit-branch
 168   emit-if
 169   emit-trivial-if
 170 }
 171 "Emitters for " { $link #recursive } ":"
 172 {
 173     $subsections
 174     emit-loop
 175     emit-recursive
 176     end-branch
 177 }
 178 "Helpers for " { $link #shuffle } ":"
 179 {
 180     $subsections
 181     height-changes
 182     out-vregs/stack
 183 } ;
 184
 185 ABOUT: "compiler.cfg.builder"