basis/compiler/cfg/linear-scan/allocation/state/state-docs.factor

   1 USING: assocs compiler.cfg compiler.cfg.instructions
   2 compiler.cfg.linear-scan.allocation
   3 compiler.cfg.linear-scan.allocation.spilling
   4 compiler.cfg.linear-scan.live-intervals cpu.architecture heaps help.markup
   5 help.syntax kernel math sequences vectors ;
   6 IN: compiler.cfg.linear-scan.allocation.state
   7
   8 HELP: activate-intervals
   9 { $values { "n" integer } }
  10 { $description "Any inactive intervals which have ended are moved to handled. Any inactive intervals which do not cover the current position are moved to active." } ;
  11
  12 HELP: active-intervals
  13 { $var-description { $link assoc } " of active live intervals. The keys are register class symbols and the values vectors of " { $link live-interval-state } "." } ;
  14
  15 HELP: add-active
  16 { $values { "live-interval" live-interval-state } }
  17 { $description "Adds a live interval to the " { $link active-intervals } " assoc." }
  18 { $see-also active-intervals } ;
  19
  20 HELP: align-spill-area
  21 { $values { "align" integer } { "cfg" cfg } }
  22 { $description "This word is used to ensure that the alignment of the spill area in the " { $link cfg } " is equal to the largest " { $link spill-slot } "." } ;
  23
  24 HELP: assign-spill-slot
  25 { $values
  26   { "coalesced-vreg" "vreg" }
  27   { "rep" representation }
  28   { "spill-slot" spill-slot }
  29 }
  30 { $description "Assigns a spill slot for the vreg." } ;
  31
  32 HELP: deactivate-intervals
  33 { $values { "n" integer } }
  34 { $description "Any active intervals which have ended are moved to handled. Any active intervals which cover the current position are moved to inactive." } ;
  35
  36 HELP: free-positions
  37 { $values
  38   { "registers" assoc }
  39   { "reg-class" reg-class }
  40   { "assoc" assoc }
  41 }
  42 { $description "Returns an assoc with the registers that can be used by the live interval. A utility used by " { $link register-status } " word." } ;
  43
  44 HELP: handled-intervals
  45 { $var-description { $link vector } " of handled live intervals. This variable I think is only used during the " { $link allocate-registers } " step." } ;
  46
  47 HELP: inactive-intervals
  48 { $var-description { $link assoc } " of inactive live intervals. Keys are register class symbols and the values vectors of " { $link live-interval-state } "." }
  49 { $see-also active-intervals } ;
  50
  51 HELP: init-allocator
  52 { $values
  53   { "live-intervals" { $link sequence } " of " { $link live-interval-state } }
  54   { "sync-points" { $link sequence } " of " { $link sync-point } }
  55   { "registers" { $link assoc } " mapping from register class to available machine registers." }
  56 }
  57 { $description "Initializes the state for the register allocator." }
  58 { $see-also reg-class } ;
  59
  60 HELP: next-spill-slot
  61 { $values { "size" "number of bytes required" } { "spill-slot" spill-slot } }
  62 { $description "Creates a new " { $link spill-slot } " of the given size and also allocates space in the " { $link cfg } " in the 'cfg' dynamic variable for it." } ;
  63
  64 HELP: progress
  65 { $var-description "Start index of current live interval. We ensure that all live intervals added to the unhandled set have a start index strictly greater than this one. This ensures that we can catch infinite loop situations. We also ensure that all live intervals added to the handled set have an end index strictly smaller than this one. This helps catch bugs." }
  66 { $see-also check-handled check-unhandled } ;
  67
  68 HELP: register-available?
  69 { $values { "new" live-interval-state } { "result" "a pair" } { "?" boolean } }
  70 { $description "Whether the register in 'result' can be used for the given live interval." } ;
  71
  72 HELP: registers
  73 { $var-description "Mapping from register classes to sequences of machine registers." } ;
  74
  75 HELP: spill-slots
  76 { $var-description "Mapping from pairs of vregs and represenation sizes to spill slots." } ;
  77
  78 HELP: unhandled-min-heap
  79 { $var-description { $link min-heap } " of all live intervals and sync points which still needs processing. It is used by " { $link (allocate-registers) } ". The key of the heap is a pair of values, " { $slot "start" } " and " { $slot "end" } " for the "  { $link live-interval-state } " tuple and " { $slot "n" } " and 1/0.0 for the " { $link sync-point } " tuple. That way smaller live intervals are always processed before larger ones and all live intervals before sync points." } ;