basis/compiler/codegen/gc-maps/gc-maps-docs.factor

   1 USING: bit-arrays byte-arrays compiler.cfg compiler.cfg.instructions
   2 compiler.cfg.stack-frame help.markup help.syntax kernel math sequences ;
   3 IN: compiler.codegen.gc-maps
   4
   5 HELP: emit-gc-info-bitmap
   6 { $values
   7   { "gc-maps" sequence }
   8   { "spill-count" "maximum number of spill slots" }
   9 }
  10 { $description "Emits a bitmap of live locations of spill slots in the 'gc-maps' to the current make sequence." } ;
  11
  12 HELP: emit-gc-roots
  13 { $values
  14   { "seqs" "a sequence of sequences" }
  15   { "n" "maximum number of spill slots" }
  16 } { $description "Emits the sequences of spill slots as a sequence of " { $link t } " and " { $link f } " values to the current make sequence." } ;
  17
  18 HELP: emit-uint
  19 { $values { "n" integer } }
  20 { $description "Emits an unsigned 32 bit integer to the make sequence being created. The word takes care of ensuring that the byte order is correct for the current machine." }
  21 { $examples
  22   { $example
  23     "USING: compiler.codegen.gc-maps make prettyprint ;"
  24     "[ 0xffff emit-uint ] B{ } make ."
  25     "B{ 255 255 0 0 }"
  26   }
  27 } ;
  28
  29 HELP: emit-gc-maps
  30 { $description "GC maps are emitted so that the end is aligned to a 16-byte boundary." } ;
  31
  32 HELP: gc-maps
  33 { $var-description "Variable that holds a sequence of " { $link gc-map } " tuples. Gc maps are added to the sequence by " { $link gc-map-here } "." } ;
  34
  35 HELP: gc-map-needed?
  36 { $values { "gc-map/f" { $maybe gc-map } } { "?" boolean } }
  37 { $description "If all slots in the gc-map are empty, then it doesn't need to be emitted." } ;
  38
  39 HELP: gc-root-offsets
  40 { $values { "gc-map" gc-map } { "offsets" sequence } }
  41 { $description "Gets the offets of all roots in a gc-map. The " { $link cfg } " variable must have been set and the stack-frame slot been initialized." } ;
  42
  43 HELP: serialize-gc-maps
  44 { $values { "byte-array" byte-array } }
  45 { $description "Serializes the gc-maps that have been registered in the " { $link gc-maps } " variable into a byte-array." } ;
  46
  47 HELP: gc-map-here
  48 { $values { "gc-map" gc-map } }
  49 { $description "Registers the gc map in the " { $link gc-maps } " dynamic variable at the current compiled offset." } ;
  50
  51 ARTICLE: "compiler.codegen.gc-maps" "GC maps"
  52 "The " { $vocab-link "compiler.codegen.gc-maps" } " vocab serializes a compiled words gc maps into a space-efficient format which is appended to the end of the code block."
  53 $nl
  54 "Every code block generated either ends with:"
  55 { $list "uint 0" }
  56 "or"
  57 { $list
  58   {
  59       "a bitmap representing the indices of the spill slots that contain roots in each gc map"
  60   }
  61   "uint[] base pointers"
  62   "uint[] return addresses"
  63   "uint largest GC root spill slot"
  64   "uint largest derived root spill slot"
  65   "int number of return addresses/gc maps"
  66 }
  67 "For example, if there are three gc maps and each contain four roots, then bit 0-3 in the bitmap would indicate liveness of the first gc maps roots, 4-7 of the second and 8-11 of the third."
  68 $nl
  69 "Main entry point:"
  70 { $subsections emit-gc-maps } ;
  71
  72 ABOUT: "compiler.codegen.gc-maps"