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 } " becase 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." } ;