basis/compiler/cfg/cfg-docs.factor

   1 USING: compiler.cfg.instructions compiler.cfg.rpo
   2 compiler.cfg.stack-frame compiler.cfg.stacks.local compiler.tree
   3 cpu.x86.assembler.operands help.markup help.syntax kernel math
   4 namespaces sequences vectors words ;
   5 IN: compiler.cfg
   6
   7 HELP: basic-block
   8 { $class-description
   9   "Factors representation of a basic block in the Call Flow Graph (CFG). A basic block is a sequence of instructions that always are executed sequentially and doesn't contain any internal branching. It has the following slots:"
  10   { $table
  11     {
  12         { $slot "number" }
  13         { "The blocks sequence number. Generated by calling " { $link number-blocks } ". " }
  14     }
  15     {
  16         { $slot "successors" }
  17         { "A " { $link vector } " of basic blocks that may be executed directly after this block. Most blocks only have one successor but a block that checks where an if-condition should branch to would have two for example." }
  18     }
  19     {
  20         { $slot "predecessors" }
  21         { "The opposite of successors -- a " { $link vector } " of basic blocks from which the execution may have arrived into this block." }
  22     }
  23     {
  24         { $slot "instructions" }
  25         { "A " { $link vector } " of " { $link insn } " tuples which form the instructions of the basic block." }
  26     }
  27     {
  28         { $slot "kill-block?" }
  29         { "The first and the last block in a cfg and all blocks containing " { $link ##call } " instructions are kill blocks. Kill blocks can't be optimized so they are omitted from certain optimization steps." }
  30     }
  31     {
  32         { $slot "height" }
  33         "Block's height as a " { $link height-state } ". What the heights of the block was at entry and how much they were increased in the block."
  34     }
  35     {
  36         { $slot "replaces" }
  37         { "Used by " { $vocab-link "compiler.cfg.stacks.local" } " for local stack analysis." }
  38     }
  39     {
  40         { $slot "peeks" }
  41         { "Used by " { $vocab-link "compiler.cfg.stacks.local" } " for local stack analysis." }
  42     }
  43     {
  44         { $slot "kills" }
  45         { "Used by " { $vocab-link "compiler.cfg.stacks.local" } " for local stack analysis." }
  46     }
  47   }
  48 }
  49 { $notes "A basic-block is an " { $link identity-tuple } " because it is used as a hash table key by the compiler." } ;
  50
  51 HELP: <basic-block>
  52 { $values { "bb" basic-block } }
  53 { $description "Creates a new empty basic block. The " { $slot "id" } " slot is initialized with the value of the basic-block " { $link counter } "." } ;
  54
  55 HELP: <cfg>
  56 { $values { "word" word } { "label" "label" } { "entry" basic-block } { "cfg" cfg } }
  57 { $description "Constructor for " { $link cfg } ". " { $slot "spill-area-size" } " and " { $slot "spill-area-align" } " are set to default values." } ;
  58
  59
  60 HELP: cfg
  61 { $class-description
  62   "Call flow graph. It has the following slots:"
  63   { $table
  64     { { $slot "entry" } { "Root " { $link basic-block } " of the graph." } }
  65     { { $slot "word" } { "The " { $link word } " the cfg is produced from." } }
  66     { { $slot "post-order" } { "The blocks of the cfg in a post order traversal " { $link sequence } "." } }
  67     { { $slot "stack-frame" } { { $link stack-frame } " of the cfg." } }
  68     { { $slot "frame-pointer?" } { "Whether the cfg needs a frame pointer. Only cfgs generated for " { $link #alien-callback } " nodes does need it. If the slot is " { $link t } ", then the frame pointer register (" { $link RBP } " on x86.64 archs) will not be clobbered by register allocation. See " { $vocab-link "compiler.cfg.linear-scan" } " for details." } }
  69   }
  70 }
  71 { $see-also <cfg> post-order } ;
  72
  73 HELP: cfg-changed
  74 { $values { "cfg" cfg } }
  75 { $description "Resets all \"calculated\" slots in the cfg which forces them to be recalculated." }
  76 { $see-also predecessors-changed } ;
  77
  78 HELP: spill-offset
  79 { $values { "n" integer } { "offset" integer } }
  80 { $description "Offset in the current " { $link stack-frame } " to byte at index 'n' in the spill area." } ;
  81
  82 ARTICLE: "compiler.cfg" "Control Flow Graph IR"
  83 "The compiler.cfg vocab and subvocabs implements the part of the optimizing compiler that analyzes code in the CFG format. The vocab " { $vocab-link "compiler.cfg.builder" } " defines words for building the CFG from SSA IR and the rest of the vocabs in the hierarchy optimization steps that are then applied to it. The graph is then passed to the " { $vocab-link "compiler.codegen" } " vocab which emits machine code."
  84 $nl
  85 "The main datatype in the vocab is the " { $link cfg } " tuple. It represents the CFG of a Factor word. The cfg tuple has a slot 'entry' pointing to a " { $link basic-block } ". This block in turn points to other basic blocks, and together they form the call flow graph of the word." ;
  86
  87 ABOUT: "compiler.cfg"