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

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