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

   1 USING: assocs compiler.cfg compiler.cfg.builder.blocks
   2 compiler.cfg.stacks.local compiler.tree help.markup help.syntax
   3 kernel literals math multiline sequences vectors words ;
   4 IN: compiler.cfg.builder
   5
   6 <<
   7 STRING: ex-emit-call
   8 USING: compiler.cfg.builder compiler.cfg.builder.blocks compiler.cfg.stacks
   9 kernel make prettyprint ;
  10 begin-stack-analysis <basic-block> set-basic-block
  11 \ dummy 3 [ emit-call ] { } make drop
  12 height-state basic-block [ get . ] bi@
  13 { { 3 0 } { 0 0 } }
  14 T{ basic-block
  15     { id 1903165 }
  16     { successors
  17         V{
  18             T{ basic-block
  19                 { id 1903166 }
  20                 { instructions
  21                     V{
  22                         T{ ##call { word dummy } }
  23                         T{ ##branch }
  24                     }
  25                 }
  26                 { successors
  27                     V{ T{ basic-block { id 1903167 } } }
  28                 }
  29                 { kill-block? t }
  30             }
  31         }
  32     }
  33 }
  34 ;
  35
  36 STRING: ex-make-input-map
  37 USING: compiler.cfg.builder prettyprint ;
  38 T{ #shuffle { in-d { 37 81 92 } } } make-input-map .
  39 H{
  40     { 81 T{ ds-loc { n 1 } } }
  41     { 37 T{ ds-loc { n 2 } } }
  42     { 92 T{ ds-loc } }
  43 }
  44 ;
  45 >>
  46
  47 HELP: procedures
  48 { $var-description "A " { $link vector } " used as temporary storage during cfg construction for all procedures being built." } ;
  49
  50 HELP: make-input-map
  51 { $values { "#shuffle" #shuffle } { "assoc" assoc } }
  52 { $description "Creates an " { $link assoc } " that maps input values to the shuffle operation to stack locations." }
  53 { $examples { $unchecked-example $[ ex-make-input-map ] } } ;
  54
  55 HELP: emit-call
  56 { $values { "word" word } { "height" number } }
  57 { $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 height-state } " variables." }
  58 { $examples
  59   "In this example, a call to a dummy word is emitted which pushes three items onto the stack."
  60   { $unchecked-example $[ ex-emit-call ] }
  61 }
  62 { $see-also call-height } ;
  63
  64 HELP: emit-loop-call
  65 { $values { "basic-block" basic-block } }
  66 { $description "Sets the given block as the successor of the current block. Then ends the block." } ;
  67
  68 HELP: emit-node
  69 { $values { "node" node } }
  70 { $description "Emits CFG instructions for the given SSA node." } ;
  71
  72 HELP: trivial-branch?
  73 { $values
  74   { "nodes" "a " { $link sequence } " of " { $link node } " instances" }
  75   { "value" { $maybe "the pushed value" } }
  76   { "?" boolean }
  77 }
  78 { $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." }
  79 { $examples
  80   { $example
  81     "USING: compiler.cfg.builder compiler.tree prettyprint ;"
  82     "{ T{ #push { literal 25 } } } trivial-branch? . ."
  83     "t\n25"
  84   }
  85 } ;
  86
  87 HELP: build-cfg
  88 { $values { "nodes" sequence } { "word" word } { "procedures" sequence } }
  89 { $description "Builds one or more cfgs from the given word." } ;
  90
  91 ARTICLE: "compiler.cfg.builder"
  92 "Final stage of compilation generates machine code from dataflow IR"
  93 "Convert tree SSA IR to CFG IR. The result is not in SSA form; this is constructed later by calling compiler.cfg.ssa.construction:construct-ssa." ;
  94
  95 ABOUT: "compiler.cfg.builder"