basis/compiler/codegen/relocation/relocation-docs.factor

   1 USING: byte-vectors compiler.constants cpu.architecture help.markup
   2 help.syntax make vectors ;
   3 IN: compiler.codegen.relocation
   4
   5 HELP: relocation-table
   6 { $description "A " { $link byte-vector } " holding the relocations for the current compilation. Each sequence of four bytes in the vector represents one relocation." }
   7 { $see-also init-relocation } ;
   8
   9 HELP: add-dlsym-parameters
  10 { $description "Adds a pair of parameters for a reference to an external C function to the " { $link parameter-table } "." } ;
  11
  12 HELP: add-relocation
  13 { $values
  14   { "class" "a relocation class such as " { $link rc-relative } }
  15   { "type" "a relocation type such as " { $link rt-safepoint } }
  16 }
  17 { $description "Adds one relocation to the relocation table." } ;
  18
  19 HELP: add-literal
  20 { $values { "obj" "a symbol" } }
  21 { $description "Adds a symbol to the " { $link literal-table } "." } ;
  22
  23 HELP: init-relocation
  24 { $description "Initializes the dynamic variables related to code relocation." } ;
  25
  26 HELP: compiled-offset
  27 { $values { "n" "offset of the code being constructed in the current " { $link make } " sequence." } }
  28 { $description "The current compiled code offset. Used for (among other things) calculating jump labels." }
  29 { $examples
  30   { $example
  31     "USING: compiler.codegen.relocation cpu.x86.assembler"
  32     "cpu.x86.assembler.operands kernel layouts make prettyprint ;"
  33     "[ init-relocation RAX 0 MOV compiled-offset ] B{ } make"
  34     "cell-bits 64 = ["
  35     "    [ 10 = ] [ B{ 72 184 0 0 0 0 0 0 0 0 } = ] bi*"
  36     "] ["
  37     "    [ 6 = ] [ B{ 72 184 0 0 0 0 } = ] bi*"
  38     "] if . ."
  39     "t\nt"
  40   }
  41 } ;
  42
  43 HELP: parameter-table
  44 { $var-description "The parameter table is a " { $link vector } " which contains all the paramters for the word being generated." } ;
  45
  46 HELP: rel-decks-offset
  47 { $values { "class" "a relocation class" } }
  48 { $description "Adds a decks offset relocation. It is used for marking cards when emitting write barriers." } ;
  49
  50 HELP: rel-safepoint
  51 { $values { "class" "a relocation class" } }
  52 { $description "Adds a safe point to the " { $link relocation-table } " for the current code offset. This word is used by the " { $link %safepoint } " generator." } ;
  53
  54 ARTICLE: "compiler.codegen.relocation" "Relocatable VM objects"
  55 "The " { $vocab-link "compiler.codegen.relocation" } " deals with assigning memory addresses to VM objects, such as the card table. Those objects have different addresses during each execution which is why they are \"relocatable\". The vocab is shared by the optimizing and non-optimizing compiler."
  56 $nl
  57 "Adding relocations:"
  58 { $subsections add-relocation rel-decks-offset rel-safepoint }
  59 "Adding parameters:"
  60 { $subsections add-dlsym-parameters }
  61 "Tables used during code generation:"
  62 { $subsections literal-table parameter-table relocation-table } ;
  63
  64 ABOUT: "compiler.codegen.relocation"